Add annotations to examples/account_management (#937)

Author: bobhancockg

examples/account_management/create_customer.py

@@ -27,13 +27,28 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.resources.types.customer import Customer
+from google.ads.googleads.v20.services.services.customer_service.client import (
+    CustomerServiceClient,
+)
+from google.ads.googleads.v20.services.types.customer_service import (
+    CreateCustomerClientResponse,
+)
 
 
 # [START create_customer]
-def main(client, manager_customer_id):
-    customer_service = client.get_service("CustomerService")
-    customer = client.get_type("Customer")
-    now = datetime.today().strftime("%Y%m%d %H:%M:%S")
+def main(client: GoogleAdsClient, manager_customer_id: str) -> None:
+    """The main method that creates all necessary entities for the example.
+
+    Args:
+        client: an initialized GoogleAdsClient instance.
+        manager_customer_id: a manager client customer ID.
+    """
+    customer_service: CustomerServiceClient = client.get_service(
+        "CustomerService"
+    )
+    customer: Customer = client.get_type("Customer")
+    now: str = datetime.today().strftime("%Y%m%d %H:%M:%S")
     customer.descriptive_name = f"Account created with CustomerService on {now}"
     # For a list of valid currency codes and time zones see this documentation:
     # https://developers.google.com/google-ads/api/reference/data/codes-formats
@@ -43,11 +58,13 @@ def main(client, manager_customer_id):
     # options see: https://support.google.com/google-ads/answer/6305348
     customer.tracking_url_template = "{lpurl}?device={device}"
     customer.final_url_suffix = (
-        "keyword={keyword}&matchtype={matchtype}" "&adgroupid={adgroupid}"
+        "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
     )
 
-    response = customer_service.create_customer_client(
-        customer_id=manager_customer_id, customer_client=customer
+    response: CreateCustomerClientResponse = (
+        customer_service.create_customer_client(
+            customer_id=manager_customer_id, customer_client=customer
+        )
     )
     print(
         f'Customer created with resource name "{response.resource_name}" '

examples/account_management/get_account_hierarchy.py

@@ -24,12 +24,31 @@
 
 import argparse
 import sys
+from typing import Optional, List, Dict
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
-
-
-def main(client, login_customer_id=None):
+from google.ads.googleads.v20.services.services.google_ads_service.client import (
+    GoogleAdsServiceClient,
+)
+from google.ads.googleads.v20.services.services.customer_service.client import (
+    CustomerServiceClient,
+)
+from google.ads.googleads.v20.resources.types.customer_client import (
+    CustomerClient,
+)
+from google.ads.googleads.v20.services.types.google_ads_service import (
+    SearchPagedResponse,
+    GoogleAdsRow,
+)
+
+# ListAccessibleCustomersResponse is not directly used for a variable type,
+# but its attribute .resource_names is used, which is List[str].
+
+
+def main(
+    client: GoogleAdsClient, login_customer_id: Optional[str] = None
+) -> None:
     """Gets the account hierarchy of the given MCC and login customer ID.
 
     Args:
@@ -38,13 +57,16 @@ def main(client, login_customer_id=None):
       method will instead list the accounts accessible from the
       authenticated Google Ads account.
     """
-
     # Gets instances of the GoogleAdsService and CustomerService clients.
-    googleads_service = client.get_service("GoogleAdsService")
-    customer_service = client.get_service("CustomerService")
+    googleads_service: GoogleAdsServiceClient = client.get_service(
+        "GoogleAdsService"
+    )
+    customer_service: CustomerServiceClient = client.get_service(
+        "CustomerService"
+    )
 
     # A collection of customer IDs to handle.
-    seed_customer_ids = []
+    seed_customer_ids: List[str] = []
 
     # Creates a query that retrieves all child accounts of the manager
     # specified in search calls below.
@@ -64,69 +86,84 @@ def main(client, login_customer_id=None):
     # the only ID in the list. Otherwise, we will issue a request for all
     # customers accessible by this authenticated Google account.
     if login_customer_id is not None:
+        # Ensure login_customer_id is treated as a string for this list.
         seed_customer_ids = [login_customer_id]
     else:
         print(
             "No manager ID is specified. The example will print the "
             "hierarchies of all accessible customer IDs."
         )
 
-        customer_resource_names = (
+        customer_resource_names: List[str] = (
             customer_service.list_accessible_customers().resource_names
         )
 
         for customer_resource_name in customer_resource_names:
-            customer_id = googleads_service.parse_customer_path(
+            # customer_id here is a string as returned by parse_customer_path
+            customer_id_from_parse: str = googleads_service.parse_customer_path(
                 customer_resource_name
             )["customer_id"]
-            print(customer_id)
-            seed_customer_ids.append(customer_id)
+            print(customer_id_from_parse)
+            seed_customer_ids.append(customer_id_from_parse)
 
-    for seed_customer_id in seed_customer_ids:
+    for (
+        seed_customer_id_str
+    ) in seed_customer_ids:  # seed_customer_id_str is a string
         # Performs a breadth-first search to build a Dictionary that maps
         # managers to their child accounts (customerIdsToChildAccounts).
-        unprocessed_customer_ids = [seed_customer_id]
-        customer_ids_to_child_accounts = dict()
-        root_customer_client = None
+        # unprocessed_customer_ids should store integers.
+        unprocessed_customer_ids: List[int] = [int(seed_customer_id_str)]
+        customer_ids_to_child_accounts: Dict[int, List[CustomerClient]] = dict()
+        root_customer_client: CustomerClient | None = None
 
         while unprocessed_customer_ids:
-            customer_id = int(unprocessed_customer_ids.pop(0))
-            response = googleads_service.search(
-                customer_id=str(customer_id), query=query
+            customer_id_loop: int = unprocessed_customer_ids.pop(
+                0
+            )  # customer_id_loop is an int
+            # The search method expects customer_id to be a string.
+            response: SearchPagedResponse = googleads_service.search(
+                customer_id=str(customer_id_loop), query=query
             )
 
             # Iterates over all rows in all pages to get all customer
             # clients under the specified customer's hierarchy.
+            googleads_row: GoogleAdsRow
             for googleads_row in response:
-                customer_client = googleads_row.customer_client
+                customer_client_loop_var: CustomerClient = (
+                    googleads_row.customer_client
+                )
 
                 # The customer client that with level 0 is the specified
                 # customer.
-                if customer_client.level == 0:
+                if customer_client_loop_var.level == 0:
                     if root_customer_client is None:
-                        root_customer_client = customer_client
+                        root_customer_client = customer_client_loop_var
                     continue
 
                 # For all level-1 (direct child) accounts that are a
                 # manager account, the above query will be run against them
                 # to create a Dictionary of managers mapped to their child
                 # accounts for printing the hierarchy afterwards.
-                if customer_id not in customer_ids_to_child_accounts:
-                    customer_ids_to_child_accounts[customer_id] = []
+                if customer_id_loop not in customer_ids_to_child_accounts:
+                    customer_ids_to_child_accounts[customer_id_loop] = []
 
-                customer_ids_to_child_accounts[customer_id].append(
-                    customer_client
+                customer_ids_to_child_accounts[customer_id_loop].append(
+                    customer_client_loop_var
                 )
 
-                if customer_client.manager:
+                if customer_client_loop_var.manager:
                     # A customer can be managed by multiple managers, so to
                     # prevent visiting the same customer many times, we
                     # need to check if it's already in the Dictionary.
+                    # Assuming customer_client_loop_var.id is an int
                     if (
-                        customer_client.id not in customer_ids_to_child_accounts
-                        and customer_client.level == 1
+                        customer_client_loop_var.id
+                        not in customer_ids_to_child_accounts
+                        and customer_client_loop_var.level == 1
                     ):
-                        unprocessed_customer_ids.append(customer_client.id)
+                        unprocessed_customer_ids.append(
+                            customer_client_loop_var.id
+                        )
 
         if root_customer_client is not None:
             print(
@@ -145,8 +182,10 @@ def main(client, login_customer_id=None):
 
 
 def print_account_hierarchy(
-    customer_client, customer_ids_to_child_accounts, depth
-):
+    customer_client: CustomerClient,
+    customer_ids_to_child_accounts: Dict[int, List[CustomerClient]],
+    depth: int,
+) -> None:
     """Prints the specified account's hierarchy using recursion.
 
     Args:
@@ -160,17 +199,19 @@ def print_account_hierarchy(
     if depth == 0:
         print("Customer ID (Descriptive Name, Currency Code, Time Zone)")
 
-    customer_id = customer_client.id
+    # Assuming customer_client.id is an int based on previous analysis for keys in customer_ids_to_child_accounts
+    customer_id_print: int = customer_client.id
     print("-" * (depth * 2), end="")
     print(
-        f"{customer_id} ({customer_client.descriptive_name}, "
+        f"{customer_id_print} ({customer_client.descriptive_name}, "
         f"{customer_client.currency_code}, "
         f"{customer_client.time_zone})"
     )
 
     # Recursively call this function for all child accounts of customer_client.
-    if customer_id in customer_ids_to_child_accounts:
-        for child_account in customer_ids_to_child_accounts[customer_id]:
+    if customer_id_print in customer_ids_to_child_accounts:
+        child_account: CustomerClient
+        for child_account in customer_ids_to_child_accounts[customer_id_print]:
             print_account_hierarchy(
                 child_account, customer_ids_to_child_accounts, depth + 1
             )

examples/account_management/get_change_details.py

@@ -21,23 +21,35 @@
 import argparse
 from datetime import datetime, timedelta
 import sys
+from typing import Any
 
 from proto.enums import ProtoEnumMeta
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
 from google.ads.googleads.util import get_nested_attr
+from google.ads.googleads.v20.services.services.google_ads_service.client import (
+    GoogleAdsServiceClient,
+)
+from google.ads.googleads.v20.services.types.google_ads_service import (
+    SearchGoogleAdsRequest,
+    SearchPagedResponse,
+    GoogleAdsRow,
+)
+from google.ads.googleads.v20.resources.types.change_event import ChangeEvent
 
 
 # [START get_change_details]
-def main(client, customer_id):
+def main(client: GoogleAdsClient, customer_id: str) -> None:
     """Gets specific details about the most recent changes in the given account.
 
     Args:
       client: The Google Ads client.
       customer_id: The Google Ads customer ID.
     """
-    googleads_service = client.get_service("GoogleAdsService")
+    googleads_service: GoogleAdsServiceClient = client.get_service(
+        "GoogleAdsService"
+    )
 
     # Construct a query to find details for recent changes in your account.
     # The LIMIT clause is required for the change_event resource.
@@ -46,9 +58,9 @@ def main(client, customer_id):
     # https://developers.google.com/google-ads/api/docs/change-event#getting_changes
     # The WHERE clause on change_date_time is also required. It must specify a
     # window within the past 30 days.
-    tomorrow = (datetime.now() + timedelta(1)).strftime("%Y-%m-%d")
-    two_weeks_ago = (datetime.now() + timedelta(-14)).strftime("%Y-%m-%d")
-    query = f"""
+    tomorrow: str = (datetime.now() + timedelta(1)).strftime("%Y-%m-%d")
+    two_weeks_ago: str = (datetime.now() + timedelta(-14)).strftime("%Y-%m-%d")
+    query: str = f"""
         SELECT
           change_event.resource_name,
           change_event.change_date_time,
@@ -66,15 +78,22 @@ def main(client, customer_id):
         ORDER BY change_event.change_date_time DESC
         LIMIT 5"""
 
-    search_request = client.get_type("SearchGoogleAdsRequest")
+    search_request: SearchGoogleAdsRequest = client.get_type(
+        "SearchGoogleAdsRequest"
+    )
     search_request.customer_id = customer_id
     search_request.query = query
 
-    results = googleads_service.search(request=search_request)
+    results: SearchPagedResponse = googleads_service.search(
+        request=search_request
+    )
 
+    row: GoogleAdsRow
     for row in results:
-        event = row.change_event
-        resource_type = event.change_resource_type.name
+        event: ChangeEvent = row.change_event
+        resource_type: str = event.change_resource_type.name
+        old_resource: Any
+        new_resource: Any
         if resource_type == "AD":
             old_resource = event.old_resource.ad
             new_resource = event.new_resource.ad
@@ -148,17 +167,18 @@ def main(client, customer_id):
             f"'{event.change_resource_name}'"
         )
 
-        operation_type = event.resource_change_operation.name
+        operation_type: str = event.resource_change_operation.name
 
         if operation_type in ("UPDATE", "CREATE"):
-            for changed_field in event.changed_fields.paths:
+            for changed_field_path in event.changed_fields.paths:
+                changed_field: str = changed_field_path
                 # Change field name from "type" to "type_" so that it doesn't
                 # raise an exception when accessed on the protobuf object, see:
                 # https://developers.google.com/google-ads/api/docs/client-libs/python/library-version-10#field_names_that_are_reserved_words
                 if changed_field == "type":
                     changed_field = "type_"
 
-                new_value = get_nested_attr(new_resource, changed_field)
+                new_value: Any = get_nested_attr(new_resource, changed_field)
                 # If the field value is an Enum get the human readable name
                 # so that it is printed instead of the field ID integer.
                 if isinstance(type(new_value), ProtoEnumMeta):
@@ -167,7 +187,9 @@ def main(client, customer_id):
                 if operation_type == "CREATE":
                     print(f"\t{changed_field} set to {new_value}")
                 else:
-                    old_value = get_nested_attr(old_resource, changed_field)
+                    old_value: Any = get_nested_attr(
+                        old_resource, changed_field
+                    )
                     # If the field value is an Enum get the human readable name
                     # so that it is printed instead of the field ID integer.
                     if isinstance(type(old_value), ProtoEnumMeta):