Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,8 @@ See [RELEASE.md](RELEASE.md) for how releases and release labels work.

## Usage

Under development: the Prices API methods (`product`, `products`) are implemented; the Marketplace
API methods are not yet.
Under development: the Prices API methods (`product`, `products`) and the Marketplace `offers`
method are implemented; the other Marketplace API methods are not yet.

```python
from pypricecharting import AsyncPriceCharting, PriceCharting
Expand Down
22 changes: 20 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ Python client for the [PriceCharting API](https://www.pricecharting.com/api-docu
It provides a synchronous client, `PriceCharting`, and an asynchronous client,
`AsyncPriceCharting`, both authenticated with a 40-character API token.

Under development: the Prices API methods (`product`, `products`) are implemented; the
Marketplace API methods are not yet.
Under development: the Prices API methods (`product`, `products`) and the Marketplace `offers`
method are implemented; the other Marketplace API methods are not yet.

## Authentication

Expand Down Expand Up @@ -65,6 +65,24 @@ with PriceCharting() as client:

An empty or whitespace-only query raises `ParameterError`.

## Listing offers

`offers` lists marketplace offers. It takes an `OffersRequestParams`; only `status` is required,
and the other fields narrow the results:

```python
from pypricecharting import Console, OffersRequestParams, OffersSort, OffersStatus, PriceCharting

