tcgapi 0.2.1__py3-none-any.whl

tcgapi/__init__.py

@@ -0,0 +1,68 @@
+"""Official Python SDK for tcgapi.dev.
+
+>>> from tcgapi import TCGApi
+>>> tcg = TCGApi(api_key="tcg_live_...")
+>>> tcg.games.get("pokemon").data.name
+'Pokemon'
+
+Async variant:
+
+>>> from tcgapi import AsyncTCGApi
+>>> async with AsyncTCGApi() as tcg:
+...     resp = await tcg.search.cards("charizard")
+"""
+
+from .async_client import AsyncTCGApi
+from .client import TCGApi
+from .errors import (
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    TcgApiError,
+    TierError,
+)
+from .models import (
+    ApiKeyCreated,
+    ApiKeySummary,
+    BulkCard,
+    BulkPriceRow,
+    Card,
+    CardWithPrice,
+    Game,
+    Meta,
+    Price,
+    PriceHistoryPoint,
+    PriceMover,
+    RateLimit,
+    Response,
+    Set,
+    UsageResponse,
+)
+
+__version__ = "0.2.1"
+__all__ = [
+    "TCGApi",
+    "AsyncTCGApi",
+    # errors
+    "TcgApiError",
+    "AuthError",
+    "TierError",
+    "NotFoundError",
+    "RateLimitError",
+    # models
+    "Game",
+    "Set",
+    "Card",
+    "CardWithPrice",
+    "Price",
+    "PriceMover",
+    "PriceHistoryPoint",
+    "BulkCard",
+    "BulkPriceRow",
+    "ApiKeySummary",
+    "ApiKeyCreated",
+    "UsageResponse",
+    "Meta",
+    "RateLimit",
+    "Response",
+]

tcgapi/_transport.py

@@ -0,0 +1,66 @@
+"""Shared HTTP transport for sync + async clients."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from .errors import make_error
+
+DEFAULT_BASE_URL = "https://api.tcgapi.dev/v1"
+DEFAULT_TIMEOUT = 30.0
+
+
+class _BaseTransport:
+    """Common transport plumbing — header construction, error handling."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("TCGAPI_KEY")
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout if timeout is not None else DEFAULT_TIMEOUT
+        self.user_agent = user_agent
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Accept": "application/json"}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        if self.user_agent:
+            headers["User-Agent"] = self.user_agent
+        return headers
+
+    @staticmethod
+    def _clean_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
+        if not params:
+            return None
+        return {k: v for k, v in params.items() if v is not None}
+
+    @staticmethod
+    def _handle_response(resp: httpx.Response) -> dict[str, Any]:
+        try:
+            body: dict[str, Any] | None = resp.json() if resp.content else None
+        except ValueError:
+            body = None
+
+        if resp.is_error:
+            err = (body or {}).get("error") if body else None
+            # Standard tcgapi: error = {message, code}. x402 402: error = "string message".
+            if isinstance(err, dict):
+                message = err.get("message") or f"Request failed with status {resp.status_code}"
+                code = err.get("code")
+            elif isinstance(err, str):
+                message = err
+                code = None
+            else:
+                message = f"Request failed with status {resp.status_code}"
+                code = None
+            raise make_error(resp.status_code, message, code, body, resp.headers.get("Retry-After"))
+
+        return body or {}

tcgapi/async_client.py

