txapi-sdk 1.0.0__py3-none-any.whl

txapi/_pagination.py

@@ -0,0 +1,140 @@
+"""Auto-paging iterators (SPEC §7).
+
+Pages are fetched lazily: nothing is requested until the iterator is consumed,
+and each further page only when the previous one is exhausted.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from typing import Any, Optional
+
+from .types import Event, EventPage, HistoryPage, HistoryRow, PlayerPage, PlayerRow
+
+__all__ = ["player_sort_key"]
+
+_SORT_ALIASES = {
+    "playTime": "playTime",
+    "tsJoined": "tsJoined",
+    "tsLastConnection": "tsLastConnection",
+    "sessions": "tsJoined",
+    "lastConnection": "tsLastConnection",
+}
+
+
+def player_sort_key(sort_by: str | None) -> str:
+    """Row field holding the sort-key value for ``sort_by`` (default ``playTime``)."""
+    if sort_by is None or not sort_by.strip():
+        return "playTime"
+    # Unknown values are rejected by the API (400) on the first page.
+    return _SORT_ALIASES.get(sort_by.strip(), sort_by.strip())
+
+
+PlayerFetch = Callable[[Optional[int], Optional[str]], PlayerPage]
+HistoryFetch = Callable[[Optional[int], Optional[str]], HistoryPage]
+EventFetch = Callable[[Optional[str]], EventPage]
+AsyncPlayerFetch = Callable[[Optional[int], Optional[str]], Awaitable[PlayerPage]]
+AsyncHistoryFetch = Callable[[Optional[int], Optional[str]], Awaitable[HistoryPage]]
+AsyncEventFetch = Callable[[Optional[str]], Awaitable[EventPage]]
+
+
+def _next_player_cursor(page: PlayerPage, sort_key: str) -> tuple[int, str] | None:
+    rows = page.get("players") or []
+    if not rows or page.get("hasReachedEnd", True):
+        return None
+    last: Any = rows[-1]
+    offset = last.get(sort_key)
+    license_ = last.get("license")
+    if offset is None or not license_:
+        return None
+    return int(offset), str(license_)
+
+
+def _next_history_cursor(page: HistoryPage) -> tuple[int, str] | None:
+    rows = page.get("history") or []
+    if not rows or page.get("hasReachedEnd", True):
+        return None
+    last: Any = rows[-1]
+    offset = last.get("timestamp")
+    action_id = last.get("id")
+    if offset is None or not action_id:
+        return None
+    return int(offset), str(action_id)
+
+
+def _next_event_cursor(page: EventPage) -> str | None:
+    if not page.get("events"):
+        return None
+    cursor = page.get("nextCursor")
+    return cursor if isinstance(cursor, str) and cursor else None
+
+
+def iter_players(fetch: PlayerFetch, sort_key: str) -> Iterator[PlayerRow]:
+    offset: int | None = None
+    cursor: str | None = None
+    while True:
+        page = fetch(offset, cursor)
+        yield from page.get("players") or []
+        following = _next_player_cursor(page, sort_key)
+        if following is None:
+            return
+        offset, cursor = following
+
+
+def iter_history(fetch: HistoryFetch) -> Iterator[HistoryRow]:
+    offset: int | None = None
+    cursor: str | None = None
+    while True:
+        page = fetch(offset, cursor)
+        yield from page.get("history") or []
+        following = _next_history_cursor(page)
+        if following is None:
+            return
+        offset, cursor = following
+
+
+def iter_events(fetch: EventFetch) -> Iterator[Event]:
+    cursor: str | None = None
+    while True:
+        page = fetch(cursor)
+        yield from page.get("events") or []
+        cursor = _next_event_cursor(page)
+        if cursor is None:
+            return
+
+
+async def aiter_players(fetch: AsyncPlayerFetch, sort_key: str) -> AsyncIterator[PlayerRow]:
+    offset: int | None = None
+    cursor: str | None = None
+    while True:
+        page = await fetch(offset, cursor)
+        for row in page.get("players") or []:
+            yield row
+        following = _next_player_cursor(page, sort_key)
+        if following is None:
+            return
+        offset, cursor = following
+
+
+async def aiter_history(fetch: AsyncHistoryFetch) -> AsyncIterator[HistoryRow]:
+    offset: int | None = None
+    cursor: str | None = None
+    while True:
+        page = await fetch(offset, cursor)
+        for row in page.get("history") or []:
+            yield row
+        following = _next_history_cursor(page)
+        if following is None:
+            return
+        offset, cursor = following
+
+
+async def aiter_events(fetch: AsyncEventFetch) -> AsyncIterator[Event]:
+    cursor: str | None = None
+    while True:
+        page = await fetch(cursor)
+        for row in page.get("events") or []:
+            yield row
+        cursor = _next_event_cursor(page)
+        if cursor is None:
+            return

txapi/_protocols.py

@@ -0,0 +1,41 @@
+"""Structural types the generated resource classes depend on."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Protocol
+
+from ._core import ApiResponse, EndpointSpec
+from .live import LiveConfig
+
+__all__ = ["AsyncRequester", "SyncRequester"]
+
+
+class SyncRequester(Protocol):
+    def _request(
+        self,
+        endpoint: EndpointSpec,
+        *,
+        path: Mapping[str, object],
+        query: Mapping[str, object],
+        body: Mapping[str, object] | None,
+        server_id: int | str | None,
+        timeout: float | None,
+    ) -> ApiResponse[Any]: ...
+
+    def _live_config(self, server_id: int | str | None) -> LiveConfig: ...
+
+
+class AsyncRequester(Protocol):
+    async def _request(
+        self,
+        endpoint: EndpointSpec,
+        *,
+        path: Mapping[str, object],
+        query: Mapping[str, object],
+        body: Mapping[str, object] | None,
+        server_id: int | str | None,
+        timeout: float | None,
+    ) -> ApiResponse[Any]: ...
+
+    def _live_config(self, server_id: int | str | None) -> LiveConfig: ...

