zabgrab.services.tokens

Managing stored API tokens (zabgrab token).

Functions

add_token(server, token, *, factory, ui, ...)	Store a token for a server in the keyring.
check_token(server, *, factory, secrets, env)	Check the token zabgrab would use for a server against the server.
choose_stored(statuses, ui)	Ask which server's stored token to act on.
delete_token(server, *, ui, secrets, yes)	Delete the stored token for a server, confirming first unless yes.
reset_tokens(*, ui, secrets, yes)	Delete every stored token, confirming first unless yes.
token_statuses(config, secrets, env)	List where each server's token comes from.

Classes

CheckResult(state[, detail])	The result of checking a token.
CheckState(*values)	The outcome of checking a token against its server.
TokenStatus(server, stored, env_var, env_set)	Whether a server has a token, and where from.

class zabgrab.services.tokens.TokenStatus(server, stored, env_var, env_set)

Bases: object

Whether a server has a token, and where from.

Parameters:

• server (Server)

• stored (bool)

• env_var (str | None)

• env_set (bool)

server

The server.

Type:

Server

stored

Whether a token is stored in the keyring.

Type:

bool

env_var

The server’s token_env variable, if it has one.

Type:

str or None

env_set

Whether that variable is set.

Type:

bool

class zabgrab.services.tokens.CheckState(*values)

Bases: StrEnum

The outcome of checking a token against its server.

VALID

The server accepted it.

REJECTED

The server rejected it.

MISSING

There’s no token for the server.

ERROR

The server couldn’t be asked (e.g. it’s unreachable).

class zabgrab.services.tokens.CheckResult(state, detail='')

Bases: object

The result of checking a token.

Parameters:

• state (CheckState)

• detail (str)

state

The outcome.

Type:

CheckState

detail

Where the token came from, or the error.

Type:

str

zabgrab.services.tokens.token_statuses(config, secrets, env)

List where each server’s token comes from.

Parameters:

• config (Config) – The configured servers.

• secrets (SecretStore) – The stored tokens.

• env (mapping of str to str) – Environment variables.

Returns:

list of TokenStatus – Every configured server, then any other server with a stored token.

Return type:

list[TokenStatus]

async zabgrab.services.tokens.check_token(server, *, factory, secrets, env)

Check the token zabgrab would use for a server against the server.

Parameters:

• server (Server) – The server.

• factory (ClientFactory) – Creates the client.

• secrets (SecretStore) – The stored tokens.

• env (mapping of str to str) – Environment variables (for token_env).

Returns:

CheckResult – Whether the token is valid, rejected, missing or couldn’t be checked.

Return type:

CheckResult

async zabgrab.services.tokens.add_token(server, token, *, factory, ui, secrets, env, check=True, update_url=None)

Store a token for a server in the keyring.

Parameters:

• server (Server) – The server.

• token (str or None) – The token, or None to ask for it.

• factory (ClientFactory) – Creates the client, to check the token.

• ui (UI) – Asks for the token, and reports the outcome.

• secrets (SecretStore) – Where to store it.

• env (mapping of str to str) – Environment variables (to warn if token_env overrides the keyring).

• check (bool, optional) – Make sure the server accepts the token first. If the server redirects, the token is stored for the URL it redirects to (see zabgrab.services.session.open_client()).

• update_url (callable, optional) – Offered to update a configured server’s URL after a redirect.

Raises:

• AuthenticationFailed – If checking and the server rejects the token.

• InputRequired – If the token is needed and the session isn’t interactive.

Return type:

None

zabgrab.services.tokens.choose_stored(statuses, ui)

Ask which server’s stored token to act on.

Raises:

ZabgrabError – If no tokens are stored.

Parameters:

• statuses (list[TokenStatus])

• ui (UI)

Return type:

Server

zabgrab.services.tokens.delete_token(server, *, ui, secrets, yes)

Delete the stored token for a server, confirming first unless yes.

Raises:

• ZabgrabError – If no token is stored for it.

• Cancelled – If the user says no.

Parameters:

• server (Server)

• ui (UI)

• secrets (SecretStore)

• yes (bool)

Return type:

None

zabgrab.services.tokens.reset_tokens(*, ui, secrets, yes)

Delete every stored token, confirming first unless yes.

Raises:

Cancelled – If the user says no.

Parameters:

• ui (UI)

• secrets (SecretStore)

• yes (bool)

Return type:

None