API:Client code/Evaluations/wikitools

Summary:

Particularly notable and useful aspects of wikitools include:
 * Very efficient usage of API calls
 * Packaged for Windows as well as for Fedora and through PyPI
 * The documentation that exists is clearly written and easily understandable
 * Code is clearly commented and nicely readable

= Suggested TODOs =
 * add directions to install with  to the README
 * mention incompatibility with Python 3 in README: https://github.com/alexz-enwp/wikitools/pull/11
 * expand documentation to modules besides, include links to the API subpages
 * remove use of  when using
 * add an example of using  to make edits to the code samples; add usage of   to the code samples
 * use the  parameter instead of   to handle query continuations
 * use  instead of
 * make it compatible with Python 3
 * add unit tests
 * consider the intended level of responsiveness (responding faster, or noting level of maintenance in README)

If these are addressed, this library will meet the gold standard.

= In-depth evaluation =

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