request_session package¶

request_session¶

Main RequestSession module.

class request_session.request_session.RequestSession(host=None, headers: dict = None, auth: tuple = None, timeout: Union[float, Tuple[float, float], request_session.request_session.Timeout] = 10, verify: Union[bool, str] = True, max_retries: int = 0, verbose_logging: bool = False, request_category: str = None, raise_for_status: bool = True, user_agent: str = None, user_agent_components: request_session.utils.UserAgentComponents = None, session_instances: List[requests.sessions.Session] = [], ddtrace: request_session.protocols.Ddtrace = None, datadog_service_name: str = None, statsd: request_session.protocols.Statsd = None, sentry_client: request_session.protocols.SentryClient = None, logger: Callable = None, log_prefix: str = 'requestsession', allowed_log_levels: Tuple[str] = ('debug', 'info', 'warning', 'error', 'critical', 'exception', 'log'))¶

Bases: object

Helper class for HTTP requests with common settings.

Parameters

host (str) – Host name
headers (dict) – (optional) Dictionary of HTTP headers to be used.
auth (tuple) – (optional) Authorization tuple to enable Basic/Digest/Custom HTTP Auth.
timeout ([float, Timeout, Tuple[float, float]]) – (optional) How many seconds to wait until retrying. Defaults to 10.
verify ([bool, str]) – (optional) Either a boolean, in which case it controls whether to verify the servers TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True.
max_retries (int) – (optional) Number of retries if the execution fails with server error. Defaults to 0.
verbose_logging (bool) – (optional) If true, add request’s parameters to event being logged. Defaults to False.
request_category (str) – (optional) Name of the event. request_category has to passed to the object or as an argument when calling some HTTP method.
raise_for_status (bool) – (optional) Raise an exception in case of an error. Defaults to False.
user_agent (str) – (optional) User-Agent to be set in headers.
session_instances (list[requests.Session]) – (optional) A list of requests.Session to be used to make the HTTP requests.
ddtrace (Ddtrace) – (optional) DataDog function to be used to trace, track and send metrics for individual HTTP requests. If set, datadog_service_name must be set too. Defaults to None.
datadog_service_name (str) – (optional) Name of the service in DataDog.
statsd (Statsd) – (optional) Datadog module to log metrics.
sentry_client (SentryClient) – (optional) Sentry module to log exceptions.
logger (Callable) – (optional) Logger to be used when logging to stdout and stderr. If none is set, builtin_logger is used. Defaults to None.
log_prefix (str) – (optional) Prefix to be used when logging to stdout and stderr. Defaults to requestsession.
allowed_log_levels (Tuple[str]) – (optional) Log levels that are supported by the logger used. Defaults to ("debug", "info", "warning", "error", "critical", "exception", "log").

close_all_sessions()¶: Close and remove all sessions in self.session_instances.

delete(path, **kwargs)¶

Delete request against a service.

Parameters

path (str) – URL path, will be combined with self.host to build whole request url.
**kwargs – Optional arguments that request takes - check request_session and requests packages documentation for further reference.

Return requests.Response

HTTP Response Object

Raises

requests.RequestException – server error on operation (if raise_for_status is True).
APIError – client error on operation (if raise_for_status is True)

get(path, **kwargs)¶

Get request against a service.

Parameters

path (str) – URL path, will be combined with self.host to build whole request URL.
**kwargs – Optional arguments that request takes - check request_session and requests packages documentation for further reference.

Return requests.Response

HTTP Response Object

Raises

requests.RequestException – server error on operation (if raise_for_status is True).
APIError – client error on operation (if raise_for_status is True)

static get_response_text(response)¶

Return response text if exists.

Parameters: response (request.Response) – HTTP Response Object
Return str: response text

static is_server_error(error, http_code)¶

Exception type and response code match server error.

Parameters

error (requests.RequestException) – exception
http_code (int) – (optional) response HTTP status code

Return bool

whether error is server error

log(level, event, **kwargs)¶

Proxy to log with provided logger.

Builtin logging library is used otherwise. :param level: string describing log level :param event: event (<request_category> or <request_category>.<action>) :param **kwargs: kw arguments to be logged

