API:Client code/Evaluations/simplemediawiki

The simplemediawiki API client library is a lightweight Python wrapper for the MediaWiki API. It offers direct access to MediaWiki API calls (documented at http://mediawiki.org/w/api.php and API:Main page, with associated links) through standard Pythonic syntax. It handles cookies and login, and otherwise essentially serves as syntactic sugar.

Particularly useful or notable features of simplemediawiki include:
 * The library is packaged for installation through multiple Linux distributions, as well as through PyPI.
 * Python 2.6+/3.3+ compatible
 * Has good unit test coverage
 * PEP8-compliant, including informative docstrings.
 * Promotes courteous API usage: uses gzip compression by default, and makes it easy for clients to include an informative user-agent

= In-depth evaluation = See: API:Client code/Gold standard

Easy to install
No installation instructions on documentation (http://pythonhosted.org/simplemediawiki/) or github (https://github.com/ianweller/python-simplemediawiki), but the library is available for installation through PyPI.
 * Installation instructions are correct and easy to find

Packaged for PyPi: https://pypi.python.org/pypi/simplemediawiki/1.2.0b2
 * Library is packaged for installation through appropriate package library (PyPI, CPAN, npm, Maven, rubygems, etc.)

The simplemediawiki library is packaged for installation through several Linux package libraries:
 * Platinum standard: library is packaged for and made available through Linux distributions

Does not auto-install python-iso8601 dependency. Issue submitted: https://github.com/ianweller/python-simplemediawiki/issues/11. A problem on Ubuntu's end. Bug report submitted to Ubuntu: https://bugs.launchpad.net/ubuntu/+source/python-simplemediawiki/+bug/1328303.
 * Ubuntu: available as python-simplemediawiki through apt-get install (https://launchpad.net/ubuntu/precise/amd64/python-simplemediawiki)
 * http://pkgs.org/centos-6/epel-i386/python-simplemediawiki-1.1-1.el6.noarch.rpm.html
 * https://apps.fedoraproject.org/packages/python-simplemediawiki

Easy to understand
Because the library is designed to offer no levels of abstraction, all API calls are available.
 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies

The Wikidata API is available when using the Wikidata endpoint.
 * Platinum standard: makes the Wikidata API available


 * Well documented:
 * Code is commented and readable
 * Auto-documented using Sphinx. All functions have docstrings; code has no further comments.


 * Uses urllib, not requests; http-related methods are more complicated to read than they might be, and urllib does not validate SSL certificates. Code is clear and follows Python coding conventions.


 * Documentation is comprehensive, accurate, and easy to find
 * Documentation is available at http://pythonhosted.org/simplemediawiki, but there is no link to it anywhere in the github repository or in any of the docstrings.


 * Filed a patch to add a link to the documentation in the README: https://github.com/ianweller/python-simplemediawiki/pull/10. For some reason the build did not pass the automated tests for Python 2.6 and Python 3.3.


 * Deprecated functions are clearly marked as such
 * n/a


 * Platinum standard: Documentation is understandable by a novice programmer
 * Documentation is aimed at a competent-to-expert developer and takes considerable effort for a novice to understand and apply.


 * Code uses idioms appropriate to the language the library is written in

Easy to use
Has one code sample demonstrating a query, but not use of the user-agent module.
 * 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


 * Query continuations using the new "continue" and not "query-continue"


 * Requests via https, including certificate validation
 * Will retrieve data if the endpoint begins with https, but uses  and doesn't check for certificate validity

Code sample doesn't show usage of the user-agent generator, but it is strongly suggested. Does not handle rate limiting.
 * Courteous API usage is promoted through code samples and smart defaults
 * gzip compression is used by default


 * Examples show how to create and use a meaningful and unique user-agent header
 * No sample code, but the method that does this is documented and its use is suggested


 * Platinum standard: generates a unique user-agent string given name/email address/repository location


 * Efficient usage of API calls
 * n/a

Compatible with Python 2.6+ and 3.3+
 * Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

Easy to debug

 * Contains unit tests for the longest and most frequently modified functions in the library

A proposed patch to the README had the Travis CI build fail: https://github.com/ianweller/python-simplemediawiki/pull/10, which it should not have n/a Docs link to mw:API:Main page.
 * 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

 * 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

Submitted pull request 3 June 2014: https://github.com/ianweller/python-simplemediawiki/pull/10.
 * Pull requests are either accepted or rejected with reason within 3 weeks (Platinum standard: 3 business days)

Depends on the bug; quick response for, no response yet for or  (submitted March 12).
 * Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)

n/a; simplemediawiki is low-level enough to not be affected by breaking changes (since May 2013)
 * 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

GPL 2.1
 * Library specifies the license it is released under

= Suggested TODOs =
 * Code-related
 * Improve the tests: fix the unexpectedly failing tests
 * Address https://github.com/ianweller/python-simplemediawiki/issues/9, possibly via configuration of HTTPDigestAuthHandler (in the case of ) or passing an   with each request (in the case of )
 * Add the capability to handle tokens for edit requests and enable automatic query continuations
 * Use the  library instead of   to handle HTTP requests. This will improve security as well as code readability.


 * Process-related
 * Make the documentation more beginner-friendly, including adding a link to the documentation to the README.
 * Improve the available code samples by demonstrating use of the user-agent function and including a sample that demonstrates use of login/cookies to make edits to a wiki.
 * Decide and communicate the intended level of responsiveness (either enabling a faster response to comments/pull requests/issues, or noting the maintenance/development status in the README). If you are interested in simplemediawiki being listed as a gold standard library, active maintenance and prompt responses are important--even if a given issue is too big to fix immediately or a patch too complex to review quickly.

If these changes are made, simplemediawiki will meet the gold standard for API client libraries and will be recommended on API:Client code.