Utils

Authoriser specific utilities which can be used to build implementations of authoriser flows.

Classes:

`AuthRequest`(**kwargs)	Request handler for sending authentication and authorisation requests.
`AuthResponse`([file_path, ...])	Handle saving, loading, enriching, sanitising etc.
`AuthTester`([request, response_test, max_expiry])	Run tests against the response of authorisation request to ensure its validity.
`SocketHandler`([port, timeout])

class aiorequestful.auth.utils.AuthRequest(**kwargs)

Bases: object

Request handler for sending authentication and authorisation requests. Supply this class with the required arguments for your request.

Arguments passed through to .aiohttp.ClientSession.request. See aiohttp reference for more info on available kwargs: https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.ClientSession.request

Attributes:

`payload`	The payload for this request
`method`
`url`
`params`
`data`
`json`
`cookies`
`headers`
`skip_auto_headers`
`auth`
`allow_redirects`
`max_redirects`
`compress`
`chunked`
`expect100`
`raise_for_status`
`read_until_eof`
`proxy`
`proxy_auth`
`timeout`
`verify_ssl`
`fingerprint`
`ssl_context`
`ssl`
`server_hostname`
`proxy_headers`
`trace_request_ctx`
`read_bufsize`
`auto_decompress`
`max_line_size`
`max_field_size`

Methods:

`set_payload_type`(kind)	Remap the payload type to query params ('params'), body ('data'), or JSON payloads
`enrich_payload`(value)	Temporarily append data to the payload of a request within a context, removing them when no longer in context.
`enrich_headers`(value)	Temporarily append data to the headers of a request within a context, removing them when no longer in context.
`request`(session)	Send the request within the given `session` and return the response.

property payload: dict[str, Any] | None: The payload for this request

method

url

set_payload_type(kind)

Remap the payload type to query params (‘params’), body (‘data’), or JSON payloads

Return type:: None

enrich_payload(value)

Temporarily append data to the payload of a request within a context, removing them when no longer in context.

Parameters:: value (dict[str, Any]) – The value to append.
Return type:: Generator[None, None, None]

enrich_headers(value)

Temporarily append data to the headers of a request within a context, removing them when no longer in context.

Parameters:: value (dict[str, Any]) – The value to append.
Return type:: Generator[None, None, None]

request(session)

Send the request within the given session and return the response.

Return type:: Coroutine[ClientResponse, None, None]

params

data

json

cookies

headers

skip_auto_headers

auth

allow_redirects

max_redirects

compress

chunked

expect100

raise_for_status

read_until_eof

proxy

proxy_auth

timeout

verify_ssl

fingerprint

ssl_context

ssl

server_hostname

proxy_headers

trace_request_ctx

read_bufsize

auto_decompress

max_line_size

max_field_size

class aiorequestful.auth.utils.AuthResponse(file_path=None, token_prefix_default=None, additional_headers=None)

Bases: MutableMapping[str, Any]

Handle saving, loading, enriching, sanitising etc. of responses. Also handles token extraction and header generation from token responses.

Parameters:

file_path (str | Path (default: None)) – Path to use for loading and saving a token.
token_prefix_default (str | None (default: None)) – Prefix to add to the header value for authorised calls to an endpoint.
additional_headers (Mapping[str, str] (default: None)) – Extra headers to add to the final headers to ensure future successful requests.

Attributes:

`token`	Extract the token from the stored response.
`headers`	Generate headers from the stored response, adding all additional headers as needed.
`sanitised`	Returns a reformatted response, making it safe to log by removing sensitive values at predefined keys.
`logger`	The `logging.Logger` for this object
`file_path`	Path to use for loading and saving a token.
`token_key`	Prefix to add to the header value for authorised calls to an endpoint.
`token_prefix_default`	The default prefix to append to the credentials in the 'Authorization' header value if one cannot be found in the response.
`additional_headers`	Extra headers to add to the final headers to ensure future successful requests.

Methods:

`replace`(response)	Replace the currently stored response with a new `response`
`enrich`([refresh_token])	Extends the response by adding granted and expiry time information to it.
`load_response_from_file`()	Load a stored response from given path
`save_response_to_file`()	Save the stored response to the stored file path.

property token: str | None: Extract the token from the stored response.

property headers: dict[str, str]: Generate headers from the stored response, adding all additional headers as needed.

property sanitised: dict[str, str | int | float | list | dict | bool | None]: Returns a reformatted response, making it safe to log by removing sensitive values at predefined keys.

logger: Logger: The logging.Logger for this object

file_path: Path | None: Path to use for loading and saving a token.

token_key: str: Prefix to add to the header value for authorised calls to an endpoint.

token_prefix_default: str | None: The default prefix to append to the credentials in the ‘Authorization’ header value if one cannot be found in the response.

additional_headers: Extra headers to add to the final headers to ensure future successful requests.

replace(response)

Replace the currently stored response with a new response

Return type:: None

enrich(refresh_token=None)

Extends the response by adding granted and expiry time information to it. Adds the given refresh_token to the response if one is not present.

Return type:: None

load_response_from_file()

Load a stored response from given path

Return type:: dict[str, str | int | float | list | dict | bool | None] | None

save_response_to_file()

Save the stored response to the stored file path.

Return type:: None

class aiorequestful.auth.utils.AuthTester(request=None, response_test=None, max_expiry=0)

Bases: object

Run tests against the response of authorisation request to ensure its validity.

When setting max_expiry, the following example illustrates how this is used:

A token has 600 second total expiry time,
it is 60 seconds old and therefore still has 540 seconds of authorised time left,
you set max_expiry = 300, the token will pass tests.
The same token is tested again later when it is 500 now seconds old,
it now has only 100 seconds of authorised time left,
it will now fail the tests as 100 < 300.

Parameters:

request (AuthRequest | None (default: None)) – The request to execute when testing the access token.
response_test (Callable[[ClientResponse], Awaitable[bool]] | None (default: None)) – Test to apply to the response from the access token request.
max_expiry (int (default: 0)) – The max allowed time in seconds left until the token is due to expire. Useful for ensuring the token will be valid for long enough to run your operations.

Attributes:

`logger`	The `logging.Logger` for this object
`request`	The request to execute when testing the access token.
`response_test`	Test to apply to the response from the access token request.
`max_expiry`	The max allowed time in seconds left until the token is due to expire

Methods:

test([response])

Test validity of the response and given headers.

logger: Logger: The logging.Logger for this object

request: The request to execute when testing the access token.

response_test: Test to apply to the response from the access token request.

max_expiry: The max allowed time in seconds left until the token is due to expire

async test(response=None)

Test validity of the response and given headers. Returns True if all tests pass, False otherwise

Return type:: bool

class aiorequestful.auth.utils.SocketHandler(port=8080, timeout=120)

Bases: object

Parameters:

port (int (default: 8080)) – The port to open on the localhost for this socket.
timeout (int (default: 120)) – The time in seconds to keep the socket listening for a request.

Attributes:

`port`	The port to open on the localhost for this socket
`timeout`	The time in seconds to keep the socket listening for a request.

port: The port to open on the localhost for this socket

timeout: The time in seconds to keep the socket listening for a request.