python-amazon-ad-api 1.2.2__py3-none-any.whl → 1.2.4__py3-none-any.whl

ad_api/api/portfolios_v3.py

@@ -7,8 +7,29 @@ class PortfoliosV3(Client):
     @sp_endpoint('/portfolios/list', method='POST')
     def list_portfolios(self, version: int = 3, prefer: bool = False, **kwargs) -> ApiResponse:
         r"""
+        Lists portfolios. Replaces the retired ``GET /v2/portfolios``.
 
-        list_portfolios(body: (str, dict)) -> ApiResponse
+        Keyword Args
+
+        - ``prefer`` (bool): send ``Prefer: return=representation`` so the answer
+          carries the full portfolio objects rather than only the ids. [optional]
+
+        Request Body (optional)
+
+        - ``portfolioIdFilter`` (object): narrow to those ids. Carries
+          ``include``, a list of portfolio ids.
+        - ``nameFilter`` (object): narrow by name. Carries ``include``, a list of
+          names, and ``queryTermMatchType``, ``BROAD_MATCH`` or ``EXACT_MATCH``.
+        - ``stateFilter`` (object): narrow by state. Carries ``include``, a list
+          of states.
+        - ``includeExtendedDataFields`` (boolean): also return
+          ``creationDateTime``, ``lastUpdateDateTime``, ``servingStatus`` and
+          ``statusReasons``.
+        - ``nextToken`` (string): pagination token from a previous answer.
+
+        Returns
+            ApiResponse with ``portfolios``, ``totalResults`` and ``nextToken``.
+            Answers ``200``.
 
         """
 
@@ -25,9 +46,41 @@ class PortfoliosV3(Client):
     @sp_endpoint('/portfolios', method='POST')
     def create_portfolios(self, version: int = 3, prefer: bool = False, **kwargs) -> ApiResponse:
         r"""
-
-        create_portfolios(body: (str, dict)) -> ApiResponse
-
+        Creates portfolios.
+
+        Keyword Args
+
+        - ``prefer`` (bool): send ``Prefer: return=representation`` so the answer
+          carries the created portfolio objects rather than only the ids.
+          [optional]
+
+        Request Body (required)
+
+        - ``portfolios`` (array): the portfolios to create.
+
+          Each one carries:
+
+          - ``name`` (string): required. The portfolio name.
+          - ``state`` (string): required. The contract lists ``ENABLED`` as the
+            only value.
+          - ``budget.amount`` (number): the budget amount. Absent when the policy
+            is ``NO_CAP``.
+          - ``budget.currencyCode`` (string): one of ``AED``, ``AUD``, ``BRL``,
+            ``CAD``, ``CLP``, ``CNY``, ``COP``, ``EGP``, ``EUR``, ``GBP``,
+            ``INR``, ``JPY``, ``MXN``, ``NGN``, ``PLN``, ``SAR``, ``SEK``,
+            ``SGD``, ``TRY``, ``USD``, ``ZAR``.
+          - ``budget.policy`` (string): ``DATE_RANGE``, ``MONTHLY_RECURRING``,
+            ``NO_CAP`` or ``OTHER``.
+          - ``budget.startDate`` (string): ISO 8601. Required when the policy is
+            ``DATE_RANGE``.
+          - ``budget.endDate`` (string): ISO 8601. Optional under either policy.
+          - ``budgetControls.campaignUnspentBudgetSharing.featureState``
+            (string): ``ENABLED`` or ``DISABLED``.
+
+        Returns
+            ApiResponse with ``success`` and ``error`` lists, each item keyed by
+            the ``index`` it held in the body. The contract answers ``207``, a
+            multi-status, not ``200``.
 
         """
         schema_version = 'application/vnd.spPortfolio.v' + str(version) + '+json'
