Sessions

class restfly.session.APISession(**kwargs)[source]

The APISession class is the base model for APISessions for different products and applications. This is the model that the APIEndpoints will be grafted onto and supports some basic wrapping of standard HTTP methods on it’s own.

_box

Should responses be converted to Box objects automatically by default? If left unspecified, the default is False

Type:bool
_build

The build number/version of the integration.

Type:str
_backoff

The default backoff timer to use when retrying. The value is either a float or integer denoting the number of seconds to delay before the next retry attempt. The number will be multiplied by the number of retries attempted.

Type:float
_base_error_map

The error mapping detailing what HTTP response code should throw what kind of error. As this is the base mapping, overloading this would remove any pre-set error mappings.

Type:dict
_error_map

The error mapping detailing what HTTP response code should throw what kind of error. This error map will overload specific error mappings.

Type:dict
_lib_name

The name of the library.

Type:str
_lib_version

The version of the library.

Type:str
_product

The product name for the integration.

Type:str
_proxies

A dictionary detailing what proxy should be used for what transport protocol. This value will be passed to the session object after it has been either attached or created. For details on the structure of this dictionary, consult the proxies section of the Requests documentation.

Type:dict
_restricted_paths

A list of paths (not complete URIs) that if seen be the _request method will not pass the query params or the request body into the logging facility. This should generally be used for paths that are sensitive in nature (such as logins).

Type:list
_retries

The number of retries to make before failing a request. The default is 3.

Type:int
_session

Provide a pre-built session instead of creating a requests session at instantiation.

Type:requests.Session
_ssl_verify

Should SSL verification be performed? If not, then inform requests that we don’t want to use SSL verification and suppress the SSL certificate warnings.

Type:bool
_timeout

The number of seconds to wait with no data returned before declaring the request as stalled and timing-out the request.

Type:int
_url

The base URL path to use. This should generally be a string value denoting the first half of the URI. For example, https://httpbin.org or https://example.api.site/api/2. The _request method will join this string with the incoming path to construct the complete URI. Note that the two strings will be joined with a backslash /.

Type:str
_vendor

The vendor name for the integration.

Type:str
Parameters:
  • adaptor (Object, optional) – A Requests Session adaptor to bind to the session object.
  • backoff (float, optional) – If a 429 response is returned, how much do we want to backoff if the response didn’t send a Retry-After header.
  • build (str, optional) – The build number to put into the User-Agent string.
  • product (str, optional) – The product name to put into the User-Agent string.
  • proxies (dict, optional) – A dictionary detailing what proxy should be used for what transport protocol. This value will be passed to the session object after it has been either attached or created. For details on the structure of this dictionary, consult the proxies section of the Requests documentation.
  • retries (int, optional) – The number of retries to make before failing a request. The default is 3.
  • session (requests.Session, optional) – Provide a pre-built session instead of creating a requests session at instantiation.
  • ssl_verify (bool, optional) – If SSL Verification needs to be disabled (for example when using a self-signed certificate), then this parameter should be set to False to disable verification and mask the Certificate warnings.
  • url (str, optional) – The base URL that the paths will be appended onto.
  • vendor (str, optional) – The vendor name to put into the User-Agent string.
_authenticate(**kwargs)[source]

Authentication stub

_build_session(**kwargs)[source]

The session builder. User-agent strings, cookies, headers, etc that should persist for the session should be initiated here. The session builder is called as part of the APISession constructor.

Parameters:session (requests.Session, optional) – If a session object was passed to the constructor, then this would contain a session, otherwise a new one is created.
Returns:None

Examples

Extending the session builder to use basic auth:

>>> class ExampleAPI(APISession):
...     def _build_session(self, session=None):
...         super(APISession, self)._build_session(**kwargs)
...         self._session.auth = (self._username, self._password)
_deauthenticate(**kwargs)[source]

Deautnethication stub

_request(method, path, **kwargs)[source]

The requests session base request method. This is considered internal as it’s generally recommended to use the bespoke methods for each HTTP method.

