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.

Initialize an authenticated session with token auto-refresh on 401/403.

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()).

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

Initialize an authenticated session with token auto-refresh on 401/403.

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()).

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:

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: Return value. :rtype: RequestsCookieJar

delete(url, **kwargs)

Send a DELETE request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

Return type:

Response

get(url, **kwargs)

Send a GET request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

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: Return value. :rtype: MutableMapping[str, str | bytes]

patch(url, **kwargs)

Send a PATCH request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

Return type:

Response

post(url, **kwargs)

Send a POST request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

Return type:

Response

put(url, **kwargs)

Send a PUT request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

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}". :param token: The bearer token to attach :type token: str

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 an authenticated session with token auto-refresh on 401/403.

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()).

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

Initialize an authenticated session with token auto-refresh on 401/403.

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()).

close()

Persist cookies and release the underlying HTTP connection pool.

property cookies: RequestsCookieJar

Underlying cookie jar.

Mutating this affects subsequent requests. :returns: Return value. :rtype: RequestsCookieJar

delete(url, **kwargs)

Send a DELETE request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

Return type:

Response

get(url, **kwargs)

Send a GET request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

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: Return value. :rtype: MutableMapping[str, str | bytes]

patch(url, **kwargs)

Send a PATCH request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

Return type:

Response

post(url, **kwargs)

Send a POST request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

Return type:

Response

put(url, **kwargs)

Send a PUT request.

See request(). :param url: Absolute URL, or a path relative to Config.base_url. :type url: str :param kwargs: Additional keyword arguments forwarded to request(). :type kwargs: Any :returns: Return value. :rtype: requests.Response

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:

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}". :param token: The bearer token to attach :type token: str