amazon-ads-api-v1 0.11.0__tar.gz

amazon_ads_api_v1-0.11.0/.gitignore

@@ -0,0 +1,38 @@
+# Claude Code settings（本地，不提交）
+.claude/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# IDE
+.idea/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# uv.lock 由 uv 管理，需提交
+
+# OS
+.DS_Store
+*.swp
+*.swo
+
+# MiMoCode
+.mimocode/
+
+# Distribution / build
+*.egg-info/
+dist/
+build/
+
+.dist/
+.cursor

amazon_ads_api_v1-0.11.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: amazon-ads-api-v1
+Version: 0.11.0
+Summary: Synchronous Amazon Ads API client — v0 and v1 (SP, SB, SD, DSP, ST, and more)
+Project-URL: Homepage, https://github.com/apollosuite/async_amazon_ads_api_v1
+Project-URL: Repository, https://github.com/apollosuite/async_amazon_ads_api_v1
+Project-URL: Issues, https://github.com/apollosuite/async_amazon_ads_api_v1/issues
+Author-email: Jack <zhangwenguang@apollosuite.com>
+License-Expression: MIT
+Keywords: ads,ads-api,advertising,amazon,api-v1,sponsored-brands,sponsored-display,sponsored-products
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.10.0
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# amazon-ads-api-v1
+
+[![PyPI version](https://img.shields.io/pypi/v/amazon-ads-api-v1)](https://pypi.org/project/amazon-ads-api-v1/)
+[![Python versions](https://img.shields.io/pypi/pyversions/amazon-ads-api-v1)](https://pypi.org/project/amazon-ads-api-v1/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+纯同步 Amazon Ads API 客户端。PyPI 安装名为 **`amazon-ads-api-v1`**，导入名为 **`ads_api`**。统一覆盖 v0 与 v1（SP、SB、SD、DSP、ST、SP Global、Accounts、Reporting、Ads Data Manager、Exports 等）。原生基于 `httpx.Client`，支持直接调用，无事件循环冲突。
+
+## Installation
+
+```bash
+pip install amazon-ads-api-v1
+# 或
+uv add amazon-ads-api-v1
+```
+
+Redis 缓存支持：
+
+```bash
+pip install "amazon-ads-api-v1[redis]"
+# 或
+uv add "amazon-ads-api-v1[redis]"
+```
+
+## Quick Start
+
+所有 API 方法仅接受 Pydantic model 实例，不支持 dict。默认 `mode="dict"`，需要模型对象时传 `mode="pydantic"`。
+
+### 使用 Access Token
+
+```python
+from ads_api import AdsClient, AmazonAdsConfig, Region
+from ads_api.models.v1.campaigns.sp import SPQueryCampaignRequest
+
+
+def main() -> None:
+    config = AmazonAdsConfig(
+        access_token="your-access-token",
+        client_id="your-client-id",
+        region=Region.NA,
+    )
+    body = SPQueryCampaignRequest(
+        adProductFilter={"include": ["SPONSORED_PRODUCTS"]},
+        stateFilter={"include": ["ENABLED"]},
+    )
+
+    with AdsClient(config) as ads:
+        resp = ads.v1.sp.campaigns.query_campaign(body)
+        print(resp)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+### 使用 Refresh Token（自动续期）
+
+```python
+from ads_api import AdsClient, AmazonAdsConfig, Region
+from ads_api.models.v1.campaigns.sp import SPQueryCampaignRequest
+
+
+def main() -> None:
+    config = AmazonAdsConfig(
+        client_id="your-client-id",
+        refresh_token="your-refresh-token",
+        client_secret="your-client-secret",
+        region=Region.NA,
+    )
+    body = SPQueryCampaignRequest(
+        adProductFilter={"include": ["SPONSORED_PRODUCTS"]},
+        stateFilter={"include": ["ENABLED"]},
+    )
+
+    with AdsClient(config) as ads:
+        resp = ads.v1.sp.campaigns.query_campaign(body, mode="pydantic")
+        print(resp.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## Token Management
+
+SDK 内置 OAuth token 生命周期管理。提供 `refresh_token` 与 `client_secret` 后会自动续期；缓存按字段推断：
+
+```python
+from ads_api import AmazonAdsConfig, Region
+
+# 自动续期，不使用磁盘 / Redis 缓存
+config = AmazonAdsConfig(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    refresh_token="your-refresh-token",
+    region=Region.NA,
+)
+
+# 文件缓存
+config = AmazonAdsConfig(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    refresh_token="your-refresh-token",
+    region=Region.NA,
+    token_cache_dir="~/.cache/ads_api",
+)
+
+# Redis 缓存
+config = AmazonAdsConfig(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    refresh_token="your-refresh-token",
+    region=Region.NA,
+    redis_url="redis://localhost:6379",
+)
+```
+
+## API 入口
+
+```python
+with AdsClient(config) as ads:
+    # v1
+    ads.v1.sp.campaigns.query_campaign(body)
+    ads.v1.sb.campaigns.query_campaign(body)
+    ads.v1.sd.campaigns.query_campaign(body)
+    ads.v1.selling_accounts.query_selling_account(body)
+    ads.v1.reports.create_report(body)
+
+    # v0
+    ads.v0.accounts.profiles.list_profiles()
+    ads.v0.portfolios.list_portfolios()
+    ads.v0.sp_v3.campaigns.create_sponsored_products_campaigns(body)
+    ads.v0.sb_v4.budget_rules.create_budget_rules_for_sb_campaigns(body)
+    ads.v0.sd.creatives.create_creatives(body)
+```
+
+## License
+
+[MIT](LICENSE)

amazon_ads_api_v1-0.11.0/README.md

@@ -0,0 +1,139 @@
+# amazon-ads-api-v1
+
+[![PyPI version](https://img.shields.io/pypi/v/amazon-ads-api-v1)](https://pypi.org/project/amazon-ads-api-v1/)
+[![Python versions](https://img.shields.io/pypi/pyversions/amazon-ads-api-v1)](https://pypi.org/project/amazon-ads-api-v1/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+纯同步 Amazon Ads API 客户端。PyPI 安装名为 **`amazon-ads-api-v1`**，导入名为 **`ads_api`**。统一覆盖 v0 与 v1（SP、SB、SD、DSP、ST、SP Global、Accounts、Reporting、Ads Data Manager、Exports 等）。原生基于 `httpx.Client`，支持直接调用，无事件循环冲突。
+
+## Installation
+
+```bash
+pip install amazon-ads-api-v1
+# 或
+uv add amazon-ads-api-v1
+```
+
+Redis 缓存支持：
+
+```bash
+pip install "amazon-ads-api-v1[redis]"
+# 或
+uv add "amazon-ads-api-v1[redis]"
+```
+
+## Quick Start
+
+所有 API 方法仅接受 Pydantic model 实例，不支持 dict。默认 `mode="dict"`，需要模型对象时传 `mode="pydantic"`。
+
+### 使用 Access Token
+
+```python
+from ads_api import AdsClient, AmazonAdsConfig, Region
+from ads_api.models.v1.campaigns.sp import SPQueryCampaignRequest
+
+
+def main() -> None:
+    config = AmazonAdsConfig(
+        access_token="your-access-token",
+        client_id="your-client-id",
+        region=Region.NA,
+    )
+    body = SPQueryCampaignRequest(
+        adProductFilter={"include": ["SPONSORED_PRODUCTS"]},
+        stateFilter={"include": ["ENABLED"]},
+    )
+
+    with AdsClient(config) as ads:
+        resp = ads.v1.sp.campaigns.query_campaign(body)
+        print(resp)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+### 使用 Refresh Token（自动续期）
+
+```python
+from ads_api import AdsClient, AmazonAdsConfig, Region
+from ads_api.models.v1.campaigns.sp import SPQueryCampaignRequest
+
+
+def main() -> None:
+    config = AmazonAdsConfig(
+        client_id="your-client-id",
+        refresh_token="your-refresh-token",
+        client_secret="your-client-secret",
+        region=Region.NA,
+    )
+    body = SPQueryCampaignRequest(
+        adProductFilter={"include": ["SPONSORED_PRODUCTS"]},
+        stateFilter={"include": ["ENABLED"]},
+    )
+
+    with AdsClient(config) as ads:
+        resp = ads.v1.sp.campaigns.query_campaign(body, mode="pydantic")
+        print(resp.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## Token Management
+
+SDK 内置 OAuth token 生命周期管理。提供 `refresh_token` 与 `client_secret` 后会自动续期；缓存按字段推断：
+
+```python
+from ads_api import AmazonAdsConfig, Region
+
+# 自动续期，不使用磁盘 / Redis 缓存
+config = AmazonAdsConfig(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    refresh_token="your-refresh-token",
+    region=Region.NA,
+)
+
+# 文件缓存
+config = AmazonAdsConfig(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    refresh_token="your-refresh-token",
+    region=Region.NA,
+    token_cache_dir="~/.cache/ads_api",
+)
+
+# Redis 缓存
+config = AmazonAdsConfig(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    refresh_token="your-refresh-token",
+    region=Region.NA,
+    redis_url="redis://localhost:6379",
+)
+```
+
+## API 入口
+
+```python
+with AdsClient(config) as ads:
+    # v1
+    ads.v1.sp.campaigns.query_campaign(body)
+    ads.v1.sb.campaigns.query_campaign(body)
+    ads.v1.sd.campaigns.query_campaign(body)
+    ads.v1.selling_accounts.query_selling_account(body)
+    ads.v1.reports.create_report(body)
+
+    # v0
+    ads.v0.accounts.profiles.list_profiles()
+    ads.v0.portfolios.list_portfolios()
+    ads.v0.sp_v3.campaigns.create_sponsored_products_campaigns(body)
+    ads.v0.sb_v4.budget_rules.create_budget_rules_for_sb_campaigns(body)
+    ads.v0.sd.creatives.create_creatives(body)
+```
+
+## License
+
+[MIT](LICENSE)

amazon_ads_api_v1-0.11.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "amazon-ads-api-v1"
+dynamic = ["version"]
+description = "Synchronous Amazon Ads API client — v0 and v1 (SP, SB, SD, DSP, ST, and more)"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [{ name = "Jack", email = "zhangwenguang@apollosuite.com" }]
+keywords = ["amazon", "ads", "ads-api", "advertising", "sponsored-products", "sponsored-brands", "sponsored-display", "api-v1"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "httpx>=0.28.0",
+    "pydantic>=2.10.0",
+]
+
+[project.optional-dependencies]
+redis = ["redis>=5.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/apollosuite/async_amazon_ads_api_v1"
+Repository = "https://github.com/apollosuite/async_amazon_ads_api_v1"
+Issues = "https://github.com/apollosuite/async_amazon_ads_api_v1/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/ads_api/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ads_api"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/ads_api", "README.md", "pyproject.toml"]

amazon_ads_api_v1-0.11.0/src/ads_api/__init__.py

@@ -0,0 +1,25 @@
+"""Amazon Ads API package (Synchronous)."""
+
+from ads_api.base import ClientContext
+from ads_api.client import AdsClient
+from ads_api.client.v0 import AdsClientV0
+from ads_api.client.v1 import AdsClientV1
+from ads_api.config.region import Region
+from ads_api.config.settings import AmazonAdsConfig
+from ads_api.config.token_cache import BaseTokenCache, FileTokenCache, RedisTokenCache
+from ads_api.config.token_manager import TokenCredentials, TokenManager
+
+__all__ = [
+    "AdsClient",
+    "AdsClientV0",
+    "AdsClientV1",
+    "AmazonAdsConfig",
+    "BaseTokenCache",
+    "ClientContext",
+    "FileTokenCache",
+    "RedisTokenCache",
+    "Region",
+    "TokenCredentials",
+    "TokenManager",
+]
+__version__ = "0.11.0"

amazon_ads_api_v1-0.11.0/src/ads_api/base.py

@@ -0,0 +1,208 @@
+"""Shared HTTP session and base resource class (Synchronous)."""
+
+from __future__ import annotations
+
+import email.utils
+import logging
+import random
+import time
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from typing import Any, Literal, cast, overload
+
+import httpx
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from ads_api.config.settings import AmazonAdsConfig
+from ads_api.errors import raise_for_status
+
+logger = logging.getLogger(__name__)
+
+type ResponseMode = Literal["dict", "pydantic", "raw"]
+
+
+def _parse_retry_after(resp: httpx.Response | None, fallback_seconds: float, max_wait: float = 60.0) -> float:
+    """Parse the Retry-After header as seconds or HTTP-Date with fallback."""
+    if resp is None:
+        return fallback_seconds
+    headers = getattr(resp, "headers", None)
+    if headers is None:
+        return fallback_seconds
+    raw = headers.get("Retry-After")
+    if not raw:
+        return fallback_seconds
+    try:
+        seconds = float(raw)
+        if seconds >= 0:
+            return min(seconds + random.uniform(0, 0.5), max_wait)
+    except (ValueError, TypeError):
+        pass
+    try:
+        target_dt = email.utils.parsedate_to_datetime(str(raw))
+        now_dt = datetime.now(UTC)
+        delta = (target_dt - now_dt).total_seconds()
+        if delta > 0:
+            return min(delta + random.uniform(0, 0.5), max_wait)
+    except Exception:
+        pass
+    return fallback_seconds
+
+
+class ClientContext:
+    """Shared HTTP state for all resource instances."""
+
+    __slots__ = ("config", "_client")
+
+    def __init__(self, config: AmazonAdsConfig) -> None:
+        self.config: AmazonAdsConfig = config
+        self._client: httpx.Client | None = None
+
+    def get_client(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(base_url=self.config.base_url, timeout=httpx.Timeout(self.config.timeout))
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+        if self.config._token_manager is not None:
+            self.config._token_manager.close()
+
+    def __enter__(self) -> ClientContext:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class BaseResource:
+    """HTTP helpers shared by generated resource classes."""
+
+    __slots__ = ("_ctx", "exclude_unset", "exclude_none")
+
+    def __init__(self, ctx: ClientContext, exclude_unset: bool = True, exclude_none: bool = True) -> None:
+        self._ctx: ClientContext = ctx
+        self.exclude_unset = exclude_unset
+        self.exclude_none = exclude_none
+
+    @overload
+    def dump_json(self, body: None) -> dict[str, Any]: ...
+    @overload
+    def dump_json(self, body: BaseModel) -> dict[str, Any]: ...
+    @overload
+    def dump_json(self, body: Sequence[BaseModel]) -> list[Any]: ...
+    def dump_json(self, body: BaseModel | Sequence[BaseModel] | None) -> dict[str, Any] | list[Any]:
+        """Serialize a request body. ``None`` becomes ``{}`` so optional OpenAPI bodies omit fields."""
+        if isinstance(body, BaseModel):
+            return body.model_dump(mode="json", exclude_unset=self.exclude_unset, exclude_none=self.exclude_none)
+        if body is None:
+            return {}
+        return [
+            item.model_dump(mode="json", exclude_unset=self.exclude_unset, exclude_none=self.exclude_none)
+            for item in body
+        ]
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | list[Any] | None = None,
+        headers: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        client = self._ctx.get_client()
+        if self._ctx.config._token_manager is not None:
+            token: str = self._ctx.config.refresh_access_token()
+        else:
+            token = self._ctx.config.access_token or ""
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+            "Amazon-Ads-ClientId": self._ctx.config.client_id,
+            "Amazon-Advertising-API-ClientId": self._ctx.config.client_id,
+            **(headers or {}),
+        }
+        if self._ctx.config.profile_id is not None:
+            headers["Amazon-Advertising-API-Scope"] = self._ctx.config.profile_id
+        if self._ctx.config.account_id is not None:
+            headers["Amazon-Ads-AccountId"] = self._ctx.config.account_id
+        for attempt in range(self._ctx.config.max_retries):
+            try:
+                resp = client.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                    json=json,
+                    headers=headers,
+                )
+                if resp.is_error:
+                    if resp.status_code == 401 and self._ctx.config._token_manager is not None and attempt == 0:
+                        token = self._ctx.config.refresh_access_token(force=True)
+                        headers["Authorization"] = f"Bearer {token}"
+                        continue
+                    if resp.status_code in (429, 503, 504) and attempt < self._ctx.config.max_retries - 1:
+                        fallback = 2**attempt + random.uniform(0, 1)
+                        wait_time = _parse_retry_after(resp, fallback_seconds=fallback)
+                        logger.warning("Rate limit exceeded, retrying in %.2f seconds %s", wait_time, resp.status_code)
+                        time.sleep(wait_time)
+                        continue
+                    logger.error("%s %s", resp.status_code, resp.text)
+                    raise_for_status(resp)
+                return resp
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.RemoteProtocolError):
+                if attempt < self._ctx.config.max_retries - 1:
+                    time.sleep(2**attempt + random.uniform(0, 1))
+                    continue
+                raise
+        raise RuntimeError("Retry loop exited unexpectedly")
+
+    @overload
+    def _response[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["dict"] = "dict"
+    ) -> dict[str, Any]: ...
+    @overload
+    def _response[T: BaseModel](self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["pydantic"]) -> T: ...
+    @overload
+    def _response[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["raw"]
+    ) -> httpx.Response: ...
+    def _response[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: ResponseMode = "dict"
+    ) -> T | dict[str, Any] | httpx.Response:
+        if mode == "raw":
+            return resp
+        if mode == "dict":
+            return cast(dict[str, Any], resp.json())
+        try:
+            return model_cls.model_validate_json(resp.text)
+        except ValidationError:
+            logger.error("Failed to parse response as %s: %s", model_cls.__name__, resp.text)
+            raise
+
+    @overload
+    def _response_list[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["dict"] = "dict"
+    ) -> list[dict[str, Any]]: ...
+    @overload
+    def _response_list[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["pydantic"]
+    ) -> list[T]: ...
+    @overload
+    def _response_list[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["raw"]
+    ) -> httpx.Response: ...
+    def _response_list[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: ResponseMode = "dict"
+    ) -> list[T] | list[dict[str, Any]] | httpx.Response:
+        if mode == "raw":
+            return resp
+        if mode == "dict":
+            return cast(list[dict[str, Any]], resp.json())
+        try:
+            list_type: Any = list[model_cls]  # type: ignore[valid-type]
+            return TypeAdapter[list[T]](list_type).validate_json(resp.text)
+        except ValidationError:
+            logger.error("Failed to parse response list as %s: %s", model_cls.__name__, resp.text)
+            raise