metric_increment(metric, request_category, tags, attempt=None)¶

Metric request increment.

Parameters

metric (str) – Name of the metric to be incremented.
request_category (str) – request category
tags (List[str]) – Tags to increment metric with.
attempt (int) – Number of attempt of the request.

patch(path, **kwargs)¶

Patch request against a service.

Parameters

path (str) – URL path, will be combined with self.host to build whole request url.
**kwargs – Optional arguments that request takes - check request_session and requests packages documentation for further reference.

Return requests.Response

HTTP Response Object

Raises

requests.RequestException – server error on operation (if raise_for_status is True).
APIError – client error on operation (if raise_for_status is True)

post(path, **kwargs)¶

Post request against a service.

Parameters

path (str) – url path, will be combined with self.host to build whole request url.
**kwargs – Optional arguments that request takes - check request_session and requests packages documentation for further reference.

Return requests.Response

HTTP Response Object

Raises

requests.RequestException – Server error on operation (if raise_for_status is True).
APIError – Client error on operation (if raise_for_status is True).

prepare_new_session()¶: Prepare new configured session.

put(path, **kwargs)¶

Put request against a service.

Parameters

path (str) – URL path, will be combined with self.host to build whole request url.
**kwargs – Optional arguments that request takes - check request_session and requests packages documentation for further reference.

Return requests.Response

HTTP Response Object

Raises

requests.RequestException – server error on operation (if raise_for_status is True).
APIError – client error on operation (if raise_for_status is True)

remove_session()¶: Close session and remove it from list of session instances.

set_user_agent()¶: Set proper user-agent string to header according to RFC22.

sleep(seconds, request_category, tags)¶

Call sleep function and send metrics to datadog.

Parameters

seconds (float) – float or int number of seconds to sleep
request_category (str) – request category
tags (List[str]) – tags for datadog

class request_session.request_session.Timeout(connection_timeout, read_timeout)¶

Bases: tuple

property connection_timeout¶: Alias for field number 0

property read_timeout¶: Alias for field number 1

Additional `requests` parameters¶

Since RequestSession uses requests.Session, you can pass any parameters that requests.Session takes to any of the GET, POST, PUT and DELETE methods as a keyword argument:

url: (optional) To override url param.
params: (optional) Dictionary or bytes to be sent in the query string for the Request.
data: (optional) Dictionary or list of tuples [(key, value)] (which is form-encoded by requests), bytes, or file-like object to send in the body of the Request.
json: (optional) A JSON serializable Python object to send in the body of the Request.
headers: (optional) Dictionary of HTTP Headers to send with the Request.
cookies: (optional) Dict or CookieJar object to send with the Request.
files: (optional) Dictionary of 'name': file-like-objects
auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
timeout: (optional) How many seconds to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) <timeouts> tuple.
allow_redirects: (optional) Boolean. Enable/disable GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD redirection. Defaults to True.
proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
verify: (optional) Can be either:
- A boolean, in which case it controls whether we verify the TLS certificate of the server.
- A string, in which case it must be a path to a CA bundle to use. Defaults to True.
stream: (optional) If it is False, the response content is immediately downloaded.
cert: (optional) If it is a String, path to ssl client cert file (.pem). If it is a Tuple, (‘cert’, ‘key’) pair.

protocols¶

Simple protocols to duck type dependency injections.

class request_session.protocols.Config¶

Bases: object

Statsd Config protocol.

get_from(obj)¶

Retrieves the configuration for the given object.

Any object that has an attached Pin must have a configuration and if a wrong object is given, an empty dict is returned for safety reasons.

class request_session.protocols.Ddtrace¶

Bases: object

Ddtrace protocol.

config = None¶

tracer = None¶

class request_session.protocols.SentryClient¶

Bases: object

SentryClient protocol.

captureException(exc_info=None, **kwargs)¶

Creates an event from an exception.

>>> try:
>>>     exc_info = sys.exc_info()
>>>     client.captureException(exc_info)
>>> finally:
>>>     del exc_info

If exc_info is not provided, or is set to True, then this method will perform the exc_info = sys.exc_info() and the requisite clean-up for you.

kwargs are passed through to .capture.

