python-amazon-ad-api 1.4.8__py3-none-any.whl → 1.5.0__py3-none-any.whl

ad_api/api/__init__.py

@@ -13,7 +13,7 @@ from .audiences import Audiences
 from .portfolios import Portfolios
 from .portfolios_v3 import PortfoliosV3
 from .insights import Insights
-from . import v1
+from . import v1 as ads_api_v1
 from . import sp as sponsored_products
 from . import sb as sponsored_brands
 from . import sd as sponsored_display
@@ -29,6 +29,7 @@ from .stores import Stores
 
 __all__ = [
     "v1",
+    "ads_api_v1",
     "sp",
     "sb",
     "sd",

ad_api/api/v1/__init__.py

@@ -9,6 +9,7 @@ from .brand_store_edition_publish_versions import BrandStoreEditionPublishVersio
 from .brand_stores import BrandStores
 from .brand_store_editions import BrandStoreEditions
 from .brand_store_pages import BrandStorePages
+from .reports import Reports
 
 __all__ = [
     "Campaigns",
@@ -22,4 +23,5 @@ __all__ = [
     "BrandStores",
     "BrandStoreEditions",
     "BrandStorePages",
+    "Reports",
 ]

ad_api/api/v1/reports.py

@@ -0,0 +1,133 @@
+from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
+
+
+class Reports(Client):
+    r"""
+    Reports(account='default', marketplace: Marketplaces = Marketplaces.EU, credentials=None, debug=False)
+
+    Amazon Ads API v1 - unified Reports endpoints
+
+    Reports in v1 are asynchronous and take three routes, not the four of the
+    entity families:
+
+        POST /adsApi/v1/create/reports      queue a report
+        POST /adsApi/v1/retrieve/reports    read its state
+        POST /adsApi/v1/delete/reports      drop it
+
+    There is no GET by id: the state is read by posting the id back to
+    retrieve, and the pair of routes is what carries the status through
+    PENDING, PROCESSING, COMPLETED and FAILED.
+
+    This generation is shaped differently from the v3 reporting route the
+    package already ships as ad_api.api.Reports:
+
+        v1 uses fields, v3 uses columns
+        v1 has no reportTypeId, adProduct, groupBy or timeUnit at all
+        v1 filters are a predicate tree, v3 filters are a flat list
+        v1 answers a list of report parts, v3 answers one url
+
+    v1 reports are addressed by advertiser account, and the account travels in
+    the body rather than only in the headers.
+
+    The field catalogue is not part of the contract: query.fields accepts any
+    string up to 1000 entries and the service decides which ones exist for each
+    product, so a wrong name is answered with a 400 naming the accepted values
+    rather than with a local rejection.
+    """
+
+    @sp_endpoint('/adsApi/v1/create/reports', method='POST')
+    def create_report(self, **kwargs) -> ApiResponse:
+        r"""
+        create_report(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Create a report (operationId: AdsApiv1CreateReport)
+
+        Request Body [Required]
+            | **accessRequestedAccounts** (list<ReportCreateAccessRequestedAccountItem>) : [required] 1..2000
+                | oneOf **advertiserAccountId** (string) : the advertiser account the report is for
+                | oneOf **managerAccountId** (string) : the manager account the report is for
+            | **reports** (list<ReportCreate>) : [required] exactly 1
+                | **format** (ReportFormat) : [required] Enum [ CSV, GZIP_JSON, PARTITIONED_CSV, PARTITIONED_GZIP_JSON ]
+                | **periods** (list<CreateReportPeriod>) : [required] exactly 1
+                    | **datePeriod** (CreateDatePeriod) : [required]
+                        | **startDate** (date) : [required]
+                        | **endDate** (date) : [required]
+                | **query** (CreateReportingQuery) : [required]
+                    | **fields** (list<string>) : [required] 1..1000
+                    | **filter** (CreateFilter) : [optional]
+                        | **on** (CreateComparisonPredicate)
+                            | **field** (string) : [required] pattern ^[a-zA-Z0-9]+\.[a-zA-Z0-9]+$
+                            | **comparisonOperator** (ComparisonOperator) : [required] Enum [ EQUALS, IN ]
+                            | **values** (list<string>) : [required] 1..2000
+                            | **not** (boolean) : [required]
+                        | **and** (CreateCompositePredicate)
+                            | **filters** (list<CreateFilter>) : [required] 1..10
+                | **currencyOfView** (CurrencyCode) : [optional]
+                | **managerAccountDspGrouping** (ManagerAccountDspGrouping) : [optional]
+
+        Answer
+            207 MultiStatus with success[] carrying the created report ids and
+            error[] carrying the index and reason of the ones refused.
+
+        Requires one of these permissions:
+            ManagerAccount_Dev, advertiser_campaign_edit, nemo_report_view,
+            MasterAccount_Viewer, MA_ReadOnly, advertiser_campaign_view,
+            reports_edit, MasterAccount_Manager, nemo_report_edit,
+            view_performance_dashboard
+        """
+        schema_version = 'application/json'
+        headers = {"Accept": schema_version, "Content-Type": schema_version}
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
+    @sp_endpoint('/adsApi/v1/retrieve/reports', method='POST')
+    def retrieve_report(self, **kwargs) -> ApiResponse:
+        r"""
+        retrieve_report(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Retrieve a report by id (operationId: AdsApiv1RetrieveReport)
+
+        Request Body [Required]
+            | **reportIds** (list<string>) : [required] exactly 1
+
+        Answer
+            The report object, with the members that matter here:
+
+            | **reportId** (string)
+            | **status** (ReportStatus) : Enum [ COMPLETED, FAILED, PENDING, PROCESSING ]
+            | **format** (ReportFormat)
+            | **periods** (list<ReportPeriod>)
+            | **query** (ReportingQuery) : the fields and filter the report was built from
+            | **creationDateTime**, **lastUpdatedDateTime**, **completedDateTime** (date-time)
+            | **failureCode** (string), **failureReason** (string) : set when status is FAILED
+            | **warnings** (list<ReportWarning>) : non-fatal notes about the generated report
+            | **completedReportParts** (list<ReportPart>) : 0..100
+                | **url** (string) : signed download url for this part
+                | **urlExpirationDateTime** (date-time)
+                | **sizeInBytes** (int64) : up to 100GB for a single part
+
+            A report split in parts answers more than one entry, so a caller that
+            only reads the first url loses data.
+
+        Requires one of these permissions:
+            none declared
+        """
+        schema_version = 'application/json'
+        headers = {"Accept": schema_version, "Content-Type": schema_version}
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)
+
+    @sp_endpoint('/adsApi/v1/delete/reports', method='POST')
+    def delete_report(self, **kwargs) -> ApiResponse:
+        r"""
+        delete_report(body: dict) -> ApiResponse
+
+        Amazon Ads API v1 - Delete a report by id (operationId: AdsApiv1DeleteReport)
+
+        Request Body [Required]
+            | **reportIds** (list<string>) : [required] exactly 1
+
+        Requires one of these permissions:
+            none declared
+        """
+        schema_version = 'application/json'
+        headers = {"Accept": schema_version, "Content-Type": schema_version}
+        return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs, headers=headers)

