icpc-api 0.1.0__py3-none-any.whl

icpc/cli/render.py

@@ -0,0 +1,160 @@
+"""Output formatting for the CLI."""
+
+from __future__ import annotations
+
+import csv
+import enum
+import json
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+from pydantic import BaseModel
+from rich.console import Console
+from rich.table import Table
+
+__all__ = ["OutputFormat", "cell", "fail", "note", "render", "warn"]
+
+#: Data console. Markup is off: a cell holding `members[i].role` or `[dim]` is a
+#: value, not a style, and rich would otherwise swallow the brackets.
+_console = Console(markup=False)
+_err = Console(stderr=True)
+
+
+class OutputFormat(enum.StrEnum):
+    """How to print results. ``auto`` means a table on a terminal, JSON in a pipe."""
+
+    AUTO = "auto"
+    TABLE = "table"
+    JSON = "json"
+    NDJSON = "ndjson"
+    CSV = "csv"
+    TSV = "tsv"
+
+
+def _resolve(fmt: OutputFormat) -> OutputFormat:
+    if fmt is not OutputFormat.AUTO:
+        return fmt
+    return OutputFormat.TABLE if sys.stdout.isatty() else OutputFormat.JSON
+
+
+def _plain(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(by_alias=True, exclude_none=True)
+    if isinstance(value, enum.Enum):
+        return value.value
+    if isinstance(value, list | tuple):
+        return [_plain(item) for item in value]
+    if isinstance(value, dict):
+        return {k: _plain(v) for k, v in value.items()}
+    return value
+
+
+#: Table cells wider than this are elided. Some columns carry whole JSON blobs
+#: (staff labels, team rosters) and one of them would otherwise squeeze every
+#: other column into a vertical stripe.
+MAX_CELL = 60
+
+
+def cell(value: Any, *, limit: int | None = None) -> str:
+    """One value as text: booleans as yes/no, structures as JSON, ``None`` blank."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, list | dict):
+        text = json.dumps(_plain(value), ensure_ascii=False)
+    else:
+        text = str(value)
+    if limit is not None and len(text) > limit:
+        return text[: limit - 1] + "…"
+    return text
+
+
+def _tsv_cell(value: Any) -> str:
+    """A cell without tabs or newlines, to put into a TSV file."""
+    text = cell(value)
+    for char in ("\t", "\r", "\n"):
+        text = text.replace(char, " ")
+    return text
+
+
+def _rows(data: Any) -> list[dict[str, Any]]:
+    items = data if isinstance(data, list) else [data]
+    out: list[dict[str, Any]] = []
+    for item in items:
+        plain = _plain(item)
+        out.append(plain if isinstance(plain, dict) else {"value": plain})
+    return out
+
+
+def render(data: Any, fmt: OutputFormat, *, columns: Sequence[str] | None = None) -> None:
+    """Print ``data`` in the requested format.
+
+    ``columns`` restricts and orders the table, CSV and TSV output; JSON always carries
+    everything, because that is what a pipeline consumer wants.
+    """
+    resolved = _resolve(fmt)
+
+    if resolved is OutputFormat.JSON:
+        _console.print_json(json.dumps(_plain(data), ensure_ascii=False, default=str))
+        return
+
+    rows = _rows(data)
+
+    if resolved is OutputFormat.NDJSON:
+        for row in rows:
+            sys.stdout.write(json.dumps(row, ensure_ascii=False, default=str) + "\n")
+        return
+
+    if not rows:
+        _err.print("[dim]no rows[/dim]")
+        return
+
+    headers = list(columns) if columns else _headers(rows)
+
+    if resolved is OutputFormat.CSV:
+        writer = csv.DictWriter(sys.stdout, fieldnames=headers, extrasaction="ignore")
+        writer.writeheader()
+        for row in rows:
+            writer.writerow({key: cell(row.get(key)) for key in headers})
+        return
+
+    if resolved is OutputFormat.TSV:
+        sys.stdout.write("\t".join(headers) + "\n")
+        for row in rows:
+            sys.stdout.write("\t".join(_tsv_cell(row.get(key)) for key in headers) + "\n")
+        return
+
+    table = Table(show_lines=False, header_style="bold")
+    for header in headers:
+        table.add_column(header, overflow="fold")
+    for row in rows:
+        table.add_row(*(cell(row.get(header), limit=MAX_CELL) for header in headers))
+    _console.print(table)
+
+
+def _headers(rows: Sequence[dict[str, Any]]) -> list[str]:
+    """Union of the rows' keys, in first-seen order.
+
+    Rows come back with unprojected columns dropped by ``exclude_none``, so the
+    first row alone is not a reliable header set.
+    """
+    seen: dict[str, None] = {}
+    for row in rows:
+        for key in row:
+            seen.setdefault(key, None)
+    return list(seen)
+
+
+def note(message: str) -> None:
+    """Progress and confirmation, on stderr so stdout stays pipeable."""
+    _err.print(f"[dim]{message}[/dim]")
+
+
+def warn(message: str) -> None:
+    _err.print(f"[yellow]{message}[/yellow]")
+
+
+def fail(message: str) -> None:
+    _err.print(f"[red]{message}[/red]")

icpc/config.py

@@ -0,0 +1,57 @@
+"""Static configuration for the client.
+
+The Cognito pool parameters belong to icpc.global's public SPA app client.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import httpx
+
+__all__ = ["COGNITO_URL", "Settings"]
+
+REGION = "us-east-1"
+USER_POOL_ID = "us-east-1_WaDOo4Gqm"
+CLIENT_ID = "6q2fe6opm0m24eoebqf9vj4emd"
+COGNITO_URL = f"https://cognito-idp.{REGION}.amazonaws.com/"
+
+BASE_URL = "https://icpc.global/api"
+
+#: Page size the frontend's largest grid offers. The server accepts more, but this
+#: is the biggest value known to be exercised in production.
+DEFAULT_PAGE_SIZE = 1000
+
+
+def _default_timeout() -> httpx.Timeout:
+    return httpx.Timeout(connect=5.0, read=30.0, write=30.0, pool=5.0)
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Tunables shared by the async and sync clients.
+
+    The concurrency and retry defaults are deliberately conservative: this is
+    someone else's production system, not ours.
+    """
+
+    base_url: str = BASE_URL
+    cognito_url: str = COGNITO_URL
+    user_pool_id: str = USER_POOL_ID
+    client_id: str = CLIENT_ID
+
+    timeout: httpx.Timeout = field(default_factory=_default_timeout)
+    #: Read timeout used for exports and large search pages.
+    slow_read_timeout: float = 120.0
+
+    max_attempts: int = 3
+    backoff_base: float = 0.5
+    backoff_cap: float = 8.0
+
+    #: Concurrent in-flight requests allowed by the client.
+    max_concurrency: int = 4
+
+    #: Renew the id token this many seconds before it actually expires.
+    refresh_margin: float = 60.0
+
+    user_agent: str = "icpc-api"

icpc/errors.py

@@ -0,0 +1,159 @@
+"""Exception hierarchy.
+
+Client-side problems (`SearchError` and friends) are raised *before* a request goes
+out; everything under `ApiError` carries the real HTTP response.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "ApiError",
+    "AuthError",
+    "BadRequest",
+    "CognitoError",
+    "ConfigError",
+    "Conflict",
+    "EmptyProjection",
+    "Forbidden",
+    "IcpcError",
+    "InvalidCredentials",
+    "InvalidFilterValue",
+    "MethodNotAllowed",
+    "MfaRequired",
+    "NotFound",
+    "RateLimited",
+    "SearchError",
+    "ServerError",
+    "TokenExpired",
+    "TransportError",
+    "Unauthorized",
+]
+
+_ERROR_CODE = re.compile(r"error code \(([0-9a-f]+)\)")
+
+
+class IcpcError(Exception):
+    """Base class for every error raised by this package."""
+
+
+class ConfigError(IcpcError):
+    """Missing or contradictory configuration (no credentials, unknown profile)."""
+
+
+# --------------------------------------------------------------------- auth --
+
+
+class AuthError(IcpcError):
+    """Authentication or token management failed."""
+
+
+class InvalidCredentials(AuthError):
+    """Cognito rejected the username/password pair."""
+
+
+class MfaRequired(AuthError):
+    """Cognito wants a software-token MFA code to finish the login."""
+
+    def __init__(self, challenge: str, session: str, username: str) -> None:
+        super().__init__(f"MFA challenge {challenge} required for {username}")
+        self.challenge = challenge
+        self.session = session
+        self.username = username
+
+
+class TokenExpired(AuthError):
+    """The id token expired and could not be renewed."""
+
+
+class CognitoError(AuthError):
+    """A Cognito RPC returned an error body."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+
+
+# ---------------------------------------------------------------- transport --
+
+
+class TransportError(IcpcError):
+    """The request never produced a response (connection, TLS or timeout)."""
+
+
+# ---------------------------------------------------------------------- api --
+
+
+class ApiError(IcpcError):
+    """A non-2xx response from icpc.global."""
+
+    def __init__(self, status: int, method: str, path: str, body: str) -> None:
+        super().__init__(f"HTTP {status} {method} {path}: {body[:400]}")
+        self.status = status
+        self.method = method
+        self.path = path
+        self.body = body
+
+
+class BadRequest(ApiError):
+    """400 — usually a missing or malformed ``q``."""
+
+
+class Unauthorized(ApiError):
+    """401 — the id token was rejected even after a refresh."""
+
+
+class Forbidden(ApiError):
+    """403 — authenticated, but not entitled to this contest or team."""
+
+
+class NotFound(ApiError):
+    """404."""
+
+
+class MethodNotAllowed(ApiError):
+    """405 — the path exists but not under this verb."""
+
+
+class Conflict(ApiError):
+    """409."""
+
+
+class RateLimited(ApiError):
+    """429."""
+
+    def __init__(
+        self, status: int, method: str, path: str, body: str, retry_after: float | None
+    ) -> None:
+        super().__init__(status, method, path, body)
+        self.retry_after = retry_after
+
+
+class ServerError(ApiError):
+    """5xx. ICPC's 500 bodies carry an opaque hex code worth quoting to support."""
+
+    def __init__(self, status: int, method: str, path: str, body: str) -> None:
+        super().__init__(status, method, path, body)
+        match = _ERROR_CODE.search(body)
+        self.error_code: str | None = match.group(1) if match else None
+
+
+class TeamNotPromotable(ServerError):
+    """``POST /team/{id}/promote/{siteId}`` refused: already promoted, or site conflict."""
+
+
+# ------------------------------------------------------------------- search --
+
+
+class SearchError(IcpcError):
+    """The search query is invalid; raised before the request is sent."""
+
+
+class InvalidFilterValue(SearchError):
+    """A filter value contains a character the ``q`` grammar cannot escape."""
+
+
+class EmptyProjection(SearchError):
+    """A projection naming no valid field would 500 server-side."""

icpc/facade/__init__.py

@@ -0,0 +1,6 @@
+"""High-level clients and the joined contest model."""
+
+from icpc.facade.client import AsyncIcpc, Icpc, Include
+from icpc.facade.domain import ContestView, Member, Team, join
+
+__all__ = ["AsyncIcpc", "ContestView", "Icpc", "Include", "Member", "Team", "join"]