`auth`¶

The credential vocabulary: what a prover authenticates with, whether it is present on this host, and how long it stays valid. Every prover reports one AuthStatus from auth_status().

class open_atp.auth.AuthStatus(kind: AuthKind, source: str, present: bool, expires_at: datetime | None = None, refreshable: bool = False, remedy: str = '')[source]¶

The state of a prover’s credential, as read from the host.

Reported by auth_status(). Reading the host never validates the credential against its provider; a present, unexpired credential can still be revoked or simply wrong.

Parameters:

kindAuthKind: Whether the prover authenticates with an API key or an OAuth token.
sourcestr: Where the credential is read from: an environment variable name, or the path of the CLI credential file.
presentbool: Whether the credential was found at source.
expires_atdatetime.datetime, optional: When the credential stops being valid. None (the default) when it does not expire or exposes no expiry.
refreshablebool, default False: Whether the credential ships a refresh token, letting its CLI renew it on the host. Sandboxed runs cannot refresh it themselves.
remedystr, optional: How to obtain the credential (e.g., command or web page). Defaults to source.

classmethod from_env(env_name: str, explicit: str | None = None, kind: AuthKind = AuthKind.API_KEY, remedy: str = '') → AuthStatus[source]¶

Read a credential held in an environment variable.

Parameters:

env_namestr: The environment variable holding the credential.
explicitstr or None, optional: A credential passed directly, taking precedence over the environment.
kindAuthKind, default AuthKind.API_KEY: What the credential type is.
remedystr, optional: How to obtain the credential.

Returns:

AuthStatus: A status that never expires; an environment variable carries no expiry.

Examples

An unset variable reads as missing:

>>> from open_atp.auth import AuthStatus
>>> AuthStatus.from_env("NOT_A_REAL_API_KEY").state()
<AuthState.MISSING: 'missing'>

time_remaining(now: datetime | None = None) → timedelta | None[source]¶

How long the credential stays valid, relative to now.

Parameters:

nowdatetime.datetime, optional: The instant to measure from; defaults to the current UTC time.

Returns:

datetime.timedelta or None: Time until expiry, negative once past it. None when the credential is absent or exposes no expiry.

state(now: datetime | None = None) → AuthState[source]¶

Classify the credential as of now.

Parameters:

nowdatetime.datetime, optional: The instant to classify against; defaults to the current UTC time.

Returns:

AuthState: MISSING if absent, else the position of now in the validity window. A credential with no expiry is always OK when present.

Examples

A key read from the environment neither expires nor refreshes:

>>> from open_atp.auth import AuthKind, AuthStatus
>>> status = AuthStatus(AuthKind.API_KEY, "OPENAI_API_KEY", present=True)
>>> status.state()
<AuthState.OK: 'ok'>

class open_atp.auth.AuthKind(*values)[source]¶: The kind of credential a prover authenticates with.

class open_atp.auth.AuthState(*values)[source]¶: Whether a credential is usable, and if not, why.

open_atp.auth.EXPIRY_WARNING_THRESHOLD = datetime.timedelta(seconds=900)¶: Threshold until expiration for AuthState.EXPIRING status.

auth¶

`auth`¶