@@ -41,9 +94,32 @@ class PortfoliosV3(Client):
     @sp_endpoint('/portfolios', method='PUT')
     def edit_portfolios(self, version: int = 3, prefer: bool = False, **kwargs) -> ApiResponse:
         r"""
+        Updates portfolios.
+
+        Keyword Args
 
-        edit_portfolios(body: (str, dict)) -> ApiResponse
+        - ``prefer`` (bool): send ``Prefer: return=representation`` so the answer
+          carries the updated portfolio objects rather than only the ids.
+          [optional]
 
+        Request Body (required)
+
+        - ``portfolios`` (array): the portfolios to update.
+
+          Each one carries ``portfolioId``, which is required, plus any of the
+          members ``create_portfolios`` accepts. Only what is sent is changed:
+
+          - ``portfolioId`` (string): required. The portfolio to update.
+          - ``name`` (string): the portfolio name.
+          - ``state`` (string): ``ENABLED``.
+          - ``budget.amount``, ``budget.currencyCode``, ``budget.policy``,
+            ``budget.startDate`` and ``budget.endDate`` as above.
+          - ``budgetControls.campaignUnspentBudgetSharing.featureState`` as above.
+
+        Returns
+            ApiResponse with ``success`` and ``error`` lists, each item keyed by
+            the ``index`` it held in the body. The contract answers ``207``, a
+            multi-status, not ``200``.
 
         """
         schema_version = 'application/vnd.spPortfolio.v' + str(version) + '+json'
@@ -58,9 +134,23 @@ class PortfoliosV3(Client):
     @sp_endpoint('/portfolios/budget/usage', method='POST')
     def get_budget_usage_for_portfolios(self, version: int = 1, **kwargs) -> ApiResponse:
         r"""
+        Reports how much of each portfolio budget has been spent.
+
+        Request Body (required)
+
+        - ``portfolioIds`` (array): the portfolios to measure.
 
-        get_budget_usage_for_portfolios(body: (str, dict)) -> ApiResponse
+        Returns
+            ApiResponse split into ``success`` and ``error``. A successful entry
+            carries ``portfolioId``, ``index``, ``budget``,
+            ``budgetUsagePercent`` and ``usageUpdatedTimestamp``. The contract
+            answers ``207``, a multi-status, not ``200``.
 
+        A portfolio set to ``NO_CAP`` answers ``9999999999.0`` here rather than
+        an absent figure, and ``budgetUsagePercent`` reads ``0.0`` against it.
+        The same portfolio carries no ``amount`` at all in ``list_portfolios``.
+        Treat that number as no ceiling, not as money, or a sum over the account
+        comes out in the billions.
 
         """
         schema_version = 'application/vnd.portfoliobudgetusage.v' + str(version) + '+json'

ad_api/version.py

@@ -1 +1 @@
-__version__ = "1.2.2"
+__version__ = "1.2.4"