with PriceCharting() as client:
params = OffersRequestParams(
status=OffersStatus.AVAILABLE, console=Console.NES, sort=OffersSort.LOWEST_PRICE
)
for offer in client.offers(params).offers:
print(offer.offer_id, offer.product_name, offer.price)
```

The API allows the same `offers` request at most once every 5 minutes.

## Errors

All errors subclass `PriceChartingError`:
Expand Down
20 changes: 10 additions & 10 deletions src/pypricecharting/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,12 @@
from pypricecharting.error import APIError, ParameterError, PriceChartingError
from pypricecharting.models import Buyer, Offer, PriceChartingModel, ProductSummary
from pypricecharting.pricecharting import PriceCharting
from pypricecharting.requests import OfferPublishRequest
from pypricecharting.requests import (
OfferPublishRequestParams,
OffersRequestParams,
OffersSort,
OffersStatus,
)
from pypricecharting.responses import (
ErrorResponse,
OfferDetailsResponse,
Expand All @@ -16,9 +21,6 @@
ProductsResponse,
)
from pypricecharting.types import (
Cards,
Coins,
Comics,
Condition,
Console,
Genre,
Expand All @@ -27,16 +29,12 @@
Rating,
State,
Status,
VideoGames,
)

__all__ = [
"APIError",
"AsyncPriceCharting",
"Buyer",
"Cards",
"Coins",
"Comics",
"Condition",
"Console",
"ErrorResponse",
Expand All @@ -45,12 +43,15 @@
"OfferDetailsResponse",
"OfferEndResponse",
"OfferFeedbackResponse",
"OfferPublishRequest",
"OfferPublishRequestParams",
"OfferPublishResponse",
"OfferRefundResponse",
"OfferShipResponse",
"OfferStatus",
"OffersRequestParams",
"OffersResponse",
"OffersSort",
"OffersStatus",
"ParameterError",
"PriceCharting",
"PriceChartingError",
Expand All @@ -62,5 +63,4 @@
"Rating",
"State",
"Status",
"VideoGames",
]
30 changes: 24 additions & 6 deletions src/pypricecharting/asyncpricecharting.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,16 @@

from pypricecharting._auth import _REDACT_FILTER, _TokenAuth
from pypricecharting.error import ParameterError
from pypricecharting.responses import ProductResponse, ProductsResponse, _parse
from pypricecharting.requests import OffersRequestParams
from pypricecharting.responses import OffersResponse, ProductResponse, ProductsResponse, _parse
from pypricecharting.route import BASE_URL, Route


class AsyncPriceCharting:
"""Asynchronous PriceCharting API client.

Reuse one client for all requests and close it when done (`async with` or `aclose()`). The Marketplace API
methods are not implemented yet and return `None`.
Reuse one client for all requests and close it when done (`async with` or `aclose()`). The Marketplace
methods other than `offers` are not implemented yet and return `None`.
"""

TOKEN_KEY = "PRICECHARTING_TOKEN"
Expand Down Expand Up @@ -126,9 +127,26 @@ async def products(self, q: str) -> ProductsResponse:
response = await self._client.get(Route.Prices.PRODUCTS, params={"q": q})
return _parse(response, ProductsResponse)

async def offers(self):
"""List marketplace offers."""
pass
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):
"""Get the details of a marketplace offer."""
Expand Down
30 changes: 24 additions & 6 deletions src/pypricecharting/pricecharting.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,16 @@

from pypricecharting._auth import _REDACT_FILTER, _TokenAuth
from pypricecharting.error import ParameterError
from pypricecharting.responses import ProductResponse, ProductsResponse, _parse
from pypricecharting.requests import OffersRequestParams
from pypricecharting.responses import OffersResponse, ProductResponse, ProductsResponse, _parse
from pypricecharting.route import BASE_URL, Route


class PriceCharting:
"""Synchronous PriceCharting API client.

Reuse one client for all requests and close it when done (`with` or `close()`). The Marketplace API
methods are not implemented yet and return `None`.
Reuse one client for all requests and close it when done (`with` or `close()`). The Marketplace
methods other than `offers` are not implemented yet and return `None`.
"""

TOKEN_KEY = "PRICECHARTING_TOKEN"
Expand Down Expand Up @@ -125,9 +126,26 @@ def products(self, q: str) -> ProductsResponse:
response = self._client.get(Route.Prices.PRODUCTS, params={"q": q})
return _parse(response, ProductsResponse)

def offers(self):
"""List marketplace offers."""
pass
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 = self._client.get(
Route.Marketplace.OFFERS,
params=params.model_dump(mode="json", by_alias=True, exclude_none=True),
)
return _parse(response, OffersResponse)

def offer_details(self):
"""Get the details of a marketplace offer."""
Expand Down
49 changes: 46 additions & 3 deletions src/pypricecharting/requests.py
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
from enum import StrEnum
from typing import Self

from pydantic import PositiveInt, model_validator

from pypricecharting.models import PriceChartingModel
from pypricecharting.types import State
from pypricecharting.types import Console, Genre, State


class OfferPublishRequest(PriceChartingModel):
class OfferPublishRequestParams(PriceChartingModel):
"""api/offer-publish request

Set one of `product`, `upc`, `asin`, or `epid` to create an offer, or `offer_id` to edit one.
Expand All @@ -24,7 +25,7 @@ class OfferPublishRequest(PriceChartingModel):
"""ID of an existing offer to edit. The other identifiers create a new offer."""
price_max: int
"""Price in pennies buyers pay, or the starting price when `price_min` is set."""
condition_id: str
condition_id: int
"""Condition ID for the product's category. See `types.Condition`."""
add_to_collection: str | None = None
"""Add the item to your collection instead of listing it for sale."""
Expand Down Expand Up @@ -62,3 +63,45 @@ def check_identifier(self) -> Self:
if id is not None:
return self
raise ValueError("One of product, upc, asin, epid, or offer_id is required")


class OffersStatus(StrEnum):
"""Offer status to filter api/offers by"""

AVAILABLE = "available"
SOLD = "sold"
ENDED = "ended"
COLLECTION = "collection"
"""Tracked in the seller's collection, not listed for sale."""


class OffersSort(StrEnum):
"""Sort order for api/offers results"""

NAME = "name"
"""Alphabetical."""
STARTS = "starts"
"""Newest listings first."""
LOWEST_PRICE = "lowest-price"


class OffersRequestParams(PriceChartingModel):
"""api/offers request

Only `status` is required. The other fields narrow the results.

https://www.pricecharting.com/api-documentation#offers
"""

status: OffersStatus
buyer: str | None = None
"""Buyer user ID."""
console: Console | None = None
condition_id: int | None = None
"""Condition ID for the product's category. See `types.Condition`."""
genre: Genre | None = None
id: str | None = None
"""PriceCharting product ID."""
seller: str | None = None
"""Seller user ID."""
sort: OffersSort | None = None
Loading
Loading