diff --git a/README.md b/README.md index ef369d0..20d7ef0 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ See [RELEASE.md](RELEASE.md) for how releases and release labels work. ## Usage Under development: the Prices API methods (`product`, `products`) and the Marketplace `offers` -method are implemented; the other Marketplace API methods are not yet. +and `offer_details` methods are implemented; the other Marketplace API methods are not yet. ```python from pypricecharting import AsyncPriceCharting, PriceCharting diff --git a/docs/index.md b/docs/index.md index 1857a52..378af3f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ 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`) and the Marketplace `offers` -method are implemented; the other Marketplace API methods are not yet. +and `offer_details` methods are implemented; the other Marketplace API methods are not yet. ## Authentication @@ -83,6 +83,23 @@ with PriceCharting() as client: The API allows the same `offers` request at most once every 5 minutes. +## Offer details + +`offer_details` returns everything about one offer by its offer ID, including the buyer's shipping +details once it has sold: + +```python +from pypricecharting import PriceCharting + +with PriceCharting() as client: + details = client.offer_details("vtdsww72uyslgooawzyyijsllm") + print(details.product_name, details.offer_status, details.price) + if details.buyer is not None: + print(details.buyer.shipping_name, details.buyer.shipping_city) +``` + +An empty or whitespace-only offer ID raises `ParameterError`. + ## Errors All errors subclass `PriceChartingError`: diff --git a/src/pypricecharting/asyncpricecharting.py b/src/pypricecharting/asyncpricecharting.py index d675f19..2ac032f 100644 --- a/src/pypricecharting/asyncpricecharting.py +++ b/src/pypricecharting/asyncpricecharting.py @@ -9,7 +9,13 @@ from pypricecharting._auth import _REDACT_FILTER, _TokenAuth from pypricecharting.error import ParameterError from pypricecharting.requests import OffersRequestParams -from pypricecharting.responses import OffersResponse, ProductResponse, ProductsResponse, _parse +from pypricecharting.responses import ( + OfferDetailsResponse, + OffersResponse, + ProductResponse, + ProductsResponse, + _parse, +) from pypricecharting.route import BASE_URL, Route @@ -17,7 +23,7 @@ class AsyncPriceCharting: """Asynchronous PriceCharting API client. 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`. + methods other than `offers` and `offer_details` are not implemented yet and return `None`. """ TOKEN_KEY = "PRICECHARTING_TOKEN" @@ -148,9 +154,29 @@ async def offers(self, params: OffersRequestParams) -> OffersResponse: ) return _parse(response, OffersResponse) - async def offer_details(self): - """Get the details of a marketplace offer.""" - pass + 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): """Publish a new marketplace offer.""" diff --git a/src/pypricecharting/pricecharting.py b/src/pypricecharting/pricecharting.py index 4575127..b414572 100644 --- a/src/pypricecharting/pricecharting.py +++ b/src/pypricecharting/pricecharting.py @@ -9,7 +9,13 @@ from pypricecharting._auth import _REDACT_FILTER, _TokenAuth from pypricecharting.error import ParameterError from pypricecharting.requests import OffersRequestParams -from pypricecharting.responses import OffersResponse, ProductResponse, ProductsResponse, _parse +from pypricecharting.responses import ( + OfferDetailsResponse, + OffersResponse, + ProductResponse, + ProductsResponse, + _parse, +) from pypricecharting.route import BASE_URL, Route @@ -17,7 +23,7 @@ class PriceCharting: """Synchronous PriceCharting API client. 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`. + methods other than `offers` and `offer_details` are not implemented yet and return `None`. """ TOKEN_KEY = "PRICECHARTING_TOKEN" @@ -147,9 +153,27 @@ def offers(self, params: OffersRequestParams) -> OffersResponse: ) return _parse(response, OffersResponse) - def offer_details(self): - """Get the details of a marketplace offer.""" - pass + 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 = self._client.get(Route.Marketplace.OFFER_DETAILS, params={"offer-id": offer_id}) + return _parse(response, OfferDetailsResponse) def offer_publish(self): """Publish a new marketplace offer.""" diff --git a/tests/test_asyncpricecharting_marketplace.py b/tests/test_asyncpricecharting_marketplace.py index dd7a803..690971e 100644 --- a/tests/test_asyncpricecharting_marketplace.py +++ b/tests/test_asyncpricecharting_marketplace.py @@ -2,11 +2,11 @@ from httpx2 import Request, Response from pypricecharting.asyncpricecharting import AsyncPriceCharting -from pypricecharting.error import APIError +from pypricecharting.error import APIError, ParameterError from pypricecharting.requests import OffersRequestParams, OffersStatus -from pypricecharting.responses import OffersResponse +from pypricecharting.responses import OfferDetailsResponse, OffersResponse from pypricecharting.types import Status -from tests.mocks.json import OFFERS_JSON, OFFERS_REQUEST_JSON +from tests.mocks.json import OFFER_DETAILS_JSON, OFFERS_JSON, OFFERS_REQUEST_JSON from tests.mocks.mock_pricecharting import TOKEN, error_body, mocked_async_client # Template tests: methods that are still placeholders only check they can be called. @@ -53,9 +53,56 @@ async def test_offers_raises_api_error(): async def test_offer_details(): - client = AsyncPriceCharting(TOKEN) - assert await client.offer_details() is None - await client.aclose() + requests: list[Request] = [] + + async with mocked_async_client( + TOKEN, Response(200, json=OFFER_DETAILS_JSON), requests + ) as client: + response = await client.offer_details("testofferid") + + assert isinstance(response, OfferDetailsResponse) + assert response.status == Status.SUCCESS + assert response.offer_id == "testofferid" + assert response.buyer is not None + assert response.buyer.buyer_email == "buyer@example.com" + + assert len(requests) == 1 + assert requests[0].method == "GET" + assert requests[0].url.path == "/api/offer-details" + assert dict(requests[0].url.params) == {"offer-id": "testofferid", "t": TOKEN} + + +async def test_offer_details_strips_offer_id(): + requests: list[Request] = [] + + async with mocked_async_client( + TOKEN, Response(200, json=OFFER_DETAILS_JSON), requests + ) as client: + await client.offer_details(" testofferid ") + + assert requests[0].url.params["offer-id"] == "testofferid" + + +@pytest.mark.parametrize("offer_id", ["", " "]) +async def test_offer_details_empty_offer_id_raises_parameter_error(offer_id: str): + requests: list[Request] = [] + + async with mocked_async_client( + TOKEN, Response(200, json=OFFER_DETAILS_JSON), requests + ) as client: + with pytest.raises(ParameterError, match="offer_id was empty"): + await client.offer_details(offer_id) + + assert requests == [] + + +async def test_offer_details_raises_api_error(): + requests: list[Request] = [] + async with mocked_async_client( + TOKEN, Response(404, json=error_body("No such offer")), requests + ) as client: + with pytest.raises(APIError, match="404: No such offer"): + await client.offer_details("missing") async def test_offer_publish(): diff --git a/tests/test_pricecharting_marketplace.py b/tests/test_pricecharting_marketplace.py index ebac6fa..39a1732 100644 --- a/tests/test_pricecharting_marketplace.py +++ b/tests/test_pricecharting_marketplace.py @@ -1,12 +1,12 @@ import pytest from httpx2 import Request, Response -from pypricecharting.error import APIError +from pypricecharting.error import APIError, ParameterError from pypricecharting.pricecharting import PriceCharting from pypricecharting.requests import OffersRequestParams, OffersStatus -from pypricecharting.responses import OffersResponse +from pypricecharting.responses import OfferDetailsResponse, OffersResponse from pypricecharting.types import Status -from tests.mocks.json import OFFERS_JSON, OFFERS_REQUEST_JSON +from tests.mocks.json import OFFER_DETAILS_JSON, OFFERS_JSON, OFFERS_REQUEST_JSON from tests.mocks.mock_pricecharting import TOKEN, error_body, mocked_client # Template tests: methods that are still placeholders only check they can be called. @@ -53,9 +53,52 @@ def test_offers_raises_api_error(): def test_offer_details(): - client = PriceCharting(TOKEN) - assert client.offer_details() is None - client.close() + requests: list[Request] = [] + + with mocked_client(TOKEN, Response(200, json=OFFER_DETAILS_JSON), requests) as client: + response = client.offer_details("testofferid") + + assert isinstance(response, OfferDetailsResponse) + assert response.status == Status.SUCCESS + assert response.offer_id == "testofferid" + assert response.buyer is not None + assert response.buyer.buyer_email == "buyer@example.com" + + assert len(requests) == 1 + assert requests[0].method == "GET" + assert requests[0].url.path == "/api/offer-details" + assert dict(requests[0].url.params) == {"offer-id": "testofferid", "t": TOKEN} + + +def test_offer_details_strips_offer_id(): + requests: list[Request] = [] + + with mocked_client(TOKEN, Response(200, json=OFFER_DETAILS_JSON), requests) as client: + client.offer_details(" testofferid ") + + assert requests[0].url.params["offer-id"] == "testofferid" + + +@pytest.mark.parametrize("offer_id", ["", " "]) +def test_offer_details_empty_offer_id_raises_parameter_error(offer_id: str): + requests: list[Request] = [] + + with ( + mocked_client(TOKEN, Response(200, json=OFFER_DETAILS_JSON), requests) as client, + pytest.raises(ParameterError, match="offer_id was empty"), + ): + client.offer_details(offer_id) + + assert requests == [] + + +def test_offer_details_raises_api_error(): + requests: list[Request] = [] + with ( + mocked_client(TOKEN, Response(404, json=error_body("No such offer")), requests) as client, + pytest.raises(APIError, match="404: No such offer"), + ): + client.offer_details("missing") def test_offer_publish():