API:Client code/Evaluations/simplemediawiki

From MediaWiki.org
Jump to navigation Jump to search

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

Yellow check.svg 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.)

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

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

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

Easy to understand[edit]

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

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

Platinum standard: makes the Wikidata API available

Yes The Wikidata API is available when using the Wikidata endpoint.

Well documented
  • Code is commented and readable
Yellow check.svg 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
Yellow check.svg 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
N 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
Yes

Easy to use[edit]

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

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

  • Demonstrates queries
Yes
  • Demonstrates edits
N
Handles API complications or idiosyncrasies so the user doesn't have to
  • Login/logout
Yes
  • Cookies
Yes
  • Tokens
N
  • Query continuations
N
  • Requests via https, including certificate validation
Yellow check.svg 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

Yellow check.svg 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
Yes
  • Examples show how to create and use a meaningful and unique user-agent header
Yes 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
Yes
  • 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)

Yes 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

Yes

Platinum standard: Unit tests for many code paths exist and are maintained

Yellow check.svg 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

Yes 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

Yellow check.svg

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)

Yellow check.svg 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

Yes GPL 2.1

Suggested TODOs[edit]

Code-related
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.