API:Client code/Evaluations/MediaWiki-Bot

From MediaWiki.org
Jump to navigation Jump to search

MediaWiki::Bot is a higher-level Perl API client library with many higher-level methods that expose a significant portion of the API. MediaWiki::Bot is considerably lighter-weight than pywikibot, but it would be easy to use to write similar wiki-maintenance scripts.

Particularly notable and useful features of MediaWiki::Bot are:

  • Covers a wide range of API functions (both GET and POST)
  • Impressively complete test suite
  • Lots of sample code and detailed documentation
  • Project has a history of active, responsive, and helpful maintainers

In-depth evaluation[edit]

Easy to install[edit]

Installation instructions are correct and easy to find

Yellow check.svg Mentions that the module is available on CPAN. No further instructions.

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

Yes Packaged for installation through CPAN.

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

N

Easy to understand[edit]

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

Yes It would also be useful to have a namespace alias-to-number helper function to reduce the dependence on bare namespace numbers.

Platinum standard: makes the Wikidata API available

Yellow check.svg MediaWiki::API does because of its generality, and MediaWiki::Bot can be used for non-Wikidata-specific API modules

Well documented
  • Code is commented and readable
Yellow check.svg 2775 sloc is far too much for one file. Bare numbers are used for error codes (referring to constants found in MediaWiki::API) and namespaces. These make the code hard to follow and also make it easier for changes to MediaWiki::API to break MediaWiki::Bot.
  • Documentation is comprehensive, accurate, and easy to find
Yes Documentation is available on CPAN. Individual methods are all documented, but there is no good overview of the module--it is primarily a list of functions.
  • Deprecated functions are clearly marked as such
Yes Deprecated functions emit a warning.
  • Platinum standard: Documentation is understandable by a novice programmer
N Documentation is quite complete, but is difficult to understand as a whole due to its lack of context. It would be most useful for a developer who is moderately experienced with both Perl and the MediaWiki API and who is interested in implementing a small set of very specific functions. However, for someone who is new to the MediaWiki API and/or common designs for its associated client libraries, the sheer quantity of documentation and details is overwhelming.
Code uses idioms appropriate to the language the library is written in

Yellow check.svg The library is generally Perlish and uses strict and warnings. However, the liberal use of shift makes assigning variables difficult to follow in some methods. As mentioned above, bare numbers should not be used for namespaces and error codes.

Easy to use[edit]

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

All methods have code samples provided in the documentation.

  • Demonstrates queries
Yes
  • Demonstrates edits
Yes
Handles API complications or idiosyncrasies so the user doesn't have to
  • Login/logout
Yes
  • Cookies
Yes
  • Tokens
Yes
  • Query continuations
Yellow check.svg MediaWiki::API handles query continuations for action=list, and MediaWiki::Bot handles query continuations in the global_image_usage method.
  • Requests via https, including certificate validation
Yes The default endpoint could also be changed to https://en.wikipedia.org/w/api.php.
Courteous API usage is promoted through code samples and smart defaults
  • gzip compression is used by default
Yes
N
  • Platinum standard: generates a unique user-agent string given name/email address/repository location
Yellow check.svg If logged in, it adds the username to the generic MediaWiki::Bot user agent.
  • Efficient usage of API calls
Yes Generally combines calls when possible; good job.
Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

Yes Compatible with Perl 5.

Easy to debug[edit]

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

Yes

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

Yes Unusually complete test suite.

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

Yellow check.svg Some are marked usefully and explained in documentation (get_text); others are marked, but are confusing or have undescribed limitations (get_all_pages_in_category, _get_ns_alias_data).

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

Yellow check.svg Some methods do; many do not.

Easy to improve[edit]

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

Yes Patches/pull requests receive useful comments.

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

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

Yes

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

Yes Very quick responses!

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

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

Yes GPL 3+

Suggested TODOs[edit]

Code-related
  • Consistently use constants instead of bare numbers[1]
  • Logically group related subroutines into several separate files[2]
  • Make sure that continuations for all types of queries are automatically handled[3]
  • Add the repository location to the default user-agent string (see [4])[5]
  • Consider refactoring get_all_pages_in_category and _get_ns_alias_data[6]
Process-related
  • Add installation instructions to documentation[7]
  • Add an "overview" section to the documentation describing MediaWiki::Bot's overall design, intended purpose, and the types of functions it makes available[8]
  • Add a code sample with a user-created user-agent that complies with https://meta.wikimedia.org/wiki/User-agent_policy (has contact information and information about the library)[9]
  • Link to relevant API documentation in the documentation for each relevant method[10]

If these issues are addressed, MediaWiki::Bot will meet the gold standard and will be listed as such on API:Client code.