Merge pull request #143 from sergioteula/add-async-support

Add async support to Creators API

Author: sergioteula

.github/workflows/check.yml

@@ -35,6 +35,9 @@ jobs:
       API_SECRET: ${{ secrets.API_SECRET }}
       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 }}
 
     steps:
       - uses: actions/checkout@v5
@@ -65,7 +68,7 @@ jobs:
 
       - name: Run all checks
         run: |
-          uv run pre-commit run --all-files
+          uv run --extra async pre-commit run --all-files --verbose
 
   test:
     runs-on: ubuntu-latest
@@ -91,4 +94,4 @@ jobs:
             ${{ runner.os }}-uv-py${{ matrix.python-version }}-
 
       - name: Run tests
-        run: uv run --python "${{ matrix.python-version }}" pytest -rs --no-cov
+        run: uv run --python "${{ matrix.python-version }}" --extra async pytest -rs --no-cov

CHANGELOG.md

@@ -5,6 +5,25 @@ 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).
 
+## [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

Makefile

@@ -30,3 +30,8 @@ mypy:
 
 pre-commit:
 	@uv run pre-commit run -a
+
+docs:
+	@cd docs && uv run make html
+
+.PHONY: setup test coverage test-all-python-tags lint format mypy pre-commit docs

README.md

@@ -13,7 +13,8 @@ A Python wrapper for Amazon's product APIs. This package supports both the legac
 ## Features
 
 - 🎯 **Simple object-oriented interface** for easy integration
-- 🔍 **Product search** by keywords, categories, or browse nodes
+- � **Async/await support** for high-performance applications
+- �🔍 **Product search** by keywords, categories, or browse nodes
 - 📦 **Product details** via ASIN or Amazon URL
 - 🔄 **Item variations** support (size, color, etc.)
 - 💰 **OffersV2 support** for enhanced pricing and offer details
@@ -118,6 +119,40 @@ amazon = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, throttling=4)  # M
 amazon = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, throttling=0)  # No wait time between requests
 ```
 
+### Async Support
+
+For async/await applications, use the async version of the API with `httpx`:
+
+```bash
+pip install python-amazon-paapi[async] --upgrade
+```
+
+The async API provides the same methods as the synchronous version, but they must be called with `await`:
+
+```python
+from amazon_creatorsapi.aio import AsyncAmazonCreatorsApi
+from amazon_creatorsapi import Country
+
+# Use as async context manager (recommended for connection pooling)
+async with AsyncAmazonCreatorsApi(
+    credential_id="your_credential_id",
+    credential_secret="your_credential_secret",
+    version="2.2",
+    tag="your-affiliate-tag",
+    country=Country.US,
+) as api:
+    items = await api.get_items(["B01N5IB20Q"])
+    results = await api.search_items(keywords="laptop")
+    variations = await api.get_variations("B01N5IB20Q")
+    nodes = await api.get_browse_nodes(["667049031"])
+
+# Or use without context manager (creates new connection per request)
+api = AsyncAmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY)
+items = await api.get_items(["B01N5IB20Q"])
+```
+
+> **Note:** All synchronous methods and parameters work identically in async mode. Use `async with` for better performance when making multiple API calls.
+
 ### Working with Models
 
 All SDK models are re-exported through `amazon_creatorsapi.models` for convenient access:

amazon_creatorsapi/aio/__init__.py

@@ -0,0 +1,14 @@
+"""Async support for Amazon Creators API."""
+
+try:
+    import httpx  # noqa: F401
+except ImportError as exc:  # pragma: no cover
+    msg = (
+        "httpx is required for async support. "
+        "Install it with: pip install python-amazon-paapi[async]"
+    )
+    raise ImportError(msg) from exc
+
+from amazon_creatorsapi.aio.api import AsyncAmazonCreatorsApi
+
+__all__ = ["AsyncAmazonCreatorsApi"]