Add type hints to examples/targeting files

This change introduces type annotations to the Python scripts
in the examples/targeting/ directory.

Type hints were added for:
- Function arguments and return values.
- Key local variables, particularly those interacting with the Google Ads API.
- GoogleAdsClient instances and argparse.Namespace objects.

The typing.Any type was used for complex Google Ads API objects where specific types were not readily apparent. This improves code readability and maintainability by making type expectations explicit.

Author: google-labs-jules[bot]

examples/targeting/add_campaign_targeting_criteria.py

@@ -16,24 +16,33 @@
 
 
 import argparse
+from typing import Any, List
 import sys
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
 
 
-def main(client, customer_id, campaign_id, keyword_text, location_id):
-    campaign_criterion_service = client.get_service("CampaignCriterionService")
+def main(
+    client: GoogleAdsClient,
+    customer_id: str,
+    campaign_id: str,
+    keyword_text: str,
+    location_id: str,
+) -> None:
+    campaign_criterion_service: Any = client.get_service(
+        "CampaignCriterionService"
+    )
 
-    operations = [
+    operations: List[Any] = [
         create_location_op(client, customer_id, campaign_id, location_id),
         create_negative_keyword_op(
             client, customer_id, campaign_id, keyword_text
         ),
         create_proximity_op(client, customer_id, campaign_id),
     ]
 
-    campaign_criterion_response = (
+    campaign_criterion_response: Any = (
         campaign_criterion_service.mutate_campaign_criteria(
             customer_id=customer_id, operations=operations
         )
@@ -44,13 +53,19 @@ def main(client, customer_id, campaign_id, keyword_text, location_id):
 
 
 # [START add_campaign_targeting_criteria]
-def create_location_op(client, customer_id, campaign_id, location_id):
-    campaign_service = client.get_service("CampaignService")
-    geo_target_constant_service = client.get_service("GeoTargetConstantService")
+def create_location_op(
+    client: GoogleAdsClient, customer_id: str, campaign_id: str, location_id: str
+) -> Any:
+    campaign_service: Any = client.get_service("CampaignService")
+    geo_target_constant_service: Any = client.get_service(
+        "GeoTargetConstantService"
+    )
 
     # Create the campaign criterion.
-    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
-    campaign_criterion = campaign_criterion_operation.create
+    campaign_criterion_operation: Any = client.get_type(
+        "CampaignCriterionOperation"
+    )
+    campaign_criterion: Any = campaign_criterion_operation.create
     campaign_criterion.campaign = campaign_service.campaign_path(
         customer_id, campaign_id
     )
@@ -67,12 +82,16 @@ def create_location_op(client, customer_id, campaign_id, location_id):
     # [END add_campaign_targeting_criteria]
 
 
-def create_negative_keyword_op(client, customer_id, campaign_id, keyword_text):
-    campaign_service = client.get_service("CampaignService")
+def create_negative_keyword_op(
+    client: GoogleAdsClient, customer_id: str, campaign_id: str, keyword_text: str
+) -> Any:
+    campaign_service: Any = client.get_service("CampaignService")
 
     # Create the campaign criterion.
-    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
-    campaign_criterion = campaign_criterion_operation.create
+    campaign_criterion_operation: Any = client.get_type(
+        "CampaignCriterionOperation"
+    )
+    campaign_criterion: Any = campaign_criterion_operation.create
     campaign_criterion.campaign = campaign_service.campaign_path(
         customer_id, campaign_id
     )
@@ -85,12 +104,16 @@ def create_negative_keyword_op(client, customer_id, campaign_id, keyword_text):
 
 
 # [START add_campaign_targeting_criteria_1]
-def create_proximity_op(client, customer_id, campaign_id):
-    campaign_service = client.get_service("CampaignService")
+def create_proximity_op(
+    client: GoogleAdsClient, customer_id: str, campaign_id: str
+) -> Any:
+    campaign_service: Any = client.get_service("CampaignService")
 
     # Create the campaign criterion.
-    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
-    campaign_criterion = campaign_criterion_operation.create
+    campaign_criterion_operation: Any = client.get_type(
+        "CampaignCriterionOperation"
+    )
+    campaign_criterion: Any = campaign_criterion_operation.create
     campaign_criterion.campaign = campaign_service.campaign_path(
         customer_id, campaign_id
     )
@@ -146,11 +169,13 @@ def create_proximity_op(client, customer_id, campaign_id):
             "https://developers.google.com/google-ads/api/reference/data/geotargets"
         ),
     )
-    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(

examples/targeting/add_customer_negative_criteria.py

@@ -19,41 +19,44 @@
 
 
 import argparse
+from typing import Any, List
 import sys
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
 
 
-def main(client, customer_id):
+def main(client: GoogleAdsClient, customer_id: str) -> None:
     """The main method that creates all necessary entities for the example.
 
     Args:
         client: an initialized GoogleAdsClient instance.
         customer_id: a client customer ID.
     """
-    tragedy_criterion_op = client.get_type("CustomerNegativeCriterionOperation")
-    tragedy_criterion = tragedy_criterion_op.create
+    tragedy_criterion_op: Any = client.get_type(
+        "CustomerNegativeCriterionOperation"
+    )
+    tragedy_criterion: Any = tragedy_criterion_op.create
     # Creates a negative customer criterion excluding the content label type
     # of 'TRAGEDY'.
     tragedy_criterion.content_label.type_ = (
         client.enums.ContentLabelTypeEnum.TRAGEDY
     )
 
-    placement_criterion_op = client.get_type(
+    placement_criterion_op: Any = client.get_type(
         "CustomerNegativeCriterionOperation"
     )
-    placement_criterion = placement_criterion_op.create
+    placement_criterion: Any = placement_criterion_op.create
     # Creates a negative customer criterion excluding the placement with URL
     # 'http://www.example.com'.
     placement_criterion.placement.url = "http://www.example.com"
 
-    customer_negative_criterion_service = client.get_service(
+    customer_negative_criterion_service: Any = client.get_service(
         "CustomerNegativeCriterionService"
     )
 
     # Issues a mutate request to add the negative customer criteria.
-    response = (
+    response: Any = (
         customer_negative_criterion_service.mutate_customer_negative_criteria(
             customer_id=customer_id,
             operations=[tragedy_criterion_op, placement_criterion_op],
@@ -80,11 +83,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(

examples/targeting/add_demographic_targeting_criteria.py

@@ -18,40 +18,49 @@
 
 
 import argparse
+from typing import Any, List
 import sys
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
 
 
-def main(client, customer_id, ad_group_id):
-    ad_group_service = client.get_service("AdGroupService")
-    ad_group_criterion_service = client.get_service("AdGroupCriterionService")
+def main(
+    client: GoogleAdsClient, customer_id: str, ad_group_id: str
+) -> None:
+    ad_group_service: Any = client.get_service("AdGroupService")
+    ad_group_criterion_service: Any = client.get_service(
+        "AdGroupCriterionService"
+    )
 
-    ad_group_resource_name = ad_group_service.ad_group_path(
+    ad_group_resource_name: str = ad_group_service.ad_group_path(
         customer_id, ad_group_id
     )
     # Create a positive ad group criterion for the gender MALE.
-    gender_ad_group_criterion_operation = client.get_type(
+    gender_ad_group_criterion_operation: Any = client.get_type(
         "AdGroupCriterionOperation"
     )
-    gender_ad_group_criterion = gender_ad_group_criterion_operation.create
+    gender_ad_group_criterion: Any = (
+        gender_ad_group_criterion_operation.create
+    )
     gender_ad_group_criterion.ad_group = ad_group_resource_name
     gender_ad_group_criterion.gender.type_ = client.enums.GenderTypeEnum.MALE
 
     # Create a negative ad group criterion for age range of 18 to 24.
-    age_range_ad_group_criterion_operation = client.get_type(
+    age_range_ad_group_criterion_operation: Any = client.get_type(
         "AdGroupCriterionOperation"
     )
-    age_range_ad_group_criterion = age_range_ad_group_criterion_operation.create
+    age_range_ad_group_criterion: Any = (
+        age_range_ad_group_criterion_operation.create
+    )
     age_range_ad_group_criterion.ad_group = ad_group_resource_name
     age_range_ad_group_criterion.negative = True
     age_range_ad_group_criterion.age_range.type_ = (
         client.enums.AgeRangeTypeEnum.AGE_RANGE_18_24
     )
 
     # Add two ad group criteria
-    ad_group_criterion_response = (
+    ad_group_criterion_response: Any = (
         ad_group_criterion_service.mutate_ad_group_criteria(
             customer_id=customer_id,
             operations=[
@@ -83,11 +92,13 @@ def main(client, customer_id, ad_group_id):
     parser.add_argument(
         "-a", "--ad_group_id", type=str, required=True, 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(googleads_client, args.customer_id, args.ad_group_id)

examples/targeting/get_geo_target_constants_by_names.py

@@ -15,38 +15,41 @@
 """This example illustrates getting GeoTargetConstants by given location names."""
 
 
+from typing import Any, List
 import sys
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
 
 # Locale is using ISO 639-1 format. If an invalid locale is given,
 # 'en' is used by default.
-LOCALE = "en"
+LOCALE: str = "en"
 
 # A list of country codes can be referenced here:
 # https://developers.google.com/google-ads/api/reference/data/geotargets
-COUNTRY_CODE = "FR"
+COUNTRY_CODE: str = "FR"
 
 
 # [START get_geo_target_constants_by_names]
-def main(client):
-    gtc_service = client.get_service("GeoTargetConstantService")
+def main(client: GoogleAdsClient) -> None:
+    gtc_service: Any = client.get_service("GeoTargetConstantService")
 
-    gtc_request = client.get_type("SuggestGeoTargetConstantsRequest")
+    gtc_request: Any = client.get_type("SuggestGeoTargetConstantsRequest")
 
     gtc_request.locale = LOCALE
     gtc_request.country_code = COUNTRY_CODE
 
     # The location names to get suggested geo target constants.
+    # Type hint for gtc_request.location_names.names is not straightforward
+    # as it's part of a complex protobuf object.
     gtc_request.location_names.names.extend(
         ["Paris", "Quebec", "Spain", "Deutschland"]
     )
 
-    results = gtc_service.suggest_geo_target_constants(gtc_request)
+    results: Any = gtc_service.suggest_geo_target_constants(gtc_request)
 
     for suggestion in results.geo_target_constant_suggestions:
-        geo_target_constant = suggestion.geo_target_constant
+        geo_target_constant: Any = suggestion.geo_target_constant
         print(
             f"{geo_target_constant.resource_name} "
             f"({geo_target_constant.name}, "
@@ -63,7 +66,9 @@ def main(client):
 if __name__ == "__main__":
     # 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)