cosplay2py 0.3.0__py3-none-any.whl

cosplay2py/__init__.py

@@ -0,0 +1,38 @@
+"""Sync and async client for the Cosplay2.ru event API."""
+
+from cosplay2py import models
+from cosplay2py._base_client import __version__
+from cosplay2py._client import AsyncCosplay2, Cosplay2
+from cosplay2py._exceptions import (
+    APIConnectionError,
+    APIError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    Cosplay2Error,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncCosplay2",
+    "AuthenticationError",
+    "BadRequestError",
+    "Cosplay2",
+    "Cosplay2Error",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "__version__",
+    "models",
+]

cosplay2py/_base_client.py

@@ -0,0 +1,220 @@
+"""Transport-agnostic plumbing shared by the sync and async clients."""
+
+import logging
+import os
+import random
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from functools import cache
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Literal
+
+import httpx2
+from pydantic import TypeAdapter, ValidationError
+
+from cosplay2py._exceptions import (
+    APIResponseValidationError,
+    Cosplay2Error,
+    make_status_error,
+)
+
+log = logging.getLogger("cosplay2py")
+
+try:
+    __version__ = version("cosplay2py")
+except PackageNotFoundError:  # pragma: no cover - running from a source checkout
+    __version__ = "0.0.0"
+
+DEFAULT_TIMEOUT = httpx2.Timeout(30.0, connect=10.0)
+DEFAULT_MAX_RETRIES = 2
+RETRYABLE_STATUSES = frozenset({429, 502, 503, 504})
+_MAX_RETRY_DELAY = 30.0
+
+
+@dataclass(frozen=True, slots=True)
+class Endpoint[T]:
+    """Everything needed to perform one API call and parse its result.
+
+    Resources build these; the clients execute them. Keeping the description of an
+    endpoint free of any I/O is what lets one definition serve both sync and async.
+    """
+
+    method: Literal["GET", "POST"]
+    path: str
+    response_type: Any
+    """The type the (possibly unwrapped) JSON payload is validated against."""
+    key: str | None = None
+    """Top-level key to unwrap, e.g. ``"state"`` for ``{"state": {...}}``."""
+    json: dict[str, Any] | None = None
+    params: dict[str, Any] | None = None
+    """Query string parameters; a few endpoints take their arguments there."""
+    data: dict[str, Any] | None = None
+    files: dict[str, Any] | None = None
+    """Multipart form fields and files, for uploads."""
+    idempotent: bool = field(kw_only=True)
+    """Whether repeating the call is harmless. Writes are only retried when the server
+    cannot have acted on the request (a failed connection)."""
+
+
+@cache
+def _adapter(tp: Any) -> TypeAdapter[Any]:
+    return TypeAdapter(tp)
+
+
+def _resolve_base_url(base_url: str | None, subdomain: str | None) -> httpx2.URL:
+    if base_url and subdomain:
+        raise Cosplay2Error("Pass either `base_url` or `subdomain`, not both.")
+    if subdomain and not re.fullmatch(
+        r"[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?", subdomain
+    ):
+        raise Cosplay2Error("Invalid event subdomain.")
+    if subdomain:
+        base_url = f"https://{subdomain}.cosplay2.ru"
+    base_url = base_url or os.environ.get("COSPLAY2_BASE_URL")
+    if not base_url:
+        raise Cosplay2Error(
+            "No event to talk to: pass `subdomain=` (e.g. 'ff26summer'), `base_url=` "
+            "(e.g. 'https://ff26summer.cosplay2.ru') or set COSPLAY2_BASE_URL."
+        )
+    try:
+        url = httpx2.URL(base_url)
+    except (httpx2.InvalidURL, ValueError):
+        raise Cosplay2Error(
+            "Invalid base_url: expected an HTTP(S) event URL."
+        ) from None
+    if url.scheme not in {"http", "https"} or not url.host:
+        raise Cosplay2Error("Invalid base_url: expected an HTTP(S) event URL.")
+    if url.userinfo or url.query or url.fragment:
+        raise Cosplay2Error("base_url must not contain credentials, query or fragment.")
+    return url
+
+
+def _resolve_credential(value: str | None, env: str, name: str) -> str:
+    value = value or os.environ.get(env)
+    if not value:
+        raise Cosplay2Error(f"Missing {name}: pass `{name}=` or set {env}.")
+    return value
+
+
+class BaseClient[HttpClientT: (httpx2.Client, httpx2.AsyncClient)]:
+    base_url: httpx2.URL
+    max_retries: int
+    _http: HttpClientT
+    _owns_http: bool
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        api_secret: str | None,
+        base_url: str | None,
+        subdomain: str | None,
+        max_retries: int,
+        headers: dict[str, str] | None,
+    ) -> None:
+        if type(max_retries) is not int or max_retries < 0:
+            raise Cosplay2Error("max_retries must be a nonnegative integer.")
+        self.base_url = _resolve_base_url(base_url, subdomain)
+        self.max_retries = max_retries
+        self._headers = {
+            "Accept": "application/json",
+            "User-Agent": f"cosplay2py/{__version__}",
+            **(headers or {}),
+            "X-API-Key": _resolve_credential(api_key, "COSPLAY2_API_KEY", "api_key"),
+            "X-API-Secret": _resolve_credential(
+                api_secret, "COSPLAY2_API_SECRET", "api_secret"
+            ),
+        }
+
+    def __repr__(self) -> str:
+        # Never include the credentials: reprs end up in logs and tracebacks.
+        return f"{type(self).__name__}(base_url={str(self.base_url.copy_with(path='/'))!r})"
+
+    def _build_request(self, endpoint: Endpoint[Any]) -> httpx2.Request:
+        return self._http.build_request(
+            endpoint.method,
+            self.base_url.join(endpoint.path),
+            params=endpoint.params,
+            json=endpoint.json,
+            data=endpoint.data,
+            files=endpoint.files,
+            headers=self._headers,
+        )
+
+    def _process_response[T](
+        self, endpoint: Endpoint[T], response: httpx2.Response
+    ) -> T:
+        log.debug("%s %s -> %s", endpoint.method, endpoint.path, response.status_code)
+        # Redirects are treated as errors too: an unauthenticated request may get
+        # bounced to an HTML page instead of a JSON error.
+        if not response.is_success:
+            raise make_status_error(response)
+
+        try:
+            data = response.json()
+        except ValueError:
+            raise APIResponseValidationError(
+                "Response body is not valid JSON.", response=response
+            ) from None
+
+        if endpoint.key is not None:
+            if not isinstance(data, dict) or endpoint.key not in data:
+                raise APIResponseValidationError(
+                    f"Expected a JSON object with a {endpoint.key!r} key.",
+                    response=response,
+                )
+            data = data[endpoint.key]
+        elif isinstance(data, dict) and data.get("message") == "ok":
+            # A success marker many endpoints put next to the payload, not part of it.
+            data = {k: v for k, v in data.items() if k != "message"}
+
+        try:
+            return _adapter(endpoint.response_type).validate_python(data)
+        except ValidationError:
+            raise APIResponseValidationError(
+                f"Unexpected response shape for {endpoint.path}.",
+                response=response,
+            ) from None
+
+    def _should_retry(
+        self, endpoint: Endpoint[Any], cause: httpx2.Response | Exception, attempt: int
+    ) -> bool:
+        if attempt >= self.max_retries:
+            return False
+        if isinstance(cause, httpx2.Response):
+            if not endpoint.idempotent:
+                return False
+            delay = _retry_after(cause)
+            return cause.status_code in RETRYABLE_STATUSES and (
+                delay is None or delay <= _MAX_RETRY_DELAY
+            )
+        return endpoint.idempotent or isinstance(cause, httpx2.ConnectError)
+
+    def _retry_delay(self, attempt: int, cause: httpx2.Response | Exception) -> float:
+        delay = _retry_after(cause) if isinstance(cause, httpx2.Response) else None
+        if delay is None:
+            delay = min(0.5 * 2 ** min(attempt, 6), _MAX_RETRY_DELAY) * random.uniform(
+                0.75, 1.0
+            )
+        log.info(
+            "Retrying %s in %.2fs (%s)",
+            type(self).__name__,
+            delay,
+            type(cause).__name__,
+        )
+        return delay
+
+
+def _retry_after(response: httpx2.Response) -> float | None:
+    value = response.headers.get("Retry-After", "").strip()
+    if re.fullmatch(r"[0-9]+", value):
+        return float(value)
+    try:
+        date = parsedate_to_datetime(value)
+        if date.tzinfo is None:
+            return None
+        return max(0.0, (date - datetime.now(UTC)).total_seconds())
+    except (ValueError, TypeError, OverflowError):
+        return None