ad_api/version.py

@@ -1 +1 @@
-__version__ = "1.4.8"
+__version__ = "1.5.0"

{python_amazon_ad_api-1.4.8.dist-info → python_amazon_ad_api-1.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.4.8
+Version: 1.5.0
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro
@@ -311,6 +311,7 @@ The v1 API lives under `/adsApi/v1/` and is **not** split by product: every call
 * [Brand Stores](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/brand_stores.html#ad_api.api.v1.BrandStores.BrandStores.query_brand_stores)
 * [Brand Store Editions](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/brand_store_editions.html#ad_api.api.v1.BrandStoreEditions.BrandStoreEditions.list_brand_store_editions)
 * [Brand Store Pages](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/brand_store_pages.html#ad_api.api.v1.BrandStorePages.BrandStorePages.query_brand_store_pages)
+* [Reports](https://python-amazon-ad-api.readthedocs.io/en/latest/v1/reports.html#ad_api.api.v1.Reports.Reports.create_report)
 
 
 ### [Modules Available Sponsored Products](https://python-amazon-ad-api.readthedocs.io/en/latest/sp.html)

{python_amazon_ad_api-1.4.8.dist-info → python_amazon_ad_api-1.5.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 ad_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ad_api/version.py,sha256=F1u2mSK8Wly-J_mt7oHk_RJLir3nEN_Ri1OneijYSlc,22
-ad_api/api/__init__.py,sha256=TLMefdmuyrj3-vtxGlzX4Sl-lHmE3Rs6daYgw3zwO0c,1600
+ad_api/version.py,sha256=X9pTeGHIYZtDOmfb9pnn2DEqWZMAyaPlqdFwEhsuSvk,22
+ad_api/api/__init__.py,sha256=M07SD5BRC1L4_PqxLc8cKPI9Iq5zC2jPhkFUeHoh6CM,1632
 ad_api/api/account.py,sha256=CmOvCfHoPWaeTUJvtB0pNoNulZVSz4oMMCKIpVTpHos,2931
 ad_api/api/account_budgets.py,sha256=jFce5eLWAFK3ydjnYR7_Sv7B0-gHTG5bMTx_TcHyy1A,2319
 ad_api/api/advertising_test_account.py,sha256=btOVbdk2tBDmyKSJaQbcIFyzNG8KFJVUmTe4p9xMhpU,1507
@@ -89,7 +89,7 @@ ad_api/api/sp/product_recommendations.py,sha256=vXoZIRqcFc5bo9MUprArKndxcEYe_Puy
 ad_api/api/sp/product_targeting_v3.py,sha256=vk_T0piHzP5uwt8HSHm5hFKP_0sXJD8nbyooPtM-BTs,9567
 ad_api/api/sp/ranked_keywords_recommendations.py,sha256=QYFje19TFmwhedh7sn5VJIypL8gp6d6tpBQCpf_SIXw,13094
 ad_api/api/sp/schedule_based_bid_optimization.py,sha256=G8VkS7iP1lTIAxZgbfRCLz8njw1DkVH9HQPOZ63pWNU,2371
-ad_api/api/v1/__init__.py,sha256=leVUKT8N-3DriGfI-VDKFnIEtcqNSyFiHfeN2dfBAVQ,722
+ad_api/api/v1/__init__.py,sha256=1Pcd2suLJAL2yOFl_2p_rQe20ogRJEMIAdfGiLxlT90,766
 ad_api/api/v1/ad_associations.py,sha256=g5L8hAIagmsb-yQ09hP7z1zbVVe868NlpOOokv-Mouc,5812
 ad_api/api/v1/ad_extensions.py,sha256=kL-7xHaXXqb2jXTwZrY0oGttLAG0CW_IjBAqL_CI92U,5519
 ad_api/api/v1/ad_groups.py,sha256=pQhCVdve_O6kbL4mBA5bxxhKcKNl_BKqa7z9DvrxwaM,12626
@@ -100,6 +100,7 @@ ad_api/api/v1/brand_store_editions.py,sha256=xW4z2jDWhNJn86tWlT3eLIRr0NEpxLhW1eA
 ad_api/api/v1/brand_store_pages.py,sha256=TrSQbqlXqFv7i7RooxlFZOBrwYfEMPLvRPSJ9FjO87o,2765
 ad_api/api/v1/brand_stores.py,sha256=zlBsKiOwmdSiIG9filgdqUlPnV6AX-gE6S5nNyAQACc,2131
 ad_api/api/v1/campaigns.py,sha256=u5PlvoAhgVhMxbCvYkPgqtbYK3TXXcb7TMie0Qjrgwc,9573
+ad_api/api/v1/reports.py,sha256=vJmWhIsALkX27HeijTsSUz3zrYhUBm4RodTCieJD8Y8,6657
 ad_api/api/v1/targets.py,sha256=a4BzPjg9m1JJwqphhpQOFkNIcgCw7v4-K0sNzOihMZI,12355
 ad_api/auth/__init__.py,sha256=B_yKdmsHENQaKfMFAIcSxQqG4aBUmNBm5orKIMUYObk,229
 ad_api/auth/access_token_client.py,sha256=_V0FGXRmqRNMb1fz1AGqnR6gYr_WqFkMTbK1os0yoIk,2983
@@ -116,8 +117,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.4.8.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
-python_amazon_ad_api-1.4.8.dist-info/METADATA,sha256=J5eizsL_okNqaRHdrfPb-y4IOyhQCxsGfUrbuxOlDXo,22832
-python_amazon_ad_api-1.4.8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_amazon_ad_api-1.4.8.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
-python_amazon_ad_api-1.4.8.dist-info/RECORD,,
+python_amazon_ad_api-1.5.0.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
+python_amazon_ad_api-1.5.0.dist-info/METADATA,sha256=ofNprBWjLQQyP6eWTdG4JRGzOJwxjU0fKGryodntY-c,22959
+python_amazon_ad_api-1.5.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_amazon_ad_api-1.5.0.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
+python_amazon_ad_api-1.5.0.dist-info/RECORD,,