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

Particularly useful or notable features of pywikibot include:

cool things: makes wikidata API accessible good and consistent code style, readable code handles deprecated methods/branches has good unit test coverage! very comprehensive and targeted to its intended usecase, running bots.

= Suggested TODOs =
 * easier to find and more intuitive installation instructions
 * make it possible to install into a venv without putting the config file in the home directory; package for and submit to PyPI
 * create documentation for people who aren't running bots with existing scripts (researchers and botwriters)
 * add code samples for common tasks, including queries and edits
 * use continue and not query-continue for query continuations
 * use gzip compression by default
 * make it easy to and give examples of a good user-agent header
 * make it Python 3 compatible (this is in progress for Core)
 * also more efficient API calls (combine, take advantage of databaseish)
 * when you have documentation, make sure it links to API subpages
 * improve the hospitality of pywikipedia-l, especially to new and/or inexperienced users
 * improve responsiveness to bug reports and/or make current status of library clear

=In-depth evaluation=

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