portals-api 0.1.0__py3-none-any.whl

portals/__init__.py

@@ -0,0 +1,40 @@
+"""Typed synchronous and asynchronous Python client for the Portals Partners API."""
+
+from . import models as _models
+from ._contract import __api_version__
+from ._models import Amount, RateLimit
+from ._version import __version__
+from .client import AsyncPortalsClient, PortalsClient
+from .exceptions import (
+    AccessDeniedError,
+    APIError,
+    AuthenticationError,
+    BetOutcomeUnknownError,
+    InvalidResponseError,
+    MarketFeedUnavailableError,
+    PortalsError,
+    RateLimitError,
+    ResponseValidationError,
+    TransportError,
+)
+from .models import *  # noqa: F403
+
+__all__ = [
+    "AccessDeniedError",
+    "APIError",
+    "Amount",
+    "AsyncPortalsClient",
+    "AuthenticationError",
+    "BetOutcomeUnknownError",
+    "InvalidResponseError",
+    "MarketFeedUnavailableError",
+    "PortalsClient",
+    "PortalsError",
+    "RateLimit",
+    "RateLimitError",
+    "ResponseValidationError",
+    "TransportError",
+    "__api_version__",
+    "__version__",
+    *_models.__all__,
+]

portals/_contract.py

@@ -0,0 +1,2 @@
+# Generated by scripts/generate_models.py from specs/partners.en.json.
+__api_version__ = "1.0.0"