txapi/_ratelimit.py

@@ -0,0 +1,81 @@
+"""Rate-limit headers (``X-RateLimit-*``) and ``Retry-After`` parsing."""
+
+from __future__ import annotations
+
+import email.utils
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+__all__ = ["RateLimit", "parse_rate_limit", "parse_retry_after"]
+
+
+@dataclass(frozen=True)
+class RateLimit:
+    """Per-minute rate-limit state reported by the API on every response.
+
+    Attributes:
+        limit: Requests allowed per minute (``X-RateLimit-Limit``), ``None`` if not sent.
+        remaining: Requests left in the current window (``X-RateLimit-Remaining``).
+        reset_seconds: Seconds until the window resets (``X-RateLimit-Reset``).
+    """
+
+    limit: int | None
+    remaining: int | None
+    reset_seconds: int | None
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    value = headers.get(name)
+    if value is None:
+        # Plain dicts are case sensitive; httpx.Headers is not.
+        lower = name.lower()
+        for key, candidate in headers.items():
+            if key.lower() == lower:
+                return candidate
+    return value
+
+
+def _int(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value.strip())
+    except ValueError:
+        try:
+            return int(float(value.strip()))
+        except ValueError:
+            return None
+
+
+def parse_rate_limit(headers: Mapping[str, str]) -> RateLimit | None:
+    """Parse ``X-RateLimit-Limit/-Remaining/-Reset``; ``None`` if none of them is sent."""
+    limit = _int(_header(headers, "X-RateLimit-Limit"))
+    remaining = _int(_header(headers, "X-RateLimit-Remaining"))
+    reset = _int(_header(headers, "X-RateLimit-Reset"))
+    if limit is None and remaining is None and reset is None:
+        return None
+    return RateLimit(limit=limit, remaining=remaining, reset_seconds=reset)
+
+
+def parse_retry_after(headers: Mapping[str, str], now: float | None = None) -> float | None:
+    """Parse ``Retry-After`` (seconds or HTTP date) to seconds; ``None`` if absent/invalid."""
+    raw = _header(headers, "Retry-After")
+    if raw is None:
+        return None
+    raw = raw.strip()
+    if not raw:
+        return None
+    try:
+        seconds = float(raw)
+    except ValueError:
+        try:
+            parsed = email.utils.parsedate_to_datetime(raw)
+        except (TypeError, ValueError, IndexError):
+            return None
+        if parsed is None:
+            return None
+        seconds = parsed.timestamp() - (time.time() if now is None else now)
+    if seconds != seconds:  # NaN
+        return None
+    return max(0.0, seconds)

txapi/_version.py

@@ -0,0 +1,7 @@
+"""Version constants of the txApi Python SDK."""
+
+__version__ = "1.0.0"
+"""Version of this SDK."""
+
+API_VERSION = "1.8.0"
+"""txApi API version this SDK targets (``spec/endpoints.json -> apiVersion``)."""