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[edit]

See: API:Client code/Gold standard

Easy to install[edit]

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:

Ubuntu: available as python-simplemediawiki through apt-get install (https://launchpad.net/ubuntu/precise/amd64/python-simplemediawiki)

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.

Easy to understand[edit]

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[edit]

Has functioning, simple, and well-written code samples for common tasks

Has one code sample demonstrating a query, but not use of the user-agent module.

Demonstrates queries

Demonstrates edits

Handles API complications or idiosyncrasies so the user doesn't have to

Login/logout

Cookies

Tokens

Query continuations

Requests via https, including certificate validation

Will retrieve data if the endpoint begins with https, but uses urllib and doesn't check for certificate validity

Courteous API usage is promoted through code samples and smart defaults

Code sample doesn't show usage of the user-agent generator, but it is strongly suggested. Does not handle rate limiting.

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
Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

Compatible with Python 2.6+ and 3.3+

Easy to debug[edit]

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

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

Terrible hacks/instances of extreme cleverness are clearly marked as such in comments

n/a

Documentation links to the relevant section/subpage of the API documentation

Docs link to mw:API:Main page.

Easy to improve[edit]

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

N

Pull requests are either accepted or rejected with reason within 3 weeks (Platinum standard: 3 business days)

N Submitted pull request 3 June 2014: https://github.com/ianweller/python-simplemediawiki/pull/10.

Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)

Depends on the bug; quick response for [1], no response yet for [2] or [3] (submitted March 12).

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

n/a; simplemediawiki is low-level enough to not be affected by breaking changes (since May 2013)

Platinum standard: library maintainers contact MediaWiki API maintainers with feedback on the API's design and function

N

Library specifies the license it is released under

GPL 2.1

Suggested TODOs[edit]

Code-related

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

Process-related

Make the documentation more beginner-friendly, including adding a link to the documentation to the README.[8][9]
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.[10]
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).[11] 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.