python-amazon-paapi 6.3.0__tar.gz → 7.0.0__tar.gz

{python_amazon_paapi-6.3.0 → python_amazon_paapi-7.0.0}/.agent/rules/code-style-guide.md

@@ -17,11 +17,11 @@ trigger: always_on
 # Test
 
 - Add tests following TDD practices
-- Mirror the amazon_paapi structure in the tests directory
+- Mirror the amazon_creatorsapi structure in the tests directory
 - Use unittest.TestCase with setUp() and tearDown()
 - Use unittest assertions, not native assert
 - Use @patch decorators for mocks (avoid context managers)
 
 # References
 
-- Documentation for the Product Advertising API here: https://webservices.amazon.com/paapi5/documentation/operations.html
+- Documentation for the Creators API here: https://webservices.amazon.com/creatorsapi/documentation/

{python_amazon_paapi-6.3.0 → python_amazon_paapi-7.0.0}/.env.template

@@ -1,13 +1,7 @@
-# Product Advertising API
-API_KEY=
-API_SECRET=
-
 # Creators API
 CREDENTIAL_ID=
 CREDENTIAL_SECRET=
 API_VERSION=
 MARKETPLACE=
-
-# Common
 AFFILIATE_TAG=
 COUNTRY_CODE=

{python_amazon_paapi-6.3.0 → python_amazon_paapi-7.0.0}/.github/ISSUE_TEMPLATE/---bug-report.md

