pkmnprices 1.0.0__tar.gz

pkmnprices-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: mypy src/pkmnprices
+      - run: pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pkmnprices-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

pkmnprices-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pkmn Prices
+
+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.

pkmnprices-1.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: pkmnprices
+Version: 1.0.0
+Summary: Python client for the Pkmn Prices API
+Project-URL: Homepage, https://pkmnprices.com
+Author: Pkmn Prices
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,cardmarket,ebay,pokemon,pricing,sdk,tcg,tcgplayer
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pkmnprices
+
+Python client for the [Pkmn Prices API](https://pkmnprices.com). Pokemon TCG card pricing from TCGPlayer, Cardmarket, and eBay.
+
+Sync and async clients, both built on httpx. Typed responses, typed errors, and iterators that page through results for you. Python 3.10+.
+
+## Install
+
+```bash
+pip install pkmnprices
+```
+
+## Usage
+
+```python
+from pkmnprices import PkmnPrices
+
+client = PkmnPrices("pk_your_key_here")
+
+page = client.cards.list(name="charizard", per_page=10)
+
+card = client.cards.get(page.data[0].id)
+for price in card.prices:
+    symbol = "€" if price.currency == "EUR" else "$"
+    print(f"{price.source}: {symbol}{price.market_price}")
+
+client.close()
+```
+
+The client is also a context manager:
+
+```python
+with PkmnPrices("pk_...") as client:
+    health = client.health()
+```
+
+### Async
+
+```python
+import asyncio
+from pkmnprices import AsyncPkmnPrices
+
+async def main():
+    async with AsyncPkmnPrices("pk_...") as client:
+        page = await client.cards.list(name="charizard")
+        async for card in client.cards.iterate(name="charizard"):
+            print(card.name)
+
+asyncio.run(main())
+```
+
+Get an API key from <https://pkmnprices.com/dashboard>.
+
+## Options
+
+```python
+PkmnPrices(
+    "pk_...",         # API key, sent as the x-api-key header
+    max_retries=2,    # retries on 429 rate limits and 5xx/network errors
+    timeout=30.0,     # per-request timeout in seconds
+)
+```
+
+Rate-limit `429`s are retried with backoff. Credit-limit `429`s (`credit_limit_exceeded`) are not, since they don't reset until the next day.
+
+## Pagination
+
+List endpoints return a `Page` (`.data`, `.pagination`). Listing endpoints (eBay/Cardmarket) return a `CursorPage`. Both resources expose iterators so you don't track pages or cursors:
+
+```python
+for card in client.cards.iterate(name="charizard"):
+    print(card.name)
+
+all_sets = client.sets.list_all(language="english")
+
+for sale in client.cards.listings.iterate_ebay(789, grader="PSA", grade="10"):
+    print(sale.title, sale.price)
+```
+
+## Currency
+
+Every price has a `currency` field. Pass `currency="usd"` or `currency="eur"` to filter, or leave it off to get everything your plan allows. EUR (Cardmarket) prices need a Pro plan; a free key asking for `eur` raises `ForbiddenError`.
+
+```python
+card = client.cards.get(789, currency="usd")
+```
+
+## Errors
+
+Everything raised subclasses `PkmnPricesError`, which carries `status`, `code`, `rate_limit`, and `retry_after`.
+
+```python
+from pkmnprices import ForbiddenError, NotFoundError, RateLimitError
+
+try:
+    client.cards.get(789, currency="eur")
+except ForbiddenError:
+    ...  # needs a higher plan
+except NotFoundError:
+    ...  # no such card
+except RateLimitError:
+    ...  # ran out of retries
+```
+
+Subclasses: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `CreditLimitError` and `RateLimitError` (429), `InternalServerError` (5xx), `APIConnectionError` (network/timeout).
+
+## License
+
+MIT

pkmnprices-1.0.0/README.md

@@ -0,0 +1,109 @@
+# pkmnprices
+
+Python client for the [Pkmn Prices API](https://pkmnprices.com). Pokemon TCG card pricing from TCGPlayer, Cardmarket, and eBay.
+
+Sync and async clients, both built on httpx. Typed responses, typed errors, and iterators that page through results for you. Python 3.10+.
+
+## Install
+
+```bash
+pip install pkmnprices
+```
+
+## Usage
+
+```python
+from pkmnprices import PkmnPrices
+
+client = PkmnPrices("pk_your_key_here")
+
+page = client.cards.list(name="charizard", per_page=10)
+
+card = client.cards.get(page.data[0].id)
+for price in card.prices:
+    symbol = "€" if price.currency == "EUR" else "$"
+    print(f"{price.source}: {symbol}{price.market_price}")
+
+client.close()
+```
+
+The client is also a context manager:
+
+```python
+with PkmnPrices("pk_...") as client:
+    health = client.health()
+```
+
+### Async
+
+```python
+import asyncio
+from pkmnprices import AsyncPkmnPrices
+
+async def main():
+    async with AsyncPkmnPrices("pk_...") as client:
+        page = await client.cards.list(name="charizard")
+        async for card in client.cards.iterate(name="charizard"):
+            print(card.name)
+
+asyncio.run(main())
+```
+
+Get an API key from <https://pkmnprices.com/dashboard>.
+
+## Options
+
+```python
+PkmnPrices(
+    "pk_...",         # API key, sent as the x-api-key header
+    max_retries=2,    # retries on 429 rate limits and 5xx/network errors
+    timeout=30.0,     # per-request timeout in seconds
+)
+```
+
+Rate-limit `429`s are retried with backoff. Credit-limit `429`s (`credit_limit_exceeded`) are not, since they don't reset until the next day.
+
+## Pagination
+
+List endpoints return a `Page` (`.data`, `.pagination`). Listing endpoints (eBay/Cardmarket) return a `CursorPage`. Both resources expose iterators so you don't track pages or cursors:
+
+```python
+for card in client.cards.iterate(name="charizard"):
+    print(card.name)
+
+all_sets = client.sets.list_all(language="english")
+
+for sale in client.cards.listings.iterate_ebay(789, grader="PSA", grade="10"):
+    print(sale.title, sale.price)
+```
+
+## Currency
+
+Every price has a `currency` field. Pass `currency="usd"` or `currency="eur"` to filter, or leave it off to get everything your plan allows. EUR (Cardmarket) prices need a Pro plan; a free key asking for `eur` raises `ForbiddenError`.
+
+```python
+card = client.cards.get(789, currency="usd")
+```
+
+## Errors
+
+Everything raised subclasses `PkmnPricesError`, which carries `status`, `code`, `rate_limit`, and `retry_after`.
+
+```python
+from pkmnprices import ForbiddenError, NotFoundError, RateLimitError
+
+try:
+    client.cards.get(789, currency="eur")
+except ForbiddenError:
+    ...  # needs a higher plan
+except NotFoundError:
+    ...  # no such card
+except RateLimitError:
+    ...  # ran out of retries
+```
+
+Subclasses: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `CreditLimitError` and `RateLimitError` (429), `InternalServerError` (5xx), `APIConnectionError` (network/timeout).
+
+## License
+
+MIT

pkmnprices-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pkmnprices"
+version = "1.0.0"
+description = "Python client for the Pkmn Prices API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Pkmn Prices" }]
+keywords = ["pokemon", "tcg", "pricing", "tcgplayer", "cardmarket", "ebay", "sdk", "api-client"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://pkmnprices.com"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "mypy>=1.10", "ruff>=0.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pkmnprices"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

pkmnprices-1.0.0/src/pkmnprices/__init__.py

@@ -0,0 +1,66 @@
+from .client import AsyncPkmnPrices, PkmnPrices
+from .errors import (
+    APIConnectionError,
+    BadRequestError,
+    ConflictError,
+    CreditLimitError,
+    ForbiddenError,
+    InternalServerError,
+    NotFoundError,
+    PkmnPricesError,
+    RateLimitError,
+    RateLimitInfo,
+    UnauthorizedError,
+)
+from .models import (
+    Card,
+    CardmarketListing,
+    CardSummary,
+    CursorInfo,
+    CursorPage,
+    EbayListing,
+    Health,
+    Page,
+    PageInfo,
+    Price,
+    PriceHistoryPoint,
+    Sealed,
+    SealedEbayListing,
+    SealedSummary,
+    Set,
+    SetRef,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "PkmnPrices",
+    "AsyncPkmnPrices",
+    "PkmnPricesError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "CreditLimitError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    "RateLimitInfo",
+    "Card",
+    "CardSummary",
+    "CardmarketListing",
+    "CursorInfo",
+    "CursorPage",
+    "EbayListing",
+    "Health",
+    "Page",
+    "PageInfo",
+    "Price",
+    "PriceHistoryPoint",
+    "Sealed",
+    "SealedEbayListing",
+    "SealedSummary",
+    "Set",
+    "SetRef",
+]

pkmnprices-1.0.0/src/pkmnprices/_endpoints.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .models import CursorInfo, CursorPage, Model, Page, PageInfo
+
+
+@dataclass
+class Request:
+    method: str
+    path: str
+    query: dict[str, Any] = field(default_factory=dict)
+    auth: bool = True
+
+
+def _clean(query: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in query.items() if value is not None}
+
+
+def health() -> Request:
+    return Request("GET", "/health", auth=False)
+
+
+def sets_list(**query: Any) -> Request:
+    return Request("GET", "/v1/sets", _clean(query))
+
+
+def sets_get(set_id: int) -> Request:
+    return Request("GET", f"/v1/sets/{set_id}")
+
+
+def cards_list(**query: Any) -> Request:
+    return Request("GET", "/v1/cards", _clean(query))
+
+
+def cards_get(card_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/cards/{card_id}", _clean(query))
+
+
+def cards_history(card_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/cards/{card_id}/prices/history", _clean(query))
+
+
+def cards_listings_ebay(card_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/cards/{card_id}/listings/ebay", _clean(query))
+
+
+def cards_listings_cardmarket(card_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/cards/{card_id}/listings/cardmarket", _clean(query))
+
+
+def sealed_list(**query: Any) -> Request:
+    return Request("GET", "/v1/sealed", _clean(query))
+
+
+def sealed_get(sealed_id: int) -> Request:
+    return Request("GET", f"/v1/sealed/{sealed_id}")
+
+
+def sealed_history(sealed_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/sealed/{sealed_id}/prices/history", _clean(query))
+
+
+def sealed_listings(sealed_id: int, **query: Any) -> Request:
+    return Request("GET", f"/v1/sealed/{sealed_id}/listings", _clean(query))
+
+
+def build_page(raw: dict[str, Any], model: type[Model]) -> Page[Any]:
+    items = [model.from_dict(item) for item in raw["data"]]
+    return Page(items, PageInfo.from_dict(raw["pagination"]))
+
+
+def build_cursor_page(raw: dict[str, Any], model: type[Model]) -> CursorPage[Any]:
+    items = [model.from_dict(item) for item in raw["data"]]
+    return CursorPage(items, CursorInfo.from_dict(raw["pagination"]))

pkmnprices-1.0.0/src/pkmnprices/_http.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import Any
+
+import httpx
+
+from ._endpoints import Request
+from .errors import (
+    APIConnectionError,
+    PkmnPricesError,
+    RateLimitError,
+    RateLimitInfo,
+    create_api_error,
+)
+
+_RETRYABLE_STATUS = {500, 502, 503, 504}
+_BASE_BACKOFF = 0.5
+_MAX_BACKOFF = 8.0
+
+
+def _int_header(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _rate_limit(headers: httpx.Headers) -> RateLimitInfo:
+    return RateLimitInfo(
+        credits_charged=_int_header(headers.get("x-credits-charged")),
+        credits_limit=_int_header(headers.get("x-credits-limit")),
+        rate_limit=_int_header(headers.get("x-rate-limit")),
+        rate_remaining=_int_header(headers.get("x-rate-remaining")),
+    )
+
+
+def _retry_after(headers: httpx.Headers) -> float | None:
+    raw = headers.get("retry-after")
+    if raw is None:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+def _handle(response: httpx.Response, path: str) -> Any:
+    rate_limit = _rate_limit(response.headers)
+
+    if response.is_success:
+        if not response.content:
+            return None
+        return response.json()
+
+    body: Any = None
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+
+    has_error = isinstance(body, dict) and isinstance(body.get("error"), dict)
+    code = body["error"]["code"] if has_error else "unknown"
+    message = (
+        body["error"]["message"]
+        if has_error
+        else f"Request to {path} failed with status {response.status_code}"
+    )
+
+    raise create_api_error(
+        status=response.status_code,
+        code=code,
+        message=message,
+        rate_limit=rate_limit,
+        retry_after=_retry_after(response.headers),
+    )
+
+
+def _is_retryable(error: Exception) -> bool:
+    if isinstance(error, (RateLimitError, APIConnectionError)):
+        return True
+    if isinstance(error, PkmnPricesError):
+        return error.status in _RETRYABLE_STATUS
+    return False
+
+
+def _backoff(attempt: int, retry_after: float | None) -> float:
+    if retry_after is not None:
+        return retry_after
+
+    exponential = _BASE_BACKOFF * 2**attempt
+    jitter = exponential * 0.25 * random.random()
+    return min(exponential + jitter, _MAX_BACKOFF)
+
+
+class _BaseTransport:
+    def __init__(self, api_key: str | None, max_retries: int) -> None:
+        self._api_key = api_key
+        self._max_retries = max_retries
+
+    def _headers(self, request: Request) -> dict[str, str]:
+        headers = {"accept": "application/json"}
+        if request.auth:
+            if not self._api_key:
+                raise APIConnectionError(
+                    "This endpoint requires an API key. Set api_key on the client."
+                )
+            headers["x-api-key"] = self._api_key
+        return headers
+
+
+class SyncTransport(_BaseTransport):
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str,
+        max_retries: int,
+        timeout: float,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        super().__init__(api_key, max_retries)
+        self._client = httpx.Client(base_url=base_url, timeout=timeout, transport=transport)
+
+    def request(self, request: Request) -> Any:
+        attempt = 0
+        while True:
+            try:
+                return self._attempt(request)
+            except Exception as error:
+                retryable = attempt < self._max_retries and _is_retryable(error)
+                if not retryable:
+                    raise
+
+                retry_after = error.retry_after if isinstance(error, PkmnPricesError) else None
+                time.sleep(_backoff(attempt, retry_after))
+                attempt += 1
+
+    def _attempt(self, request: Request) -> Any:
+        try:
+            response = self._client.request(
+                request.method, request.path, params=request.query, headers=self._headers(request)
+            )
+        except httpx.TimeoutException as error:
+            raise APIConnectionError(f"Request to {request.path} timed out", error) from error
+        except httpx.HTTPError as error:
+            raise APIConnectionError(f"Request to {request.path} failed", error) from error
+
+        return _handle(response, request.path)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncTransport(_BaseTransport):
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str,
+        max_retries: int,
+        timeout: float,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        super().__init__(api_key, max_retries)
+        self._client = httpx.AsyncClient(base_url=base_url, timeout=timeout, transport=transport)
+
+    async def request(self, request: Request) -> Any:
+        attempt = 0
+        while True:
+            try:
+                return await self._attempt(request)
+            except Exception as error:
+                retryable = attempt < self._max_retries and _is_retryable(error)
+                if not retryable:
+                    raise
+
+                retry_after = error.retry_after if isinstance(error, PkmnPricesError) else None
+                await asyncio.sleep(_backoff(attempt, retry_after))
+                attempt += 1
+
+    async def _attempt(self, request: Request) -> Any:
+        try:
+            response = await self._client.request(
+                request.method, request.path, params=request.query, headers=self._headers(request)
+            )
+        except httpx.TimeoutException as error:
+            raise APIConnectionError(f"Request to {request.path} timed out", error) from error
+        except httpx.HTTPError as error:
+            raise APIConnectionError(f"Request to {request.path} failed", error) from error
+
+        return _handle(response, request.path)
+
+    async def close(self) -> None:
+        await self._client.aclose()