@@ -0,0 +1,75 @@
+"""Async TCGApi client. Mirror of the sync client surface."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._transport import _BaseTransport
+from .resources.bulk import AsyncBulkResource
+from .resources.cards import AsyncCardsResource
+from .resources.export import AsyncExportResource
+from .resources.games import AsyncGamesResource
+from .resources.keys import AsyncKeysResource
+from .resources.prices import AsyncPricesResource
+from .resources.search import AsyncSearchResource
+from .resources.sets import AsyncSetsResource
+from .resources.usage import AsyncUsageResource
+
+
+class AsyncTCGApi(_BaseTransport):
+    """Asynchronous client. Backed by httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        user_agent: str | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(api_key=api_key, base_url=base_url, timeout=timeout, user_agent=user_agent)
+        self._client = client or httpx.AsyncClient(timeout=self.timeout)
+        self._owns_client = client is None
+
+        self.games = AsyncGamesResource(self)
+        self.sets = AsyncSetsResource(self)
+        self.cards = AsyncCardsResource(self)
+        self.search = AsyncSearchResource(self)
+        self.prices = AsyncPricesResource(self)
+        self.bulk = AsyncBulkResource(self)
+        self.export = AsyncExportResource(self)
+        self.keys = AsyncKeysResource(self)
+        self.usage = AsyncUsageResource(self)
+
+    async def _request(self, method: str, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        resp = await self._client.request(
+            method,
+            self.base_url + path,
+            params=self._clean_params(params),
+            headers=self._headers(),
+        )
+        return self._handle_response(resp)
+
+    async def _request_raw(self, method: str, path: str, params: dict[str, Any] | None = None) -> str:
+        resp = await self._client.request(
+            method,
+            self.base_url + path,
+            params=self._clean_params(params),
+            headers=self._headers(),
+        )
+        if resp.is_error:
+            self._handle_response(resp)  # raises
+        return resp.text
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncTCGApi":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

tcgapi/client.py

@@ -0,0 +1,79 @@
+"""Sync TCGApi client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._transport import _BaseTransport
+from .resources.bulk import BulkResource
+from .resources.cards import CardsResource
+from .resources.export import ExportResource
+from .resources.games import GamesResource
+from .resources.keys import KeysResource
+from .resources.prices import PricesResource
+from .resources.search import SearchResource
+from .resources.sets import SetsResource
+from .resources.usage import UsageResource
+
+
+class TCGApi(_BaseTransport):
+    """Synchronous client. Backed by httpx.Client.
+
+    Get a key at https://tcgapi.dev/dashboard. If `api_key` is omitted,
+    the client reads from the `TCGAPI_KEY` environment variable.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        user_agent: str | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(api_key=api_key, base_url=base_url, timeout=timeout, user_agent=user_agent)
+        self._client = client or httpx.Client(timeout=self.timeout)
+        self._owns_client = client is None
+
+        self.games = GamesResource(self)
+        self.sets = SetsResource(self)
+        self.cards = CardsResource(self)
+        self.search = SearchResource(self)
+        self.prices = PricesResource(self)
+        self.bulk = BulkResource(self)
+        self.export = ExportResource(self)
+        self.keys = KeysResource(self)
+        self.usage = UsageResource(self)
+
+    def _request(self, method: str, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        resp = self._client.request(
+            method,
+            self.base_url + path,
+            params=self._clean_params(params),
+            headers=self._headers(),
+        )
+        return self._handle_response(resp)
+
+    def _request_raw(self, method: str, path: str, params: dict[str, Any] | None = None) -> str:
+        resp = self._client.request(
+            method,
+            self.base_url + path,
+            params=self._clean_params(params),
+            headers=self._headers(),
+        )
+        if resp.is_error:
+            self._handle_response(resp)  # raises
+        return resp.text
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "TCGApi":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

tcgapi/errors.py

@@ -0,0 +1,78 @@
+"""Typed exceptions for tcgapi responses."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TcgApiError(Exception):
+    """Base exception for all tcgapi errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        code: str | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code or f"HTTP_{status}"
+        self.body = body
+
+
+class AuthError(TcgApiError):
+    """401 — invalid or missing API key."""
+
+    def __init__(self, message: str = "Invalid or missing API key", body: dict[str, Any] | None = None) -> None:
+        super().__init__(message, 401, "UNAUTHORIZED", body)
+
+
+class TierError(TcgApiError):
+    """403 — endpoint requires a higher tier than the current key has."""
+
+    def __init__(self, message: str = "Tier upgrade required", body: dict[str, Any] | None = None) -> None:
+        super().__init__(message, 403, "TIER_REQUIRED", body)
+
+
+class NotFoundError(TcgApiError):
+    """404 — resource not found."""
+
+    def __init__(self, message: str = "Resource not found", body: dict[str, Any] | None = None) -> None:
+        super().__init__(message, 404, "NOT_FOUND", body)
+
+
+class RateLimitError(TcgApiError):
+    """429 — daily request limit reached."""
+
+    def __init__(
+        self,
+        message: str = "Daily request limit reached",
+        retry_after: int | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, 429, "RATE_LIMITED", body)
+        self.retry_after = retry_after
+
+
+def make_error(
+    status: int,
+    message: str,
+    code: str | None,
+    body: dict[str, Any] | None,
+    retry_after: str | None,
+) -> TcgApiError:
+    if status == 401:
+        return AuthError(message, body)
+    if status == 403:
+        return TierError(message, body)
+    if status == 404:
+        return NotFoundError(message, body)
+    if status == 429:
+        ra: int | None
+        try:
+            ra = int(retry_after) if retry_after else None
+        except (TypeError, ValueError):
+            ra = None
+        return RateLimitError(message, ra, body)
+    return TcgApiError(message, status, code, body)

tcgapi/models.py

@@ -0,0 +1,211 @@
+"""Pydantic models for tcgapi responses. Mirrors openapi/spec.yaml."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+T = TypeVar("T")
+
+
+class _Base(BaseModel):
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+
+class Game(_Base):
+    id: int
+    name: str
+    slug: str
+    tcgplayer_id: int
+    priority: int | None = None
+    set_count: int | None = None
+    card_count: int | None = None
+    image_url: str | None = None
+    logo_url: str | None = None
+    last_synced_at: str | None = None
+
+
+class Set(_Base):
+    id: int
+    name: str
+    slug: str | None = None
+    tcgplayer_id: int
+    abbreviation: str | None = None
+    release_date: str | None = None
+    card_count: int | None = None
+    image_url: str | None = None
+    set_icon_url: str | None = None
+    game_name: str | None = None
+    game_slug: str | None = None
+
+
+class Card(_Base):
+    id: int
+    name: str
+    clean_name: str | None = None
+    number: str | None = None
+    rarity: str | None = None
+    image_url: str | None = None
+    tcgplayer_id: int
+    tcgplayer_url: str | None = None
+    product_type: str | None = None
+    foil_only: int | None = None
+    game_name: str | None = None
+    game_slug: str | None = None
+    set_name: str | None = None
+    set_slug: str | None = None
+    custom_attributes: dict[str, Any] | None = None
+
+
+class Price(_Base):
+    card_id: int
+    printing: str | None = None
+    market_price: float | None = None
+    low_price: float | None = None
+    median_price: float | None = None
+    lowest_with_shipping: float | None = None
+    buylist_price: float | None = None
+    price_change_24h: float | None = None
+    price_change_7d: float | None = None
+    price_change_30d: float | None = None
+    last_updated_at: str | None = None
+    # Sales velocity — Pro/Business tiers only; the API omits these below Pro.
+    sales_volume: int | None = None
+    avg_sales_price: float | None = None
+    sales_as_of: str | None = None
+
+
+class CardWithPrice(_Base):
+    id: int
+    name: str
+    clean_name: str | None = None
+    number: str | None = None
+    rarity: str | None = None
+    tcgplayer_id: int
+    product_type: str | None = None
+    foil_only: int | None = None
+    total_listings: int | None = None
+    printing: str | None = None
+    market_price: float | None = None
+    low_price: float | None = None
+    median_price: float | None = None
+    lowest_with_shipping: float | None = None
+    price_updated_at: str | None = None
+    image_url: str | None = None
+    game_name: str | None = None
+    game_slug: str | None = None
+    set_name: str | None = None
+
+
+class PriceMover(_Base):
+    card_id: int
+    name: str
+    tcgplayer_id: int
+    product_type: str | None = None
+    foil_only: int | None = None
+    set_name: str | None = None
+    game_name: str | None = None
+    game_slug: str | None = None
+    printing: str | None = None
+    market_price: float
+    price_change: float
+    last_updated_at: str | None = None
+    image_url: str | None = None
+
+
+class BulkPriceRow(_Base):
+    card_id: int
+    name: str | None = None
+    tcgplayer_id: int | None = None
+    product_type: str | None = None
+    foil_only: int | None = None
+    printing: str | None = None
+    market_price: float | None = None
+    low_price: float | None = None
+    median_price: float | None = None
+    lowest_with_shipping: float | None = None
+    buylist_price: float | None = None
+    price_change_24h: float | None = None
+    price_change_7d: float | None = None
+    price_change_30d: float | None = None
+    last_updated_at: str | None = None
+    image_url: str | None = None
+
+
+class BulkCard(Card):
+    prices: list[Price] = Field(default_factory=list)
+
+
+class PriceHistoryPoint(_Base):
+    date: str
+    printing: str | None = None
+    market_price: float | None = None
+    low_price: float | None = None
+    avg_sales_price: float | None = None
+    sales_volume: int | None = None
+
+
+class Meta(_Base):
+    total: int | None = None
+    page: int | None = None
+    per_page: int | None = None
+    has_more: bool | None = None
+
+
+class RateLimit(_Base):
+    daily_limit: int
+    daily_remaining: int
+    daily_reset: str
+
+
+class ApiKeySummary(_Base):
+    id: str
+    key_prefix: str
+    name: str
+    tier: str
+    is_active: int
+    total_requests: int
+    created_at: str
+
+
+class ApiKeyCreated(_Base):
+    id: str
+    key: str
+    key_prefix: str
+    name: str
+    tier: str
+    message: str | None = None
+
+
+class UsageAccount(_Base):
+    today_requests: int
+    daily_limit: int
+    daily_remaining: int
+
+
+class UsageKey(_Base):
+    id: str
+    key_prefix: str
+    name: str
+    tier: str
+    total_requests: int
+
+
+class UsageSubscription(_Base):
+    plan: str
+    status: str
+
+
+class UsageResponse(_Base):
+    account: UsageAccount
+    keys: list[UsageKey] = Field(default_factory=list)
+    subscription: UsageSubscription | None = None
+
+
+class Response(_Base, Generic[T]):
+    """Wrapper returned by every method. Reach `.data`, `.meta`, `.rate_limit`."""
+
+    data: T
+    meta: Meta | None = None
+    rate_limit: RateLimit | None = None

tcgapi/resources/_base.py

@@ -0,0 +1,27 @@
+"""Helpers shared by every resource module."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from ..models import Meta, RateLimit, Response
+
+T = TypeVar("T")
+
+
+def parse_response(model: type[T], body: dict[str, Any]) -> Response[T]:
+    """Coerce a raw response body into a typed Response[T] wrapper."""
+    raw_data = body.get("data")
+    if isinstance(model, type) and issubclass(model, BaseModel):
+        data = model.model_validate(raw_data)
+    else:
+        # Generic types (list[X], dict[str, list[X]], etc.) handled with TypeAdapter via the caller.
+        from pydantic import TypeAdapter
+
+        data = TypeAdapter(model).validate_python(raw_data)
+
+    meta = Meta.model_validate(body["meta"]) if body.get("meta") else None
+    rate_limit = RateLimit.model_validate(body["rate_limit"]) if body.get("rate_limit") else None
+    return Response[T](data=data, meta=meta, rate_limit=rate_limit)  # type: ignore[valid-type]