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: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,5 +23,5 @@ Add a release label to this PR from the Labels section of the PR sidebar
- [ ] `just lint` passes
- [ ] `just test` passes
- [ ] Tests added or updated for the change
- [ ] `README.md` updated if needed
- [ ] Docs updated if needed (`README.md`, `docs/`, `CLAUDE.md`)
- [ ] Release label added
58 changes: 58 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
name: Docs

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
workflow_dispatch:

permissions: {}

concurrency:
group: pages
cancel-in-progress: false

jobs:
build:
runs-on: ubuntu-slim
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
enable-cache: false
version: ">=0.13,<0.14"
- name: Setup environment
run: |
uv tool install rust-just
just sync
- name: Build docs
run: |
just docs-build
- name: Upload Pages artifact
if: github.event_name != 'pull_request'
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: site

deploy:
if: github.event_name != 'pull_request'
needs: build
runs-on: ubuntu-slim
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Configure Pages
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
8 changes: 1 addition & 7 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,20 +40,14 @@ jobs:
VERSION: ${{ steps.drafter.outputs.resolved_version }}
run: uv version "$VERSION"

- name: Update CHANGELOG.md
uses: stefanzweifel/changelog-updater-action@a938690fad7edf25368f37e43a1ed1b34303eb36 # v1.12.0
with:
latest-version: ${{ steps.drafter.outputs.tag_name }}
release-notes: ${{ steps.drafter.outputs.body }}

- name: Commit and push
id: commit
env:
TAG: ${{ steps.drafter.outputs.tag_name }}
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add pyproject.toml uv.lock CHANGELOG.md
git add pyproject.toml uv.lock
git commit -m "Release $TAG"
git push origin main
echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
Expand Down
8 changes: 0 additions & 8 deletions CHANGELOG.md

This file was deleted.

9 changes: 6 additions & 3 deletions CI.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,11 @@
| `security.yml` | push to `main`, all PRs | zizmor workflow audit, gitleaks secret scan |
| `release-drafter.yml` | push to `main`, PRs | update the draft release, label PRs |
| `release.yml` | manual | publish a release |
| `docs.yml` | push / PR to `main`, manual | build docs, deploy to GitHub Pages (not PRs) |

* 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
* 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, Python
dependencies, the dev container image, and dev container features. New releases wait 7 days
before an update is proposed. Dependabot PRs get the `dependencies` label
* 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
wait 7 days before an update is proposed. Dependabot PRs get the `dependencies` label
23 changes: 21 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ manage project configuration and commands
* `just prek` - run all pre-commit hooks
* `just git-leaks` - scan staged changes for secrets
* `just zizmor` - audit GitHub Actions workflows for security issues
* `just docs` - serve the docs site locally with live reload
* `just docs-build` - build the docs site into `site/` in strict mode
* `uv add {package}` - install a dependency

### Pre-commit Hooks
Expand All @@ -51,17 +53,34 @@ manage project configuration and commands

See [CI.md](CI.md) for the GitHub Actions workflows and Dependabot setup.

## Documentation