@@ -17,7 +17,7 @@ assignees: ''
 "Add some code that helps understanding the issue"
 ```
 **Current behavior**
-A clear and concise description of what is currenctly happening.
+A clear and concise description of what is currently happening.
 
 **Expected behavior**
 A clear and concise description of what you expected to happen.

python_amazon_paapi-7.0.0/.github/workflows/check.yml

@@ -0,0 +1,100 @@
+name: Run linters and tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Check CHANGELOG was updated
+        if: github.event_name == 'pull_request'
+        run: |
+          if git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -q "^CHANGELOG.md$"; then
+            echo "✅ CHANGELOG.md was updated"
+          else
+            echo "❌ ERROR: CHANGELOG.md was not updated"
+            echo "Please add your changes to the CHANGELOG.md file"
+            exit 1
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Cache pre-commit
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: ${{ runner.os }}-pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pre-commit-
+
+      # Tests are owned by the test job below, so the test hook is skipped here.
+      - name: Run all checks
+        env:
+          SKIP: test
+        run: uv run --extra async pre-commit run --all-files --verbose
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          # Only this leg has the credentials for the integration tests, so it
+          # is the one that can meet the coverage threshold.
+          - python-version: "3.13"
+            coverage: true
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+          # Each version resolves to different wheels, so they cannot share one
+          # cache entry.
+          cache-suffix: py${{ matrix.python-version }}
+
+      - name: Run tests
+        if: ${{ !matrix.coverage }}
+        run: uv run --python "${{ matrix.python-version }}" --extra async pytest -rs --no-cov
+
+      - name: Run tests with coverage
+        if: ${{ matrix.coverage }}
+        env:
+          AFFILIATE_TAG: ${{ secrets.AFFILIATE_TAG }}
+          COUNTRY_CODE: ${{ secrets.COUNTRY_CODE }}
+          CREDENTIAL_ID: ${{ secrets.CREDENTIAL_ID }}
+          CREDENTIAL_SECRET: ${{ secrets.CREDENTIAL_SECRET }}
+          API_VERSION: ${{ secrets.API_VERSION }}
+        run: uv run --python "${{ matrix.python-version }}" --extra async pytest -rs --cov=amazon_creatorsapi

{python_amazon_paapi-6.3.0 → python_amazon_paapi-7.0.0}/.github/workflows/release.yml

@@ -10,6 +10,7 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     if: github.ref == 'refs/heads/master'
     environment: pypi
     outputs:
@@ -19,6 +20,9 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v5
+        with:
+          # Needed so the tag existence check below can see the tags.
+          fetch-depth: 0
 
       - name: Extract version and notes from CHANGELOG
         id: changelog
@@ -40,7 +44,7 @@ jobs:
       - name: Check if tag already exists
         id: check_tag
         run: |
-          if git rev-parse "v${{ steps.changelog.outputs.version }}" >/dev/null 2>&1; then
+          if git rev-parse -q --verify "refs/tags/${{ steps.changelog.outputs.version }}" >/dev/null; then
             echo "exists=true" >> $GITHUB_OUTPUT
           else
             echo "exists=false" >> $GITHUB_OUTPUT
@@ -59,21 +63,17 @@ jobs:
       - name: Skip release (tag exists)
         if: steps.check_tag.outputs.exists == 'true'
         run: |
-          echo "⚠️ Tag v${{ steps.changelog.outputs.version }} already exists. Skipping release creation."
+          echo "⚠️ Tag ${{ steps.changelog.outputs.version }} already exists. Skipping release creation."
           exit 1
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: Install UV
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
-          python-version: "3.x"
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install build
+          # uv build only needs the build backend, not the project dependencies.
+          enable-cache: false
 
       - name: Build package
-        run: python -m build
+        run: uv build
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

{python_amazon_paapi-6.3.0 → python_amazon_paapi-7.0.0}/.pre-commit-config.yaml

@@ -28,12 +28,14 @@ repos:
       - id: check-merge-conflict
       - id: debug-statements
       - id: name-tests-test
+        # Support shared by the integration tests, which holds no test of its own
+        exclude: ^tests/integration_support\.py$
 
   - repo: https://github.com/lk16/detect-missing-init
     rev: v0.1.6
     hooks:
       - id: detect-missing-init
-        args: ["--create", "--python-folders", "amazon_paapi"]
+        args: ["--create", "--python-folders", "amazon_creatorsapi"]
 
   - repo: https://github.com/gitleaks/gitleaks
     rev: v8.30.0
@@ -52,7 +54,7 @@ repos:
       - id: test
         name: Running tests
         language: system
-        entry: "bash -c 'set -a && source .env 2>/dev/null; set +a && uv run pytest -rs --cov=amazon_paapi --cov=amazon_creatorsapi'"
+        entry: "bash -c 'set -a && source .env 2>/dev/null; set +a && uv run pytest -rs --cov=amazon_creatorsapi'"
         types_or: [python]
         pass_filenames: false
 

python_amazon_paapi-7.0.0/CHANGELOG.md

@@ -0,0 +1,182 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [7.0.0] - 2026-09-04
+
+### Added
+
+- `list_feeds`, `get_feed`, `list_reports` and `get_report` methods in `amazon_creatorsapi` and `amazon_creatorsapi.aio`, with `Feed`, `FeedType`, `ReportMetadata` and `ReportType` in `amazon_creatorsapi.models` and in the bundled SDK
+- `timeout` parameter in `AmazonCreatorsApi` and `AsyncAmazonCreatorsApi` to set the request timeout in seconds, or `None` to wait indefinitely
+- `retries` parameter in `AmazonCreatorsApi` and `AsyncAmazonCreatorsApi` to retry the throttled and failed requests that Amazon asks to retry, waiting longer before every attempt and honouring the `Retry-After` header, whether Amazon sends it as an amount of seconds or as a date
+- `include_unavailable` parameter in `get_items` to get an item holding only the ASIN for every requested item missing from the response
+- `availability` parameter in `search_items` to include the items that are out of stock, keyword only and placed after the rest, so the arguments of a caller not using keywords keep their position
+- `host` and `auth_endpoint` parameters in `AmazonCreatorsApi` and `AsyncAmazonCreatorsApi` to replace the endpoints of the API, useful to run tests against a mock server or to use a version newer than the ones known by the library, as long as the library can authenticate its family
+- `AccessDeniedError`, raised when the credentials cannot perform the requested operation
+- `ResourceNotFoundError`, raised when a feed or report does not exist, telling it apart from missing items
+- Partial errors of a response are available in the `errors` attribute of the lists returned by `get_items` and `get_browse_nodes`, and are reported in the message of `ItemsNotFoundError`
+- `ErrorData` and `ResultList` available in `amazon_creatorsapi.models`
+- `get_asin` and `errors` are available directly in `amazon_creatorsapi`
+- The identifier that Amazon gives to a request is part of the message of the error, so it can be reported to Amazon support
+- `close` method and context manager support in `AmazonCreatorsApi`, to release the connections of a client that is not going to be reused
+- `py.typed` marker, so the type hints of the package are used by type checkers
+- Migration guide from version 6, listing what can break in code written for `amazon_creatorsapi` and how to fix it
+- The values accepted by `version`, the countries and the marketplace each one maps to, and the `marketplace` argument are documented, instead of having to read the code to find them
+- `CONTRIBUTING.md`, with the setup of the project, the commands of the `Makefile`, the conventions of the code and the tests, and what a pull request is expected to carry
+- Tests pinning the signatures of both clients and the hierarchy of the errors, so a change that breaks the code of the users is noticed
+
+### Changed
+
+- Requests time out after 30 seconds instead of waiting indefinitely, the refresh of the token included, which waited indefinitely in `AmazonCreatorsApi` and used the 5 second default of `httpx` in `AsyncAmazonCreatorsApi`. Pass `timeout=None` to restore the previous behaviour
+- Errors are mapped from the response of the Creators API instead of the codes of the old Product Advertising API, so the reason and the fields that failed are part of the message
+- A rejected request raises `InvalidArgumentError`, missing or expired credentials raise `AuthenticationError` and a forbidden request raises `AccessDeniedError`, instead of a generic `RequestError`
+- Values rejected by the API constraints raise `InvalidArgumentError` instead of a `pydantic.ValidationError`
+- Connection failures and unparseable responses raise `RequestError` instead of leaking the errors of the HTTP client
+- An expired token is refreshed once and the request is sent again instead of failing
+- `AuthenticationError` and `AccessDeniedError` are subclasses of `RequestError`, which is what a failed request raised before they got their own type
+- `InvalidArgumentError` is also a `ValueError`, as the `pydantic.ValidationError` and the plain `ValueError` it replaced were
+- `get_items` splits a request with more items than the API accepts into as many calls as needed, so any amount of items can be requested at once
+- `get_items` returns the items in the order they were requested, and asks for duplicated items only once
+- `get_items` raises `ItemsNotFoundError` when the response holds no requested item, as documented, instead of returning an empty list
+- `search_items` rejects a search without any criteria instead of sending it to the API
+- An unsupported `version` raises `InvalidArgumentError` instead of a plain `ValueError`, like the rest of the arguments of the clients, and a version of a family that the library cannot authenticate is rejected even when `auth_endpoint` is given, instead of being sent with the Cognito flow and rejected by Amazon without an explanation
+- The error of an unsupported version tells that a newer version of a known family can be used by providing its `auth_endpoint`
+- `AmazonCreatorsApi` validates the version when it is created, as `AsyncAmazonCreatorsApi` already did, instead of failing on the first request
+- The auth flow of a version and the `Authorization` header it expects are decided in a single place shared by both clients, and the copies bundled in the SDK are pinned to them by tests, so a bump of the SDK cannot leave both halves disagreeing
+- `AsyncAmazonCreatorsApi` builds its requests with the models of the SDK, so both clients validate the same values before sending a request
+- Every client uses its own configuration for the SDK instead of the one shared by the whole process
+- Throttling is measured with a monotonic clock and is safe to use from several threads
+- `throttling` is validated like the rest of the options, so a negative or invalid value raises `InvalidArgumentError` instead of being accepted or failing with a `TypeError`
+- The usage guide covers everything the README does, so the documentation does not have to be read in both places, and the README links to it
+- The integration tests reach every operation of the API, feeds and reports included, and both clients share the same assertions, so a difference between them is a failure instead of a gap
+- Every integration test reads the results of a single round of calls, which loads each request with as much as it can check, so the whole API is covered without spending more requests of the account
+- The async integration tests make their calls when the suite runs instead of when the module is imported, so they are not sent when the tests are deselected and a failure is reported as such
+- The CI workflow runs the test suite once per Python version instead of also running it inside the linter job, cancels superseded pull request runs and installs `uv` through a cached action
+- The release workflow builds with `uv build`, and its check for an already existing tag looks for the tag name that is actually created, which never matched before
+- Bumped the bundled `creatorsapi-python-sdk` from `1.2.0` to `1.3.0`, which makes `partnerTag` a required field of `SearchItemsRequestContent`
+- Pinned `ruff` to the version run by pre-commit, so `make lint` matches CI
+
+### Fixed
+
+- Examples in the documentation that used names that do not exist, such as `SortBy.PRICE_LOW_TO_HIGH` or `GetItemsResource.ITEMINFO_TITLE`
+- Documented limits of `item_count`, `min_reviews_rating` and `variation_page`, which did not match the ones accepted by the API
+- A token response that does not hold JSON raises `AuthenticationError` in `AsyncAmazonCreatorsApi`, instead of the error of the JSON parser
+- Errors reported by the transport, such as an invalid certificate, keep their reason instead of being reported as `Request failed with status 0`
+- An ASIN longer than ten characters in a URL is rejected instead of being trimmed to a different item
+- Threads sharing a client ask for a single token when the cached one expires, instead of one for every thread
+- Search integration tests no longer assume Amazon always returns a full page of items
+
+### Removed
+
+- The deprecated `amazon_paapi` module and its bundled Product Advertising API 5.0 SDK, with `AmazonApi`, `amazon_paapi.errors`, `amazon_paapi.helpers`, `amazon_paapi.models` and `amazon_paapi.tools`. Use `amazon_creatorsapi` instead, following the [migration guide](https://python-amazon-paapi.readthedocs.io/en/latest/pages/migration-guide-6.html) for the credential, method and exception mapping
+- Product Advertising API documentation and deprecation notices in the README and docs
+- `API_KEY` and `API_SECRET` environment variables, only used by the removed module
+- `six` dependency, which was not used
+
+## [6.3.0] - 2026-05-15
+
+### Added
+
+- `delivery_flags` parameter in `search_items` for `amazon_creatorsapi` and `amazon_creatorsapi.aio`
+
+## [6.2.0] - 2026-03-12
+
+### Added
+
+- LWA support in the `amazon_creatorsapi.aio` API layer
+
+### Changed
+
+- Bumped `creatorsapi-python-sdk` from `1.1.2` to `1.2.0`
+- Updated bundled SDK support to include LWA endpoints for v3.x
+
+## [6.1.0] - 2026-02-09
+
+### Added
+
+- Full async/await support with new `amazon_creatorsapi.aio` subpackage ([#143](https://github.com/sergioteula/python-amazon-paapi/pull/143))
+- `AsyncAmazonCreatorsApi` class for non-blocking API interactions
+- Async HTTP client with `httpx` integration for connection pooling
+- `AuthenticationError` exception for improved OAuth2 error handling
+- Optional `[async]` installation extra: `pip install python-amazon-paapi[async]`
+- Comprehensive async test suite with integration tests
+- Documentation for async API usage in README and usage guide
+- `make docs` command in Makefile for building documentation
+
+### Changed
+
+- GitHub Actions workflow now installs async dependencies for complete test coverage
+- Test coverage threshold lowered from 99% to 98% to accommodate async tests
+- Additional Ruff linting rules for test files (ARG002, S101, S105, S106, SIM117)
+
+## [6.0.0] - 2026-01-29
+
+### Added
+
+- New `amazon_creatorsapi` module for Amazon Creators API support
+- `creatorsapi_python_sdk` package bundled for OAuth2 authentication
+- `models` submodule exposing all SDK model classes (Item, Condition, SortBy, etc.)
+- Migration guide from PAAPI to Creators API (`docs/pages/migration-guide-6.md`)
+- Integration tests for the new Creators API module
+- New dependencies: `pydantic>=2.0.0` and `requests>=2.28.0`
+
+### Changed
+
+- **BREAKING**: The `amazon_paapi` module is now deprecated in favor of `amazon_creatorsapi`
+- Updated documentation to reflect the new Creators API module
+- Reorganized utility functions into `amazon_creatorsapi.core` package
+- Updated README with Creators API examples and deprecation notice
+
+### Deprecated
+
+- `amazon_paapi` module - use `amazon_creatorsapi` instead
+- All PAAPI-specific documentation pages removed
+
+### Removed
+
+- Migration guides for versions 4 and 5 (`migration-guide-4.md`, `migration-guide-5.md`)
+
+## [5.2.0] - 2026-01-11
+
+### Added
+
+- Support for OffersV2 resources with new model classes ([#141](https://github.com/sergioteula/python-amazon-paapi/pull/141))
+
+## [5.1.0] - 2026-01-11
+
+### Added
+
+- Integration tests with real Amazon API calls
+- Type hints throughout the codebase using `Literal` types for country codes
+- `.env.template` file for easier development setup
+- Code style guide for AI assistants (`.agent/rules/code-style-guide.md`)
+- Pre-commit hooks with Ruff integration
+- Version consistency check script (`scripts/check_version.py`)
+- Manual release workflow (`release.yml`) that creates GitHub releases from CHANGELOG
+- CI check to ensure CHANGELOG is updated in every PR
+
+### Changed
+
+- **BREAKING**: Minimum Python version raised from 3.7 to 3.9
+- Migrated from `setup.py` to `pyproject.toml` for project configuration
+- Replaced multiple linters (Flake8, isort, Black, Pylint) with Ruff
+- Replaced Docker-based development environment with `uv` package manager
+- Consolidated coverage, mypy, and pytest configuration into `pyproject.toml`
+- Renamed test files to use `_test.py` suffix instead of `test_` prefix
+- Updated GitHub Actions workflows to use `uv` instead of Docker
+- Improved docstrings across the codebase
+- Completely rewritten README with clearer structure and examples
+- Updated Read the Docs configuration to v2 format with modern Sphinx versions
+- Updated documentation to furo theme
+
+### Removed
+
+- `setup.py` - replaced by `pyproject.toml`
+- `.coveragerc` - configuration moved to `pyproject.toml`
+- `.flake8` - replaced by Ruff configuration in `pyproject.toml`
+- Docker development environment (`docker/`, `docker-compose.yml`)
+- Legacy shell scripts (`scripts/` directory)
+- Custom git hooks (`.githooks/`) - replaced by pre-commit

python_amazon_paapi-7.0.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing
+
+Thanks for taking the time to contribute. This guide covers how to set the project up,
+what the checks expect and how a change should be shaped.
+
+## Setting up
+
+The project is managed with [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/sergioteula/python-amazon-paapi.git
+cd python-amazon-paapi
+uv sync --extra async
+make setup
+```
+
+`make setup` installs the pre-commit hooks, which run Ruff, mypy and the tests before
+every commit. The `async` extra is needed to run the tests of `AsyncAmazonCreatorsApi`.
+
+Copy `.env.template` to `.env` and fill it with your Creators API credentials to run the
+integration tests. Without it the unit tests still run, and the integration tests are
+skipped and reported as such.
+
+## Commands
+
+| Command                     | What it does                                            |
+| --------------------------- | ------------------------------------------------------- |
+| `make test`                 | Run the test suite                                      |
+| `make coverage`             | Run the tests with a coverage report                    |
+| `make test-all-python-tags` | Run the tests on every supported Python version         |
+| `make lint`                 | Run Ruff and apply the fixes it can make                |
+| `make format`               | Format the code with Ruff                               |
+| `make mypy`                 | Check the types                                         |
+| `make pre-commit`           | Run every hook against all the files, as CI does        |
+| `make docs`                 | Build the documentation into `docs/_build/html`          |
+
+## Layout
+
+| Path                      | What it holds                                                     |
+| ------------------------- | ------------------------------------------------------------------ |
+| `amazon_creatorsapi/`     | The library: the clients, the errors and the core utilities        |
+| `creatorsapi_python_sdk/` | The SDK generated from the API schema, vendored and not edited     |
+| `tests/`                  | The test suite, mirroring the structure of `amazon_creatorsapi`    |
+| `docs/`                   | The Sphinx documentation published on Read the Docs                |
+
+`creatorsapi_python_sdk` is generated code: it is excluded from Ruff, mypy and the
+formatter, and it is replaced wholesale when the SDK is bumped, so a fix belongs in
+`amazon_creatorsapi` and not there.
+
+## Style
+
+- Everything in English: code, comments, docstrings and commit messages.
+- Docstrings on every function, and type hints on every signature.
+- Comments only where the reason for the code is not obvious from the code itself.
+- No abbreviations or single-letter names.
+- `noqa` only when there is no other way, and never without a reason.
+
+## Tests
+
+- Tests come with the change, following TDD.
+- The `tests` directory mirrors the structure of `amazon_creatorsapi`.
+- `unittest.TestCase` with `setUp` and `tearDown`, unittest assertions and `@patch`
+  decorators rather than context managers.
+- Coverage may not drop below 98%, which is enforced by the test run.
+
+## Documentation
+
+A change that adds or changes something a user can see belongs in the documentation as
+well:
+
+- `README.md` and `docs/pages/usage-guide.md` cover the same ground, the guide in more
+  depth. Keep both in step.
+- Docstrings feed the API reference, so a new argument is documented there too.
+
+## Sending a change
+
+1. Add an entry to `CHANGELOG.md`, under `[Unreleased]`, in the section that matches the
+   change: `Added`, `Changed`, `Fixed` or `Removed`. CI rejects a pull request that does
+   not touch the changelog.
+2. Run `make pre-commit` and make sure everything passes.
+3. Open the pull request describing what changes for the user and why.
+
+The version lives in `pyproject.toml`, `docs/conf.py` and `CHANGELOG.md`, and
+`scripts/check_version.py` checks that the three agree. Only a release changes them.
+
+## Getting help
+
+Ask in the [Telegram group](https://t.me/PythonAmazonPAAPI) or open an
+[issue](https://github.com/sergioteula/python-amazon-paapi/issues).

{python_amazon_paapi-6.3.0 → python_amazon_paapi-7.0.0}/Makefile

@@ -11,7 +11,7 @@ test:
 	@uv run --env-file .env pytest -rs
 
 coverage:
-	@uv run pytest -rs --cov=amazon_paapi --cov=amazon_creatorsapi --cov-report=html --cov-report=term --cov-report=xml
+	@uv run pytest -rs --cov=amazon_creatorsapi --cov-report=html --cov-report=term --cov-report=xml
 
 test-all-python-tags:
 	@touch .env