portals/_models.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from typing import Annotated, Any
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, PlainSerializer
+
+
+def _amount(value: Any) -> Decimal:
+    if not isinstance(value, (str, Decimal)):
+        raise ValueError("Amounts must be decimal strings or Decimal instances")
+    try:
+        result = Decimal(value)
+    except InvalidOperation as exc:
+        raise ValueError(f"Invalid decimal amount: {value!r}") from exc
+    if not result.is_finite():
+        raise ValueError("Amounts must be finite")
+    return result
+
+
+def _serialize_amount(value: Decimal) -> str:
+    return format(value, "f")
+
+
+Amount = Annotated[
+    Decimal,
+    BeforeValidator(_amount),
+    PlainSerializer(_serialize_amount, return_type=str),
+]
+
+
+class PortalsModel(BaseModel):
+    """Common Pydantic base model for Portals API schemas."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class PortalsRequest(PortalsModel):
+    """Base model for API request payloads (`extra="forbid"`)."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class PortalsResponse(PortalsModel):
+    """Base model for API response payloads (`extra="allow"`)."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimit:
+    """Rate-limit state parsed from `X-RateLimit-*` response headers."""
+
+    limit: int
+    remaining: int
+    reset_seconds: int
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> RateLimit | None:
+        """Parse rate-limit headers from an HTTP response, or return `None` if absent."""
+        normalized = {key.lower(): value for key, value in headers.items()}
+        try:
+            return cls(
+                limit=int(normalized["x-ratelimit-limit"]),
+                remaining=int(normalized["x-ratelimit-remaining"]),
+                reset_seconds=int(normalized["x-ratelimit-reset"]),
+            )
+        except (KeyError, TypeError, ValueError):
+            return None

portals/_transport.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Mapping, Sequence
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from functools import cache
+from typing import Any, TypeVar, overload
+
+import httpx2
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from ._models import RateLimit
+from ._version import __version__
+from .exceptions import (
+    AccessDeniedError,
+    APIError,
+    AuthenticationError,
+    BetOutcomeUnknownError,
+    InvalidResponseError,
+    MarketFeedUnavailableError,
+    RateLimitError,
+    ResponseValidationError,
+    TransportError,
+)
+
+
+@cache
+def _adapter(model: Any) -> TypeAdapter[Any]:
+    return TypeAdapter(model)
+
+
+_T = TypeVar("_T")
+
+
+def dump_model(model: BaseModel) -> dict[str, Any]:
+    return model.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+
+def prepare_params(params: Mapping[str, Any] | None) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in (params or {}).items():
+        if value is None:
+            continue
+        if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+            value = ",".join(str(_param_value(item)) for item in value)
+        else:
+            value = _param_value(value)
+        result[key] = value
+    return result
+
+
+def _param_value(value: Any) -> Any:
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, Decimal):
+        return format(value, "f")
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    return value
+
+
+class BaseTransport:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str,
+        timeout: float | httpx2.Timeout,
+    ) -> None:
+        if not api_key.strip():
+            raise ValueError("api_key must not be empty")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._headers = {
+            "Authorization": f"partners {api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"portals-api-python/{__version__}",
+        }
+        self.last_rate_limit: RateLimit | None = None
+
+    def _url(self, path: str) -> str:
+        if not path.startswith("/"):
+            raise ValueError("path must start with '/'")
+        return f"{self._base_url}{path}"
+
+    def _handle_response(self, response: httpx2.Response, response_model: Any) -> Any:
+        self.last_rate_limit = RateLimit.from_headers(response.headers)
+        if response.status_code >= 400:
+            self._raise_api_error(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise InvalidResponseError("The Portals API returned invalid JSON") from exc
+        if response_model is None:
+            return data
+        try:
+            return _adapter(response_model).validate_python(data)
+        except ValidationError as exc:
+            raise ResponseValidationError(
+                f"The response from {response.request.method} {response.request.url.path} "
+                "does not match the expected model",
+                response=data,
+            ) from exc
+
+    def _raise_api_error(self, response: httpx2.Response) -> None:
+        try:
+            data = response.json() if response.content else None
+        except ValueError:
+            data = None
+        if isinstance(data, dict):
+            message = str(
+                data.get("message")
+                or f"Portals API request failed with HTTP {response.status_code}"
+            )
+            code = str(data["code"]) if data.get("code") is not None else None
+        else:
+            message = response.text.strip() or (
+                f"Portals API request failed with HTTP {response.status_code}"
+            )
+            code = None
+
+        error_type: type[APIError] = APIError
+        if response.status_code == 401:
+            error_type = AuthenticationError
+        elif response.status_code == 403:
+            error_type = AccessDeniedError
+        elif response.status_code == 429:
+            error_type = RateLimitError
+        elif response.status_code == 503 and code == "MARKET_FEED_UNAVAILABLE":
+            error_type = MarketFeedUnavailableError
+        elif response.status_code == 504 and code == "BET_OUTCOME_UNKNOWN":
+            error_type = BetOutcomeUnknownError
+        raise error_type(
+            message,
+            status_code=response.status_code,
+            code=code,
+            response=data,
+            rate_limit=self.last_rate_limit,
+        )
+
+
+class SyncTransport(BaseTransport):
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str,
+        timeout: float | httpx2.Timeout,
+        client: httpx2.Client | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout)
+        self._client = client
+        self._owns_client = client is None
+        self._lock = threading.Lock()
+
+    def _get_client(self) -> httpx2.Client:
+        if self._client is None:
+            with self._lock:
+                if self._client is None:
+                    self._client = httpx2.Client(timeout=self._timeout)
+        return self._client
+
+    @overload
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: None = None,
+    ) -> Any: ...
+
+    @overload
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: type[_T],
+    ) -> _T: ...
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: Any = None,
+    ) -> Any:
+        if isinstance(json_data, BaseModel):
+            json_data = dump_model(json_data)
+        try:
+            response = self._get_client().request(
+                method,
+                self._url(path),
+                params=prepare_params(params),
+                json=json_data,
+                headers=self._headers,
+                timeout=self._timeout,
+            )
+        except httpx2.HTTPError as exc:
+            raise TransportError(f"Could not reach the Portals API: {exc}", original=exc) from exc
+        return self._handle_response(response, response_model)
+
+    def close(self) -> None:
+        client, self._client = self._client, None
+        if self._owns_client and client is not None:
+            client.close()
+
+
+class AsyncTransport(BaseTransport):
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str,
+        timeout: float | httpx2.Timeout,
+        client: httpx2.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url=base_url, timeout=timeout)
+        self._client = client
+        self._owns_client = client is None
+        self._lock = asyncio.Lock()
+
+    async def _get_client(self) -> httpx2.AsyncClient:
+        if self._client is None:
+            async with self._lock:
+                if self._client is None:
+                    self._client = httpx2.AsyncClient(timeout=self._timeout)
+        return self._client
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: None = None,
+    ) -> Any: ...
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: type[_T],
+    ) -> _T: ...
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: Any = None,
+    ) -> Any:
+        if isinstance(json_data, BaseModel):
+            json_data = dump_model(json_data)
+        try:
+            client = await self._get_client()
+            response = await client.request(
+                method,
+                self._url(path),
+                params=prepare_params(params),
+                json=json_data,
+                headers=self._headers,
+                timeout=self._timeout,
+            )
+        except httpx2.HTTPError as exc:
+            raise TransportError(f"Could not reach the Portals API: {exc}", original=exc) from exc
+        return self._handle_response(response, response_model)
+
+    async def aclose(self) -> None:
+        client, self._client = self._client, None
+        if self._owns_client and client is not None:
+            await client.aclose()

portals/_version.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from importlib.metadata import version
+
+__version__ = version("portals-api")

portals/client.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any, TypeVar, overload
+
+import httpx2
+
+from ._models import RateLimit
+from ._transport import AsyncTransport, SyncTransport
+from .resources.arena import Arena, AsyncArena
+from .resources.collection_offers import AsyncCollectionOffers, CollectionOffers
+from .resources.collections import AsyncCollections, Collections
+from .resources.market import AsyncMarket, Market
+from .resources.nfts import AsyncNFTs, NFTs
+from .resources.users import AsyncUsers, Users
+from .resources.wallet import AsyncWalletResource, WalletResource
+
+_T = TypeVar("_T")
+
+
+class PortalsClient:
+    """Synchronous client for the Portals Partners API.
+
+    Args:
+        api_key: Partner API token sent as `Authorization: partners <api_key>`.
+        base_url: Base URL for the Portals API.
+        timeout: Request timeout in seconds or an `httpx2.Timeout` instance.
+        client: Optional pre-configured `httpx2.Client`. When provided, the
+            caller retains ownership and is responsible for closing it.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://portal-market.com",
+        timeout: float | httpx2.Timeout = 30.0,
+        client: httpx2.Client | None = None,
+    ) -> None:
+        self._transport = SyncTransport(api_key, base_url=base_url, timeout=timeout, client=client)
+        self.arena = Arena(self._transport)
+        self.offers = CollectionOffers(self._transport)
+        self.collections = Collections(self._transport)
+        self.market = Market(self._transport)
+        self.nfts = NFTs(self._transport)
+        self.users = Users(self._transport)
+        self.wallet = WalletResource(self._transport)
+
+    @property
+    def last_rate_limit(self) -> RateLimit | None:
+        """Rate-limit metadata parsed from the most recent HTTP response, if present."""
+        return self._transport.last_rate_limit
+
+    @overload
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: None = None,
+    ) -> Any: ...
+
+    @overload
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: type[_T],
+    ) -> _T: ...
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: Any = None,
+    ) -> Any:
+        """Send an arbitrary request to the Portals API and optionally validate the response."""
+        return self._transport.request(
+            method,
+            path,
+            params=params,
+            json_data=json_data,
+            response_model=response_model,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client if it was created by this instance."""
+        self._transport.close()
+
+    def __enter__(self) -> PortalsClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncPortalsClient:
+    """Asynchronous client for the Portals Partners API.
+
+    Args:
+        api_key: Partner API token sent as `Authorization: partners <api_key>`.
+        base_url: Base URL for the Portals API.
+        timeout: Request timeout in seconds or an `httpx2.Timeout` instance.
+        client: Optional pre-configured `httpx2.AsyncClient`. When provided, the
+            caller retains ownership and is responsible for closing it.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://portal-market.com",
+        timeout: float | httpx2.Timeout = 30.0,
+        client: httpx2.AsyncClient | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(api_key, base_url=base_url, timeout=timeout, client=client)
+        self.arena = AsyncArena(self._transport)
+        self.offers = AsyncCollectionOffers(self._transport)
+        self.collections = AsyncCollections(self._transport)
+        self.market = AsyncMarket(self._transport)
+        self.nfts = AsyncNFTs(self._transport)
+        self.users = AsyncUsers(self._transport)
+        self.wallet = AsyncWalletResource(self._transport)
+
+    @property
+    def last_rate_limit(self) -> RateLimit | None:
+        """Rate-limit metadata parsed from the most recent HTTP response, if present."""
+        return self._transport.last_rate_limit
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: None = None,
+    ) -> Any: ...
+
+    @overload
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: type[_T],
+    ) -> _T: ...
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_data: Any = None,
+        response_model: Any = None,
+    ) -> Any:
+        """Send an arbitrary request to the Portals API and optionally validate the response."""
+        return await self._transport.request(
+            method,
+            path,
+            params=params,
+            json_data=json_data,
+            response_model=response_model,
+        )
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP client if it was created by this instance."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncPortalsClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()

