gamesheet_sdk.common.session

Reusable HTTP session for talking to the GameSheet WebUI.

Wraps requests.Session with the bits every WebUI workflow needs and nobody wants to wire up by hand: - A pinned, version-stamped User-Agent. - Configurable base URL so callers can hand in relative paths. - Cookie persistence to disk between process invocations. - Retries on 5xx and connection errors for idempotent methods. - POST is intentionally excluded from retries (no double-submission). Direct access to the cookie jar and default headers is via Session.cookies and Session.headers.

Classes

Session

A requests.Session wrapper configured for GameSheet WebUI access.

class gamesheet_sdk.common.session.Session

Bases: object

A requests.Session wrapper configured for GameSheet WebUI access.

Example::

from gamesheet_sdk import Config, Session with Session(Config()) as s:

resp = s.get(“/api/leagues”) resp.raise_for_status()

The context-manager form persists cookies on exit. If you do not use with, call Session.close() explicitly to save state.

Initialize an HTTP session configured for GameSheet WebUI access.

Constructs a requests.Session with automatic retry logic, a version-stamped User-Agent, and restores any previously-saved cookies from disk. The session is ready for immediate use after construction.

Parameters:

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

__init__(config=None)

Initialize an HTTP session configured for GameSheet WebUI access.

Constructs a requests.Session with automatic retry logic, a version-stamped User-Agent, and restores any previously-saved cookies from disk. The session is ready for immediate use after construction.

Parameters:

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

property cookies: RequestsCookieJar

Underlying cookie jar.

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

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]

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

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

Send an HTTP request, resolving url against the configured base URL.

Parameters:

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

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

• timeout (float | None) – Per-request timeout override; falls back to Config.timeout if not supplied.

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

Returns:

Return value.

Return type:

requests.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

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

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

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

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.

close()

Persist cookies and release the underlying HTTP connection pool.