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 @@ -73,8 +73,8 @@ 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`,
`offer_details`, `offer_publish`, and `offer_feedback` methods are implemented; the other
Marketplace API methods are not yet.
`offer_details`, `offer_publish`, `offer_feedback`, and `offer_ship` methods are implemented;
`offer_end` and `offer_refund` are not yet.

```python
from pypricecharting import AsyncPriceCharting, PriceCharting
Expand Down
21 changes: 19 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ 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`,
`offer_details`, `offer_publish`, and `offer_feedback` methods are implemented; the other
Marketplace API methods are not yet.
`offer_details`, `offer_publish`, `offer_feedback`, and `offer_ship` methods are implemented;
`offer_end` and `offer_refund` are not yet.

## Authentication

Expand Down Expand Up @@ -138,6 +138,23 @@ with PriceCharting() as client:

An empty or whitespace-only offer ID raises `ParameterError`.

## Marking an offer as shipped

`offer_ship` tells PriceCharting a sold offer has shipped. It takes the offer ID and an optional
tracking number:

```python
from pypricecharting import PriceCharting

with PriceCharting() as client:
shipped = client.offer_ship("vtdsww72uyslgooawzyyijsllm", "901234567890000")
print(shipped.offer_id, shipped.is_shipped, shipped.shipped_time)
```

A valid tracking number can earn you positive feedback if the buyer leaves none, as long as it
shows shipment within 3 days and delivery to the buyer's address. An empty or whitespace-only
offer ID raises `ParameterError`.

## Errors

All errors subclass `PriceChartingError`:
Expand Down
35 changes: 31 additions & 4 deletions src/pypricecharting/asyncpricecharting.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
OfferDetailsResponse,
OfferFeedbackResponse,
OfferPublishResponse,
OfferShipResponse,
OffersResponse,
ProductResponse,
ProductsResponse,
Expand All @@ -26,7 +27,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 `offer_ship`, `offer_end`, and `offer_refund` are not implemented yet and return `None`.
methods `offer_end` and `offer_refund` are not implemented yet and return `None`.
"""

TOKEN_KEY = "PRICECHARTING_TOKEN"
Expand Down Expand Up @@ -230,9 +231,35 @@ async def offer_feedback(
response = await self._client.post(Route.Marketplace.OFFER_FEEDBACK, data=data)
return _parse(response, OfferFeedbackResponse)

async def offer_ship(self):
"""Mark a marketplace offer as shipped."""
pass
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):
"""End a marketplace offer."""
Expand Down
33 changes: 29 additions & 4 deletions src/pypricecharting/pricecharting.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
OfferDetailsResponse,
OfferFeedbackResponse,
OfferPublishResponse,
OfferShipResponse,
OffersResponse,
ProductResponse,
ProductsResponse,
Expand All @@ -26,7 +27,7 @@ class PriceCharting:
"""Synchronous PriceCharting API client.

Reuse one client for all requests and close it when done (`with` or `close()`). The Marketplace
methods `offer_ship`, `offer_end`, and `offer_refund` are not implemented yet and return `None`.
methods `offer_end` and `offer_refund` are not implemented yet and return `None`.
"""

TOKEN_KEY = "PRICECHARTING_TOKEN"
Expand Down Expand Up @@ -227,9 +228,33 @@ def offer_feedback(
response = self._client.post(Route.Marketplace.OFFER_FEEDBACK, data=data)
return _parse(response, OfferFeedbackResponse)

def offer_ship(self):
"""Mark a marketplace offer as shipped."""
pass
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 = self._client.post(Route.Marketplace.OFFER_SHIP, data=data)
return _parse(response, OfferShipResponse)

def offer_end(self):
"""End a marketplace offer."""
Expand Down
57 changes: 54 additions & 3 deletions tests/test_asyncpricecharting_marketplace.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
OfferDetailsResponse,
OfferFeedbackResponse,
OfferPublishResponse,
OfferShipResponse,
OffersResponse,
)
from pypricecharting.types import Condition, Rating, Status
Expand All @@ -18,6 +19,7 @@
OFFER_FEEDBACK_JSON,
OFFER_PUBLISH_REQUEST_JSON,
OFFER_PUBLISH_RESPONSE_JSON,
OFFER_SHIP_JSON,
OFFERS_JSON,
OFFERS_REQUEST_JSON,
)
Expand Down Expand Up @@ -237,9 +239,58 @@ async def test_offer_feedback_raises_api_error():


async def test_offer_ship():
client = AsyncPriceCharting(TOKEN)
assert await client.offer_ship() is None
await client.aclose()
requests: list[Request] = []

async with mocked_async_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client:
response = await client.offer_ship("vtdsww72uyslgooawzyyijsllm", "901234567890000")

assert isinstance(response, OfferShipResponse)
assert response.status == Status.SUCCESS
assert response.offer_id == "vtdsww72uyslgooawzyyijsllm"
assert response.is_shipped is True
assert response.tracking_number == "901234567890000"

assert len(requests) == 1
assert requests[0].method == "POST"
assert requests[0].url.path == "/api/offer-ship"
assert "t" not in requests[0].url.params
assert dict(parse_qsl(requests[0].content.decode())) == {
"offer-id": "vtdsww72uyslgooawzyyijsllm",
"tracking-number": "901234567890000",
"t": TOKEN,
}


async def test_offer_ship_without_tracking_number():
requests: list[Request] = []

async with mocked_async_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client:
await client.offer_ship(" testofferid ")

assert dict(parse_qsl(requests[0].content.decode())) == {
"offer-id": "testofferid",
"t": TOKEN,
}


@pytest.mark.parametrize("offer_id", ["", " "])
async def test_offer_ship_empty_offer_id_raises_parameter_error(offer_id: str):
requests: list[Request] = []

async with mocked_async_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client:
with pytest.raises(ParameterError, match="offer_id was empty"):
await client.offer_ship(offer_id)

assert requests == []


async def test_offer_ship_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_ship("missing")


async def test_offer_end():
Expand Down
59 changes: 56 additions & 3 deletions tests/test_pricecharting_marketplace.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
OfferDetailsResponse,
OfferFeedbackResponse,
OfferPublishResponse,
OfferShipResponse,
OffersResponse,
)
from pypricecharting.types import Condition, Rating, Status
Expand All @@ -18,6 +19,7 @@
OFFER_FEEDBACK_JSON,
OFFER_PUBLISH_REQUEST_JSON,
OFFER_PUBLISH_RESPONSE_JSON,
OFFER_SHIP_JSON,
OFFERS_JSON,
OFFERS_REQUEST_JSON,
)
Expand Down Expand Up @@ -223,9 +225,60 @@ def test_offer_feedback_raises_api_error():


def test_offer_ship():
client = PriceCharting(TOKEN)
assert client.offer_ship() is None
client.close()
requests: list[Request] = []

with mocked_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client:
response = client.offer_ship("vtdsww72uyslgooawzyyijsllm", "901234567890000")

assert isinstance(response, OfferShipResponse)
assert response.status == Status.SUCCESS
assert response.offer_id == "vtdsww72uyslgooawzyyijsllm"
assert response.is_shipped is True
assert response.tracking_number == "901234567890000"

assert len(requests) == 1
assert requests[0].method == "POST"
assert requests[0].url.path == "/api/offer-ship"
assert "t" not in requests[0].url.params
assert dict(parse_qsl(requests[0].content.decode())) == {
"offer-id": "vtdsww72uyslgooawzyyijsllm",
"tracking-number": "901234567890000",
"t": TOKEN,
}


def test_offer_ship_without_tracking_number():
requests: list[Request] = []

with mocked_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client:
client.offer_ship(" testofferid ")

assert dict(parse_qsl(requests[0].content.decode())) == {
"offer-id": "testofferid",
"t": TOKEN,
}


@pytest.mark.parametrize("offer_id", ["", " "])
def test_offer_ship_empty_offer_id_raises_parameter_error(offer_id: str):
requests: list[Request] = []

with (
mocked_client(TOKEN, Response(200, json=OFFER_SHIP_JSON), requests) as client,
pytest.raises(ParameterError, match="offer_id was empty"),
):
client.offer_ship(offer_id)

assert requests == []


def test_offer_ship_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_ship("missing")


def test_offer_end():
Expand Down
Loading