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:

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

In-depth evaluation

Easy to install

Installation instructions are correct and easy to find

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.

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

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 virtualenv), it still requires a copy of user-config.py in the home directory before import pywikibot will run without error.

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

N

Easy to understand

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

The lowest-level functions to access the API can be found in api.py.

Platinum standard: makes the Wikidata API available

Y https://github.com/wikimedia/pywikibot-core/blob/master/pywikibot/data/wikidataquery.py

Well documented

• Code is commented and readable

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

• Documentation is comprehensive, accurate, and easy to find

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

• Deprecated functions are clearly marked as such

Y 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, core has deprecated methods: "deprecated

methods still work, but print a warning message in debug mode" (from README-conversion.txt).

• Platinum standard: Documentation is understandable by a novice programmer

N Documentation assumes considerable expertise with MediaWiki. There is also little easily available documentation aimed at enabling users to write new scripts.

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

Y

Easy to use

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

• Demonstrates queries

N

• Demonstrates edits

There are a number of available scripts.[1] Simpler examples would help.

Handles API complications or idiosyncrasies so the user doesn't have to

• Login/logout

Y

• Cookies

Y

• Tokens

Y

• Query continuations

Y

• Requests via https, including certificate validation

Y

Courteous API usage is promoted through code samples and smart defaults

• gzip compression is used by default

Y httplib2 does this automatically.

• Examples show how to create and use a meaningful and unique user-agent header (as in https://meta.wikimedia.org/wiki/User-agent_policy)

N

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

N

• Efficient usage of API calls

N Pywikibot generally fetches a list of pages meeting given criteria, then retrieves/acts on each page individually.

Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

N Python 3 support is currently being implemented in Core.

Easy to debug

Contains unit tests for the longest and most frequently modified functions in the library

Y

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

Y

Terrible hacks/instances of extreme cleverness are clearly marked as such in comments

Y

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

N

Easy to improve

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

Much interaction takes place on pywikipedia-l, which can be contentious and which tends to assume expertise.

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

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

N

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

Replies are faster on the mailing list than on the bug tracker.

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

Y MIT License

Suggested TODOs

Code-related

• Make it easy to add a user-agent header and give examples of a good one in the documentation for it (see https://meta.wikimedia.org/wiki/User-agent_policy) (in progress: https://gerrit.wikimedia.org/r/#/c/147381/)
• Add Python 3 compatibility (this is in progress for the core branch) (bugzilla:58053)
• Package pywikibot for installation from PyPI via pip install (bugzilla:65176)
• Make the initial installation process lighter-weight:
  • Design pwb.py with user experience in mind, particularly valuing feedback from new or one-time users during the redesign process
  • Make it possible to install into a virtualenv without putting a config file in the home directory (bugzilla:61783)
  • Make it possible to run import pywikibot without having to log in
  • Amir Ladsgroup has some good feedback/suggestions here: http://lists.wikimedia.org/pipermail/pywikipedia-l/2014-June/008784.html
• Iterating over a list and calling the API for each item is an inefficient use of API calls. Efficiency in API usage is an important feature of a gold standard library. If you are interested in gold standard status, consider making this more efficient by combining API calls as much as possible (e.g. using generators and combining resultstitle=title1|title2|...). One option may be a constructor method that collects Page requests and enables larger, less frequent API calls. It may be possible to take advantage of the database-like structure of the MediaWiki API and help users save bandwidth.

Process-related

• Foster a hospitable attitude on pywikipedia-l, especially to new and/or inexperienced users. Consider agreeing on community standards for interaction; the Hacker School social rules may be a useful starting point.
• Create more centralized and updated documentation, including the following. Also see Manual:Pywikibot/Documentation RFC.
  • Easy-to-find, complete, and intuitive installation instructions, including installing via pip and into virtual environments
  • Code samples for common tasks, including queries and edits
  • Documentation for people who aren't running bots with existing scripts (particularly researchers and beginning/intermediate bot writers)
  • Links in method documentation to the corresponding API subpages
• Streamline or add more resources to the patch review process to reduce the backlog of unreviewed patches

Pywikibot appears to be too specialized to easily meet the gold standard. However, collecting a lightweight subset of the available modules and documenting how to use the framework to send queries and not just make edits could be very useful, particularly the portion of the code that deals with the wikibase API modules.