gamesheet_sdk.common.auth.flow module

Login flow protocol for pluggable authentication strategies.

Defines LoginFlow, the structural interface that both admin (browser-based) and teams (HTTP-only) authentication implement. Downstream code that needs to authenticate — CLI commands, session construction helpers — depends on this protocol rather than on a concrete login function, so the auth mechanism can vary per pillar without changing the consumer.

Example — using a LoginFlow implementation:

from gamesheet_sdk.common.auth.flow import LoginFlow
from gamesheet_sdk.common.auth.tokens import save_tokens
from gamesheet_sdk.common.config import Config


def run_login(flow: LoginFlow, config: Config) -> None:
    tokens = flow.authenticate(email="user@example.com")
    save_tokens(config, **tokens)
class gamesheet_sdk.common.auth.flow.LoginFlow[source]

Bases: Protocol

Structural interface for authentication flows.

Any class that exposes an authenticate method with the signature below is a valid LoginFlow — no explicit inheritance needed (structural subtyping via typing.Protocol).

Implementations hold whatever state they need (a Config, a BrowserSession, HTTP clients, etc.) and expose only the common authenticate entry point.

The returned dict contains at minimum "access" and "refresh" keys. Admin flows may also include "roles". The shape matches refresh_access_token()’s return value and can be unpacked directly into save_tokens().

authenticate(email=None, password=None, *, timeout=None)[source]

Authenticate with the GameSheet platform and return tokens.

Credential resolution follows a standard fallback chain: explicit arguments → GAMESHEET_USERNAME / GAMESHEET_PASSWORD env vars → Config fields. Implementations raise AuthenticationError when credentials are missing or authentication is rejected.

Parameters:

  • email (str | None) – Login email, or None to resolve from config/env.

  • password (str | None) – Login password, or None to resolve from config/env.

  • timeout (float | None) – Auth round-trip timeout in seconds, or None for the implementation’s default.

Returns:

Token bundle with at least "access" and "refresh" keys.

Return type:

dict[str, str]

Raises:

AuthenticationError – If credentials are missing or the auth backend rejects them.

__init__(*args, **kwargs)