gamesheet_sdk.common.auth.session module

Authenticated sessions with automatic token refresh on 401/403.

class gamesheet_sdk.common.auth.session.BaseAuthenticatedSession[source]

Bases: Session, ABC

Abstract base for sessions that auto-refresh their bearer on 401 or 403.

Subclasses provide _do_refresh() to perform the actual token refresh HTTP call against their pillar’s endpoint. Everything else — constructor, retry logic, callback notification — is shared.

On any 401 or 403 response the session calls _do_refresh(), updates its bearer, optionally invokes on_refresh with the new token bundle, and retries the original request once. Both 401 and 403 are treated as authentication failures because different GameSheet API endpoints use different status codes for expired tokens. If the refresh itself fails the original response propagates to the caller.

Parameters:

  • config (Config | None) – Optional configuration object. If None, a default Config is created.

  • access_token (str) – Current access token to use as the bearer in the Authorization header.

  • refresh_token (str) – Refresh token used to renew the access token on 401/403 responses.

  • on_refresh (OnRefreshCallback | None) – Optional callback invoked with a token dict after a successful token refresh. Use this to persist the new tokens to disk (e.g. via save_tokens()).

Initialize BaseAuthenticatedSession instance.

Parameters:

  • config (Config | None) – Optional SDK configuration.

  • access_token (str) – Access token.

  • refresh_token (str) – Refresh token.

  • on_refresh (OnRefreshCallback | None) – Optional callback invoked when tokens refresh.

__init__(config=None, *, access_token, refresh_token, on_refresh=None)[source]

Initialize BaseAuthenticatedSession instance.

Parameters:

  • config (Config | None) – Optional SDK configuration.

  • access_token (str) – Access token.

  • refresh_token (str) – Refresh token.

  • on_refresh (OnRefreshCallback | None) – Optional callback invoked when tokens refresh.

request(method, url, *, timeout=None, **kwargs)[source]

Send a request, refreshing the bearer and retrying once on 401 or 403.

Parameters:

  • method (str) – HTTP method (GET, POST, PUT, DELETE, etc.).

  • url (str) – Target URL for the request.

  • timeout (float | None) – Request timeout in seconds. If None, uses the timeout from config.

  • **kwargs (Any) – Additional keyword arguments forwarded to the parent request().

Returns:

requests.Response –

HTTP response object from the request. If token refresh fails, returns the

original 401/403 response without raising an exception.

Return type:

requests.Response

close()

Persist cookies and release the underlying HTTP connection pool.

property cookies: RequestsCookieJar

Underlying cookie jar.

Mutating this affects subsequent requests.

Returns:

RequestsCookieJar – Return value.

delete(url, **kwargs)

Send a DELETE request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

get(url, **kwargs)

Send a GET request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

property headers: MutableMapping[str, str | bytes]

Default headers attached to every request from this session.

The underlying mapping is a case-insensitive dict (as supplied by requests.Session), but the declared return type matches the stub for requests.Session.headers.

Returns:

MutableMapping[str, str | bytes] – Return value.

patch(url, **kwargs)

Send a PATCH request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

post(url, **kwargs)

Send a POST request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

put(url, **kwargs)

Send a PUT request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

save()

Persist the current cookie state to Config.session_path.

The on-disk format preserves the full cookie attribute set (domain, path, secure, expires) so that reloaded cookies are sent against the correct scopes.

set_bearer_token(token)

Attach Authorization: Bearer <token> to all subsequent requests.

Convenience for s.headers["Authorization"] = f"Bearer {token}".

Parameters:

token (str) – The bearer token to attach

class gamesheet_sdk.common.auth.session.AuthenticatedSession[source]

Bases: BaseAuthenticatedSession

Admin-pillar session that refreshes via the admin token endpoint.

Delegates to refresh_access_token(), forwarding the session’s User-Agent header so the admin gateway can log the calling client.

Example:

from gamesheet_sdk.common.auth import (
    load_access_token,
    load_refresh_token,
    save_tokens,
)
from gamesheet_sdk.common.auth.session import AuthenticatedSession
from gamesheet_sdk.admin.associations import list_associations
from gamesheet_sdk.common.config import Config

config = Config()
with AuthenticatedSession(
    config,
    access_token=load_access_token(config),
    refresh_token=load_refresh_token(config),
    on_refresh=lambda tokens: save_tokens(config, **tokens),
) as s:
    for assoc in list_associations(s):
        print(assoc.name)

Initialize BaseAuthenticatedSession instance.

Parameters:

  • config (Config | None) – Optional SDK configuration.

  • access_token (str) – Access token.

  • refresh_token (str) – Refresh token.

  • on_refresh (OnRefreshCallback | None) – Optional callback invoked when tokens refresh.

__init__(config=None, *, access_token, refresh_token, on_refresh=None)

Initialize BaseAuthenticatedSession instance.

Parameters:

  • config (Config | None) – Optional SDK configuration.

  • access_token (str) – Access token.

  • refresh_token (str) – Refresh token.

  • on_refresh (OnRefreshCallback | None) – Optional callback invoked when tokens refresh.

close()

Persist cookies and release the underlying HTTP connection pool.

property cookies: RequestsCookieJar

Underlying cookie jar.

Mutating this affects subsequent requests.

Returns:

RequestsCookieJar – Return value.

delete(url, **kwargs)

Send a DELETE request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

get(url, **kwargs)

Send a GET request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

property headers: MutableMapping[str, str | bytes]

Default headers attached to every request from this session.

The underlying mapping is a case-insensitive dict (as supplied by requests.Session), but the declared return type matches the stub for requests.Session.headers.

Returns:

MutableMapping[str, str | bytes] – Return value.

patch(url, **kwargs)

Send a PATCH request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

post(url, **kwargs)

Send a POST request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

put(url, **kwargs)

Send a PUT request.

See request().

Parameters:

  • url (str) – Absolute URL, or a path relative to Config.base_url.

  • **kwargs (Any) – Additional keyword arguments forwarded to request().

Returns:

requests.Response – The HTTP response from the server.

Return type:

Response

request(method, url, *, timeout=None, **kwargs)

Send a request, refreshing the bearer and retrying once on 401 or 403.

Parameters:

  • method (str) – HTTP method (GET, POST, PUT, DELETE, etc.).

  • url (str) – Target URL for the request.

  • timeout (float | None) – Request timeout in seconds. If None, uses the timeout from config.

  • **kwargs (Any) – Additional keyword arguments forwarded to the parent request().

Returns:

requests.Response –

HTTP response object from the request. If token refresh fails, returns the

original 401/403 response without raising an exception.

Return type:

requests.Response

save()

Persist the current cookie state to Config.session_path.

The on-disk format preserves the full cookie attribute set (domain, path, secure, expires) so that reloaded cookies are sent against the correct scopes.

set_bearer_token(token)

Attach Authorization: Bearer <token> to all subsequent requests.

Convenience for s.headers["Authorization"] = f"Bearer {token}".

Parameters:

token (str) – The bearer token to attach