Client Module

Facilitates submission of multiple requests for different endpoints to a single server.

author

Doug Skrypa

class requests_client.client.RequestsClient(host_or_url, port=None, *, scheme=None, path_prefix=None, raise_errors=True, exc=None, headers=None, verify=None, user_agent_fmt='{script}/{script_ver} ({url}; {email}; {os_name} {os_rel}; {arch}) {py_impl}/{py_ver} Requests/{requests_ver} RequestsClient/{rc_ver}', log_lvl=10, log_params=True, rate_limit=0, session_fn=<class 'requests.sessions.Session'>, local_sessions=False, nopath=False, **kwargs)[source]

Bases: object

Facilitates submission of multiple requests for different endpoints to a single server.

Parameters

  • host_or_url (str) – A hostname or host:port, or a URL from which the scheme, host, port, and path_prefix should be derived.

  • port (str|int) – A port

  • scheme (str) – The URI scheme to use (http, https, etc.) (default: http)

  • path_prefix (str) – A URI path prefix to include on all URLs. If provided, it may be overridden on a per-request basis. A / will be added to the beginning and end if it was not included.

  • raise_errors (bool) – Whether Response.raise_for_status should be used to raise an exception if a response has a 4xx/5xx status code. This may be overridden on a per-request basis.

  • exc (class) – A custom exception class to raise when an error is encountered. Its init method must accept two positional arguments: cause (either a Response or a RequestException / a subclass thereof) and url (string). When a response has a 4xx/5xx status code and raise_errors is True, then the exception will be initialized with the response object. For non-code-based exceptions, the exception will be initialized with the original exception.

  • headers (dict) – Headers that should be included in the session.

  • verify (bool|str) – Allows the verify option to be specified at a session level. See the documentation for requests.request() for more information.

  • user_agent_fmt (str|None) – A format string to be used to generate the User-Agent header. If a custom value already exists in the provided headers, then this format is not used.

  • log_lvl (int) – Log level to use when logging messages about the method/url when requests are made

  • log_params (bool) – Include query params in logged messages when requests are made

  • rate_limit (float) – Interval in seconds to wait between requests (default: no rate limiting). If specified, then a lock is used to prevent concurrent requests.

  • session_fn (callable) – A callable that returns a Session object. Defaults to the normal constructor for Session. Allows users to perform other initialization tasks for the session, such as adding an auth handler.

  • local_sessions (bool) – By default, sessions are shared between threads. If this is specified, then sessions are stored locally in each thread.

  • nopath (bool) – When initialized with a URL, ignore the path portion

  • kwargs – Keyword arguments to pass to the given session_fn whenever a new session is initialized. The default constructor does not accept any arguments, so these should only be provided if session_fn is also specified.

_init_session()[source]
_log_req(method, url, path, relative, params, log_params)[source]
_url_fmt[source]
close()[source]

Close the session, if it exists

delete(path, *, relative=True, raise_errors=None, log=True, log_params=None, **kwargs)
get(path, *, relative=True, raise_errors=None, log=True, log_params=None, **kwargs)
head(path, *, relative=True, raise_errors=None, log=True, log_params=None, **kwargs)
host
options(path, *, relative=True, raise_errors=None, log=True, log_params=None, **kwargs)
patch(path, *, relative=True, raise_errors=None, log=True, log_params=None, **kwargs)
path_prefix
port
post(path, *, relative=True, raise_errors=None, log=True, log_params=None, **kwargs)
put(path, *, relative=True, raise_errors=None, log=True, log_params=None, **kwargs)
request(method, path, *, relative=True, raise_errors=None, log=True, log_params=None, **kwargs)[source]

Submit a request to the URL based on the given path, using the given HTTP method.

Parameters

  • method (str) – HTTP method to use (GET/PUT/POST/etc.)

  • path (str) – The URL path to retrieve

  • relative (bool) – Whether the stored path_prefix should be used

  • raise_errors (bool) – Whether Response.raise_for_status should be used to raise an exception if the response has a 4xx/5xx status code. Overrides the setting stored when initializing RequestsClient, if provided. Setting this to False does not prevent exceptions caused by anything other than 4xx/5xx errors from being raised.

  • log (bool) – Whether a message should be logged with the method and url. The log level is set when initializing RequestsClient.

  • log_params (bool) – Whether query params should be logged, if log=True. Overrides the setting stored when initializing RequestsClient, if provided.

  • kwargs – Keyword arguments to pass to Session.request

Returns

The Response to the request

Raises

RequestException (or a subclass thereof) if the request failed. If the exception is caused by an HTTP error code, then a HTTPError will be raised, and the code can be accessed via the exception’s .response.status_code attribute. If the exception is due to a request or connection timeout, then a Timeout (or further subclass thereof) will be raised, and the exception will not have a response property.

scheme
property session[source]

Initializes a new session using the provided session_fn, or returns the already created one if it already exists.

Returns

The Session that will be used for requests

url_for(path, params=None, relative=True)[source]
Parameters

  • path (str) – The URL path to retrieve

  • params (dict) – Request query parameters

  • relative (bool) – Whether the stored path_prefix should be used

Return str

The full URL for the given path