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
API:Client code/Evaluations/simplemediawiki

Easy to install
Instructions are easy to find in README. Could also include directions wih pip. Does not mention incompatibility with Python 3 (Patch/pull request submitted: https://github.com/alexz-enwp/wikitools/pull/11)
 * 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
With endpoint ( object) and parameters (appropriate  ), all calls are available. Higher-level methods are available as well (e.g. many of the methods in page.py).
 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies

If the Wikidata endpoint is used for APIRequest and then query is called on the resulting APIRequest object, yes. For example
 * Platinum standard: makes the Wikidata API available

Code is nicely commented and looks like Python.
 * Well documented:
 * Code is commented and readable

Documentation is here: https://code.google.com/p/python-wikitools/wiki/Documentation. Documentation is only linked to from. Documentation only covers the  module in depth, but is very clear and thorough for that module. Documentation appears accurate.
 * Documentation is comprehensive, accurate, and easy to find

n/a
 * Deprecated functions are clearly marked as such

This would be a if the documentation were more complete. The documentation that exists is easily understandable by an advanced beginner, with useful code samples in the README.
 * Platinum standard: Documentation is understandable by a novice programmer


 * Code uses idioms appropriate to the language the library is written in

Easy to use
https://code.google.com/p/python-wikitools/wiki/APIRequest#Examples and in README.
 * Has functioning, simple, and well-written code samples for common tasks
 * Demonstrates queries

From README:
 * Demonstrates edits

Documentation specifies a slight difference in creating an  object for writing to the wiki: pass in. There are a variety of methods for making changes to the wiki, but there is no example for using, e.g.,  to make edits directly.


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


 * Cookies


 * Tokens

Uses query-continue; this is also different for wikibase calls but it does not appear that wikidata is intentionally in the scope of the library.
 * 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


 * Courteous API usage is promoted through code samples and smart defaults
 * gzip compression is used by default

Wiki.setUserAgent can be used to set a user agent, but the library/sample gives no guidance on what it should contain
 * Examples show how to create and use a meaningful and unique user-agent header

When logged in, the username is automatically included in the user agent. However, there is nothing comparable for a logged-out user.
 * Platinum standard: generates a unique user-agent string given name/email address/repository location

Nicely done. The API is called once to get information about Page and Wiki objects when they are created, and API calls are generally combined as much as possible. For example, only one combined API call is made to retrieve data on a list of pages.
 * Efficient usage of API calls

Python 2 only (2.5+)
 * 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


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

Good example here:
 * 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 API. The Page.edit docstring links to the associated API module documentation page.

Easy to improve
Library maintainer is not very responsive (via GitHub) as of June 2014, but existing wikitools-related comment threads are largely courteous and helpful.
 * 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

https://github.com/alexz-enwp/wikitools/pull/11 has not been accepted or rejected yet.
 * Pull requests are either accepted or rejected with reason within 3 weeks (Platinum standard: 3 business days)

About half of the issues in the last year have received a response within 1 week; most of the others received no response from maintainers.
 * Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)

is still used for ; it was removed from in May 2013. No breaking changes have affected the library since then, however.
 * 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

Contributions from Mr.Z-man include:, ,
 * Platinum standard: library maintainers contact MediaWiki API maintainers with feedback on the API's design and function

GPL 3
 * Library specifies the license it is released under

mwclient
The mwclient library is another framework for interaction with the API. It has the capability to support MediaWiki installations that lack the write API.

Easy to install
Version 0.6.5 (released in 2011) is available through PyPI. Release notes: https://github.com/mwclient/mwclient/blob/master/RELEASE-NOTES.md. Version 0.7 is in progress.
 * Installation instructions are correct and easy to find
 * Library is packaged for installation through appropriate package library (PyPI, CPAN, npm, Maven, rubygems, etc.)
 * Platinum standard: library is packaged for and made available through Linux distributions

Easy to understand
Makes many MediaWiki API calls available. It may be possible with available methods, but using the  library with the MediaWiki web API endpoint appears to be an easier option to access the Wikidata API. The development version is mostly PEP8-compliant, and has some comments. However, more consistent comments and more/better docstrings would make it easier to understand how the code works. Documentation is easy to find (, , and the mwclient GitHub wiki) and appears accurate. The documentation is not complete; the section on Generators, in particular, would be very helpful for a less experienced Python developer who is trying to understand the underlying structure of the library. n/a The README and the documentation on the wiki is clearly written and does not assume very much background, and there is a handful of tutorials that a new user can expand on. Library is distinctly Pythonic;  is used to iterate,   and   are used for variable numbers of arguments, functions like   are used to deal with dictionaries, and Python's generator-type functions are used.
 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies
 * Platinum standard: makes the Wikidata API available
 * Well documented:
 * Code is commented and readable
 * Documentation is comprehensive, accurate, and easy to find
 * 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


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


 * Cookies


 * Tokens

