tcgapi 0.2.1__tar.gz → 0.3.0__tar.gz

{tcgapi-0.2.1 → tcgapi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcgapi
-Version: 0.2.1
+Version: 0.3.0
 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/
@@ -127,6 +127,22 @@ bulk = tcg.bulk.prices([1, 2, 3, ...])  # thousands ok
 print(f"Got prices for {len(bulk.data)} card-printings")
 ```
 
+### Per-condition prices (Pro+)
+
+```python
+# Price floors per (printing, condition) — Near Mint, Lightly Played, etc.
+conditions = tcg.cards.conditions(13217, printing="Holofoil")
+for row in conditions.data:
+    # median_with_shipping is robust to $0.01 junk listings — prefer it when pricing inventory
+    print(f"{row.printing} / {row.condition}: ${row.median_with_shipping}")
+print(conditions.meta.cached, conditions.meta.condition_counts)
+
+# Bulk variant — up to 500 cards per call, served from the nightly cache.
+# Cards without condition data yet are absent; fetch them once via
+# tcg.cards.conditions() to warm them.
+bulk_conditions = tcg.bulk.conditions([13217, 13218, 13219])
+```
+
 ### Top movers
 
 ```python

{tcgapi-0.2.1 → tcgapi-0.3.0}/README.md

@@ -91,6 +91,22 @@ bulk = tcg.bulk.prices([1, 2, 3, ...])  # thousands ok
 print(f"Got prices for {len(bulk.data)} card-printings")
 ```
 
+### Per-condition prices (Pro+)
+
+```python
+# Price floors per (printing, condition) — Near Mint, Lightly Played, etc.
+conditions = tcg.cards.conditions(13217, printing="Holofoil")
+for row in conditions.data:
+    # median_with_shipping is robust to $0.01 junk listings — prefer it when pricing inventory
+    print(f"{row.printing} / {row.condition}: ${row.median_with_shipping}")
+print(conditions.meta.cached, conditions.meta.condition_counts)
+
+# Bulk variant — up to 500 cards per call, served from the nightly cache.
+# Cards without condition data yet are absent; fetch them once via
+# tcg.cards.conditions() to warm them.
+bulk_conditions = tcg.bulk.conditions([13217, 13218, 13219])
+```
+
 ### Top movers
 
 ```python

{tcgapi-0.2.1 → tcgapi-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tcgapi"
-version = "0.2.1"
+version = "0.3.0"
 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"

{tcgapi-0.2.1 → tcgapi-0.3.0}/tcgapi/__init__.py

@@ -25,9 +25,12 @@ from .models import (
     ApiKeyCreated,
     ApiKeySummary,
     BulkCard,
+    BulkConditionRow,
     BulkPriceRow,
     Card,
     CardWithPrice,
+    ConditionMeta,
+    ConditionPrice,
     Game,
     Meta,
     Price,
@@ -39,7 +42,7 @@ from .models import (
     UsageResponse,
 )
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 __all__ = [
     "TCGApi",
     "AsyncTCGApi",
@@ -59,6 +62,9 @@ __all__ = [
     "PriceHistoryPoint",
     "BulkCard",
     "BulkPriceRow",
+    "ConditionPrice",
+    "BulkConditionRow",
+    "ConditionMeta",
     "ApiKeySummary",
     "ApiKeyCreated",
     "UsageResponse",

{tcgapi-0.2.1 → tcgapi-0.3.0}/tcgapi/models.py

@@ -137,6 +137,33 @@ class BulkCard(Card):
     prices: list[Price] = Field(default_factory=list)
 
 
+class ConditionPrice(_Base):
+    """Per-condition price floors for one (printing, condition) pair (Pro+)."""
+
+    card_id: int
+    printing: str | None = None
+    # TCGPlayer condition grade, e.g. "Near Mint", "Lightly Played".
+    condition: str
+    language: str | None = None
+    # Lowest listed item price for this printing + condition.
+    low_price: float | None = None
+    # Lowest listed price including shipping.
+    lowest_with_shipping: float | None = None
+    # Median of sampled shipping-inclusive prices. None when sample_count < 3 —
+    # prefer this over low_price when pricing inventory (robust to $0.01 junk listings).
+    median_with_shipping: float | None = None
+    # Listings sampled for this row (not total market depth — see ConditionMeta.condition_counts).
+    sample_count: int | None = None
+    last_updated_at: str | None = None
+
+
+class BulkConditionRow(ConditionPrice):
+    """Row shape of /bulk/conditions — a ConditionPrice plus card identity."""
+
+    name: str | None = None
+    tcgplayer_id: int | None = None
+
+
 class PriceHistoryPoint(_Base):
     date: str
     printing: str | None = None
@@ -153,6 +180,20 @@ class Meta(_Base):
     has_more: bool | None = None
 
 
+class ConditionMeta(Meta):
+    """Meta for /cards/{id}/prices/conditions — cache/staleness signals."""
+
+    # True when served from cache without a live refresh.
+    cached: bool | None = None
+    # Present (True) when rows are older than 24h and a live refresh
+    # wasn't possible (quota or upstream failure).
+    stale: bool | None = None
+    as_of: str | None = None
+    # Total live listings per condition across ALL printings
+    # (only present on live-refreshed responses).
+    condition_counts: dict[str, int] | None = None
+
+
 class RateLimit(_Base):
     daily_limit: int
     daily_remaining: int

{tcgapi-0.2.1 → tcgapi-0.3.0}/tcgapi/resources/_base.py

@@ -11,8 +11,14 @@ 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."""
+def parse_response(
+    model: type[T], body: dict[str, Any], *, meta_model: type[Meta] = Meta
+) -> Response[T]:
+    """Coerce a raw response body into a typed Response[T] wrapper.
+
+    `meta_model` overrides the meta shape for endpoints with a non-standard
+    meta (e.g. ConditionMeta for per-condition prices).
+    """
     raw_data = body.get("data")
     if isinstance(model, type) and issubclass(model, BaseModel):
         data = model.model_validate(raw_data)
@@ -22,6 +28,6 @@ def parse_response(model: type[T], body: dict[str, Any]) -> Response[T]:
 
         data = TypeAdapter(model).validate_python(raw_data)
 
-    meta = Meta.model_validate(body["meta"]) if body.get("meta") else None
+    meta = meta_model.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]

{tcgapi-0.2.1 → tcgapi-0.3.0}/tcgapi/resources/bulk.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Literal
 
-from ..models import BulkCard, BulkPriceRow, PriceHistoryPoint, Response
+from ..models import BulkCard, BulkConditionRow, BulkPriceRow, PriceHistoryPoint, Response
 from ._base import parse_response
 
 if TYPE_CHECKING:
@@ -14,6 +14,7 @@ if TYPE_CHECKING:
 BULK_PRICES_MAX = 500
 BULK_CARDS_MAX = 100
 BULK_HISTORY_MAX = 50
+BULK_CONDITIONS_MAX = 500
 
 RangeLiteral = Literal["month", "quarter", "year", "all"]
 
@@ -56,6 +57,24 @@ class BulkResource:
             last = resp
         return Response[list[BulkCard]](data=rows, rate_limit=last.rate_limit if last else None)
 
+    def conditions(self, ids: list[int]) -> Response[list[BulkConditionRow]]:
+        # Pro+ only. Cache-only: cards without condition data yet are absent —
+        # request them once via cards.conditions() to warm them.
+        if len(ids) <= BULK_CONDITIONS_MAX:
+            body = self._client._request("GET", "/bulk/conditions", {"ids": _ids(ids)})
+            return parse_response(list[BulkConditionRow], body)
+        rows: list[BulkConditionRow] = []
+        last: Response[list[BulkConditionRow]] | None = None
+        for i in range(0, len(ids), BULK_CONDITIONS_MAX):
+            chunk = ids[i : i + BULK_CONDITIONS_MAX]
+            body = self._client._request("GET", "/bulk/conditions", {"ids": _ids(chunk)})
+            resp: Response[list[BulkConditionRow]] = parse_response(list[BulkConditionRow], body)
+            rows.extend(resp.data)
+            last = resp
+        return Response[list[BulkConditionRow]](
+            data=rows, rate_limit=last.rate_limit if last else None
+        )
+
     def history(
         self,
         ids: list[int],
@@ -114,6 +133,24 @@ class AsyncBulkResource:
             last = resp
         return Response[list[BulkCard]](data=rows, rate_limit=last.rate_limit if last else None)
 
+    async def conditions(self, ids: list[int]) -> Response[list[BulkConditionRow]]:
+        # Pro+ only. Cache-only: cards without condition data yet are absent —
+        # request them once via cards.conditions() to warm them.
+        if len(ids) <= BULK_CONDITIONS_MAX:
+            body = await self._client._request("GET", "/bulk/conditions", {"ids": _ids(ids)})
+            return parse_response(list[BulkConditionRow], body)
+        rows: list[BulkConditionRow] = []
+        last: Response[list[BulkConditionRow]] | None = None
+        for i in range(0, len(ids), BULK_CONDITIONS_MAX):
+            chunk = ids[i : i + BULK_CONDITIONS_MAX]
+            body = await self._client._request("GET", "/bulk/conditions", {"ids": _ids(chunk)})
+            resp: Response[list[BulkConditionRow]] = parse_response(list[BulkConditionRow], body)
+            rows.extend(resp.data)
+            last = resp
+        return Response[list[BulkConditionRow]](
+            data=rows, rate_limit=last.rate_limit if last else None
+        )
+
     async def history(
         self,
         ids: list[int],

{tcgapi-0.2.1 → tcgapi-0.3.0}/tcgapi/resources/cards.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Literal
 
-from ..models import BulkCard, Card, Price, PriceHistoryPoint, Response
+from ..models import BulkCard, Card, ConditionMeta, ConditionPrice, Price, PriceHistoryPoint, Response
 from ._base import parse_response
 
 if TYPE_CHECKING:
@@ -26,6 +26,15 @@ class CardsResource:
         body = self._client._request("GET", f"/cards/{card_id}/prices", {"printing": printing})
         return parse_response(list[Price], body)
 
+    def conditions(
+        self, card_id: int, *, printing: str | None = None
+    ) -> Response[list[ConditionPrice]]:
+        # Pro+ only. `meta` is a ConditionMeta (cached/stale/as_of/condition_counts).
+        body = self._client._request(
+            "GET", f"/cards/{card_id}/prices/conditions", {"printing": printing}
+        )
+        return parse_response(list[ConditionPrice], body, meta_model=ConditionMeta)
+
     def by_tcgplayer_id(self, tcgplayer_id: int) -> Response[BulkCard]:
         body = self._client._request("GET", f"/cards/tcgplayer/{tcgplayer_id}")
         return parse_response(BulkCard, body)
@@ -63,6 +72,15 @@ class AsyncCardsResource:
         body = await self._client._request("GET", f"/cards/{card_id}/prices", {"printing": printing})
         return parse_response(list[Price], body)
 
+    async def conditions(
+        self, card_id: int, *, printing: str | None = None
+    ) -> Response[list[ConditionPrice]]:
+        # Pro+ only. `meta` is a ConditionMeta (cached/stale/as_of/condition_counts).
+        body = await self._client._request(
+            "GET", f"/cards/{card_id}/prices/conditions", {"printing": printing}
+        )
+        return parse_response(list[ConditionPrice], body, meta_model=ConditionMeta)
+
     async def by_tcgplayer_id(self, tcgplayer_id: int) -> Response[BulkCard]:
         body = await self._client._request("GET", f"/cards/tcgplayer/{tcgplayer_id}")
         return parse_response(BulkCard, body)