pypricecharting 0.0.1__py3-none-any.whl

pypricecharting/__init__.py

@@ -0,0 +1,66 @@
+from pypricecharting.asyncpricecharting import AsyncPriceCharting
+from pypricecharting.error import APIError, ParameterError, PriceChartingError
+from pypricecharting.models import Buyer, Offer, PriceChartingModel, ProductSummary
+from pypricecharting.pricecharting import PriceCharting
+from pypricecharting.requests import (
+    OfferPublishRequestParams,
+    OffersRequestParams,
+    OffersSort,
+    OffersStatus,
+)
+from pypricecharting.responses import (
+    ErrorResponse,
+    OfferDetailsResponse,
+    OfferEndResponse,
+    OfferFeedbackResponse,
+    OfferPublishResponse,
+    OfferRefundResponse,
+    OfferShipResponse,
+    OffersResponse,
+    ProductResponse,
+    ProductsResponse,
+)
+from pypricecharting.types import (
+    Condition,
+    Console,
+    Genre,
+    OfferStatus,
+    RateLimit,
+    Rating,
+    State,
+    Status,
+)
+
+__all__ = [
+    "APIError",
+    "AsyncPriceCharting",
+    "Buyer",
+    "Condition",
+    "Console",
+    "ErrorResponse",
+    "Genre",
+    "Offer",
+    "OfferDetailsResponse",
+    "OfferEndResponse",
+    "OfferFeedbackResponse",
+    "OfferPublishRequestParams",
+    "OfferPublishResponse",
+    "OfferRefundResponse",
+    "OfferShipResponse",
+    "OfferStatus",
+    "OffersRequestParams",
+    "OffersResponse",
+    "OffersSort",
+    "OffersStatus",
+    "ParameterError",
+    "PriceCharting",
+    "PriceChartingError",
+    "PriceChartingModel",
+    "ProductResponse",
+    "ProductSummary",
+    "ProductsResponse",
+    "RateLimit",
+    "Rating",
+    "State",
+    "Status",
+]

pypricecharting/_auth.py

@@ -0,0 +1,57 @@
+import logging
+import re
+from collections.abc import Generator
+from urllib.parse import urlencode
+
+from httpx2 import Auth, Request, Response
+from pydantic import SecretStr
+
+_TOKEN_PARAM = re.compile(r"([?&]t=)[^&\s\"']+")
+
+
+class _TokenAuth(Auth):
+    """Add the PriceCharting token as `t` in the query string (GET) or form body (POST)."""
+
+    requires_request_body = True
+
+    def __init__(self, token: SecretStr):
+        self._token = token
+
+    def auth_flow(self, request: Request) -> Generator[Request, Response]:
+        """Attach the token to the outgoing request."""
+        token = self._token.get_secret_value()
+
+        if request.method == "GET":
+            request.url = request.url.copy_set_param("t", token)
+            yield request
+            return
+
+        param = urlencode({"t": token}).encode()
+        body = request.content + b"&" + param if request.content else param
+        headers = request.headers.copy()
+        headers.pop("Content-Length", None)  # forces httpx2 to recalculate length
+        headers["Content-Type"] = "application/x-www-form-urlencoded"
+
+        yield Request(
+            request.method,
+            request.url,
+            headers=headers,
+            content=body,
+            extensions=request.extensions,
+        )
+
+
+class _RedactTokenFilter(logging.Filter):
+    """Replace the `t` query parameter in httpx2 log records with `REDACTED`."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Redact the token in place and always let the record through."""
+        message = record.getMessage()
+        redacted = _TOKEN_PARAM.sub(r"\1REDACTED", message)
+        if redacted != message:
+            record.msg = redacted
+            record.args = None
+        return True
+
+
+_REDACT_FILTER = _RedactTokenFilter()

pypricecharting/asyncpricecharting.py