class request_session.protocols.Span(tracer: request_session.protocols.Tracer = None, name: str = None, service: str = None, resource: str = None, span_type: str = None, trace_id: int = None, parent_id: int = None, span_id: int = None, start: int = None, context: object = None)¶

Bases: object

Span protocol.

set_metas(kvs)¶: Set metas.

class request_session.protocols.Statsd¶

Bases: object

Statsd protocol.

config¶: alias of Config

increment(metric, value=1, tags=None, sample_rate=1)¶

Increment a counter, optionally setting a value, tags and a sample rate.

>>> statsd.increment('page.views')
>>> statsd.increment('files.transferred', 124)

namespace = None¶

timed(metric=None, tags=None, sample_rate=1, use_ms=None)¶

A decorator or context manager that will measure the distribution of a function’s/context’s run time.

Optionally specify a list of tags or a sample rate. If the metric is not defined as a decorator, the module name and function name will be used. The metric is required as a context manager.

@statsd.timed('user.query.time', sample_rate=0.5)
def get_user(user_id):
    # Do what you need to ...
    pass

# Is equivalent to ...
with statsd.timed('user.query.time', sample_rate=0.5):
    # Do what you need to ...
    pass

# Is equivalent to ...
start = time.time()
try:
    get_user(user_id)
finally:
    statsd.timing('user.query.time', time.time() - start)

tracer¶: alias of Tracer

class request_session.protocols.TimedContextManagerDecorator¶

Bases: object

TimedContextManagerDecorator protocol.

elapsed = _CountingAttr(counter=28, _default=None, repr=True, cmp=True, hash=None, init=True, metadata={})¶

metric = _CountingAttr(counter=24, _default=None, repr=True, cmp=True, hash=None, init=True, metadata={})¶

sample_rate = _CountingAttr(counter=26, _default=None, repr=True, cmp=True, hash=None, init=True, metadata={})¶

statsd = _CountingAttr(counter=23, _default=None, repr=True, cmp=True, hash=None, init=True, metadata={})¶

tags = _CountingAttr(counter=25, _default=None, repr=True, cmp=True, hash=None, init=True, metadata={})¶

use_ms = _CountingAttr(counter=27, _default=None, repr=True, cmp=True, hash=None, init=True, metadata={})¶

class request_session.protocols.Tracer¶

Bases: object

Statsd Tracer protocol.

trace(name, service=None, resource=None, span_type=None)¶

Return a span that will trace an operation called name.

The context that created the span as well as the span parenting, are automatically handled by the tracing function.

Parameters

name (str) – the name of the operation being traced
service (str) – the name of the service being traced. If not set, it will inherit the service from its parent.
resource (str) – an optional name of the resource being tracked.
span_type (str) – an optional operation type.

You must call finish on all spans, either directly or with a context manager:

>>> span = tracer.trace('web.request')
    try:
        # do something
    finally:
        span.finish()

>>> with tracer.trace('web.request') as span:
        # do something

Trace will store the current active span and subsequent child traces will become its children:

parent = tracer.trace('parent')     # has no parent span
child  = tracer.trace('child')      # is a child of a parent
child.finish()
parent.finish()

parent2 = tracer.trace('parent2')   # has no parent span
parent2.finish()

utilities¶

Utilites used in RequestSession.

exception request_session.utils.APIError(*args, **kwargs)¶

Bases: Exception

Base error for API mishandling.

default_message = 'API error occured.'¶

exception request_session.utils.InvalidUserAgentString¶

Bases: Exception

Provided user agent string is not in correct format.

class request_session.utils.UserAgentComponents(service_name: str, version: str, organization: str, environment: str, sys_info: str = None)¶

Bases: object

Helper class to wrap user-agent items into one object.

request_session.utils.dict_to_string(dictionary)¶: Convert dictionary to key=value pairs separated by a space.

request_session.utils.reraise_as_third_party()¶: Add tags to raised exception for Sentry.

request_session.utils.split_tags_and_update(dictionary, tags)¶

Update dict with tags from string.

Individual tags must be in format of <key>:<value>.

request_session package¶

request_session¶

Additional requests parameters¶

protocols¶

utilities¶

Additional `requests` parameters¶