cosplay2py/_client.py

@@ -0,0 +1,240 @@
+import time
+from itertools import count
+from types import TracebackType
+from typing import Self
+
+import anyio
+import httpx2
+
+from cosplay2py._base_client import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    BaseClient,
+    Endpoint,
+)
+from cosplay2py._exceptions import APIConnectionError, APITimeoutError
+from cosplay2py.resources import (
+    AsyncCards,
+    AsyncDesign,
+    AsyncETickets,
+    AsyncEvents,
+    AsyncGeo,
+    AsyncMedia,
+    AsyncPages,
+    AsyncRequests,
+    AsyncTickets,
+    AsyncTopics,
+    AsyncUsers,
+    Cards,
+    Design,
+    ETickets,
+    Events,
+    Geo,
+    Media,
+    Pages,
+    Requests,
+    Tickets,
+    Topics,
+    Users,
+)
+
+
+class Cosplay2(BaseClient[httpx2.Client]):
+    """Synchronous client for the API of one Cosplay2 event.
+
+    API tokens are issued per event (Orgs -> Settings -> API tokens), so a client is
+    bound to a single event site::
+
+        with Cosplay2(subdomain="ff26summer", api_key="...", api_secret="...") as c2:
+            for topic in c2.topics.get_list():
+                print(topic.title)
+
+    Credentials and the event fall back to the ``COSPLAY2_API_KEY``,
+    ``COSPLAY2_API_SECRET`` and ``COSPLAY2_BASE_URL`` environment variables.
+
+    :param subdomain: Event subdomain on cosplay2.ru, e.g. ``"ff26summer"``.
+    :param base_url: Full event URL instead of ``subdomain``; use it for events
+        served from a custom domain.
+    :param max_retries: Retries for connection errors, timeouts and 429/502/503/504.
+    :param http_client: Bring your own ``httpx2.Client`` (proxies, transports, ...).
+        It is not closed by ``close()``; its ``base_url`` is ignored. Its timeout and default headers apply;
+        wrapper headers take precedence. Redirects are always disabled.
+    """
+
+    events: Events
+    topics: Topics
+    requests: Requests
+    geo: Geo
+    users: Users
+    design: Design
+    pages: Pages
+    media: Media
+    cards: Cards
+    etickets: ETickets
+    tickets: Tickets
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        api_secret: str | None = None,
+        subdomain: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx2.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        headers: dict[str, str] | None = None,
+        http_client: httpx2.Client | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            api_secret=api_secret,
+            base_url=base_url,
+            subdomain=subdomain,
+            max_retries=max_retries,
+            headers=headers,
+        )
+        self._owns_http = http_client is None
+        self._http = http_client or httpx2.Client(timeout=timeout)
+
+        self.events = Events(self)
+        self.topics = Topics(self)
+        self.requests = Requests(self)
+        self.geo = Geo(self)
+        self.users = Users(self)
+        self.design = Design(self)
+        self.pages = Pages(self)
+        self.media = Media(self)
+        self.cards = Cards(self)
+        self.etickets = ETickets(self)
+        self.tickets = Tickets(self)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client, unless it was passed in by the caller."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _request[T](self, endpoint: Endpoint[T]) -> T:
+        request = self._build_request(endpoint)
+        for attempt in count():
+            try:
+                response = self._http.send(request, follow_redirects=False)
+            except httpx2.TransportError as exc:
+                if self._should_retry(endpoint, exc, attempt):
+                    time.sleep(self._retry_delay(attempt, exc))
+                    continue
+                if isinstance(exc, httpx2.TimeoutException):
+                    raise APITimeoutError(request=request) from None
+                raise APIConnectionError(request=request) from None
+
+            if self._should_retry(endpoint, response, attempt):
+                response.close()
+                time.sleep(self._retry_delay(attempt, response))
+                continue
+            return self._process_response(endpoint, response)
+        raise AssertionError("unreachable")
+
+
+class AsyncCosplay2(BaseClient[httpx2.AsyncClient]):
+    """Asynchronous client for the API of one Cosplay2 event.
+
+    Same interface as ``Cosplay2``, with awaitable methods::
+
+        async with AsyncCosplay2(subdomain="ff26summer") as c2:
+            topics = await c2.topics.get_list()
+
+    Works with asyncio and trio.
+    """
+
+    events: AsyncEvents
+    topics: AsyncTopics
+    requests: AsyncRequests
+    geo: AsyncGeo
+    users: AsyncUsers
+    design: AsyncDesign
+    pages: AsyncPages
+    media: AsyncMedia
+    cards: AsyncCards
+    etickets: AsyncETickets
+    tickets: AsyncTickets
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        api_secret: str | None = None,
+        subdomain: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx2.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        headers: dict[str, str] | None = None,
+        http_client: httpx2.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            api_secret=api_secret,
+            base_url=base_url,
+            subdomain=subdomain,
+            max_retries=max_retries,
+            headers=headers,
+        )
+        self._owns_http = http_client is None
+        self._http = http_client or httpx2.AsyncClient(timeout=timeout)
+
+        self.events = AsyncEvents(self)
+        self.topics = AsyncTopics(self)
+        self.requests = AsyncRequests(self)
+        self.geo = AsyncGeo(self)
+        self.users = AsyncUsers(self)
+        self.design = AsyncDesign(self)
+        self.pages = AsyncPages(self)
+        self.media = AsyncMedia(self)
+        self.cards = AsyncCards(self)
+        self.etickets = AsyncETickets(self)
+        self.tickets = AsyncTickets(self)
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client, unless it was passed in by the caller."""
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def _request[T](self, endpoint: Endpoint[T]) -> T:
+        request = self._build_request(endpoint)
+        for attempt in count():
+            try:
+                response = await self._http.send(request, follow_redirects=False)
+            except httpx2.TransportError as exc:
+                if self._should_retry(endpoint, exc, attempt):
+                    await anyio.sleep(self._retry_delay(attempt, exc))
+                    continue
+                if isinstance(exc, httpx2.TimeoutException):
+                    raise APITimeoutError(request=request) from None
+                raise APIConnectionError(request=request) from None
+
+            if self._should_retry(endpoint, response, attempt):
+                await response.aclose()
+                await anyio.sleep(self._retry_delay(attempt, response))
+                continue
+            return self._process_response(endpoint, response)
+        raise AssertionError("unreachable")

cosplay2py/_exceptions.py

@@ -0,0 +1,125 @@
+from typing import Any
+
+import httpx2
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "BadRequestError",
+    "Cosplay2Error",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+]
+
+
+class Cosplay2Error(Exception):
+    """Base class for every error raised by cosplay2py."""
+
+
+class APIError(Cosplay2Error):
+    """An error that happened while talking to the Cosplay2 API."""
+
+    message: str
+    request: httpx2.Request
+
+    def __init__(self, message: str, *, request: httpx2.Request) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request = request
+
+
+class APIConnectionError(APIError):
+    """The request never got a response (DNS failure, refused connection, etc.)."""
+
+    def __init__(
+        self, *, request: httpx2.Request, message: str = "Connection error."
+    ) -> None:
+        super().__init__(message, request=request)
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out."""
+
+    def __init__(self, *, request: httpx2.Request) -> None:
+        super().__init__(request=request, message="Request timed out.")
+
+
+class APIResponseValidationError(APIError):
+    """The server answered successfully, but the payload did not match the expected shape."""
+
+    response: httpx2.Response
+    status_code: int
+
+    def __init__(self, message: str, *, response: httpx2.Response) -> None:
+        super().__init__(message, request=response.request)
+        self.response = response
+        self.status_code = response.status_code
+
+
+class APIStatusError(APIError):
+    """The server answered with a non-2xx status code."""
+
+    response: httpx2.Response
+    status_code: int
+    body: Any
+
+    def __init__(self, message: str, *, response: httpx2.Response, body: Any) -> None:
+        super().__init__(message, request=response.request)
+        self.response = response
+        self.status_code = response.status_code
+        self.body = body
+
+
+class BadRequestError(APIStatusError):
+    """HTTP 400."""
+
+
+class AuthenticationError(APIStatusError):
+    """HTTP 401: the API key or secret is missing, invalid or expired."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """HTTP 403: the token has no access to this event or action."""
+
+
+class NotFoundError(APIStatusError):
+    """HTTP 404."""
+
+
+class RateLimitError(APIStatusError):
+    """HTTP 429."""
+
+
+class InternalServerError(APIStatusError):
+    """HTTP 5xx."""
+
+
+_STATUS_ERRORS: dict[int, type[APIStatusError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def make_status_error(response: httpx2.Response) -> APIStatusError:
+    """Build the most specific ``APIStatusError`` subclass for ``response``."""
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = response.text
+
+    message = f"HTTP {response.status_code} API request failed."
+
+    if response.status_code >= 500:
+        cls: type[APIStatusError] = InternalServerError
+    else:
+        cls = _STATUS_ERRORS.get(response.status_code, APIStatusError)
+    return cls(message, response=response, body=body)

cosplay2py/_types.py

@@ -0,0 +1,48 @@
+"""Reusable annotated types that normalize Cosplay2's inconsistent wire formats."""
+
+import json
+from datetime import UTC, datetime
+from typing import Annotated, Any
+
+from pydantic import AfterValidator, BeforeValidator
+
+
+def _as_utc(value: datetime) -> datetime:
+    return value.replace(tzinfo=UTC) if value.tzinfo is None else value
+
+
+def _parse_local(value: Any) -> Any:
+    if isinstance(value, str):
+        return datetime.strptime(value, "%d.%m.%y %H:%M")  # noqa: DTZ007 - naive by design
+    return value
+
+
+def _parse_json(value: Any) -> Any:
+    if isinstance(value, str):
+        return json.loads(value) if value.strip() else None
+    return value
+
+
+def _empty_as_none(value: Any) -> Any:
+    return None if value == "" else value
+
+
+UTCDateTime = Annotated[datetime, AfterValidator(_as_utc)]
+"""A timezone-aware UTC datetime.
+
+The API sends these as ``"YYYY-MM-DD HH:MM:SS"`` strings (in UTC), Unix seconds
+or Unix milliseconds depending on the endpoint.
+"""
+
+LocalDateTime = Annotated[datetime, BeforeValidator(_parse_local)]
+"""A naive datetime, exactly as displayed by the site.
+
+Some endpoints return pre-formatted ``"DD.MM.YY HH:MM"`` strings meant for display;
+these are usually in the event's timezone (see ``Event.timezone``).
+"""
+
+JsonEncoded = BeforeValidator(_parse_json)
+"""Marker for fields that the API returns as a JSON document packed into a string."""
+
+EmptyAsNone = BeforeValidator(_empty_as_none)
+"""Marker for optional fields where the API sends ``""`` instead of ``null``."""