portals/exceptions.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._models import RateLimit
+
+
+class PortalsError(Exception):
+    """Base exception for all errors raised by the Portals client."""
+
+
+class TransportError(PortalsError):
+    """Raised when an underlying network or HTTP transport operation fails."""
+
+    def __init__(self, message: str, *, original: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.original = original
+
+
+class InvalidResponseError(PortalsError):
+    """Raised when the API returns non-JSON content where JSON was expected."""
+
+
+class ResponseValidationError(InvalidResponseError):
+    """Raised when a JSON response payload fails Pydantic model validation."""
+
+    def __init__(self, message: str, *, response: Any = None) -> None:
+        super().__init__(message)
+        self.response = response
+
+
+class APIError(PortalsError):
+    """Raised when the Portals API returns an HTTP 4xx or 5xx error response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        response: Any = None,
+        rate_limit: RateLimit | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.response = response
+        self.rate_limit = rate_limit
+
+
+class AuthenticationError(APIError):
+    """Raised on HTTP 401 responses when the API key is missing or invalid."""
+
+
+class AccessDeniedError(APIError):
+    """Raised on HTTP 403 responses when the API key lacks permission."""
+
+
+class RateLimitError(APIError):
+    """Raised on HTTP 429 responses when the rate limit is exceeded."""
+
+
+class MarketFeedUnavailableError(APIError):
+    """Raised on HTTP 503 `MARKET_FEED_UNAVAILABLE` responses."""
+
+
+class BetOutcomeUnknownError(APIError):
+    """Raised on HTTP 504 `BET_OUTCOME_UNKNOWN` when an Arena bet outcome timed out."""