Added annotations to examples/basic_operations (#943)

Author: bobhancockg

examples/basic_operations/add_ad_groups.py

@@ -20,28 +20,49 @@
 
 import argparse
 import sys
+from typing import List
 import uuid
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.services.services.ad_group_service import (
+    AdGroupServiceClient,
+)
+from google.ads.googleads.v20.services.types.ad_group_service import (
+    AdGroupOperation,
+    MutateAdGroupsResponse,
+)
+from google.ads.googleads.v20.services.services.campaign_service import (
+    CampaignServiceClient,
+)
+from google.ads.googleads.v20.resources.types.ad_group import AdGroup
 
 
-def main(client, customer_id, campaign_id):
-    ad_group_service = client.get_service("AdGroupService")
-    campaign_service = client.get_service("CampaignService")
+def main(client: GoogleAdsClient, customer_id: str, campaign_id: str) -> None:
+    ad_group_service: AdGroupServiceClient = client.get_service(
+        "AdGroupService"
+    )
+    campaign_service: CampaignServiceClient = client.get_service(
+        "CampaignService"
+    )
 
     # Create ad group.
-    ad_group_operation = client.get_type("AdGroupOperation")
-    ad_group = ad_group_operation.create
+    ad_group_operation: AdGroupOperation = client.get_type("AdGroupOperation")
+    ad_group: AdGroup = ad_group_operation.create
     ad_group.name = f"Earth to Mars cruises {uuid.uuid4()}"
     ad_group.status = client.enums.AdGroupStatusEnum.ENABLED
     ad_group.campaign = campaign_service.campaign_path(customer_id, campaign_id)
     ad_group.type_ = client.enums.AdGroupTypeEnum.SEARCH_STANDARD
     ad_group.cpc_bid_micros = 10000000
 
+    operations: List[AdGroupOperation] = [ad_group_operation]
+
     # Add the ad group.
-    ad_group_response = ad_group_service.mutate_ad_groups(
-        customer_id=customer_id, operations=[ad_group_operation]
+    ad_group_response: MutateAdGroupsResponse = (
+        ad_group_service.mutate_ad_groups(
+            customer_id=customer_id,
+            operations=operations,
+        )
     )
     print(f"Created ad group {ad_group_response.results[0].resource_name}.")
 
@@ -61,11 +82,13 @@ def main(client, customer_id, campaign_id):
     parser.add_argument(
         "-i", "--campaign_id", type=str, required=True, help="The campaign ID."
     )
-    args = parser.parse_args()
+    args: argparse.Namespace = parser.parse_args()
 
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    googleads_client = GoogleAdsClient.load_from_storage(version="v20")
+    googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage(
+        version="v20"
+    )
 
     try:
         main(googleads_client, args.customer_id, args.campaign_id)

examples/basic_operations/add_campaigns.py

@@ -21,44 +21,77 @@
 import argparse
 import datetime
 import sys
+from typing import List
 import uuid
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
-
-
-_DATE_FORMAT = "%Y%m%d"
-
-
-def main(client, customer_id):
-    campaign_budget_service = client.get_service("CampaignBudgetService")
-    campaign_service = client.get_service("CampaignService")
+from google.ads.googleads.v20.services.services.campaign_budget_service import (
+    CampaignBudgetServiceClient,
+)
+from google.ads.googleads.v20.services.types.campaign_budget_service import (
+    CampaignBudgetOperation,
+    MutateCampaignBudgetsResponse,
+)
+from google.ads.googleads.v20.services.services.campaign_service import (
+    CampaignServiceClient,
+)
+from google.ads.googleads.v20.services.types.campaign_service import (
+    CampaignOperation,
+    MutateCampaignsResponse,
+)
+from google.ads.googleads.v20.resources.types.campaign_budget import (
+    CampaignBudget,
+)
+from google.ads.googleads.v20.resources.types.campaign import Campaign
+
+
+_DATE_FORMAT: str = "%Y%m%d"
+
+
+def main(client: GoogleAdsClient, customer_id: str) -> None:
+    campaign_budget_service: CampaignBudgetServiceClient = client.get_service(
+        "CampaignBudgetService"
+    )
+    campaign_service: CampaignServiceClient = client.get_service(
+        "CampaignService"
+    )
 
     # [START add_campaigns]
     # Create a budget, which can be shared by multiple campaigns.
-    campaign_budget_operation = client.get_type("CampaignBudgetOperation")
-    campaign_budget = campaign_budget_operation.create
+    campaign_budget_operation: CampaignBudgetOperation = client.get_type(
+        "CampaignBudgetOperation"
+    )
+    campaign_budget: CampaignBudget = campaign_budget_operation.create
     campaign_budget.name = f"Interplanetary Budget {uuid.uuid4()}"
     campaign_budget.delivery_method = (
         client.enums.BudgetDeliveryMethodEnum.STANDARD
     )
     campaign_budget.amount_micros = 500000
 
     # Add budget.
+    campaign_budget_response: MutateCampaignBudgetsResponse
     try:
+        budget_operations: List[CampaignBudgetOperation] = [
+            campaign_budget_operation
+        ]
         campaign_budget_response = (
             campaign_budget_service.mutate_campaign_budgets(
-                customer_id=customer_id, operations=[campaign_budget_operation]
+                customer_id=customer_id,
+                operations=budget_operations,
             )
         )
     except GoogleAdsException as ex:
         handle_googleads_exception(ex)
         # [END add_campaigns]
+        # We are exiting in handle_googleads_exception so this return is not
+        # strictly necessary, but it makes static analysis happier.
+        return
 
     # [START add_campaigns_1]
     # Create campaign.
-    campaign_operation = client.get_type("CampaignOperation")
-    campaign = campaign_operation.create
+    campaign_operation: CampaignOperation = client.get_type("CampaignOperation")
+    campaign: Campaign = campaign_operation.create
     campaign.name = f"Interplanetary Cruise {uuid.uuid4()}"
     campaign.advertising_channel_type = (
         client.enums.AdvertisingChannelTypeEnum.SEARCH
@@ -83,24 +116,28 @@ def main(client, customer_id):
     # [END add_campaigns_1]
 
     # Optional: Set the start date.
-    start_time = datetime.date.today() + datetime.timedelta(days=1)
+    start_time: datetime.date = datetime.date.today() + datetime.timedelta(
+        days=1
+    )
     campaign.start_date = datetime.date.strftime(start_time, _DATE_FORMAT)
 
     # Optional: Set the end date.
-    end_time = start_time + datetime.timedelta(weeks=4)
+    end_time: datetime.date = start_time + datetime.timedelta(weeks=4)
     campaign.end_date = datetime.date.strftime(end_time, _DATE_FORMAT)
 
     # Add the campaign.
+    campaign_response: MutateCampaignsResponse
     try:
+        campaign_operations: List[CampaignOperation] = [campaign_operation]
         campaign_response = campaign_service.mutate_campaigns(
-            customer_id=customer_id, operations=[campaign_operation]
+            customer_id=customer_id, operations=campaign_operations
         )
         print(f"Created campaign {campaign_response.results[0].resource_name}.")
     except GoogleAdsException as ex:
         handle_googleads_exception(ex)
 
 
-def handle_googleads_exception(exception):
+def handle_googleads_exception(exception: GoogleAdsException) -> None:
     print(
         f'Request with ID "{exception.request_id}" failed with status '
         f'"{exception.error.code().name}" and includes the following errors:'
@@ -125,10 +162,12 @@ def handle_googleads_exception(exception):
         required=True,
         help="The Google Ads customer ID.",
     )
-    args = parser.parse_args()
+    args: argparse.Namespace = parser.parse_args()
 
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    googleads_client = GoogleAdsClient.load_from_storage(version="v20")
+    googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage(
+        version="v20"
+    )
 
     main(googleads_client, args.customer_id)

examples/basic_operations/get_campaigns.py

@@ -20,27 +20,38 @@
 
 import argparse
 import sys
+from typing import Iterator, List
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.services.services.google_ads_service import (
+    GoogleAdsServiceClient,
+)
+from google.ads.googleads.v20.services.types.google_ads_service import (
+    SearchGoogleAdsStreamResponse,
+    GoogleAdsRow,
+)
 
 
 # [START get_campaigns]
-def main(client, customer_id):
-    ga_service = client.get_service("GoogleAdsService")
+def main(client: GoogleAdsClient, customer_id: str) -> None:
+    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")
 
-    query = """
+    query: str = """
         SELECT
           campaign.id,
           campaign.name
         FROM campaign
         ORDER BY campaign.id"""
 
     # Issues a search request using streaming.
-    stream = ga_service.search_stream(customer_id=customer_id, query=query)
+    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
+        customer_id=customer_id, query=query
+    )
 
     for batch in stream:
-        for row in batch.results:
+        rows: List[GoogleAdsRow] = batch.results
+        for row in rows:
             print(
                 f"Campaign with ID {row.campaign.id} and name "
                 f'"{row.campaign.name}" was found.'
@@ -60,11 +71,13 @@ def main(client, customer_id):
         required=True,
         help="The Google Ads customer ID.",
     )
-    args = parser.parse_args()
+    args: argparse.Namespace = parser.parse_args()
 
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    googleads_client = GoogleAdsClient.load_from_storage(version="v20")
+    googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage(
+        version="v20"
+    )
 
     try:
         main(googleads_client, args.customer_id)

examples/basic_operations/get_responsive_search_ads.py

@@ -20,46 +20,67 @@
 
 import argparse
 import sys
+from typing import List, Optional, Sequence
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
-
-
-def main(client, customer_id, ad_group_id=None):
-    ga_service = client.get_service("GoogleAdsService")
-
-    query = '''
-        SELECT ad_group.id, ad_group_ad.ad.id,
-        ad_group_ad.ad.responsive_search_ad.headlines,
-        ad_group_ad.ad.responsive_search_ad.descriptions,
-        ad_group_ad.status FROM ad_group_ad
-        WHERE ad_group_ad.ad.type = RESPONSIVE_SEARCH_AD
-        AND ad_group_ad.status != "REMOVED"'''
+from google.ads.googleads.v20.common.types.ad_asset import AdTextAsset
+from google.ads.googleads.v20.resources.types.ad import Ad
+from google.ads.googleads.v20.services.services.google_ads_service import (
+    GoogleAdsServiceClient,
+)
+from google.ads.googleads.v20.services.types.google_ads_service import (
+    SearchGoogleAdsRequest,
+    SearchGoogleAdsResponse,
+)
+
+
+def main(
+    client: GoogleAdsClient,
+    customer_id: str,
+    ad_group_id: Optional[str] = None,
+) -> None:
+    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")
+
+    query: str = """
+        SELECT
+          ad_group.id,
+          ad_group_ad.ad.id,
+          ad_group_ad.ad.responsive_search_ad.headlines,
+          ad_group_ad.ad.responsive_search_ad.descriptions,
+          ad_group_ad.status
+        FROM ad_group_ad
+          WHERE ad_group_ad.ad.type = RESPONSIVE_SEARCH_AD
+          AND ad_group_ad.status != REMOVED"""
 
     # Optional: Specify an ad group ID to restrict search to only a given
     # ad group.
     if ad_group_id:
         query += f" AND ad_group.id = {ad_group_id}"
 
-    ga_search_request = client.get_type("SearchGoogleAdsRequest")
+    ga_search_request: SearchGoogleAdsRequest = client.get_type(
+        "SearchGoogleAdsRequest"
+    )
     ga_search_request.customer_id = customer_id
     ga_search_request.query = query
-    results = ga_service.search(request=ga_search_request)
+    results: SearchGoogleAdsResponse = ga_service.search(
+        request=ga_search_request
+    )
 
-    one_found = False
+    one_found: bool = False
 
     for row in results:
         one_found = True
-        ad = row.ad_group_ad.ad
+        ad: Ad = row.ad_group_ad.ad
         print(
             "Responsive search ad with resource name "
             f'"{ad.resource_name}", status {row.ad_group_ad.status.name} '
             "was found."
         )
-        headlines = "\n".join(
+        headlines: str = "\n".join(
             ad_text_assets_to_strs(ad.responsive_search_ad.headlines)
         )
-        descriptions = "\n".join(
+        descriptions: str = "\n".join(
             ad_text_assets_to_strs(ad.responsive_search_ad.descriptions)
         )
         print(f"Headlines:\n{headlines}\nDescriptions:\n{descriptions}\n")
@@ -68,9 +89,10 @@ def main(client, customer_id, ad_group_id=None):
         print("No responsive search ads were found.")
 
 
-def ad_text_assets_to_strs(assets):
+def ad_text_assets_to_strs(assets: Sequence[AdTextAsset]) -> List[str]:
     """Converts a list of AdTextAssets to a list of user-friendly strings."""
-    s = []
+    s: List[str] = []
+    asset: AdTextAsset
     for asset in assets:
         s.append(f"\t {asset.text} pinned to {asset.pinned_field.name}")
     return s
@@ -96,11 +118,13 @@ def ad_text_assets_to_strs(assets):
         required=False,
         help="The ad group ID. ",
     )
-    args = parser.parse_args()
+    args: argparse.Namespace = parser.parse_args()
 
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    googleads_client = GoogleAdsClient.load_from_storage(version="v20")
+    googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage(
+        version="v20"
+    )
 
     try:
         main(