Installation

pip install pymw

Usage

To avoid directly providing username and password for login calls create a .pymw.json file in your home directory with the following format:

{
    "https://test.wikipedia.org/w/api.php": {
        "<Username@Special:BotPasswords>": {
            "BotPassword": "<BotPassword>"
        },
        "<Username2>": {
            "BotPassword": "<BotPassword>",
            "limit": 500
        }
    },
    "https://*.wikipedia.org/w/api.php": {
        "<Username>": {
            "BotPassword": "<BotPassword>"
        }
    }
}

As you can see, glob patterns are supported.

Notable features

• Has a post_and_continue method that can handle continuations.

• Parameter values can be str or any Python iterable. Iterable values that are not an str instance will be converted to a pipe-joined str before being sent.

• The post_and_continue method automatically breaks a value that has too many items in it into several API calls according the API limit for the current user and yields the results. (Currently this feature works only if there is just one violating parameter. The algorithm might be improved in the future to handle more complex situations.)

• prop method handles batchcomplete signals for prop queries and yields the results as soon as a batch is complete.

• Configurable maxlag. Waits as the API recommends and then retries.

• Automatically tries to login before performing actions that are known to require login.

• Automatically tries to login if an API call returns login-required error (requires username and password to be set in ~/.pymw.json).

• Some convenient methods for accessing common API calls, e.g. for login and upload.

• Lightweight. pymw is a thin wrapper. Method signatures are very similar to the parameters in an actual API URL. You can consult MediaWiki’s documentation if in doubt about what a parameter does.

• The post_and_continue method can handle most toomanyvalues errors by automatically splitting the violating parameter into several API calls. (not a feature to rely on in production, but nice to have during a console session for example.)

• Supports setting a custom User-Agent header for each API instance.