@@ -0,0 +1,313 @@
+import logging
+import os
+from types import TracebackType
+from typing import Self
+
+from httpx2 import AsyncBaseTransport, AsyncClient
+from pydantic import SecretStr
+
+from pypricecharting._auth import _REDACT_FILTER, _TokenAuth
+from pypricecharting.error import ParameterError
+from pypricecharting.requests import OfferPublishRequestParams, OffersRequestParams
+from pypricecharting.responses import (
+    OfferDetailsResponse,
+    OfferEndResponse,
+    OfferFeedbackResponse,
+    OfferPublishResponse,
+    OfferRefundResponse,
+    OfferShipResponse,
+    OffersResponse,
+    ProductResponse,
+    ProductsResponse,
+    _parse,
+)
+from pypricecharting.route import BASE_URL, Route
+from pypricecharting.types import Rating
+
+
+class AsyncPriceCharting:
+    """Asynchronous PriceCharting API client.
+
+    Reuse one client for all requests and close it when done (`async with` or `aclose()`).
+    """
+
+    TOKEN_KEY = "PRICECHARTING_TOKEN"
+    """Environment variable the token is read from when none is passed."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str = BASE_URL,
+        transport: AsyncBaseTransport | None = None,
+    ):
+        """Create a client authenticated with a PriceCharting API token.
+
+        The token is redacted from `httpx2` request logs.
+
+        Args:
+            token: The 40-character PriceCharting API token. If omitted, it is read from the
+                `PRICECHARTING_TOKEN` environment variable.
+            base_url: API base URL. Override it to use a mock server.
+            transport: Custom `httpx2` async transport, such as `httpx2.MockTransport` in tests.
+
+        Raises:
+            ValueError: If the token is missing or not 40 characters.
+
+        """
+        if token is not None and len(token) != 40:
+            raise ValueError("PriceCharting API token is not 40 characters")
+        token = token or os.environ.get(self.TOKEN_KEY)
+
+        if token is None:
+            raise ValueError("PriceCharting API token not found")
+        if len(token) != 40:
+            raise ValueError("PriceCharting API token is not 40 characters")
+
+        self._token = SecretStr(token)
+        self._client = AsyncClient(
+            base_url=base_url, auth=_TokenAuth(self._token), transport=transport
+        )
+        logging.getLogger("httpx2").addFilter(_REDACT_FILTER)
+
+    async def aclose(self):
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context and return the client."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the underlying HTTP client on exit."""
+        await self.aclose()
+
+    async def product(
+        self, id: str | None = None, upc: str | None = None, q: str | None = None
+    ) -> ProductResponse:
+        """Get a single product by exactly one of `id`, `upc`, or `q`.
+
+        Args:
+            id: PriceCharting product ID.
+            upc: UPC barcode.
+            q: Full text search on title and/or console. Only the best match is returned.
+
+        Returns:
+            The matching product.
+
+        Raises:
+            ParameterError: If not exactly one of `id`, `upc`, or `q` is given.
+            APIError: If the API returns an error.
+
+        """
+        params = {
+            key: value for key, value in {"id": id, "upc": upc, "q": q}.items() if value is not None
+        }
+
+        if len(params) == 0:
+            raise ParameterError("Invalid parameters. Either id, upc, or q are required.")
+        if len(params) > 1:
+            raise ParameterError("Invalid parameters. Only one of id, upc, or q is allowed.")
+
+        response = await self._client.get(Route.Prices.PRODUCT, params=params)
+        return _parse(response, ProductResponse)
+
+    async def products(self, q: str) -> ProductsResponse:
+        """Search for products by title and/or console.
+
+        Args:
+            q: Full text search on title and/or console. Surrounding whitespace is stripped.
+
+        Returns:
+            Up to 20 matching products.
+
+        Raises:
+            ParameterError: If `q` is empty or only whitespace.
+            APIError: If the API returns an error.
+
+        """
+        q = q.strip()
+
+        if len(q) == 0:
+            raise ParameterError("Invalid parameter; Query string q was empty.")
+
+        response = await self._client.get(Route.Prices.PRODUCTS, params={"q": q})
+        return _parse(response, ProductsResponse)
+
+    async def offers(self, params: OffersRequestParams) -> OffersResponse:
+        """List marketplace offers matching the given filters.
+
+        The same request can be made at most once every 5 minutes.
+
+        Args:
+            params: Offer filters. Only `status` is required.
+
+        Returns:
+            The matching offers.
+
+        Raises:
+            APIError: If the API returns an error.
+
+        """
+        response = await self._client.get(
+            Route.Marketplace.OFFERS,
+            params=params.model_dump(mode="json", by_alias=True, exclude_none=True),
+        )
+        return _parse(response, OffersResponse)
+
+    async def offer_details(self, offer_id: str) -> OfferDetailsResponse:
+        """Get the full details of one marketplace offer.
+
+        Args:
+            offer_id: The offer ID. Surrounding whitespace is stripped.
+
+        Returns:
+            The offer, including the buyer's shipping details once it has sold.
+
+        Raises:
+            ParameterError: If `offer_id` is empty or only whitespace.
+            APIError: If the API returns an error.
+
+        """
+        offer_id = offer_id.strip()
+
+        if len(offer_id) == 0:
+            raise ParameterError("Invalid parameter; offer_id was empty.")
+
+        response = await self._client.get(
+            Route.Marketplace.OFFER_DETAILS, params={"offer-id": offer_id}
+        )
+        return _parse(response, OfferDetailsResponse)
+
+    async def offer_publish(self, params: OfferPublishRequestParams) -> OfferPublishResponse:
+        """Publish a new marketplace offer, or edit an existing one.
+
+        Args:
+            params: The offer to publish. Set `offer_id` to edit an existing offer.
+
+        Returns:
+            The published offer.
+
+        Raises:
+            APIError: If the API returns an error.
+
+        """
+        response = await self._client.post(
+            Route.Marketplace.OFFER_PUBLISH,
+            data=params.model_dump(mode="json", by_alias=True, exclude_none=True),
+        )
+        return _parse(response, OfferPublishResponse)
+
+    async def offer_feedback(
+        self, offer_id: str, rating: Rating, comment: str | None = None
+    ) -> OfferFeedbackResponse:
+        """Leave feedback on a marketplace offer.
+
+        Args:
+            offer_id: The offer ID. Surrounding whitespace is stripped.
+            rating: How the transaction went.
+            comment: Text explaining the rating.
+
+        Returns:
+            The feedback left.
+
+        Raises:
+            ParameterError: If `offer_id` is empty or only whitespace.
+            APIError: If the API returns an error.
+
+        """
+        offer_id = offer_id.strip()
+
+        if len(offer_id) == 0:
+            raise ParameterError("Invalid parameter; offer_id was empty.")
+
+        data: dict[str, str | int] = {"offer-id": offer_id, "rating": rating.value}
+        if comment is not None:
+            data["comment"] = comment
+
+        response = await self._client.post(Route.Marketplace.OFFER_FEEDBACK, data=data)
+        return _parse(response, OfferFeedbackResponse)
+
+    async def offer_ship(
+        self, offer_id: str, tracking_number: str | None = None
+    ) -> OfferShipResponse:
+        """Mark a sold marketplace offer as shipped.
+
+        Args:
+            offer_id: The offer ID. Surrounding whitespace is stripped.
+            tracking_number: USPS, FedEx, UPS, or other tracking number. A valid one can earn
+                positive feedback if the buyer leaves none.
+
+        Returns:
+            The shipped offer.
+
+        Raises:
+            ParameterError: If `offer_id` is empty or only whitespace.
+            APIError: If the API returns an error.
+
+        """
+        offer_id = offer_id.strip()
+
+        if len(offer_id) == 0:
+            raise ParameterError("Invalid parameter; offer_id was empty.")
+
+        data = {"offer-id": offer_id}
+        if tracking_number is not None:
+            data["tracking-number"] = tracking_number
+
+        response = await self._client.post(Route.Marketplace.OFFER_SHIP, data=data)
+        return _parse(response, OfferShipResponse)
+
+    async def offer_end(self, offer_id: str) -> OfferEndResponse:
+        """End a marketplace offer so it can no longer be purchased.
+
+        For a collection item, this removes it from the collection.
+
+        Args:
+            offer_id: The offer ID. Surrounding whitespace is stripped.
+
+        Returns:
+            The ended offer.
+
+        Raises:
+            ParameterError: If `offer_id` is empty or only whitespace.
+            APIError: If the API returns an error.
+
+        """
+        offer_id = offer_id.strip()
+
+        if len(offer_id) == 0:
+            raise ParameterError("Invalid parameter; offer_id was empty.")
+
+        response = await self._client.post(Route.Marketplace.OFFER_END, data={"offer-id": offer_id})
+        return _parse(response, OfferEndResponse)
+
+    async def offer_refund(self, offer_id: str) -> OfferRefundResponse:
+        """Refund a purchased marketplace offer.
+
+        Payment is returned immediately from the seller's PayPal account to the buyer.
+
+        Args:
+            offer_id: The offer ID. Surrounding whitespace is stripped.
+
+        Returns:
+            The refunded offer.
+
+        Raises:
+            ParameterError: If `offer_id` is empty or only whitespace.
+            APIError: If the API returns an error.
+
+        """
+        offer_id = offer_id.strip()
+
+        if len(offer_id) == 0:
+            raise ParameterError("Invalid parameter; offer_id was empty.")
+
+        response = await self._client.post(
+            Route.Marketplace.OFFER_REFUND, data={"offer-id": offer_id}
+        )
+        return _parse(response, OfferRefundResponse)

