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: Host to which to connect to. Must include http:// or https:// and no trailing “/”.
user_agent: 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: The formatversion to supply to the API for all requests.
api_path: The path to “api.php” on the server – must begin with “/”.
timeout: 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: (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: Which HTTP method to use for the request? (Usually “POST” or “GET”)
params: 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: A dictionary of (filename : str, data : bytes) pairs to send with the initial request.
auth: Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
query_continue: 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: Which HTTP method to use for the request? (Usually “POST” or “GET”)
params: 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: A ‘continue’ field from a past request. This field represents the point from which a query should be continued.
files: A dictionary of (filename : str, data : bytes) pairs to send with the request.
auth: Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
continuation: 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)

Session¶

Related Topics

This Page