API:Client code/Evaluations/mwclient

The mwclient library facilitates interaction with the MediaWiki API. It can be used to make specific API calls or the many built-in methods can be used for common functions such as retrieving and editing page text, managing user permissions, and more. It has the capability to support MediaWiki installations that lack the write API.

Particularly useful or notable features of mwclient include:
 * active development and a community of developers/maintainers
 * offers abstraction and a clear and easy way to do tasks (not just a wrapper)
 * screenscraping fallback
 * full-featured for a basic client library
 * decent docs and some tests

=In-depth evaluation=

Easy to install
Version 0.6.5 (released in 2011) is available through PyPI. Release notes: https://github.com/mwclient/mwclient/blob/master/RELEASE-NOTES.md. Version 0.7 is in progress.
 * Installation instructions are correct and easy to find
 * Library is packaged for installation through appropriate package library (PyPI, CPAN, npm, Maven, rubygems, etc.)
 * Platinum standard: library is packaged for and made available through Linux distributions

Easy to understand
Makes many MediaWiki API calls available and also lower-level API requests. It may be possible with available methods, but using the  library with the Wikidata web API endpoint appears to be an easier option to access the Wikidata API. The development version is mostly PEP8-compliant, and has some comments. However, more consistent comments and more/better docstrings would make it easier to understand how the code works. Documentation is easy to find (, , and the mwclient GitHub wiki) and appears accurate. The documentation is not complete; the section on Generators, in particular, would be very helpful for a less experienced Python developer who is trying to understand the underlying structure of the library. n/a The README and the documentation on the wiki is clearly written and does not assume very much background, and there is a handful of tutorials that a new user can expand on. Library is distinctly Pythonic;  is used to iterate,   and   are used for variable numbers of arguments, functions like   are used to deal with dictionaries, and Python's generator-type functions are used.
 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies
 * Platinum standard: makes the Wikidata API available
 * Well documented:
 * Code is commented and readable
 * Documentation is comprehensive, accurate, and easy to find
 * Deprecated functions are clearly marked as such
 * Platinum standard: Documentation is understandable by a novice programmer
 * Code uses idioms appropriate to the language the library is written in

Easy to use

 * Has functioning, simple, and well-written code samples for common tasks
 * Demonstrates queries
 * Demonstrates edits


 * Handles API complications or idiosyncrasies so the user doesn't have to:
 * Login/logout


 * Cookies


 * Tokens

Handles query continuations, but uses the old  parameter. As of version 0.6.5, mwclient uses  to make the API calls, which does not validate SSL certificates and is vulnerable to an interception attack. Using a library like  would make the library more secure and also make the code more readable. However, version 0.7 is being finished and will use  for better security and compatibility with the latest version of MediaWiki.
 * Query continuations using the new "continue" and not "query-continue"
 * Requests via https, including certificate validation
 * Courteous API usage is promoted through code samples and smart defaults
 * gzip compression is used by default

There is only a default header (with version number, library name, and main repository link) and no mention of changing the header for each user.
 * Examples show how to create and use a meaningful and unique user-agent header (as in https://meta.wikimedia.org/wiki/User-agent_policy)
 * Platinum standard: generates a unique user-agent string given name/email address/repository location

The generator functions iterate over lists, and therefore make multiple API calls for a given list of pages instead of making a single call to retrieve information on multiple titles. Python 2 (2.4+) only. It is confusing that the user calls  to retrieve the text of a page, and   to edit the text of a page. Consider deprecating/renaming these functions for clarity. "Generator"-type classes could clarify whether they refer to/use Python generators or the MediaWiki API's generator module.
 * Efficient usage of API calls
 * Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)
 * Comment on method names

Easy to debug
There is a unit test for  but no others. There are integration tests in  and. These were last updated in June 2013. Some things are marked as "BAD." or "hack" but there is no commentary on why this is the case. Links to API in documentation, but not to subpages.
 * Contains unit tests for the longest and most frequently modified functions in the library
 * Platinum standard: Unit tests for many code paths exist and are maintained
 * Terrible hacks/instances of extreme cleverness are clearly marked as such in comments
 * Documentation links to the relevant section/subpage of the API documentation

Easy to improve
Yes. Maintainers and contributors are courteous, responsive, and interested in improving the project.
 * Library maintainers are responsive and courteous, and foster a thoughtful and inclusive community of developers and users
 * Platinum standard: Project sets clear expectations for conduct for spaces where project-related interactions occur (mailing list, IRC, repository, issue tracker). It should:
 * State desired attitudes and behaviors
 * Provide examples of unwelcome and harassing behavior
 * Specify how these expectations will be enforced

Recent pull requests were merged within 3 days. Responsive maintainers and a library in active development. n/a; breaking changes have not affected mwclient MIT License.
 * Pull requests are either accepted or rejected with reason within 3 weeks (Platinum standard: 3 business days)
 * Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)
 * The library is updated and a new version is released within 3 weeks (Platinum standard: 3 business days) when breaking changes are made to the API
 * Platinum standard: library maintainers contact MediaWiki API maintainers with feedback on the API's design and function
 * Library specifies the license it is released under

= Suggested TODOs =
 * Ensure that version 0.7 is packaged for PyPI and any other desired package repositories
 * Use the  parameter for query continuations, not
 * Add and improve docstrings and expand on terse comments (i.e. explain why a line is "BAD.")
 * Improve documentation:
 * Link to relevant API subpages
 * Include information on Generators
 * Include examples of individual user/contact information in the user-agent (also consider writing a function to make this easier for logged-out users)
 * Add a basic description of the workflow this library expects
 * Add unit tests for the most commonly used and frequently updated portions of the library
 * Use the  library for http requests (this is in progress for v. 0.7)
 * Make mwclient compatible with Python 3

If these issues are addressed, mwclient will meet the gold standard and will be listed as such on API:Client code.

Other issues for your consideration:
 * Iterating over a list and calling the API for each item is inefficient; if a structural redesign is in the works, consider making this more efficient by combining API calls as much as possible (e.g. using generators and combining results ). It may be possible to take advantage of the database-like structure of the MediaWiki API and help users save bandwidth.
 * It is confusing that the user calls page.edit to retrieve the text of a page, and page.save(...) to edit the text of a page. Consider deprecating/renaming these functions for clarity. "Generator"-type classes could clarify whether they refer to/use Python generators or the MediaWiki API's generator module.