pypricecharting/error.py

@@ -0,0 +1,25 @@
+class PriceChartingError(Exception):
+    """Base class for all PriceCharting errors"""
+
+
+class ParameterError(PriceChartingError, ValueError):
+    """Raised when an API method is called with invalid parameters
+
+    Raised before any request is sent.
+    """
+
+
+class APIError(PriceChartingError):
+    """Raised when the API returns an error response
+
+    Attributes:
+        message: The API's `error-message`, or the HTTP reason phrase if it has none.
+        status_code: The HTTP status code of the response.
+
+    """
+
+    def __init__(self, message: str, status_code: int):
+        """Store the API error message and HTTP status code."""
+        super().__init__(f"{status_code}: {message}")
+        self.message = message
+        self.status_code = status_code

pypricecharting/models.py

@@ -0,0 +1,82 @@
+from datetime import date
+
+from pydantic import BaseModel, ConfigDict
+
+from pypricecharting.types import OfferStatus
+
+
+def to_kebab(name: str) -> str:
+    """Convert a snake_case field name to the API's kebab-case key."""
+    return name.replace("_", "-")
+
+
+class PriceChartingModel(BaseModel):
+    """Base model that maps snake_case fields to the API's kebab-case keys."""
+
+    model_config = ConfigDict(
+        alias_generator=to_kebab,
+        populate_by_name=True,
+        use_attribute_docstrings=True,
+    )
+
+
+class ProductSummary(PriceChartingModel):
+    """A product as listed in /api/products search results.
+
+    https://www.pricecharting.com/api-documentation#api-products
+    """
+
+    id: str | None = None
+    """PriceCharting product ID."""
+    product_name: str | None = None
+    console_name: str | None = None
+
+
+class Offer(PriceChartingModel):
+    """An offer as listed in /api/offers results.
+
+    https://www.pricecharting.com/api-documentation#offers
+    """
+
+    offer_id: str | None = None
+    """Unique offer ID, also shown in the offer URL."""
+    offer_status: OfferStatus | None = None
+    offer_url: str | None = None
+    """Relative URL of the offer page. Prepend `route.BASE_URL` for a full link."""
+    id: int | None = None
+    """PriceCharting product ID, not the offer ID."""
+    product_name: str | None = None
+    console_name: str | None = None
+    condition_string: str | None = None
+    """Condition shown to buyers, such as "Normal Wear"."""
+    include_string: str | None = None
+    """What comes with the item, such as game only or game and box."""
+    price: int | None = None
+    """Current price in pennies, or the sale price if sold. Includes any shipping premium."""
+    is_available: bool | None = None
+    is_sold: bool | None = None
+    is_ended: bool | None = None
+    is_shipped: bool | None = None
+    sale_time: date | None = None
+    """Date the offer sold. `0001-01-01` if it hasn't happened."""
+    shipped_time: date | None = None
+    """Date the seller told PriceCharting the offer shipped. `0001-01-01` if it hasn't happened."""
+    ended_time: date | None = None
+    """Date the offer ended, by sale or by the seller. `0001-01-01` if it hasn't happened."""
+    cert_id: str | None = None
+    """Grading company certificate number. Graded offers only."""
+    grade_co_id: int | None = None
+    """ID of the grading company. Graded offers only."""
+
+
+class Buyer(PriceChartingModel):
+    """The buyer of a sold offer, as returned by /api/offer-details."""
+
+    buyer_email: str | None = None
+    shipping_name: str | None = None
+    shipping_line1: str | None = None
+    shipping_line2: str | None = None
+    shipping_city: str | None = None
+    shipping_state: str | None = None
+    shipping_zip: str | None = None
+    shipping_country: str | None = None