The docs site is built with [Zensical](https://zensical.org) from `mkdocs.yml` and the pages in
`docs/`. API reference pages are generated from docstrings with `mkdocstrings`. The `docs.yml`
workflow deploys the site to GitHub Pages on every push to `main`.

## Releases

See [RELEASE.md](RELEASE.md) for how releases and release labels work.

## Usage

### Types
The client is under development. `PriceCharting` and `AsyncPriceCharting` can be created and used
as context managers, but their API methods are not implemented yet.

```python
from pypricecharting import AsyncPriceCharting, PriceCharting

with PriceCharting("<40-character API token>") as client:
...

async with AsyncPriceCharting("<40-character API token>") as client:
...
```

## Supporting Files

Project contains an OpenAPI spec and a Bruno project for easy testing and mocking

* `./bruno` - Bruno project
* `./open_api` - OpenApi spec
* `./open_api` - OpenAPI spec
3 changes: 2 additions & 1 deletion RELEASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,5 @@ labels; other repository labels (e.g. `good first issue`, `question`) are ignore
`ci/`, `docs/`, `refactor/`) and from the files it changes. 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`, updates `CHANGELOG.md`, tags the release, and uploads build artifacts
`pyproject.toml`/`uv.lock`, tags the release, and uploads build artifacts. The GitHub Release
notes are the changelog
5 changes: 5 additions & 0 deletions docs/api/clients.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Clients

::: pypricecharting.pricecharting.PriceCharting

::: pypricecharting.asyncpricecharting.AsyncPriceCharting
3 changes: 3 additions & 0 deletions docs/api/models.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Models

::: pypricecharting.models
3 changes: 3 additions & 0 deletions docs/api/requests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Requests

::: pypricecharting.requests
3 changes: 3 additions & 0 deletions docs/api/responses.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Responses

::: pypricecharting.responses
3 changes: 3 additions & 0 deletions docs/api/route.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Routes

::: pypricecharting.route
3 changes: 3 additions & 0 deletions docs/api/types.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Types

::: pypricecharting.types
11 changes: 11 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# PyPriceCharting

Python client for the [PriceCharting API](https://www.pricecharting.com/api-documentation).

The package provides a synchronous client, `PriceCharting`, and an asynchronous client,
`AsyncPriceCharting`. Both authenticate with a 40-character PriceCharting API token.

The client is under development: the clients can be created and used as context managers, but
their API methods are not implemented yet.

See the [API Reference](api/clients.md) for the classes and types in the package.
4 changes: 4 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ ci-lint:
uv run ruff check .
uv run ruff format --check .
uv run codespell
docs:
uv run zensical serve
docs-build:
uv run zensical build --strict
git-leaks:
gitleaks git --pre-commit --staged --redact
lint:
Expand Down
49 changes: 49 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
site_name: PyPriceCharting
site_description: Python PriceCharting API Client
repo_url: https://github.com/ahcodedev/pypricecharting
repo_name: ahcodedev/pypricecharting
strict: true

theme:
name: material
variant: classic
features:
- content.code.copy
- navigation.sections
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
toggle:
icon: material/brightness-4
name: Switch to light mode

plugins:
- search
- mkdocstrings:
handlers:
python:
paths: [src]
options:
show_source: false
show_root_heading: true
members_order: source

markdown_extensions:
- admonition
- pymdownx.highlight
- pymdownx.superfences

nav:
- Home: index.md
- API Reference:
- Clients: api/clients.md
- Models: api/models.md
- Requests: api/requests.md
- Responses: api/responses.md
- Types: api/types.md
- Routes: api/route.md
6 changes: 6 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,16 @@ dev = [
"ruff>=0.16.0",
"ty>=0.0.96",
]
docs = [
"mkdocstrings[python]>=1.0.8",
"zensical>=0.1.0",
]

[tool.codespell]
# Product names used in PriceCharting's example data.
ignore-words-list = "gameboy"
# MkDocs build output.
skip = "./site"

[tool.pytest.ini_options]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under 98"
Expand Down
23 changes: 18 additions & 5 deletions src/pypricecharting/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ class PriceChartingModel(BaseModel):
model_config = ConfigDict(
alias_generator=to_kebab,
populate_by_name=True,
use_attribute_docstrings=True,
)


Expand All @@ -26,6 +27,7 @@ class ProductSummary(PriceChartingModel):
"""

id: str | None = None
"""PriceCharting product ID."""
product_name: str | None = None
console_name: str | None = None

Expand All @@ -37,23 +39,34 @@ class Offer(PriceChartingModel):
"""

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, prepend https://www.pricecharting.com
id: int | None = None # PriceCharting product ID
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
price: int | None = None # current price, or sale price with shipping premium if sold
"""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
cert_id: str | None = None # grading company certificate number, graded offers only
grade_co_id: int | None = None # grading company ID, graded offers only
"""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):
Expand Down
17 changes: 17 additions & 0 deletions src/pypricecharting/requests.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,45 @@
class OfferPublishRequest(PriceChartingModel):
"""api/offer-publish request

Set one of `product`, `upc`, `asin`, or `epid` to create an offer, or `offer_id` to edit one.
Set each condition tag that applies to `State.ON`. Leave them all unset for normal wear.

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

product: str | None = None
"""PriceCharting product ID of the item to list."""
upc: str | None = None
asin: str | None = None
epid: str | None = None
offer_id: str | None = None
"""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 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."""
cost_basis: int | None = None
"""What you paid for the item, in pennies."""
description: str | None = None
"""Listing description, up to 300 characters."""
broken: State | None = None
pristine: State | None = None
"""No blemishes. Overrides the other condition tags."""
scratch: State | None = None
stickers: State | None = None
tear: State | None = None
writing: State | None = None
price_min: PositiveInt | None = None
"""Lowest price in pennies.

Makes the offer a reverse auction that drops from `price_max` over 30 days.
"""
sku: str | None = None
"""Your internal SKU, up to 64 alphanumeric characters. Unique among active offers."""
quantity: PositiveInt | None = None
"""Number of copies owned. Collections only. The API defaults to 1."""

@model_validator(mode="after")
def check_identifier(self) -> Self:
Expand Down
Loading
Loading