Add annotations to examples/targeting (#954)

Author: bobhancockg

examples/targeting/add_campaign_targeting_criteria.py

@@ -16,24 +16,52 @@
 
 
 import argparse
+from typing import List
 import sys
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.common.types.criteria import (
+    KeywordInfo,
+)
+from google.ads.googleads.v20.resources.types.campaign_criterion import (
+    CampaignCriterion,
+)
+from google.ads.googleads.v20.services.services.campaign_service import (
+    CampaignServiceClient,
+)
+from google.ads.googleads.v20.services.services.campaign_criterion_service import (
+    CampaignCriterionServiceClient,
+)
+from google.ads.googleads.v20.services.services.geo_target_constant_service import (
+    GeoTargetConstantServiceClient,
+)
+from google.ads.googleads.v20.services.types.campaign_criterion_service import (
+    CampaignCriterionOperation,
+    MutateCampaignCriteriaResponse
+)
+
+
+def main(
+    client: GoogleAdsClient,
+    customer_id: str,
+    campaign_id: str,
+    keyword_text: str,
+    location_id: str,
+) -> None:
+    campaign_criterion_service: CampaignCriterionServiceClient = client.get_service(
+        "CampaignCriterionService"
+    )
 
-
-def main(client, customer_id, campaign_id, keyword_text, location_id):
-    campaign_criterion_service = client.get_service("CampaignCriterionService")
-
-    operations = [
+    operations: List[CampaignCriterionOperation] = [
         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: MutateCampaignCriteriaResponse = (
         campaign_criterion_service.mutate_campaign_criteria(
             customer_id=customer_id, operations=operations
         )
@@ -44,13 +72,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
+) -> CampaignCriterionOperation:
+    campaign_service: CampaignServiceClient = client.get_service("CampaignService")
+    geo_target_constant_service: GeoTargetConstantServiceClient = client.get_service(
+        "GeoTargetConstantService"
+    )
 
     # Create the campaign criterion.
-    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
-    campaign_criterion = campaign_criterion_operation.create
+    campaign_criterion_operation: CampaignCriterionOperation = client.get_type(
+        "CampaignCriterionOperation"
+    )
+    campaign_criterion: CampaignCriterion = campaign_criterion_operation.create
     campaign_criterion.campaign = campaign_service.campaign_path(
         customer_id, campaign_id
     )
@@ -67,30 +101,38 @@ 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
+) -> CampaignCriterionOperation:
+    campaign_service: CampaignServiceClient = client.get_service("CampaignService")
 
     # Create the campaign criterion.
-    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
-    campaign_criterion = campaign_criterion_operation.create
+    campaign_criterion_operation: CampaignCriterionOperation = client.get_type(
+        "CampaignCriterionOperation"
+    )
+    campaign_criterion: CampaignCriterion = campaign_criterion_operation.create
     campaign_criterion.campaign = campaign_service.campaign_path(
         customer_id, campaign_id
     )
     campaign_criterion.negative = True
-    criterion_keyword = campaign_criterion.keyword
+    criterion_keyword: KeywordInfo = campaign_criterion.keyword
     criterion_keyword.text = keyword_text
     criterion_keyword.match_type = client.enums.KeywordMatchTypeEnum.BROAD
 
     return campaign_criterion_operation
 
 
 # [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
+) -> CampaignCriterionOperation:
+    campaign_service: CampaignServiceClient = client.get_service("CampaignService")
 
     # Create the campaign criterion.
-    campaign_criterion_operation = client.get_type("CampaignCriterionOperation")
-    campaign_criterion = campaign_criterion_operation.create
+    campaign_criterion_operation: CampaignCriterionOperation = client.get_type(
+        "CampaignCriterionOperation"
+    )
+    campaign_criterion: CampaignCriterion = campaign_criterion_operation.create
     campaign_criterion.campaign = campaign_service.campaign_path(
         customer_id, campaign_id
     )
@@ -146,11 +188,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

@@ -23,42 +23,54 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.resources.types.customer_negative_criterion import (
+    CustomerNegativeCriterion,
+)
+from google.ads.googleads.v20.services.services.customer_negative_criterion_service import (
+    CustomerNegativeCriterionServiceClient,
+)
+from google.ads.googleads.v20.services.types.customer_negative_criterion_service import (
+    CustomerNegativeCriterionOperation,
+    MutateCustomerNegativeCriteriaResponse
+)
 
-
-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: CustomerNegativeCriterionOperation = client.get_type(
+        "CustomerNegativeCriterionOperation"
+    )
+    tragedy_criterion: CustomerNegativeCriterion = 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: CustomerNegativeCriterionOperation = client.get_type(
         "CustomerNegativeCriterionOperation"
     )
-    placement_criterion = placement_criterion_op.create
+    placement_criterion: CustomerNegativeCriterion = 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: CustomerNegativeCriterionServiceClient = client.get_service(
         "CustomerNegativeCriterionService"
     )
 
     # Issues a mutate request to add the negative customer criteria.
-    response = (
+    response: MutateCustomerNegativeCriteriaResponse = (
         customer_negative_criterion_service.mutate_customer_negative_criteria(
             customer_id=customer_id,
             operations=[tragedy_criterion_op, placement_criterion_op],
         )
     )
+
     print(f"Added {len(response.results)} negative customer criteria:")
     for negative_criterion in response.results:
         print(f"Resource name: '{negative_criterion.resource_name}'")
@@ -80,11 +92,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

@@ -22,36 +22,57 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.resources.types.ad_group_criterion import (
+    AdGroupCriterion,
+)
+from google.ads.googleads.v20.services.services.ad_group_criterion_service import (
+    AdGroupCriterionServiceClient,
+)
+from google.ads.googleads.v20.services.services.ad_group_service import (
+    AdGroupServiceClient,
+)
+from google.ads.googleads.v20.services.types.ad_group_criterion_service import (
+    AdGroupCriterionOperation,
+    MutateAdGroupCriteriaResponse,
+)
 
 
-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: AdGroupServiceClient = client.get_service("AdGroupService")
+    ad_group_criterion_service: AdGroupCriterionServiceClient = 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: AdGroupCriterionOperation = client.get_type(
         "AdGroupCriterionOperation"
     )
-    gender_ad_group_criterion = gender_ad_group_criterion_operation.create
+    gender_ad_group_criterion: AdGroupCriterion = (
+        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: AdGroupCriterionOperation = client.get_type(
         "AdGroupCriterionOperation"
     )
-    age_range_ad_group_criterion = age_range_ad_group_criterion_operation.create
+    age_range_ad_group_criterion: AdGroupCriterion = (
+        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: MutateAdGroupCriteriaResponse = (
         ad_group_criterion_service.mutate_ad_group_criteria(
             customer_id=customer_id,
             operations=[
@@ -62,7 +83,7 @@ def main(client, customer_id, ad_group_id):
     )
 
     for result in ad_group_criterion_response.results:
-        print("Created keyword {}.".format(result.resource_name))
+        print(f"Created ad group criterion '{result.resource_name}'.")
 
 
 if __name__ == "__main__":
@@ -83,11 +104,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

@@ -19,34 +19,53 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.resources.types.geo_target_constant import (
+    GeoTargetConstant,
+)
+from google.ads.googleads.v20.services.services.geo_target_constant_service import (
+    GeoTargetConstantServiceClient,
+)
+from google.ads.googleads.v20.services.types.geo_target_constant_service import (
+    GeoTargetConstantSuggestion,
+    SuggestGeoTargetConstantsRequest,
+    SuggestGeoTargetConstantsResponse,
+)
 
 # 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")
-
-    gtc_request = client.get_type("SuggestGeoTargetConstantsRequest")
+def main(client: GoogleAdsClient) -> None:
+    gtc_service: GeoTargetConstantServiceClient = client.get_service(
+        "GeoTargetConstantService"
+    )
 
+    gtc_request: SuggestGeoTargetConstantsRequest = 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: SuggestGeoTargetConstantsResponse = (
+        gtc_service.suggest_geo_target_constants(gtc_request)
+    )
 
+    suggestion: GeoTargetConstantSuggestion
     for suggestion in results.geo_target_constant_suggestions:
-        geo_target_constant = suggestion.geo_target_constant
+        geo_target_constant: GeoTargetConstant = suggestion.geo_target_constant
         print(
             f"{geo_target_constant.resource_name} "
             f"({geo_target_constant.name}, "
@@ -63,7 +82,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)