Development¶

git clone https://github.com/anthonyblazejack/amazon-ads-py
cd amazon-ads-py
uv sync --all-extras
uv run pytest

Checks¶

CI runs all of these on Python 3.11 to 3.14. Run them before pushing:

uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run mypy
uv run pytest --cov=amazon_ads
uv run python scripts/generate_catalog.py --docs-only && git diff --exit-code docs
uv run mkdocs build --strict

Tests¶

Tests mock Amazon with respx and run offline. Every test should name the bug it catches: a retry that could duplicate a write, a 207 error paired with the wrong input, a report chunk that skips a day. Ids in tests are invented. Never paste real profile ids, ASINs, campaign names or bids from an account into this repository.

Live tests hit the real API and are opt-in:

AMAZON_ADS_ENV_FILE=/path/to/.env uv run pytest -m live

They only read.

Regenerating from Amazon's specs¶

uv run python scripts/fetch_specs.py        # downloads ~220 specs into specs/ (gitignored)
uv run python scripts/generate_catalog.py   # rebuilds the catalog and the coverage page

The specs are Amazon's documents and are not committed. The generated src/amazon_ads/_generated/catalog.json and docs/reference/coverage.md are. A weekly workflow (.github/workflows/specs.yml) runs both scripts, runs the tests, the em dash check and the strict docs build, and when anything changed commits the result straight to main, listing added and removed operations in the commit message. A failed run pushes nothing.

When the typed layer changes which operations it wraps, update WRAPPED_PREFIXES in scripts/generate_catalog.py so the coverage page marks them.

When the live API refuses a media type its own spec documents, add an entry to CORRECTIONS in src/amazon_ads/catalog.py, never a hand edit of catalog.json: the catalog applies corrections when it loads, so regenerating keeps them. A test fails when a correction's operation id no longer exists (Amazon renamed it) or when the spec starts documenting the corrected type, so a failed weekly spec refresh can mean a correction needs another look against the live API.

API quirks¶

When you find live behavior the specs do not describe, add it to src/amazon_ads/notes.py, handle it in code, and run scripts/generate_catalog.py --docs-only to update docs/guide/quirks.md. The same text is served to Claude by the MCP server.

Documentation¶

Every change to public behavior updates the relevant page under docs/, the README if it affects the quick start, and CHANGELOG.md, in the same commit.

uv run mkdocs serve

Releasing¶

Update version in pyproject.toml and src/amazon_ads/_version.py, and move the changelog's Unreleased section under the new version.
Tag vX.Y.Z and push the tag. The release workflow builds and publishes to PyPI with trusted publishing (no token stored in the repository).