gamesheet_sdk.teams.session module

Authenticated session with automatic token refresh for the teams API gateway.

class gamesheet_sdk.teams.session.TeamsAuthenticatedSession[source]

Bases: BaseAuthenticatedSession

Teams-pillar session that refreshes via the teams API gateway.

Delegates to refresh_access_token(), which POSTs to the teams gateway’s /api/auth/refresh endpoint.

Example:

from gamesheet_sdk.common.auth import load_access_token, load_refresh_token, save_tokens
from gamesheet_sdk.teams.session import TeamsAuthenticatedSession
from gamesheet_sdk.common.config import Config

config = Config(base_url="https://teams.gamesheet.app")
with TeamsAuthenticatedSession(
    config,
    access_token=load_access_token(config),
    refresh_token=load_refresh_token(config),
    on_refresh=lambda tokens: save_tokens(config, **tokens),
) as s:
    resp = s.get("/api/seasons/team/123")
    print(resp.json())

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