Add type hints to examples/account_management

This change adds Python type hints to all Python files within the
examples/account_management directory. This includes:
- Function signatures
- Variable annotations where appropriate

Type hints improve code readability and help with static analysis.
No functional changes were made.

Author: google-labs-jules[bot]

examples/account_management/create_customer.py

@@ -27,12 +27,16 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v19.resources.types.customer import Customer
+from google.ads.googleads.v19.services.services.customer_service.client import CustomerServiceClient
+from google.ads.googleads.v19.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:
+    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
@@ -45,7 +49,7 @@ def main(client, manager_customer_id):
         "keyword={keyword}&matchtype={matchtype}" "&adgroupid={adgroupid}"
     )
 
-    response = customer_service.create_customer_client(
+    response: CreateCustomerClientResponse = customer_service.create_customer_client(
         customer_id=manager_customer_id, customer_client=customer
     )
     print(

examples/account_management/get_account_hierarchy.py

@@ -24,12 +24,18 @@
 
 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.v19.services.services.google_ads_service.client import GoogleAdsServiceClient
+from google.ads.googleads.v19.services.services.customer_service.client import CustomerServiceClient
+from google.ads.googleads.v19.resources.types.customer_client import CustomerClient
+from google.ads.googleads.v19.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:
@@ -40,11 +46,11 @@ def main(client, login_customer_id=None):
     """
 
     # 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 +70,74 @@ 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.
-            for googleads_row in response:
-                customer_client = googleads_row.customer_client
+            for googleads_row: GoogleAdsRow in response:
+                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 +156,8 @@ 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 +171,18 @@ 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:
+        for child_account: CustomerClient 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,27 @@
 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.v19.services.services.google_ads_service.client import GoogleAdsServiceClient
+from google.ads.googleads.v19.services.types.google_ads_service import SearchGoogleAdsRequest, SearchPagedResponse, GoogleAdsRow
+from google.ads.googleads.v19.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 +50,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 +70,17 @@ 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)
 
-    for row in results:
-        event = row.change_event
-        resource_type = event.change_resource_type.name
+    for row: GoogleAdsRow in results:
+        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 +154,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 +174,7 @@ 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):

examples/account_management/get_change_summary.py

@@ -23,11 +23,14 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v19.services.services.google_ads_service.client import GoogleAdsServiceClient
+from google.ads.googleads.v19.services.types.google_ads_service import SearchGoogleAdsRequest, SearchPagedResponse, GoogleAdsRow
+from google.ads.googleads.v19.resources.types.change_status import ChangeStatus
 
 
 # [START get_change_summary]
-def main(client, customer_id):
-    ads_service = client.get_service("GoogleAdsService")
+def main(client: GoogleAdsClient, customer_id: str) -> None:
+    ads_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")
 
     # Construct a query to find information about changed resources in your
     # account.
@@ -47,15 +50,16 @@ def main(client, customer_id):
         ORDER BY change_status.last_change_date_time
         LIMIT 10000"""
 
-    search_request = client.get_type("SearchGoogleAdsRequest")
+    search_request: SearchGoogleAdsRequest = client.get_type("SearchGoogleAdsRequest")
     search_request.customer_id = customer_id
     search_request.query = query
 
-    response = ads_service.search(request=search_request)
+    response: SearchPagedResponse = ads_service.search(request=search_request)
 
-    for row in response:
-        cs = row.change_status
-        resource_type = cs.resource_type.name
+    for row: GoogleAdsRow in response:
+        cs: ChangeStatus = row.change_status
+        resource_type: str = cs.resource_type.name
+        resource_name: str
         if resource_type == "AD_GROUP":
             resource_name = cs.ad_group
         elif resource_type == "AD_GROUP_AD":
@@ -69,7 +73,7 @@ def main(client, customer_id):
         else:
             resource_name = "UNKNOWN"
 
-        resource_status = cs.resource_status.name
+        resource_status: str = cs.resource_status.name
         print(
             f"On '{cs.last_change_date_time}', change status "
             f"'{cs.resource_name}' shows that a resource type of "

examples/account_management/invite_user_with_access_role.py

@@ -23,27 +23,34 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v19.services.services.customer_user_access_invitation_service.client import CustomerUserAccessInvitationServiceClient
+from google.ads.googleads.v19.services.types.customer_user_access_invitation_service import CustomerUserAccessInvitationOperation, MutateCustomerUserAccessInvitationResponse
+from google.ads.googleads.v19.resources.types.customer_user_access_invitation import CustomerUserAccessInvitation
+# AccessRoleEnum is part of google.ads.googleads.v19.enums.types.access_role
+# but it's accessed via client.enums.AccessRoleEnum, so direct import for type hint might not be strictly needed for the parameter.
+# The field invitation.access_role expects an int (the enum value).
 
-
-def main(client, customer_id, email_address, access_role):
+def main(client: GoogleAdsClient, customer_id: str, email_address: str, access_role: str) -> None:
     """The main method that creates all necessary entities for the example.
 
     Args:
         client: An initialized GoogleAdsClient instance.
         customer_id: The client customer ID str.
         email_address: The email address for the user receiving the invitation.
-        access_role: The desired access role for the invitee.
+        access_role: The desired access role for the invitee (e.g., "ADMIN", "STANDARD").
     """
-    service = client.get_service("CustomerUserAccessInvitationService")
+    service: CustomerUserAccessInvitationServiceClient = client.get_service("CustomerUserAccessInvitationService")
     # [START invite_user_with_access_role]
-    invitation_operation = client.get_type(
+    invitation_operation: CustomerUserAccessInvitationOperation = client.get_type(
         "CustomerUserAccessInvitationOperation"
     )
-    invitation = invitation_operation.create
+    invitation: CustomerUserAccessInvitation = invitation_operation.create
     invitation.email_address = email_address
+    # The access_role field in the CustomerUserAccessInvitation message expects
+    # an AccessRoleEnum value (which is an int).
     invitation.access_role = client.enums.AccessRoleEnum[access_role].value
 
-    response = service.mutate_customer_user_access_invitation(
+    response: MutateCustomerUserAccessInvitationResponse = service.mutate_customer_user_access_invitation(
         customer_id=customer_id, operation=invitation_operation
     )
     print(