API:Client code/Evaluations/wikitools

From MediaWiki.org
Jump to navigation Jump to search

Wikitools is a small library that facilitates interaction with the MediaWiki API. There are methods available for easily making changes to or getting information about pages, categories, users, and the wiki itself.

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 usefully commented and impressively readable

In-depth evaluation[edit]

Easy to install[edit]

Installation instructions are correct and easy to find

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

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

Yes Packaged for PyPI: https://pypi.python.org/pypi/wikitools

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

Yellow check.svg Packaged for Fedora (rpm), but not for Debian. Also packaged as a Windows .exe.

Easy to understand[edit]

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

Yes With endpoint (Wiki object) and parameters (appropriate APIRequest.params), all calls are available. Higher-level methods are available as well (e.g. many of the methods in page.py).

Platinum standard: makes the Wikidata API available

Yes If the Wikidata endpoint is used for APIRequest and then query() is called on the resulting APIRequest object, yes. For example

from wikitools import wiki, api

wikidata = wiki.Wiki('https://www.wikidata.org/w/api.php')
params = {'action': 'wbsearchentities', 'search': 'abc', 'language': 'en'}
request = api.APIRequest(wikidata, params)
result = request.query()
print result
Well documented
  • Code is commented and readable
Yes Code is nicely commented and looks like Python.
  • Documentation is comprehensive, accurate, and easy to find
N Documentation is here: https://code.google.com/p/python-wikitools/wiki/Documentation. Documentation is only linked to from api.py. Documentation only covers the api module in depth, but is very clear and thorough for that module. Documentation appears accurate.
  • Deprecated functions are clearly marked as such
n/a
  • Platinum standard: Documentation is understandable by a novice programmer
N This would be a Yellow check.svg if the documentation were more complete. The documentation that exists is easily understandable by an advanced beginner, with useful code samples in the README.
Code uses idioms appropriate to the language the library is written in

Yes

Easy to use[edit]

Has functioning, simple, and well-written code samples for common tasks
  • Demonstrates queries
Yes https://code.google.com/p/python-wikitools/wiki/APIRequest#Examples and in README.
  • Demonstrates edits
Yellow check.svg From README:
from wikitools import wiki
from wikitools import category
site = wiki.Wiki("http://my.wikisite.org/w/api.php")
site.login("username", "password")
# Create object for "Category:Foo"
cat = category.Category(site, "Foo")
# iterate through all the pages in ns 0
for article in cat.getAllMembersGen(namespaces=[0]):
# edit each page
article.edit(prependtext="{{template}}\n")
Documentation specifies a slight difference in creating an APIRequest object for writing to the wiki: pass in write=true. There are a variety of methods for making changes to the wiki, but there is no example for using, e.g., APIRequest.query() to make edits directly.
Handles API complications or idiosyncrasies so the user doesn't have to
  • Login/logout
Yes
  • Cookies
Yes
  • Tokens
Yes
  • Query continuations
Yes
  • Requests via https, including certificate validation
Yellow check.svg Will retrieve data if the endpoint begins with https, but uses urllib2 and doesn't check for certificate validity
Courteous API usage is promoted through code samples and smart defaults
  • gzip compression is used by default
Yes
N Wiki.setUserAgent can be used to set a user agent, but the library/sample gives no guidance on what it should contain
  • Platinum standard: generates a unique user-agent string given name/email address/repository location
Yellow check.svg When logged in, the username is automatically included in the user agent. However, there is nothing comparable for a logged-out user.
  • Efficient usage of API calls
Yes 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.
Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

N Python 2 only (2.5+)

Easy to debug[edit]

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

N

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

N

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

Yes Good example here:

def resultCombine(type, old, new):
"""Experimental-ish result-combiner thing
If the result isn't something from action=query,
this will just explode, but that shouldn't happen hopefully?
"""
Documentation links to the relevant section/subpage of the API documentation

Yellow check.svg README links to API. The Page.edit docstring links to the associated API module documentation page.

Easy to improve[edit]

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

Yellow check.svg Library maintainer is not very responsive (via GitHub) as of June 2014, but existing wikitools-related comment threads are largely courteous and helpful.

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)

N Still no response on https://github.com/alexz-enwp/wikitools/pull/11.

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

Yellow check.svg 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.

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

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

Yes Contributions from Mr.Z-man include: [1], [2], [3]

Library specifies the license it is released under

Yes GPL 3

Suggested TODOs[edit]

Code-related
  • Remove use of gettoken when using action=block[4]
  • For security and clarity, use requests instead of urllib2 to handle http requests[5]
  • Add compatibility with Python 3[6]
  • Add unit tests for the longest and most frequently modified functions[7]
Process-related
  • Improve documentation:[8]
    • Add directions to install with pip to the README
    • Expand the documentation to modules besides api, including links to the relevant API subpages
  • Add to the code samples:
    • an example of using APIRequest.query() to make edits
    • usage of Wiki.setUserAgent
  • Decide and communicate the intended level of responsiveness (either enabling a faster response to comments/pull requests/issues, or noting the maintenance/development status in the README).[9] If you are interested in wikitools being listed as a gold standard library, active maintenance and prompt responses are important--even if a given issue is too big to fix immediately or a patch too complex to review quickly.

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