python-amazon-ad-api 1.7.0__tar.gz → 1.8.1__tar.gz

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.7.0
+Version: 1.8.1
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro
@@ -14,8 +14,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests<2.35.0,>=2.27.1
 Requires-Dist: six<1.18,>=1.16
-Requires-Dist: cachetools<7.3,>=5.0
-Requires-Dist: pycryptodome<4.3,>=3.13
+Requires-Dist: cachetools<8.1,>=5.0
+Requires-Dist: pycryptodome<4.5,>=3.13
 Requires-Dist: pytz<2027.0,>=2021.3
 Requires-Dist: confuse<2.4,>=1.7
 Dynamic: author

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/ad_api/api/portfolios_v3.py

@@ -2,9 +2,20 @@ from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
 
 
 class PortfoliosV3(Client):
-    """ """
+    r"""
+    Amazon Ads API v3 - portfolios, under /portfolios.
+
+    Deprecated: Amazon moved portfolios into the unified v1 generation.
+    Use ad_api.api.v1.Portfolios, on /adsApi/v1/create|query|update/portfolios,
+    which adds budget sharing between the campaigns of a portfolio and per
+    marketplace overrides on a global portfolio.
+
+    The routes here still match the contract they were built on; they are kept
+    for anyone pinning an older release.
+    """
 
     @sp_endpoint('/portfolios/list', method='POST')
+    @Utils.deprecated
     def list_portfolios(self, version: int = 3, prefer: bool = False, **kwargs) -> ApiResponse:
         r"""
         Lists portfolios. Replaces the retired ``GET /v2/portfolios``.
@@ -45,6 +56,7 @@ class PortfoliosV3(Client):
 
 
     @sp_endpoint('/portfolios', method='POST')
+    @Utils.deprecated
     def create_portfolios(self, version: int = 3, prefer: bool = False, **kwargs) -> ApiResponse:
         r"""
         Creates portfolios.
@@ -93,6 +105,7 @@ class PortfoliosV3(Client):
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
 
     @sp_endpoint('/portfolios', method='PUT')
+    @Utils.deprecated
     def edit_portfolios(self, version: int = 3, prefer: bool = False, **kwargs) -> ApiResponse:
         r"""
         Updates portfolios.
@@ -133,6 +146,7 @@ class PortfoliosV3(Client):
 
 
     @sp_endpoint('/portfolios/budget/usage', method='POST')
+    @Utils.deprecated
     def get_budget_usage_for_portfolios(self, version: int = 1, **kwargs) -> ApiResponse:
         r"""
         Reports how much of each portfolio budget has been spent.

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/ad_api/api/v1/__init__.py

@@ -18,6 +18,7 @@ from .label_object_associations import LabelObjectAssociations
 from .geo_locations import GeoLocations
 from .location_indexes import LocationIndexes
 from .recommendation_types import RecommendationTypes
