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
2 changes: 2 additions & 0 deletions CI.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@

* The docs site deploys through GitHub Pages, so the repo's Pages source must be set to
**GitHub Actions**. PRs build the docs in strict mode without deploying
* On PRs, `release-drafter.yml` also runs the `require-label` check, which fails until the PR has
at least one release label (see [RELEASE.md](RELEASE.md))
* GitHub Actions are pinned to full commit SHAs, with the version in a trailing comment
* Dependabot (`.github/dependabot.yml`) checks weekly for updates to GitHub Actions and Python
dependencies, and monthly for the dev container image and dev container features. New releases
Expand Down
19 changes: 16 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,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`,
`offer_details`, `offer_publish`, `offer_feedback`, and `offer_ship` methods are implemented;
`offer_end` and `offer_refund` are not yet.
Both clients have a method for every Prices API and Marketplace API operation.

```python
from pypricecharting import AsyncPriceCharting, PriceCharting
Expand All @@ -97,3 +95,18 @@ Project contains an OpenAPI spec and a Bruno project for easy testing and mockin

* `./bruno` - Bruno project
* `./open_api` - OpenAPI spec

## TODO / Investigate

None of the client methods have been run against the live API yet. They are tested against a mock
transport and the two specs only. Items to settle with real responses:

* **Offer details price limits** - `OfferDetailsResponse` reads `price-max` and `price-min`, the
names in the documentation's key table. If the API sends `max-price` and `min-price` instead,
`price_max` and `price_min` come back as `None` with no error. Check one real
`/api/offer-details` response
* **Extra Marketplace keys** - `pending-reason`, `seller-id`, `image-url`, `best-competing-price`,
`is-best-priced-offer` and `value` are only on `OfferDetailsResponse`. The documentation doesn't
say which endpoint returns each one. If `/api/offers` returns any of them, add them to `Offer`
* **Live test of every endpoint** - call each method once with a real token and compare the
response to its model
6 changes: 5 additions & 1 deletion RELEASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,12 @@ labels; other repository labels (e.g. `good first issue`, `question`) are ignore
* Every PR must have at least one release label, or the `Release Drafter / require-label` check fails. If a release
has PRs with different labels, the largest bump wins
* Release labels are added automatically from the PR's branch name prefix (`feat/`, `fix/`, `chore/`,
`ci/`, `docs/`, `refactor/`) and from the files it changes. You can add or change them by hand
`ci/`, `docs/`, `refactor/`) and from the files it changes: `.github/workflows/*` adds `ci`,
`*.md` adds `documentation`, and `uv.lock` adds `dependencies`. You can add or change them by hand
* Merging to `main` updates a draft GitHub Release with the next version and notes
* To release, run the **Release** workflow from the Actions tab. It bumps the version in
`pyproject.toml`/`uv.lock`, tags the release, and uploads build artifacts. The GitHub Release
notes are the changelog
* The Release workflow commits the version bump as `Release vX.Y.Z` and pushes it straight to
`main` as `github-actions[bot]`, with no PR. The tag points at that commit. Branch protection
on `main` must allow this push, or the workflow fails before the release is published
12 changes: 6 additions & 6 deletions bruno/PricechartingAPI/Marketplace API/offer-details.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ docs: |-
{
"status":"success",
"buyer": { // buyer's shipping info
"buyer-email":"[email protected]",
"buyer-email":"example@email.com",
"shipping-city":"Anytown",
"shipping-country":"United States",
"shipping-line1":"123 Smith St",
Expand All @@ -52,12 +52,12 @@ docs: |-
"is-refunded":false, // has offer been refunded
"is-shipped":true, // has offer been shipped
"is-sold":true, // has offer sold
"max-price":12000,
"min-price":10000,
"offer-id":"vtdsww72uyslgooawzyyijsllm", // unique offer ID
"offer-status":"sold",
"offer-url":"/offer/vtdsww72uyslgooawzyyijsllm", // url for offer
"price":11281, // sales price. $112.81
"price-max":12000,
"price-min":10000,
"product-name":"Mega Man 7",
"refunded-time":"0001-01-01", // date of refund. zero value
"sale-time":"2017-10-31",
Expand All @@ -73,7 +73,7 @@ docs: |-
- `buyer`: `buyer-email`, `shipping-name`, `shipping-line1`, `shipping-line2`, `shipping-city`, `shipping-state`, `shipping-zip`, `shipping-country`
- `buyer-left-feedback`, `seller-left-feedback`
- `id`, `product-name`, `console-name`, `condition`, `includes`
- `price`, `max-price`, `min-price`, `cost-basis`, `shipping-premium`
- `has-pictures`, `is-collection`, `is-ended`, `is-price-descending`, `is-refunded`, `is-shipped`, `is-sold`
- `offer-id`, `offer-status`, `offer-url`, `sku`, `tracking-number`
- `price`, `price-max`, `price-min`, `cost-basis`, `shipping-premium`, `best-competing-price`, `value`
- `has-pictures`, `is-best-priced-offer`, `is-collection`, `is-ended`, `is-price-descending`, `is-refunded`, `is-shipped`, `is-sold`
- `offer-id`, `offer-status`, `pending-reason`, `offer-url`, `image-url`, `seller-id`, `sku`, `tracking-number`
- `start-time`, `sale-time`, `shipped-time`, `ended-time`, `refunded-time`
2 changes: 1 addition & 1 deletion bruno/PricechartingAPI/Marketplace API/offer-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ settings:
docs: |-
Publish a new offer, or edit an existing one when `offer-id` is given.

Provide one identifier: `product`, `upc`, `asin`, `epid`, or `offer-id`.
Either `product`, `upc`, `asin`, `epid` or `offer-id` is required.

Condition tags (`broken`, `pristine`, `scratch`, `stickers`, `tear`, `writing`) are set to `on`. With no tags, the listing shows "Normal wear".

Expand Down
32 changes: 29 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,7 @@ 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`) and the Marketplace `offers`,
`offer_details`, `offer_publish`, `offer_feedback`, and `offer_ship` methods are implemented;
`offer_end` and `offer_refund` are not yet.
Both clients have a method for every Prices API and Marketplace API operation.

## Authentication

Expand Down Expand Up @@ -155,6 +153,34 @@ A valid tracking number can earn you positive feedback if the buyer leaves none,
shows shipment within 3 days and delivery to the buyer's address. An empty or whitespace-only
offer ID raises `ParameterError`.

## Ending an offer

`offer_end` ends an offer so it can no longer be purchased. For a collection item, it removes the
item from the collection:

```python
from pypricecharting import PriceCharting

with PriceCharting() as client:
ended = client.offer_end("vtdsww72uyslgooawzyyijsllm")
print(ended.offer_id, ended.is_ended, ended.ended_time)
```

## Refunding an offer

`offer_refund` refunds a purchased offer. Payment is returned immediately from your PayPal account
to the buyer:

```python
from pypricecharting import PriceCharting

with PriceCharting() as client:
refunded = client.offer_refund("vtdsww72uyslgooawzyyijsllm")
print(refunded.offer_id, refunded.is_refunded, refunded.refunded_time)
```

Both raise `ParameterError` for an empty or whitespace-only offer ID.

## Errors

All errors subclass `PriceChartingError`:
Expand Down
34 changes: 27 additions & 7 deletions open_api/pricecharting.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,7 @@ paths:
is-shipped: true
is-sold: true
offer-id: nw6asacmsbvvoq5yeyrkvzcdky
offer-status: sold
offer-status: available
offer-url: /offer/nw6asacmsbvvoq5yeyrkvzcdky
price: 6281
product-name: Shatterhand
Expand Down Expand Up @@ -257,7 +257,7 @@ paths:
example:
status: success
buyer:
buyer-email: buyer@example.com
buyer-email: example@email.com
shipping-city: Anytown
shipping-country: United States
shipping-line1: 123 Smith St
Expand All @@ -279,12 +279,12 @@ paths:
is-refunded: false
is-shipped: true
is-sold: true
max-price: 12000
min-price: 10000
offer-id: vtdsww72uyslgooawzyyijsllm
offer-status: sold
offer-url: /offer/vtdsww72uyslgooawzyyijsllm
price: 11281
price-max: 12000
price-min: 10000
product-name: Mega Man 7
refunded-time: "0001-01-01"
sale-time: "2017-10-31"
Expand All @@ -307,7 +307,7 @@ paths:
description: |-
Publishes a new offer, or edits an existing one when `offer-id` is given.

Provide exactly one identifier: `product`, `upc`, `asin`, `epid`, or `offer-id`.
Either `product`, `upc`, `asin`, `epid` or `offer-id` is required.

Condition tags (`broken`, `pristine`, `scratch`, `stickers`, `tear`, `writing`) are
set to `on`. With no tags, the listing shows "Normal wear". `pristine` displays as
Expand Down Expand Up @@ -864,15 +864,26 @@ components:
$ref: "#/components/schemas/Pennies"
price:
$ref: "#/components/schemas/Pennies"
max-price:
price-max:
$ref: "#/components/schemas/Pennies"
min-price:
description: Maximum price entered, or the starting price of a reverse auction.
price-min:
$ref: "#/components/schemas/Pennies"
description: Minimum price of a reverse auction. Not set for standard listings.
shipping-premium:
$ref: "#/components/schemas/Pennies"
description: Extra paid by the buyer for international shipping.
best-competing-price:
$ref: "#/components/schemas/Pennies"
description: Lowest Marketplace price for the same product and includes.
value:
$ref: "#/components/schemas/Pennies"
description: Current value of a collection item.
has-pictures:
type: boolean
is-best-priced-offer:
type: boolean
description: Whether this is the lowest priced offer for the product.
is-collection:
type: boolean
is-ended:
Expand All @@ -890,8 +901,17 @@ components:
type: string
offer-status:
$ref: "#/components/schemas/OfferStatus"
pending-reason:
type: string
description: Why `offer-status` is `pending`.
offer-url:
type: string
image-url:
type: string
description: Relative URL of the offer's main image.
seller-id:
type: string
description: Seller user ID.
sku:
type: string
description: Only returned to the seller.
Expand Down
59 changes: 51 additions & 8 deletions src/pypricecharting/asyncpricecharting.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@
from pypricecharting.requests import OfferPublishRequestParams, OffersRequestParams
from pypricecharting.responses import (
OfferDetailsResponse,
OfferEndResponse,
OfferFeedbackResponse,
OfferPublishResponse,
OfferRefundResponse,
OfferShipResponse,
OffersResponse,
ProductResponse,
Expand All @@ -26,8 +28,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_end` and `offer_refund` are not implemented yet and return `None`.
Reuse one client for all requests and close it when done (`async with` or `aclose()`).
"""

TOKEN_KEY = "PRICECHARTING_TOKEN"
Expand Down Expand Up @@ -261,10 +262,52 @@ async def offer_ship(
response = await self._client.post(Route.Marketplace.OFFER_SHIP, data=data)
return _parse(response, OfferShipResponse)

async def offer_end(self):
"""End a marketplace offer."""
pass
async def offer_end(self, offer_id: str) -> OfferEndResponse:
"""End a marketplace offer so it can no longer be purchased.

async def offer_refund(self):
"""Refund a marketplace offer."""
pass
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)
57 changes: 49 additions & 8 deletions src/pypricecharting/pricecharting.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@
from pypricecharting.requests import OfferPublishRequestParams, OffersRequestParams
from pypricecharting.responses import (
OfferDetailsResponse,
OfferEndResponse,
OfferFeedbackResponse,
OfferPublishResponse,
OfferRefundResponse,
OfferShipResponse,
OffersResponse,
ProductResponse,
Expand All @@ -26,8 +28,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_end` and `offer_refund` are not implemented yet and return `None`.
Reuse one client for all requests and close it when done (`with` or `close()`).
"""

TOKEN_KEY = "PRICECHARTING_TOKEN"
Expand Down Expand Up @@ -256,10 +257,50 @@ def offer_ship(self, offer_id: str, tracking_number: str | None = None) -> Offer
response = self._client.post(Route.Marketplace.OFFER_SHIP, data=data)
return _parse(response, OfferShipResponse)

def offer_end(self):
"""End a marketplace offer."""
pass
def offer_end(self, offer_id: str) -> OfferEndResponse:
"""End a marketplace offer so it can no longer be purchased.

def offer_refund(self):
"""Refund a marketplace offer."""
pass
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 = self._client.post(Route.Marketplace.OFFER_END, data={"offer-id": offer_id})
return _parse(response, OfferEndResponse)

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 = self._client.post(Route.Marketplace.OFFER_REFUND, data={"offer-id": offer_id})
return _parse(response, OfferRefundResponse)
Loading
Loading