mwng 0.0.10
MediaWiki API for Python 3
Requires Python: >=3.6

`mwng` (MediaWiki API NG) is a MediaWiki API library for Python 3.

## MediaWiki API
We will use `mw` to call `mwng` in this document. `import mwng as mw`!
### `API = mw.API(api_php,[session])`
Create an `mw.API` instance.
* `api_php`: URL to the `api.php`, usually at `$SITEROOT/w/api.php`.
* `session`: a `requests.Session()`, either supplied or create a new one by the library.
### `API.login(username,botpassword)`
Login via botpassword.
* `username`: the username supplied by Special:Botpasswords
* `botpassword`: the passowrd supplied by Special:Botpasswords
As of MediaWiki 1.27, using the main account for login is not supported. Obtain credentials via Special:BotPasswords or use clientlogin method. We have no plan to introduce clientlogin, so you have to use a botpassword, or do it yourself via raw `API.get` and `API.post` requests.
### `API.edit(page,content,[token,timestamp])`
Edit a page, by its ID or title.
* `page`: either the page ID or the page title
* `content`: either a dictionary or a string, if it is a string, replace the entire page with `content`.
* `token`: (Optional) the `csrf` token, can be obtained via the first returned value of `API.csrf()`, or generated by the library itself.
* `timestamp`: (Optional) a valid timestamp for detecting edit confident, can be obtained via the second returned value of `API.csrf()`. Not detecting edit confident (`"now"`) by default.
### `API.upload(file,filename,[comment,token])`
Upload a file
* `file`: the file to upload, can be a URL, local file path or a binary file object
* `filename`: the target file name, without the `File:` prefix
* `comment`: (Optional) the upload summary. For new files, also set the wikitext content to this
* `token`: (Optional) the `csrf` token, can be obtained via the first returned value of `API.csrf()`, or generated by the library itself.
### `API.watch(pages,[expiry,unwatch,token])
Watch or unwatch a page
* `pages`: Array of page titles or string of a page title
* `expiry`: (Optional) When the watch expires, can be relative (`"1 month"`), absolutive (`"2014-09-18T12:34:56Z"`) or no expiry (`"infinite"`, `"indefinite"`, `"infinity"` or `"never"`, this is the default option)
* `unwatch`: (Optional) if true, unwatch instead of watch the pages, default to false
* `token`: (Optional) the `watch` token, can be obtained via `API.token("watch")`, or generated by the library itself.
### `API.block(user,[expiry,reason,token,anononly,nocreate,autoblock,noemail,hidename,allowusertalk,reblock,watchuser,watchlistexpiry,pagerestrictions, namespacerestrictions])`
Block a user. All parameters except the follow have the same meaning and usage as what MediaWiki API said (action block)
* `user`: Either a user ID (`int`), IP (range), or username.
* `token`: (Optional) the `csrf` token, can be obtained via the first returned value of `API.csrf()`, or generated by the library itself.
Note that the `partial` parameter is hidden, will be set to `True` once `pagerestrictions` or/and `namespacerestrictions` is given.
### `API.unblock(user,[reason,token],blockid)`
Unblock a user.
* `user`: Either a user ID (`int`), IP (range), or username. Cannot be used with `blockid`.
* `reason`: (Optional) Unblock reason, default to empty.
* `token`: (Optional) the `csrf` token, can be obtained via the first returned value of `API.csrf()`, or generated by the library itself.
* `blockid`: Block ID, cannot be used with `user`.
### `API.token(type)`
Get a action token.
* `type`: The token type, can be one of these: `createaccount`, `csrf`, `deleteglobalaccount`, `login`, `patrol`, `rollback`, `setglobalaccountstatus`, `userrights`, `watch`
#### `API.logintoken()`
Get a login token (type: `login`).
#### `API.csrf()`
Get a CSRF token (type: `csrf`).
### `API.get(body)` and `API.post(body,[files])`
Do RAW API requests, by GET or POST.
* `body`: the request parameters
* `files`: (Optional, POST only) the file to upload, for `action = upload`
## Error handling
### `mw.MWAPIError`
The father of all MediaWiki Error Class. The following data are given:
* `dump`: the RAW JSON data, in case you have to do more things to the data
* `codes`: List of error codes
* `message`: The error description text (if there are only one), or human-readable list of error codes (if there are more than one)
### `mw.MWLoginError`
Error during login. There are no error codes (an empty list), only `dump` and `message` are given.