Handles query continuations, but uses the old  parameter. As of version 0.6.5, mwclient uses  to make the API calls, which does not validate SSL certificates and is vulnerable to an interception attack. Using a library like  would make the library more secure and also make the code more readable. However, version 0.7 is being finished and will use  for better security and compatibility with the latest version of MediaWiki.
 * Query continuations using the new "continue" and not "query-continue"
 * Requests via https, including certificate validation
 * Courteous API usage is promoted through code samples and smart defaults
 * gzip compression is used by default

There is only a default header (with version number, library name, and main repository link) and no mention of changing the header for each user.
 * 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

The generator functions iterate over lists, and therefore make multiple API calls for a given list of pages instead of making a single call to retrieve information on multiple titles. Python 2 (2.4+) only. It is confusing that the user calls  to retrieve the text of a page, and   to edit the text of a page. Consider deprecating/renaming these functions for clarity. "Generator"-type classes could clarify whether they refer to/use Python generators or the MediaWiki API's generator module.
 * 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)
 * Comment on method names

Easy to debug
There is a unit test for  but no others. There are integration tests in  and. These were last updated in June 2013. Some things are marked as "BAD." or "hack" but there is no commentary on why this is the case. Links to API in documentation, but not to subpages.
 * 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
 * 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
Yes. Maintainers and contributors are courteous, responsive, and interested in improving the project.
 * 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

Recent pull requests were merged within 3 d. Responsive maintainers and a library in active development. n/a; breaking changes have not affected mwclient
 * 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


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

MIT License.
 * Library specifies the license it is released under

Pywikibot
Pywikibot is a full-featured API client framework geared towards power users who want to edit wikis: wiki maintainers, bot-runners, and others who want to automate work on MediaWiki sites.

Easy to install
The clearest and simplest installation and configuration instructions are in the slides from the 2013 Pywikipediabot/Hackathon 2013. There are also installation instructions at Manual:Pywikibot/Installation, which are extensive and may be confusing to the casual user. It is possible to install through pip using the instructions in this bug report. However, even when pywikibot is installed in a virtual environment (using ), it still requires a copy of   in the home directory before   will run without error.
 * Installation instructions are correct and easy to find
 * Library is packaged for installation through appropriate package library (PyPI, CPAN, npm, Maven, rubygems, etc.)
 * Platinum standard: library is packaged for and made available through Linux distributions

Easy to understand
The lowest-level functions to access the API can be found in api.py. https://github.com/wikimedia/pywikibot-core/blob/master/pywikibot/data/wikidataquery.py Clear coding with a consistent style. Docstrings are present classes and functions and are generally clearly written and helpful. Pywikibot's Development guidelines are being followed. Many of the issues with Pywikibot's documentation are summarized in Pywikibot/Documentation RFC. In general, the easily findable documentation is aimed at running bots using the scripts available with pywikibot, not at writing new scripts. |README-conversion.txt has some information for script-writers. Pywikibot has been rewritten to use the API, and the rewritten version is the new "core" branch. There is some debate on deprecation of "compat": http://lists.wikimedia.org/pipermail/pywikipedia-l/2014-June/008764.html. Additionally,  has deprecated methods: "deprecated methods still work, but print a warning message in debug mode" (from README-conversion.txt). Documentation assumes considerable expertise with MediaWiki. There is also little easily available documentation aimed at enabling users to write new scripts.
 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies
 * Platinum standard: makes the Wikidata API available
 * Well documented:
 * Code is commented and readable
 * Documentation is comprehensive, accurate, and easy to find
 * 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

There are a number of available scripts. Simpler examples would help.
 * Demonstrates edits
 * Handles API complications or idiosyncrasies so the user doesn't have to:
 * Login/logout


 * Cookies


 * Tokens

Handles continuations using the old  parameter.
 * Query continuations using the new "continue" and not "query-continue"
 * Requests via https, including certificate validation


 * 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

??? Python 3 support is being implemented in Core.
 * 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)

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


 * 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
Much interaction takes place on pywikipedia-l, which can be contentious and which tends to assume expertise.
 * 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

A good start for setting community expectations for behavior can be found in the IRC channel: " Don't ask to ask, ask. Please be patient for an answer. Do not private message unless asked."


 * 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


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

MIT License
 * Library specifies the license it is released under

= Template =

Library name
[Brief description]

Easy to install

 * Installation instructions are correct and easy to find


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


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

Easy to understand

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


 * Platinum standard: makes the Wikidata API available


 * Well documented:
 * Code is commented and readable


 * Documentation is comprehensive, accurate, and easy to find


 * 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


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


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


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

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


 * 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


 * 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


 * 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