API:Client code/Evaluations

This page holds evaluations of the client libraries listed on API talk:Client code according to API:Client code/Gold standard, in varying stages of completion.

=Python=

simplemediawiki
The simplemediawiki API client library is a simple wrapper around 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.

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.
 * 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. 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
yes
 * 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

n/a? Docs link to mw:API:Main page.
 * 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
Somewhat responsive(?)
 * 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. No response as of 5 June; automatic testing failed and I'm not sure why it should.
 * 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)

Submitted a bug (https://github.com/ianweller/python-simplemediawiki/issues/11) June 3, received a response 5 June.

However, https://github.com/ianweller/python-simplemediawiki/issues/9 has been open with no comment since March 12 (~3 mo).


 * 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 (low-level library; no relevant breaking changes since June 2013)

Will inquire/search
 * 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

Easy to install
Instructions are easy to find in README. Could also include directions wih pip. Does not mention incompatibility with Python 3 (TODO: submit patch to README)
 * Installation instructions are correct and easy to find

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

Packaged for Fedora (rpm), but not for Debian. Also packaged as a Windows .exe.
 * Platinum standard: library is packaged for and made available through Linux distributions

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

no
 * Platinum standard: makes the Wikidata API available


 * Well documented:

Documentation is not easy to find: it is here: https://code.google.com/p/python-wikitools/wiki/Documentation
 * Documentation is comprehensive, accurate, and easy to find

submitted pull req to add link to readme: https://github.com/alexz-enwp/wikitools/pull/11

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


 * Platinum standard: Documentation is understandable by a novice programmer


 * 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

yes
 * Handles API complications or idiosyncrasies so the user doesn't have to:
 * Login/logout

yes
 * Cookies

TODO
 * Tokens

TODO
 * 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
 * Requests via https, including certificate validation

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

self.useragent = "python-wikitools/%s" % VERSION Logged-in, self.useragent = "python-wikitools/%s (User:%s)" % (VERSION, self.username)


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

def setUserAgent(self, useragent): """Function to set a different user-agent""" self.useragent = str(useragent) return self.useragent

TODO
 * Efficient usage of API calls

Easy to debug
no
 * Contains unit tests for the longest and most frequently modified functions in the library

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

UNKNOWN, look at it?
 * Terrible hacks/instances of extreme cleverness are clearly marked as such in comments


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

README links to http://www.mediawiki.org/wiki/API. The Page.edit docstring links to the associated API module documentation page.

Easy to improve

 * Library maintainers are responsive and courteous, and foster a thoughtful and inclusive community of developers and users

UNKNOWN

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

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

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

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

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

yes, GPL 3
 * Library specifies the license it is released under