+from .portfolios import Portfolios
 
 __all__ = [
     "Campaigns",
@@ -40,4 +41,5 @@ __all__ = [
     "GeoLocations",
     "LocationIndexes",
     "RecommendationTypes",
+    "Portfolios",
 ]

python_amazon_ad_api-1.8.1/ad_api/api/v1/portfolios.py

@@ -0,0 +1,168 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class Portfolios(Client):
+    r"""
+    Portfolios(account='default', marketplace: Marketplaces = Marketplaces.EU, credentials=None, debug=False)
+
+    Amazon Ads API v1 - unified Portfolios endpoints
+
+    A portfolio groups campaigns under one name, one budget and one set of
+    marketplace rules. It is the v1 replacement for the v2 ``/v2/portfolios``
+    routes, retired in March 2025, and for the v3 ``/portfolios`` family.
+
+    Three routes, all POST. There is no GET on a path and no DELETE:
+
+        /adsApi/v1/create/portfolios   CreatePortfolio
+        /adsApi/v1/query/portfolios    QueryPortfolio
+        /adsApi/v1/update/portfolios   UpdatePortfolio
+
+    A portfolio is never deleted: it is retired by updating ``state`` to
+    ARCHIVED, which is a terminal state and cannot be reverted.
+
+    Budget sharing is the new part
+    ------------------------------
+    ``budgetControls.campaignBudgetSharing.shareUnspentCampaignBudget``
+    (ENABLED or DISABLED) lets the campaigns of the portfolio spend budget
+    that the other campaigns did not use, instead of each campaign being
+    capped on its own.
+
+    Global and per marketplace
+    --------------------------
+    A portfolio is GLOBAL, covering every marketplace named in
+    ``marketplaces``, or SINGLE_MARKETPLACE. When it is global,
+    ``marketplaceConfigurations`` overrides ``budgetControls``,
+    ``startDateTime``, ``endDateTime`` and ``state`` for one marketplace, up
+    to 30 overrides. Anything not overridden carries the global value.
+
+    Writes answer 207, not 200: a batch can create some portfolios and
+    reject others, so ``success`` and ``error`` in the payload have to be read
+    together, indexed the same way.
+    """
+
+    @sp_endpoint('/adsApi/v1/create/portfolios', method='POST')
+    def create_portfolios(self, **kwargs) -> ApiResponse:
+        r"""
+        create_portfolios(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Create Portfolios (operationId: CreatePortfolio)
+
+        Request Body [Required]
+            | **portfolios** (list<PortfolioCreate>) : [required] 1..100
+
+        PortfolioCreate fields
+            | **name** (string) : the name of the portfolio
+            | **state** (string) : Enum [ DRAFT, ENABLED, PAUSED, PROPOSED ]
+            | **marketplaceScope** (string) : Enum [ GLOBAL, SINGLE_MARKETPLACE ]
+            | **marketplaces** (list<Marketplace>) : 0..30 country codes
+            | **budget** (dict)
+                | **budgetType** (string) : [required] MONETARY
+                | **budgetValue** (dict) : [required] the monetary value
+                | **recurrenceTimePeriod** (string) : [required]
+                  Enum [ DAILY, LIFETIME ]
+            | **budgetControls** (dict)
+                | **campaignBudgetSharing** (dict) : [required]
+                    | **shareUnspentCampaignBudget** (string) : [required]
+                      Enum [ DISABLED, ENABLED ]
+            | **marketplaceConfigurations** (list<dict>) : 0..30
+                | **marketplace** (string) : [required] the country code
+                | **overrides** (dict) : [required]
+                    | **budgetControls**, **startDateTime**,
+                      **endDateTime**, **state**
+            | **startDateTime** (string) : ISO 8601, with a LIFETIME budget
+            | **endDateTime** (string) : ISO 8601, with a LIFETIME budget
+
+        Returns
+            207 MultiStatus with success[] and error[] indexed together.
+            Each success carries the created Portfolio and its position.
+
+        This writes into the account. A 207 is not all or nothing: read both
+        lists before assuming every portfolio was created.
+        """
+        schema_version = 'application/json'
+        headers = {"Accept": schema_version, "Content-Type": schema_version}
+        body = kwargs.pop('body', None)
+        return self._request(kwargs.pop('path'), params=kwargs, headers=headers,
+                             **({'data': Utils.convert_body(body, False)} if body is not None else {}))
+
+    @sp_endpoint('/adsApi/v1/query/portfolios', method='POST')
+    def query_portfolios(self, **kwargs) -> ApiResponse:
+        r"""
+        query_portfolios(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Query Portfolios (operationId: QueryPortfolio)
+
+        A POST that reads: the filters travel in the body, not in the path.
+
+        Request Body
+            | **portfolioIdFilter** (dict) [optional]
+                | **include** (list<string>) : 1..1000 portfolio identifiers
+            | **nameFilter** (dict) [optional]
+                | **include** (list<string>) : 1..100 names
+                | **queryTermMatchType** (string) : [required]
+                  Enum [ BROAD_MATCH, EXACT_MATCH ]
+            | **stateFilter** (dict) [optional]
+                | **include** (list<State>) : ARCHIVED, DRAFT, ENABLED,
+                  PAUSED, PROPOSED
+            | **marketplaceScopeFilter** (dict) [optional]
+                | **include** (list<MarketplaceScope>) : exactly 1,
+                  GLOBAL or SINGLE_MARKETPLACE
+            | **maxResults** (int) : 1..100, default 100
+            | **nextToken** (string) : the token from the previous page
+
+        Returns
+            | **portfolios** (list<Portfolio>), **nextToken** (string)
+
+        Portfolio fields
+            | **portfolioId**, **globalPortfolioId**, **name**, **state**,
+              **status**
+            | **budget**, **budgetControls**
+            | **startDateTime**, **endDateTime**
+            | **marketplaces** (list<string>), **marketplaceScope**
+            | **marketplaceConfigurations** (list<dict>) : the per marketplace
+              overrides, 0..30
+        """
+        schema_version = 'application/json'
+        headers = {"Accept": schema_version, "Content-Type": schema_version}
+        body = kwargs.pop('body', None)
+        return self._request(kwargs.pop('path'), params=kwargs, headers=headers,
+                             **({'data': Utils.convert_body(body, False)} if body is not None else {}))
+
+    @sp_endpoint('/adsApi/v1/update/portfolios', method='POST')
+    def update_portfolios(self, **kwargs) -> ApiResponse:
+        r"""
+        update_portfolios(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Update Portfolios (operationId: UpdatePortfolio)
+
+        Request Body [Required]
+            | **portfolios** (list<PortfolioUpdate>) : [required] 1..100
+
+        PortfolioUpdate fields
+            | **portfolioId** (string) : [required] the portfolio to rewrite
+            | **name** (string)
+            | **state** (string) : Enum [ DRAFT, ENABLED, PAUSED, PROPOSED,
+              ARCHIVED ]
+            | **budget** (dict)
+                | **budgetType**, **budgetValue** (UpdateBudgetValue),
+                  **recurrenceTimePeriod**
+            | **budgetControls** (dict)
+                | **campaignBudgetSharing** (dict)
+                    | **shareUnspentCampaignBudget** (string) : ENABLED, DISABLED
+            | **marketplaces** (list<Marketplace>) : 0..30
+            | **marketplaceConfigurations** (list<dict>) : 0..30
+            | **startDateTime** (string) : nullable
+            | **endDateTime** (string) : nullable
+
+        Returns
+            207 MultiStatus with success[] and error[] indexed together.
+
+        ARCHIVED is terminal: a portfolio set to ARCHIVED cannot be
+        reactivated. With no delete route, archiving is how a portfolio is
+        retired.
+        """
+        schema_version = 'application/json'
+        headers = {"Accept": schema_version, "Content-Type": schema_version}
+        body = kwargs.pop('body', None)
+        return self._request(kwargs.pop('path'), params=kwargs, headers=headers,
+                             **({'data': Utils.convert_body(body, False)} if body is not None else {}))

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/ad_api/api/v1/recommendations.py

@@ -31,13 +31,13 @@ class Recommendations(Client):
         Amazon Ads API v1 - Query Recommendations (operationId: QueryRecommendation)
 
         Request Body [Required]
-            | **accessRequestedAccounts** (list<QueryRecommendationRequestAccessRequestedAccountItem>) : [required] 1..2000
+            | **accessRequestedAccounts** (list<QueryRecommendationRequestAccessRequestedAccountItem>) : [required] 1..2000, each item is either {advertiserAccountId} or {managerAccountId}
             | **adProductFilter** (dict) [optional]
             | **recommendationTypeFilter** (dict) [optional]
             | **recommendationTypeDetailsFilter** (dict) [optional]
             | **marketplacesFilter** (dict) [optional]
             | **languageFilter** (dict) [optional]
-            | **maxResults** (int) : 1..100, default 100
+            | **maxResults** (int) : 1..300, default 100
             | **nextToken** (string)
 
         Returns
@@ -58,6 +58,15 @@ class Recommendations(Client):
 
         A GET with query parameters, not a body.
 
+        Parameters
+            | **Amazon-Ads-AccountId** (string) : advertiser account, optional
+            | **Amazon-Ads-Manager-AccountId** (string) : manager account, optional
+            | **nextToken**, **maxResults** (1..300), **adProduct**, **marketplace**, **language**, **recommendationType**
+
+        The account travels in the headers, and since 2026-11-11 the contract
+        marks both of them optional: the list can be read for an advertiser
+        account or for a manager account.
+
         Returns
             | **recommendations** (list<Recommendation>) : 0..300
             | **totalResults** (int)

python_amazon_ad_api-1.8.1/ad_api/version.py

@@ -0,0 +1 @@
+__version__ = "1.8.1"

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/python_amazon_ad_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.7.0
+Version: 1.8.1
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro
@@ -14,8 +14,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests<2.35.0,>=2.27.1
 Requires-Dist: six<1.18,>=1.16
-Requires-Dist: cachetools<7.3,>=5.0
-Requires-Dist: pycryptodome<4.3,>=3.13
+Requires-Dist: cachetools<8.1,>=5.0
+Requires-Dist: pycryptodome<4.5,>=3.13
 Requires-Dist: pytz<2027.0,>=2021.3
 Requires-Dist: confuse<2.4,>=1.7
 Dynamic: author

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/python_amazon_ad_api.egg-info/SOURCES.txt

@@ -110,6 +110,7 @@ ad_api/api/v1/label_object_associations.py
 ad_api/api/v1/labels.py
 ad_api/api/v1/location_indexes.py
 ad_api/api/v1/manager_accounts.py
+ad_api/api/v1/portfolios.py
 ad_api/api/v1/recommendation_types.py
 ad_api/api/v1/recommendations.py
 ad_api/api/v1/reports.py

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/python_amazon_ad_api.egg-info/requires.txt

@@ -1,6 +1,6 @@
 requests<2.35.0,>=2.27.1
 six<1.18,>=1.16
-cachetools<7.3,>=5.0
-pycryptodome<4.3,>=3.13
+cachetools<8.1,>=5.0
+pycryptodome<4.5,>=3.13
 pytz<2027.0,>=2021.3
 confuse<2.4,>=1.7

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = python-amazon-ad-api
-version = 1.7.0
+version = 1.8.1
 author = Daniel Alvaro
 author_email = denisneuf@hotmail.com
 description = Python wrapper for the Amazon Advertising API

{python_amazon_ad_api-1.7.0 → python_amazon_ad_api-1.8.1}/setup.py

@@ -2,12 +2,12 @@ from setuptools import setup
 
 setup(
     name='python-amazon-ad-api',
-    version='1.7.0',
+    version='1.8.1',
     install_requires=[
         "requests>=2.27.1,<2.35.0",
         "six>=1.16,<1.18",
-        "cachetools>=5.0,<7.3",
-        "pycryptodome>=3.13,<4.3",
+        "cachetools>=5.0,<8.1",
+        "pycryptodome>=3.13,<4.5",
         "pytz>=2021.3,<2027.0",
         "confuse>=1.7,<2.4",
     ],

python_amazon_ad_api-1.7.0/ad_api/version.py

@@ -1 +0,0 @@
-__version__ = "1.7.0"