tcgapi 0.2.1__tar.gz

tcgapi-0.2.1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+.venv/
+venv/
+.env
+.coverage
+htmlcov/

tcgapi-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tcgapi.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tcgapi-0.2.1/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: tcgapi
+Version: 0.2.1
+Summary: Official Python SDK for tcgapi.dev — pricing data for Pokemon, Magic: The Gathering, Yu-Gi-Oh!, Lorcana, One Piece, and 80+ more trading card games.
+Project-URL: Homepage, https://tcgapi.dev
+Project-URL: Documentation, https://tcgapi.dev/api/
+Project-URL: Source, https://github.com/gordy-ftw/tcgapi-python
+Project-URL: Issues, https://github.com/gordy-ftw/tcgapi-python/issues
+Project-URL: Quickstart, https://tcgapi.dev/quickstart/
+Author: tcgapi.dev
+License: MIT
+License-File: LICENSE
+Keywords: card-prices,flesh-and-blood,lorcana,magic-the-gathering,mtg,one-piece-tcg,pokemon,pokemon-prices,pokemon-tcg,sdk,tcg,tcg-api,tcgapi,tcgplayer,trading-cards,yugioh
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: eval-type-backport>=0.2; python_version < '3.10'
+Requires-Dist: httpx>=0.25
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tcgapi
+
+[![PyPI](https://img.shields.io/pypi/v/tcgapi.svg)](https://pypi.org/project/tcgapi/)
+[![Python](https://img.shields.io/pypi/pyversions/tcgapi.svg)](https://pypi.org/project/tcgapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python SDK for [**tcgapi.dev**](https://tcgapi.dev) — a unified pricing API for **89+ trading card games**, including:
+
+- Pokémon TCG (English + Japanese)
+- Magic: The Gathering
+- Yu-Gi-Oh!
+- Lorcana
+- One Piece Card Game
+- Flesh and Blood
+- Star Wars Unlimited
+- Digimon, Dragon Ball Super, Riftbound, Union Arena, Final Fantasy TCG, Weiss Schwarz, Cardfight!! Vanguard, and dozens more.
+
+Real-time market prices, full price history, fuzzy search, bulk lookups, and exports — all from one HTTP API. Sync and async clients, fully typed with Pydantic.
+
+## Install
+
+```bash
+pip install tcgapi
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+Get a free API key at [**tcgapi.dev/dashboard**](https://tcgapi.dev/dashboard) (100 requests/day, no credit card).
+
+```python
+from tcgapi import TCGApi
+
+tcg = TCGApi(api_key="tcg_live_...")  # or set TCGAPI_KEY env var
+
+# Look up a single card
+card = tcg.cards.get(123456)
+print(card.data.name)
+
+# Get every printing's current price
+prices = tcg.cards.prices(123456)
+for p in prices.data:
+    print(f"{p.printing}: ${p.market_price}")
+```
+
+If `api_key` is omitted, the client reads from `TCGAPI_KEY`.
+
+## Examples
+
+### Search across every game
+
+```python
+results = tcg.search.cards(
+    "charizard",
+    game="pokemon",
+    sort="price_desc",
+    per_page=20,
+)
+for card in results.data:
+    print(card.name, card.set_name, card.market_price)
+```
+
+### Iterate without pagination boilerplate
+
+```python
+for card in tcg.search.iter("lightning", game="magic"):
+    # walks meta.has_more automatically — caps at the API's 200/page max
+    ...
+```
+
+### Browse sets
+
+```python
+games = tcg.games.list()
+pokemon_sets = tcg.games.sets("pokemon")
+surging_sparks = next(
+    (s for s in pokemon_sets.data if "Surging Sparks" in s.name), None
+)
+
+if surging_sparks:
+    cards = tcg.sets.cards(surging_sparks.id, sort="price_desc")
+    print(f"{surging_sparks.name}: {cards.meta.total} cards")
+```
+
+### Bulk price lookup (Pro+)
+
+```python
+# Auto-chunks if you pass more than 500 IDs.
+bulk = tcg.bulk.prices([1, 2, 3, ...])  # thousands ok
+print(f"Got prices for {len(bulk.data)} card-printings")
+```
+
+### Top movers
+
+```python
+movers = tcg.prices.top_movers(
+    game="pokemon",
+    direction="up",
+    period="7d",
+    limit=10,
+)
+for m in movers.data:
+    print(f"{m.name} ({m.set_name}): +{m.price_change}% — ${m.market_price}")
+```
+
+### Price history (Hobby+)
+
+```python
+# Window scales with your tier: free=7d, hobby=30d, starter=90d, pro/business=full.
+history = tcg.cards.history(123456, range="year")
+for point in history.data:
+    print(point.date, point.market_price)
+```
+
+### Async client
+
+The async API mirrors the sync surface verbatim:
+
+```python
+import asyncio
+from tcgapi import AsyncTCGApi
+
+async def main():
+    async with AsyncTCGApi() as tcg:
+        resp = await tcg.search.cards("charizard", game="pokemon")
+        async for card in tcg.search.iter("dragon", game="magic"):
+            print(card.name)
+
+asyncio.run(main())
+```
+
+## Rate limits
+
+Every successful response carries the live rate-limit budget:
+
+```python
+resp = tcg.games.list()
+print(resp.rate_limit)
+# RateLimit(daily_limit=10000, daily_remaining=9871, daily_reset='2026-04-29T00:00:00.000Z')
+```
+
+When you exceed the daily limit you'll get a typed `RateLimitError`:
+
+```python
+from tcgapi import RateLimitError
+
+try:
+    tcg.cards.get(123)
+except RateLimitError as err:
+    print(f"Hit the limit — retry in {err.retry_after}s")
+```
+
+Other error classes: `AuthError` (401), `TierError` (403), `NotFoundError` (404), `TcgApiError` (anything else). All extend `Exception`.
+
+## Tiers
+
+| Plan | Daily requests | History | Bulk endpoints | Sales velocity |
+|------|---------------|---------|----------------|----------------|
+| Free | 100 | 7 days | — | — |
+| Hobby ($9.99/mo) | 1,000 | 30 days | — | — |
+| Starter ($19.99/mo) | 2,500 | 90 days | Limited | — |
+| Pro ($49.99/mo) | 10,000 | Full | Yes | Yes |
+| Business ($99.99/mo) | 50,000 | Full | Yes | Yes |
+
+Sales velocity = `sales_volume`, `avg_sales_price`, and `sales_as_of` on price responses (Pro+). The fields are absent below Pro.
+
+Or pay per request via [x402](https://tcgapi.dev/api/x402) — no signup, USDC on Base or Solana.
+
+## API reference
+
+Full endpoint reference: [**tcgapi.dev/api**](https://tcgapi.dev/api/)
+OpenAPI spec: [**tcgapi.dev/openapi.yaml**](https://tcgapi.dev/openapi.yaml)
+Quickstart guide: [**tcgapi.dev/quickstart**](https://tcgapi.dev/quickstart/)
+
+## License
+
+MIT

tcgapi-0.2.1/README.md

@@ -0,0 +1,178 @@
+# tcgapi
+
+[![PyPI](https://img.shields.io/pypi/v/tcgapi.svg)](https://pypi.org/project/tcgapi/)
+[![Python](https://img.shields.io/pypi/pyversions/tcgapi.svg)](https://pypi.org/project/tcgapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python SDK for [**tcgapi.dev**](https://tcgapi.dev) — a unified pricing API for **89+ trading card games**, including:
+
+- Pokémon TCG (English + Japanese)
+- Magic: The Gathering
+- Yu-Gi-Oh!
+- Lorcana
+- One Piece Card Game
+- Flesh and Blood
+- Star Wars Unlimited
+- Digimon, Dragon Ball Super, Riftbound, Union Arena, Final Fantasy TCG, Weiss Schwarz, Cardfight!! Vanguard, and dozens more.
+
+Real-time market prices, full price history, fuzzy search, bulk lookups, and exports — all from one HTTP API. Sync and async clients, fully typed with Pydantic.
+
+## Install
+
+```bash
+pip install tcgapi
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+Get a free API key at [**tcgapi.dev/dashboard**](https://tcgapi.dev/dashboard) (100 requests/day, no credit card).
+
+```python
+from tcgapi import TCGApi
+
+tcg = TCGApi(api_key="tcg_live_...")  # or set TCGAPI_KEY env var
+
+# Look up a single card
+card = tcg.cards.get(123456)
+print(card.data.name)
+
+# Get every printing's current price
+prices = tcg.cards.prices(123456)
+for p in prices.data:
+    print(f"{p.printing}: ${p.market_price}")
+```
+
+If `api_key` is omitted, the client reads from `TCGAPI_KEY`.
+
+## Examples
+
+### Search across every game
+
+```python
+results = tcg.search.cards(
+    "charizard",
+    game="pokemon",
+    sort="price_desc",
+    per_page=20,
+)
+for card in results.data:
+    print(card.name, card.set_name, card.market_price)
+```
+
+### Iterate without pagination boilerplate
+
+```python
+for card in tcg.search.iter("lightning", game="magic"):
+    # walks meta.has_more automatically — caps at the API's 200/page max
+    ...
+```
+
+### Browse sets
+
+```python
+games = tcg.games.list()
+pokemon_sets = tcg.games.sets("pokemon")
+surging_sparks = next(
+    (s for s in pokemon_sets.data if "Surging Sparks" in s.name), None
+)
+
+if surging_sparks:
+    cards = tcg.sets.cards(surging_sparks.id, sort="price_desc")
+    print(f"{surging_sparks.name}: {cards.meta.total} cards")
+```
+
+### Bulk price lookup (Pro+)
+
+```python
+# Auto-chunks if you pass more than 500 IDs.
+bulk = tcg.bulk.prices([1, 2, 3, ...])  # thousands ok
+print(f"Got prices for {len(bulk.data)} card-printings")
+```
+
+### Top movers
+
+```python
+movers = tcg.prices.top_movers(
+    game="pokemon",
+    direction="up",
+    period="7d",
+    limit=10,
+)
+for m in movers.data:
+    print(f"{m.name} ({m.set_name}): +{m.price_change}% — ${m.market_price}")
+```
+
+### Price history (Hobby+)
+
+```python
+# Window scales with your tier: free=7d, hobby=30d, starter=90d, pro/business=full.
+history = tcg.cards.history(123456, range="year")
+for point in history.data:
+    print(point.date, point.market_price)
+```
+
+### Async client
+
+The async API mirrors the sync surface verbatim:
+
+```python
+import asyncio
+from tcgapi import AsyncTCGApi
+
+async def main():
+    async with AsyncTCGApi() as tcg:
+        resp = await tcg.search.cards("charizard", game="pokemon")
+        async for card in tcg.search.iter("dragon", game="magic"):
+            print(card.name)
+
+asyncio.run(main())
+```
+
+## Rate limits
+
+Every successful response carries the live rate-limit budget:
+
+```python
+resp = tcg.games.list()
+print(resp.rate_limit)
+# RateLimit(daily_limit=10000, daily_remaining=9871, daily_reset='2026-04-29T00:00:00.000Z')
+```
+
+When you exceed the daily limit you'll get a typed `RateLimitError`:
+
+```python
+from tcgapi import RateLimitError
+
+try:
+    tcg.cards.get(123)
+except RateLimitError as err:
+    print(f"Hit the limit — retry in {err.retry_after}s")
+```
+
+Other error classes: `AuthError` (401), `TierError` (403), `NotFoundError` (404), `TcgApiError` (anything else). All extend `Exception`.
+
+## Tiers
+
+| Plan | Daily requests | History | Bulk endpoints | Sales velocity |
+|------|---------------|---------|----------------|----------------|
+| Free | 100 | 7 days | — | — |
+| Hobby ($9.99/mo) | 1,000 | 30 days | — | — |
+| Starter ($19.99/mo) | 2,500 | 90 days | Limited | — |
+| Pro ($49.99/mo) | 10,000 | Full | Yes | Yes |
+| Business ($99.99/mo) | 50,000 | Full | Yes | Yes |
+
+Sales velocity = `sales_volume`, `avg_sales_price`, and `sales_as_of` on price responses (Pro+). The fields are absent below Pro.
+
+Or pay per request via [x402](https://tcgapi.dev/api/x402) — no signup, USDC on Base or Solana.
+
+## API reference
+
+Full endpoint reference: [**tcgapi.dev/api**](https://tcgapi.dev/api/)
+OpenAPI spec: [**tcgapi.dev/openapi.yaml**](https://tcgapi.dev/openapi.yaml)
+Quickstart guide: [**tcgapi.dev/quickstart**](https://tcgapi.dev/quickstart/)
+
+## License
+
+MIT

tcgapi-0.2.1/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tcgapi"
+version = "0.2.1"
+description = "Official Python SDK for tcgapi.dev — pricing data for Pokemon, Magic: The Gathering, Yu-Gi-Oh!, Lorcana, One Piece, and 80+ more trading card games."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "tcgapi.dev" }]
+keywords = [
+  "tcg",
+  "tcgplayer",
+  "pokemon",
+  "pokemon-tcg",
+  "pokemon-prices",
+  "magic-the-gathering",
+  "mtg",
+  "yugioh",
+  "lorcana",
+  "one-piece-tcg",
+  "flesh-and-blood",
+  "card-prices",
+  "tcg-api",
+  "tcgapi",
+  "trading-cards",
+  "sdk",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Games/Entertainment",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.25",
+  "pydantic>=2.0",
+  # Lets pydantic evaluate `int | None` (PEP 604) annotations on Python 3.9,
+  # where the `|` union operator isn't available at runtime.
+  "eval_type_backport>=0.2; python_version < '3.10'",
+]
+
+[project.urls]
+Homepage = "https://tcgapi.dev"
+Documentation = "https://tcgapi.dev/api/"
+Source = "https://github.com/gordy-ftw/tcgapi-python"
+Issues = "https://github.com/gordy-ftw/tcgapi-python/issues"
+Quickstart = "https://tcgapi.dev/quickstart/"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+  "ruff>=0.1",
+  "mypy>=1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["tcgapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/tcgapi", "/README.md", "/LICENSE"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B", "UP"]
+# UP037: keep string-quoted TYPE_CHECKING refs even with `from __future__ import annotations`
+# UP006/UP035: keep typing.List/Dict generic forms readable on 3.9
+ignore = ["E501", "UP037", "UP006", "UP035"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

tcgapi-0.2.1/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-0.2.1/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 {}