pybragerone.models.token¶

Token storage implementations for pybragerone.

This module provides token management and persistence strategies for the pybragerone library. It includes:

Token: A Pydantic model representing OAuth2-style authentication tokens
TokenStore: A protocol defining the interface for token persistence
CLITokenStore: A concrete implementation for CLI applications using keyring/file storage
HATokenStore: An adapter for Home Assistant integration storage

The token storage implementations handle secure persistence of authentication tokens, including access tokens, refresh tokens, and expiration information.

Classes:: Token: Pydantic model representing an authentication token with expiration tracking. TokenStore: Protocol defining the interface for token storage implementations. CLITokenStore: Token storage for CLI applications with keyring and file fallback. HATokenStore: Adapter for Home Assistant storage with callable-based implementation.

Examples

Using CLITokenStore for CLI applications:

>>> store = CLITokenStore(email="user@example.com")
>>> token = store.load()
>>> if token and not token.is_expired():
...     print("Token is valid")

Using HATokenStore with custom storage callbacks:

>>> def my_loader() -> Token | None:
...     # Load from HA storage
...     pass
>>> def my_saver(token: Token) -> None:
...     # Save to HA storage
...     pass
>>> def my_clearer() -> None:
...     # Clear from HA storage
...     pass
>>> store = HATokenStore(loader=my_loader, saver=my_saver, clearer=my_clearer)

Notes

CLITokenStore prefers system keyring when available, falling back to file storage
File storage uses 0600 permissions for security
All token storage operations suppress exceptions to prevent disruption
Token expiration includes a configurable leeway period (default 60 seconds)

ivar _HAS_KEYRING:: Whether the keyring library is available for secure storage.
vartype _HAS_KEYRING:: bool
ivar log:: Module logger for debugging and error reporting.
vartype log:: logging.Logger

Classes

`CLITokenStore`(email[, service])	Token persistence for CLI.
`HATokenStore`(loader, saver, clearer)	Minimal example adapter for Home Assistant storage.
`Token`(**data)	Authentication token payload returned by POST /v1/auth/user.
`TokenStore`(args, *kwargs)	Abstract persistence for auth tokens.

class pybragerone.models.token.CLITokenStore(email: str, service: str = 'pybragerone')[source]¶

Bases: object

Token persistence for CLI.

Preference order:

system keyring (if available)
file at ~/.config/pybragerone/token-<email>.json (0600)

Parameters:

email (str)
service (str)

clear()[source]¶

Remove any persisted token.

Return type:: None

email: str¶

load()[source]¶

Return a cached Token or None if not present.

Return type:: Token | None

save(token: Token)[source]¶

Persist the Token atomically.

Return type:: None
Parameters:: token (Token)

service: str = 'pybragerone'¶

class pybragerone.models.token.HATokenStore(loader: Callable[[], Token | None], saver: Callable[[Token], None], clearer: Callable[[], None])[source]¶

Bases: TokenStore

Minimal example adapter for Home Assistant storage.

Expects an object with async load/save/clear; wraps sync API expected by BragerOneApiClient. Replace with your concrete implementation in the HA integration.

Parameters:

loader (Callable[[], Token | None])
saver (Callable[[Token], None])
clearer (Callable[[], None])

clear()[source]¶

Remove any persisted token.

Return type:: None

load()[source]¶

Return a cached Token or None if not present.

Return type:: Token | None

save(token: Token)[source]¶

Persist the Token atomically.

Return type:: None
Parameters:: token (Token)

class pybragerone.models.token.Token(**data: Any)[source]¶

Bases: BaseModel

Authentication token payload returned by POST /v1/auth/user.

Parameters:

access_token (str | None)
refresh_token (str | None)
token_type (str)
expires_at (datetime | None)
user_id (int | None)
objects (list[dict[str, Any]])

access_token: str | None¶

expires_at: datetime | None¶

classmethod from_login_payload(data: dict[str, Any])[source]¶

Create a Token instance from a login response payload.

Return type:: Token
Parameters:: data (dict[str, Any])

is_expired(*, leeway: int = 60)[source]¶

Return True if the token is expired or will expire within leeway seconds.

Return type:: bool
Parameters:: leeway (int)

model_config: ClassVar[ConfigDict] = {'frozen': False}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].