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
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:
- 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
- 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
- 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
- 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 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
- Query continuations
- Requests via https, including certificate validation
- Will retrieve data if the endpoint begins with https, but uses
urlliband doesn't check for certificate validity
- 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
- 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
- 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
- Documentation links to the relevant section/subpage of the API documentation
Docs link to mw:API:Main page.
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
- 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
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
- Library specifies the license it is released under
- 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
urllib) or passing an
auth=...with each request (in the case of
- Add the capability to handle tokens for edit requests and enable automatic query continuations
- Use the
requestslibrary instead of
urllibto handle HTTP requests. This will improve security as well as code readability.
- 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.