Parameters:
  • method (str) – The HTTP method
  • path (str) – The URI path to append to the base path.
  • **kwargs (dict) – The keyword arguments to pass to the requests lib.
  • retry_on (list, optional) – A list of numeric response status codes to attempt retry on. This behavior is additive to the retry parameter in the exceptions.
  • box (bool, optional) – A request-specific override as to if the response should attempted to be converted into a Box object.
  • box_attrs (dict, optional) – A request-specific override with a list of key-values to pass to the box constructor.
  • use_base (bool, optional) – Should the base path be appended to the URL? if left unspecified the default is True.
Returns:

requests.Response or box.Box

If the request was informed to attempt to “boxify” the response and the response was JSON data, then a Box will be returned. In all other scenarios, a Response object will be returned.

Examples

>>> api = APISession()
>>> resp = api._request('GET', '/')
_resp_error_check(response, **kwargs)[source]

If there is a need for additional error checking (for example within the JSON response) then overload this method with the necessary checking.

Parameters:
  • response (request.Response) – The response object.
  • **kwargs (dict) – The request keyword arguments.
Returns:

The response object.

Return type:

requests.Response

_retry_request(response, retries, **kwargs)[source]

A method to be overloaded to return any modifications to the request upon retries. By default just passes back what was send in the same order.

Parameters:
  • response (request.Response) – The response object
  • retries (int) – The number of retries that have been performed.
  • **kwargs (dict) – The keyword arguments that were passed to the request.
Returns:

The keyword arguments

Return type:

dict

delete(path, **kwargs)[source]

Initiates an HTTP DELETE request using the specified path. Refer to the requests.request for more detailed information on what keyword arguments can be passed:

Parameters:
Returns:

requests.Response or box.Box

If the request was informed to attempt to “boxify” the response and the response was JSON data, then a Box will be returned. In all other scenarios, a Response object will be returned.

Examples

>>> api = APISession()
>>> resp = api.delete('/')
get(path, **kwargs)[source]

Initiates an HTTP GET request using the specified path. Refer to requests.request for more detailed information on what keyword arguments can be passed:

Parameters:
Returns:

requests.Response or box.Box

If the request was informed to attempt to “boxify” the response and the response was JSON data, then a Box will be returned. In all other scenarios, a Response object will be returned.

Examples

>>> api = APISession()
>>> resp = api.get('/')
head(path, **kwargs)[source]

Initiates an HTTP HEAD request using the specified path. Refer to the requests.request for more detailed information on what keyword arguments can be passed:

Parameters:
Returns:

requests.Response or box.Box

If the request was informed to attempt to “boxify” the response and the response was JSON data, then a Box will be returned. In all other scenarios, a Response object will be returned.

Examples

>>> api = APISession()
>>> resp = api.head('/')
patch(path, **kwargs)[source]

Initiates an HTTP PATCH request using the specified path. Refer to the requests.request for more detailed information on what keyword arguments can be passed:

Parameters:
Returns:

requests.Response or box.Box

If the request was informed to attempt to “boxify” the response and the response was JSON data, then a Box will be returned. In all other scenarios, a Response object will be returned.

Examples

>>> api = APISession()
>>> resp = api.patch('/')
post(path, **kwargs)[source]

Initiates an HTTP POST request using the specified path. Refer to the requests.request for more detailed information on what keyword arguments can be passed:

Parameters:
Returns:

requests.Response or box.Box

If the request was informed to attempt to “boxify” the response and the response was JSON data, then a Box will be returned. In all other scenarios, a Response object will be returned.

Examples

>>> api = APISession()
>>> resp = api.post('/')
put(path, **kwargs)[source]

Initiates an HTTP PUT request using the specified path. Refer to the requests.request for more detailed information on what keyword arguments can be passed:

Parameters:
Returns:

requests.Response or box.Box

If the request was informed to attempt to “boxify” the response and the response was JSON data, then a Box will be returned. In all other scenarios, a Response object will be returned.

Examples

>>> api = APISession()
>>> resp = api.put('/')