ws.client.connection module

The ws.client.connection module provides a low-level interface for connections to the wiki. The requests.Session class from the requests library is used to manage the cookies, authentication and making requests.

class ws.client.connection.Connection(api_url, index_url, session, timeout=60)

Bases: object

The base object handling connection between a wiki and scripts.

Parameters

  • api_url (str) – URL path to the wiki’s api.php entry point

  • index_url (str) – URL path to the wiki’s index.php entry point

  • session (requests.Session) – session created by make_session()

  • timeout (int) – connection timeout in seconds

static make_session(user_agent='wiki-scripts/1.2 (https://github.com/lahwaacz/wiki-scripts)', max_retries=0, cookie_file=None, cookiejar=None, http_user=None, http_password=None)

Creates a requests.Session object for the connection.

It is possible to save the session data by specifying either cookiejar or cookie_file arguments. If cookiejar is present, cookie_file is ignored.

Parameters

  • user_agent (str) – string sent as User-Agent header to the web server

  • max_retries (int) – Maximum number of retries for each connection. Applies only to failed DNS lookups, socket connections and connection timeouts, never to requests where data has made it to the server.

  • cookie_file (str) – path to a cookielib.FileCookieJar file

  • cookiejar – an existing cookielib.CookieJar object

Returns

requests.Session object

static set_argparser(argparser)

Add arguments for constructing a Connection object to an instance of argparse.ArgumentParser.

See also the ws.config module.

Parameters

argparser – an instance of argparse.ArgumentParser

classmethod from_argparser(args)

Construct a Connection object from arguments parsed by argparse.ArgumentParser.

Parameters

args – an instance of argparse.Namespace.

Returns

an instance of Connection

request(method, url, **kwargs)

Simple HTTP request handler. It is basically a wrapper around requests.request() using the established session including cookies, so it should be used only for connections with url leading to the same site.

The parameters are the same as for requests.request(), see Requests documentation for details.

There is no translation of exceptions, the requests exceptions (notably requests.exceptions.ConnectionError, requests.exceptions.Timeout and requests.exceptions.HTTPError) should be catched by the caller.

call_api(params=None, *, expand_result=True, check_warnings=True, **kwargs)

Convenient method to call the api.php entry point.

Checks the action parameter (default is "help" as in the API), selects correct HTTP request method, handles API errors and warnings.

Parameters of the call can be passed either as a dict to params, or as keyword arguments. params and kwargs cannot be specified at the same time.

Parameters

  • params – dictionary of API parameters

  • expand_result – if True, return only part of the response relevant to the given action, otherwise full response is returned

  • check_warnings – if True, the response is investigated and all API warnings are output into the logger

  • kwargs – API parameters passed as keyword arguments

Returns

a dictionary containing (part of) the API response

call_index(method='GET', **kwargs)

Convenient method to call the index.php entry point.

Currently it only calls self.request() with specific URL, default method "GET" and other kwargs (at least "params" or "data" should be specified).

See MediaWiki for possible parameters to index.php.

get_hostname()
Returns

the hostname part of self.api_url

exception ws.client.connection.APIWrongAction(action, available)

Bases: Exception

Raised when a wrong API action is specified.

This is a programming error, it should be fixed in the client code.

exception ws.client.connection.APIJsonError

Bases: Exception

Raised when json-decoding of server response failed.

exception ws.client.connection.APIError(params, server_response)

Bases: Exception

Raised when API response contains error attribute.