{python_amazon_ad_api-1.2.2.dist-info → python_amazon_ad_api-1.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.2.2
+Version: 1.2.4
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro
@@ -263,10 +263,6 @@ curl \
 * [Profiles](https://python-amazon-ad-api.readthedocs.io/en/latest/api/profiles.html)
 * [Manager Accounts](https://python-amazon-ad-api.readthedocs.io/en/latest/api/manager_accounts.html)
 
-Warning: [PLANNED DEPRECATION 1/3/2025]
-There is a new version 3 Portfolios API, please check the [migration guide](https://advertising.amazon.com/API/docs/en-us/reference/migration-guides/portfolios-v2-v3).
-
-* [Portfolios](https://python-amazon-ad-api.readthedocs.io/en/latest/api/portfolios.html)
 * [PortfoliosV3](https://python-amazon-ad-api.readthedocs.io/en/latest/api/portfoliosV3.html)
 * [Invoices](https://python-amazon-ad-api.readthedocs.io/en/latest/api/invoices.html)
 * [Billing](https://python-amazon-ad-api.readthedocs.io/en/latest/api/billing.html)

{python_amazon_ad_api-1.2.2.dist-info → python_amazon_ad_api-1.2.4.dist-info}/RECORD

@@ -1,5 +1,5 @@
 ad_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ad_api/version.py,sha256=uuf4VNtTNA93fMhoAur9YafzaKJFnczY-H1SSCSuRVQ,22
+ad_api/version.py,sha256=XBKH8E1LmDxv06U39yqMBbXZapOERFgICEDYZs_kRso,22
 ad_api/api/__init__.py,sha256=E9c0ZyK4vplMlKKEBF8CV5u7P4uSkTMSQsAuSQu5bfY,1514
 ad_api/api/account.py,sha256=CmOvCfHoPWaeTUJvtB0pNoNulZVSz4oMMCKIpVTpHos,2931
 ad_api/api/advertising_test_account.py,sha256=btOVbdk2tBDmyKSJaQbcIFyzNG8KFJVUmTe4p9xMhpU,1507
@@ -17,7 +17,7 @@ ad_api/api/localization.py,sha256=HdkChAawloJ8zj5rCye9NVf7kLnQ7vW6aKsBLZ2W-gI,17
 ad_api/api/manager_accounts.py,sha256=tnmJxOGIKTuJ3i8wciwfs931REW0aeNKQiqCpBrTZ2Y,5107
 ad_api/api/metadata.py,sha256=vWPbDGvEB72421fjSu4KrNkTdrIijHTPV8k36hceSbA,2406
 ad_api/api/portfolios.py,sha256=Oe3LS2HsjMJSq1Id8cwOWrH2AiPMcBb7oTkFHjudnTI,7103
-ad_api/api/portfolios_v3.py,sha256=3vOfyz0awonr2NJOCm5SjX_bOz9-4hyQbf67DIY9IQU,2596
+ad_api/api/portfolios_v3.py,sha256=qqIzXmhnb3g2QmTENsgzOayhvOObgI-rD7PTfftgDQg,6842
 ad_api/api/profiles.py,sha256=mMSCUd5HdR_nFBDFngLY94tIfMCA4yGnjHz-PSMe0rE,7200
 ad_api/api/recommendations.py,sha256=aVDnnX8GEhdOVSKypIs8lyUJCiFxo9ujMYVXqzHTvBc,4633
 ad_api/api/reports.py,sha256=gNmDHLULD2uaJgsMpIbCX9kabwhMXRr9WfZBtHUdsOY,6043
@@ -108,8 +108,8 @@ ad_api/base/exceptions.py,sha256=9D3M40ZIlLS0fA-aQh1BTWPOW-Nvf0tRhbA85jFnDJ4,438
 ad_api/base/helpers.py,sha256=UK7Q13vZ0mNdF54xzfzoGDn2O_cd2yPrK2X4rOzC41c,2334
 ad_api/base/marketplaces.py,sha256=44lvCcluXNpqTprWQ80e3weSQmQbJoWL-WDSOWVbCyQ,4657
 ad_api/base/utils.py,sha256=_qnCBOvyJTLgaZjJzUWTi38GGLHkQszXELs79133Rb4,5618
-python_amazon_ad_api-1.2.2.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
-python_amazon_ad_api-1.2.2.dist-info/METADATA,sha256=KPanEM-HPMFE2e2jnXwtaE6WqqtTX5u2qJsF3UFzw7M,21778
-python_amazon_ad_api-1.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_amazon_ad_api-1.2.2.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
-python_amazon_ad_api-1.2.2.dist-info/RECORD,,
+python_amazon_ad_api-1.2.4.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
+python_amazon_ad_api-1.2.4.dist-info/METADATA,sha256=TYwJLNkevDvojJVYRbb8DDtVtTMUC7FjQZqFxXQ60R0,21479
+python_amazon_ad_api-1.2.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_amazon_ad_api-1.2.4.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
+python_amazon_ad_api-1.2.4.dist-info/RECORD,,