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.

_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
_error_map

The error mapping detailing what HTTP response code should throw what kind of error. Specifically meant to be overloadable based on need.

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
_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
_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)
_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.
Returns:

The response object from the requests lib.

Return type:

requests.Response

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:
  • path (str) – The path to be appended onto the base URL for the request.
  • **kwargs (dict) – Keyword arguments to be passed to the Requests library.
Returns:

requests.Response

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:
  • path (str) – The path to be appended onto the base URL for the request.
  • **kwargs (dict) – Keyword arguments to be passed to the Requests library.
Returns:

requests.Response

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:
  • path (str) – The path to be appended onto the base URL for the request.
  • **kwargs (dict) – Keyword arguments to be passed to the Requests library.
Returns:

requests.Response

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:
  • path (str) – The path to be appended onto the base URL for the request.
  • **kwargs (dict) – Keyword arguments to be passed to the Requests library.
Returns:

requests.Response

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:
  • path (str) – The path to be appented onto the base URL for the request.
  • **kwargs (dict) – Keyword arguments to be passed to the Requests library.
Returns:

requests.Response

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:
  • path (str) – The path to be appended onto the base URL for the request.
  • **kwargs (dict) – Keyword arguments to be passed to the Requests library.
Returns:

requests.Response

Examples

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