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>.