Authorise

Handle API authorisation for requesting access tokens to an API.

Classes:

APIAuthoriser(name[, auth_args, user_args, ...])

Authorises and validates an API token for given input parameters.

class musify.api.authorise.APIAuthoriser(name, auth_args=None, user_args=None, refresh_args=None, test_args=None, test_condition=None, test_expiry=0, token=None, token_file_path=None, token_key_path=('access_token',), header_key='Authorization', header_prefix='Bearer ', header_extra=None)

Bases: object

Authorises and validates an API token for given input parameters. Functions for returning formatted headers for future, authorised requests.

Any ..._args parameters must be provided as a dictionary of parameters to be passed directly to the requests module e.g.

user_args = {
    "url": token_url,
    "params": {},
    "data": {
        "client_id": client_id,
        "client_secret": client_secret,
        "grant_type": "client_credentials",
    },
    "auth": ('user', 'pass'),
    "headers": {},
    "json": {},
}

Parameters:

• name (str) – The name of the API service being accessed.

• auth_args (MutableMapping[str, Any] | None (default: None)) – The parameters to be passed to the requests.post() function for initial token authorisation. See description for possible example values.

• user_args (Mapping[str, Any] | None (default: None)) –

  The parameters to be passed to the requests.post() function for requesting user authorised access to API services. The code response from this request is then added to the authorisation request args to grant user authorisation to the API. See description for possible example values.

• refresh_args (Mapping[str, Any] | None (default: None)) –

  The parameters to be passed to the requests.post() function for refreshing an expired token when a refresh_token is present. See description for possible example values.

• test_args (Mapping[str, Any] | None (default: None)) – The parameters to be passed to the requests.get() function for testing validity of the token. Must be set in conjunction with test_condition to work. See description for possible example values.

• test_condition (Callable[[str | Mapping[str, Any]], bool] | None (default: None)) – Callable function for testing the response from the given test_args. e.g. lambda r: "error" not in r

• test_expiry (int (default: 0)) –

  The time allowance in seconds left until the token is due to expire to use when testing. Useful for ensuring the token will be valid for long enough to run your operations e.g.

  • 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 test_expiry = 300, the token will pass tests.

  • the same token is tested again later when it is 500 seconds old,

  • it now has only 100 seconds of authorised time left,

  • it will now fail the tests as 100 < 300 and will need to be refreshed.

• token (Mapping[str, Any] | None (default: None)) – Define a custom input token for initialisation.

• token_file_path (str | None (default: None)) – Path to use for loading and saving a token.

• token_key_path (Sequence[str] (default: ('access_token',))) – Keys to the token in auth response. Looks for key ‘access_token’ by default.

• header_key (str (default: 'Authorization')) – Header key to apply to headers for authorised calls to the API.

• header_prefix (str | None (default: 'Bearer ')) – Prefix to add to the header value for authorised calls to the API.

• header_extra (Mapping[str, str] | None (default: None)) – Extra data to add to the final headers for future successful requests.

Attributes:

token_safe	Returns a reformatted token, making it safe to log by removing sensitive values at predefined keys.
headers	Format headers to usage appropriate format
logger	The MusifyLogger for this object
name
auth_args
user_args
refresh_args
test_args
test_condition
test_expiry
token
token_file_path
token_key_path
header_key
header_prefix
header_extra

Methods:

load_token()	Load stored token from given path
save_token()	Save new/updated token to given path
test_token()	Test validity of token and given headers.

property token_safe: dict[str, Any]

Returns a reformatted token, making it safe to log by removing sensitive values at predefined keys.

property headers: dict[str, str]

Format headers to usage appropriate format

Raises:

APIError – If no token has been loaded, or a valid value was not found at the token_key_path within the token

logger: MusifyLogger

The MusifyLogger for this object

name

auth_args: MutableMapping[str, Any] | None

user_args: dict[str, Any] | None

refresh_args: dict[str, Any] | None

test_args: Mapping[str, Any] | None

test_condition: Callable[[str | Mapping[str, Any]], bool] | None

test_expiry: int

token: Mapping[str, Any] | None

token_file_path: str | None

token_key_path: Sequence[str]

header_key: str

header_prefix: str

header_extra: dict[str, str]

load_token()

Load stored token from given path

Return type:

dict[str, Any] | None

save_token()

Save new/updated token to given path

Return type:

None

test_token()

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

Return type:

bool