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 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

 * Installation instructions are correct and easy to find

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.


 * Library is packaged for installation through appropriate package library (PyPI, CPAN, npm, Maven, rubygems, etc.)

Packaged for PyPi: https://pypi.python.org/pypi/simplemediawiki/1.2.0b2


 * Platinum standard: library is packaged for and made available through Linux distributions

The simplemediawiki library is packaged for installation through several Linux package libraries:

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

 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies

Because the library is designed to offer no levels of abstraction, all API calls are available.


 * Platinum standard: makes the Wikidata API available

The Wikidata API is available when using the Wikidata endpoint.


 * 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"

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.
 * Requests via https, including certificate validation
 * Courteous API usage is promoted through code samples and smart defaults
 * gzip compression is used by default

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


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

n/a Compatible with Python 2.6+ and 3.3+
 * 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)

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 =
 * Improve the tests and documentation: fix the unexpectedly failing tests and 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.
 * Add the capability to handle tokens for edit requests and enable automatic querycontinuations (using the  parameter).
 * Use the  library instead of   to handle HTTP requests. This will improve security as well as readibility. [This may or may not help with https://github.com/ianweller/python-simplemediawiki/issues/9]
 * 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.