Session

Sessions encapsulate a a set of interactions with a MediaWiki API. mwapi.Session provides both a set of convenience functions (e.g. get() and post()) that automatically convert parameters and handle error code responses and raise them as exceptions. You can also maintain a logged-in connection to the API by using login() to authenticate and using the same session call get() and post() afterwards.

class mwapi.Session(host, user_agent=None, formatversion=None, api_path=None, timeout=None, session=None, **session_params)[source]

Constructs a new API session.

Parameters:
host
: str

Host to which to connect to. Must include http:// or https:// and no trailing “/”.

user_agent
: str

The User-Agent header to include with all requests. Use this field to identify your script/bot/application to system admins of the MediaWiki API you are using.

formatversion
: int

The formatversion to supply to the API for all requests.

api_path
: str

The path to “api.php” on the server – must begin with “/”.

timeout
: float

How long to wait for the server to send data before giving up and raising an error (requests.exceptions.Timeout, requests.exceptions.ReadTimeout or requests.exceptions.ConnectTimeout). The default behavior is to hang indefinitely.

session
: requests.Session

(optional) a requests session object to use

continuation(method, params=None, query_continue=None, auth=None, files=None)[source]

Makes a request and, if the response calls for a continuation, performs that continuation.

Parameters:
method
: str

Which HTTP method to use for the request? (Usually “POST” or “GET”)

params
: dict

A set of parameters to send with the request. These parameters will be included in the POST body for post requests or a query string otherwise.

files
: dict

A dictionary of (filename : str, data : bytes) pairs to send with the initial request.

auth
: mixed

Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.

query_continue
: dict

A ‘continue’ field from a past request. This field represents the point from which a query should be continued.

Returns:

A generator of response JSON documents.

continue_login(login_token, **params)[source]

Continues a login that requires an additional step. This is common for when login requires completing a captcha or supplying a two-factor authentication token.

Parameters:
login_token
: str

A login token generated by the MediaWiki API (and used in a previous call to login())

params
: mixed

A set of parameters to include with the request. This depends on what “requests” for additional information were made by the MediaWiki API.

get(query_continue=None, auth=None, continuation=False, **params)[source]

Makes an API request with the GET method

Parameters:
query_continue
: dict

Optionally, the value of a query continuation ‘continue’ field.

auth
: mixed

Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.

continuation
: bool

If true, a continuation will be attempted and a generator of JSON response documents will be returned.

params :

Keyword parameters to be sent in the query string.

Returns:

A response JSON documents (or a generator of documents if continuation == True)

Raises:

mwapi.errors.APIError : if the API responds with an error

login(username, password, login_token=None)[source]

Authenticate with the given credentials. If authentication is successful, all further requests sent will be signed the authenticated user.

Note that passwords are sent as plaintext. This is a limitation of the Mediawiki API. Use a https host if you want your password to be secure

Parameters:
username
: str

The username of the user to be authenticated

password
: str

The password of the user to be authenticated

Raises:

mwapi.errors.LoginError : if authentication fails mwapi.errors.ClientInteractionRequest : if authentication requires a continue_login() call mwapi.errors.APIError : if the API responds with an error

logout()[source]

Logs out of the session with MediaWiki

Raises:mwapi.errors.APIError : if the API responds with an error
post(query_continue=None, upload_file=None, auth=None, continuation=False, **params)[source]

Makes an API request with the POST method

Parameters:
query_continue
: dict

Optionally, the value of a query continuation ‘continue’ field.

upload_file
: bytes

The bytes of a file to upload.

auth
: mixed

Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.

continuation
: bool

If true, a continuation will be attempted and a generator of JSON response documents will be returned.

params :

Keyword parameters to be sent in the POST message body.

Returns:

A response JSON documents (or a generator of documents if continuation == True)

Raises:

mwapi.errors.APIError : if the API responds with an error

request(method, params=None, query_continue=None, files=None, auth=None, continuation=False)[source]

Sends an HTTP request to the API.

Parameters:
method
: str

Which HTTP method to use for the request? (Usually “POST” or “GET”)

params
: dict

A set of parameters to send with the request. These parameters will be included in the POST body for post requests or a query string otherwise.

query_continue
: dict

A ‘continue’ field from a past request. This field represents the point from which a query should be continued.

files
: dict

A dictionary of (filename : str, data : bytes) pairs to send with the request.

auth
: mixed

Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.

continuation
: bool

If true, a continuation will be attempted and a generator of JSON response documents will be returned.

Returns:

A response JSON documents (or a generator of documents if continuation == True)