MediaWiki API for Python 3
Project description
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 theapi.php
, usually at$SITEROOT/w/api.php
.session
: arequests.Session()
, either supplied or create a new one by the library.
API.login(username,botpassword)
Login via botpassword.
username
: the username supplied by Special:Botpasswordsbotpassword
: 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 rawAPI.get
andAPI.post
requests.
API.edit(page,content,[token,timestamp])
Edit a page, by its ID or title.
page
: either the page ID or the page titlecontent
: either a dictionary or a string, if it is a string, replace the entire page withcontent
.token
: (Optional) thecsrf
token, can be obtained via the first returned value ofAPI.csrf()
, or generated by the library itself.timestamp
: (Optional) a valid timestamp for detecting edit confident, can be obtained via the second returned value ofAPI.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 objectfilename
: the target file name, without theFile:
prefixcomment
: (Optional) the upload summary. For new files, also set the wikitext content to thistoken
: (Optional) thecsrf
token, can be obtained via the first returned value ofAPI.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 titleexpiry
: (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 falsetoken
: (Optional) thewatch
token, can be obtained viaAPI.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) thecsrf
token, can be obtained via the first returned value ofAPI.csrf()
, or generated by the library itself. Note that thepartial
parameter is hidden, will be set toTrue
oncepagerestrictions
or/andnamespacerestrictions
is given.
API.unblock(user,[reason,token],blockid)
Unblock a user.
user
: Either a user ID (int
), IP (range), or username. Cannot be used withblockid
.reason
: (Optional) Unblock reason, default to empty.token
: (Optional) thecsrf
token, can be obtained via the first returned value ofAPI.csrf()
, or generated by the library itself.blockid
: Block ID, cannot be used withuser
.
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 parametersfiles
: (Optional, POST only) the file to upload, foraction = 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 datacodes
: List of error codesmessage
: 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.