Add type hints to examples/planning files

This change adds Python type hints to the following scripts:
- examples/planning/forecast_reach.py
- examples/planning/generate_forecast_metrics.py
- examples/planning/generate_historical_metrics.py
- examples/planning/generate_keyword_ideas.py
- examples/planning/get_ad_group_criterion_cpc_bid_simulations.py

Type hints were added to function arguments, return values, and variables
where appropriate to improve code readability and maintainability.
The `typing.Any` type was used for complex Google Ads API objects where
specific types were not readily available or too verbose to import directly.

Author: google-labs-jules[bot]

examples/planning/forecast_reach.py

@@ -17,14 +17,15 @@
 import argparse
 import math
 import sys
+from typing import Any, Dict, List, Tuple
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
 
-ONE_MILLION = 1.0e6
+ONE_MILLION: float = 1.0e6
 
 
-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:
@@ -34,23 +35,23 @@ def main(client, customer_id):
     # You can review a list of valid location IDs by visiting:
     # https://developers.google.com/google-ads/api/reference/data/geotargets
     # or by calling the ListPlannableLocations method on ReachPlanService.
-    location_id = "2840"  # US
-    currency_code = "USD"
-    budget = 500000
+    location_id: str = "2840"  # US
+    currency_code: str = "USD"
+    budget: int = 500000
 
     show_plannable_locations(client)
     show_plannable_products(client, location_id)
     forecast_manual_mix(client, customer_id, location_id, currency_code, budget)
 
 
-def show_plannable_locations(client):
+def show_plannable_locations(client: GoogleAdsClient) -> None:
     """Shows map of plannable locations to their IDs.
 
     Args:
         client: an initialized GoogleAdsClient instance.
     """
-    reach_plan_service = client.get_service("ReachPlanService")
-    response = reach_plan_service.list_plannable_locations()
+    reach_plan_service: Any = client.get_service("ReachPlanService")
+    response: Any = reach_plan_service.list_plannable_locations()
 
     print("Plannable Locations")
     print("Name,\tId,\tParentCountryId")
@@ -61,15 +62,15 @@ def show_plannable_locations(client):
 
 
 # [START forecast_reach_2]
-def show_plannable_products(client, location_id):
+def show_plannable_products(client: GoogleAdsClient, location_id: str) -> None:
     """Lists plannable products for a given location.
 
     Args:
         client: an initialized GoogleAdsClient instance.
         location_id: The location ID to plan for.
     """
-    reach_plan_service = client.get_service("ReachPlanService")
-    response = reach_plan_service.list_plannable_products(
+    reach_plan_service: Any = client.get_service("ReachPlanService")
+    response: Any = reach_plan_service.list_plannable_products(
         plannable_location_id=location_id
     )
     print(f"Plannable Products for Location ID {location_id}")
@@ -96,8 +97,12 @@ def show_plannable_products(client, location_id):
 
 # [START forecast_reach]
 def request_reach_curve(
-    client, customer_id, product_mix, location_id, currency_code
-):
+    client: GoogleAdsClient,
+    customer_id: str,
+    product_mix: List[Any],
+    location_id: str,
+    currency_code: str,
+) -> None:
     """Creates a sample request for a given product mix.
 
     Args:
@@ -109,7 +114,7 @@ def request_reach_curve(
     """
     # See the docs for defaults and valid ranges:
     # https://developers.google.com/google-ads/api/reference/rpc/latest/GenerateReachForecastRequest
-    request = client.get_type("GenerateReachForecastRequest")
+    request: Any = client.get_type("GenerateReachForecastRequest")
     request.customer_id = customer_id
     # Valid durations are between 1 and 90 days.
     request.campaign_duration.duration_in_days = 28
@@ -128,7 +133,7 @@ def request_reach_curve(
         client.enums.GenderTypeEnum.FEMALE,
         client.enums.GenderTypeEnum.MALE,
     ]:
-        gender = client.get_type("GenderInfo")
+        gender: Any = client.get_type("GenderInfo")
         gender.type_ = gender_type
         request.targeting.genders.append(gender)
 
@@ -138,19 +143,19 @@ def request_reach_curve(
         client.enums.DeviceEnum.MOBILE,
         client.enums.DeviceEnum.TABLET,
     ]:
-        device = client.get_type("DeviceInfo")
+        device: Any = client.get_type("DeviceInfo")
         device.type_ = device_type
         request.targeting.devices.append(device)
 
-    reach_plan_service = client.get_service("ReachPlanService")
-    response = reach_plan_service.generate_reach_forecast(request=request)
+    reach_plan_service: Any = client.get_service("ReachPlanService")
+    response: Any = reach_plan_service.generate_reach_forecast(request=request)
 
     print(
         "Currency, Cost, On-Target Reach, On-Target Imprs, Total Reach,"
         " Total Imprs, Products"
     )
     for point in response.reach_curve.reach_forecasts:
-        product_splits = []
+        product_splits: List[Dict[str, float]] = []
         for p in point.planned_product_reach_forecasts:
             product_splits.append(
                 {p.plannable_product_code: p.cost_micros / ONE_MILLION}
@@ -171,27 +176,30 @@ def request_reach_curve(
 
 # [START forecast_reach_3]
 def forecast_manual_mix(
-    client, customer_id, location_id, currency_code, budget
-):
+    client: GoogleAdsClient,
+    customer_id: str,
+    location_id: str,
+    currency_code: str,
+    budget: int,
+) -> None:
     """Pulls a forecast for product mix created manually.
 
     Args:
         client: an initialized GoogleAdsClient instance.
         customer_id: The customer ID for the reach forecast.
-        product_mix: The product mix for the reach forecast.
         location_id: The location ID to plan for.
         currency_code: Three-character ISO 4217 currency code.
         budget: Budget to allocate to the plan.
     """
-    product_mix = []
-    trueview_allocation = 0.15
-    bumper_allocation = 1 - trueview_allocation
-    product_splits = [
+    product_mix: List[Any] = []
+    trueview_allocation: float = 0.15
+    bumper_allocation: float = 1 - trueview_allocation
+    product_splits: List[Tuple[str, float]] = [
         ("TRUEVIEW_IN_STREAM", trueview_allocation),
         ("BUMPER", bumper_allocation),
     ]
     for product, split in product_splits:
-        planned_product = client.get_type("PlannedProduct")
+        planned_product: Any = client.get_type("PlannedProduct")
         planned_product.plannable_product_code = product
         planned_product.budget_micros = math.trunc(budget * ONE_MILLION * split)
         product_mix.append(planned_product)
@@ -218,7 +226,9 @@ def forecast_manual_mix(
 
     # GoogleAdsClient will read the google-ads.yaml configuration file in the
     # home directory if none is specified.
-    googleads_client = GoogleAdsClient.load_from_storage(version="v19")
+    googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage(
+        version="v19"
+    )
 
     try:
         main(googleads_client, args.customer_id)

examples/planning/generate_forecast_metrics.py

@@ -21,24 +21,25 @@
 import argparse
 from datetime import datetime, timedelta
 import sys
+from typing import Any
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
 
 
 # [START generate_forecast_metrics]
-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.
     """
-    campaign_to_forecast = create_campaign_to_forecast(client)
+    campaign_to_forecast: Any = create_campaign_to_forecast(client)
     generate_forecast_metrics(client, customer_id, campaign_to_forecast)
 
 
-def create_campaign_to_forecast(client):
+def create_campaign_to_forecast(client: GoogleAdsClient) -> Any:
     """Creates the campaign to forecast.
 
     A campaign to forecast lets you try out various configurations and keywords
@@ -53,9 +54,9 @@ def create_campaign_to_forecast(client):
     Returns:
         An CampaignToForecast instance.
     """
-    googleads_service = client.get_service("GoogleAdsService")
+    googleads_service: Any = client.get_service("GoogleAdsService")
     # Create a campaign to forecast.
-    campaign_to_forecast = client.get_type("CampaignToForecast")
+    campaign_to_forecast: Any = client.get_type("CampaignToForecast")
     campaign_to_forecast.keyword_plan_network = (
         client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH
     )
@@ -67,7 +68,7 @@ def create_campaign_to_forecast(client):
 
     # For the list of geo target IDs, see:
     # https://developers.google.com/google-ads/api/reference/data/geotargets
-    criterion_bid_modifier = client.get_type("CriterionBidModifier")
+    criterion_bid_modifier: Any = client.get_type("CriterionBidModifier")
     # Geo target constant 2840 is for USA.
     criterion_bid_modifier.geo_target_constant = (
         googleads_service.geo_target_constant_path("2840")
@@ -83,24 +84,24 @@ def create_campaign_to_forecast(client):
 
     # Create forecast ad groups based on themes such as creative relevance,
     # product category, or cost per click.
-    forecast_ad_group = client.get_type("ForecastAdGroup")
+    forecast_ad_group: Any = client.get_type("ForecastAdGroup")
 
     # Create and configure three BiddableKeyword instances.
-    biddable_keyword_1 = client.get_type("BiddableKeyword")
+    biddable_keyword_1: Any = client.get_type("BiddableKeyword")
     biddable_keyword_1.max_cpc_bid_micros = 2500000
     biddable_keyword_1.keyword.text = "mars cruise"
     biddable_keyword_1.keyword.match_type = (
         client.enums.KeywordMatchTypeEnum.BROAD
     )
 
-    biddable_keyword_2 = client.get_type("BiddableKeyword")
+    biddable_keyword_2: Any = client.get_type("BiddableKeyword")
     biddable_keyword_2.max_cpc_bid_micros = 1500000
     biddable_keyword_2.keyword.text = "cheap cruise"
     biddable_keyword_2.keyword.match_type = (
         client.enums.KeywordMatchTypeEnum.PHRASE
     )
 
-    biddable_keyword_3 = client.get_type("BiddableKeyword")
+    biddable_keyword_3: Any = client.get_type("BiddableKeyword")
     biddable_keyword_3.max_cpc_bid_micros = 1990000
     biddable_keyword_3.keyword.text = "cheap cruise"
     biddable_keyword_3.keyword.match_type = (
@@ -114,7 +115,7 @@ def create_campaign_to_forecast(client):
 
     # Create and configure a negative keyword, then add it to the forecast ad
     # group.
-    negative_keyword = client.get_type("KeywordInfo")
+    negative_keyword: Any = client.get_type("KeywordInfo")
     negative_keyword.text = "moon walk"
     negative_keyword.match_type = client.enums.KeywordMatchTypeEnum.BROAD
     forecast_ad_group.negative_keywords.append(negative_keyword)
@@ -124,32 +125,36 @@ def create_campaign_to_forecast(client):
     return campaign_to_forecast
 
 
-def generate_forecast_metrics(client, customer_id, campaign_to_forecast):
+def generate_forecast_metrics(
+    client: GoogleAdsClient, customer_id: str, campaign_to_forecast: Any
+) -> None:
     """Generates forecast metrics and prints the results.
 
     Args:
         client: an initialized GoogleAdsClient instance.
         customer_id: a client customer ID.
         campaign_to_forecast: a CampaignToForecast to generate metrics for.
     """
-    keyword_plan_idea_service = client.get_service("KeywordPlanIdeaService")
-    request = client.get_type("GenerateKeywordForecastMetricsRequest")
+    keyword_plan_idea_service: Any = client.get_service(
+        "KeywordPlanIdeaService"
+    )
+    request: Any = client.get_type("GenerateKeywordForecastMetricsRequest")
     request.customer_id = customer_id
     request.campaign = campaign_to_forecast
     # Set the forecast range. Repeat forecasts with different horizons to get a
     # holistic picture.
     # Set the forecast start date to tomorrow.
-    tomorrow = datetime.now() + timedelta(days=1)
+    tomorrow: datetime = datetime.now() + timedelta(days=1)
     request.forecast_period.start_date = tomorrow.strftime("%Y-%m-%d")
     # Set the forecast end date to 30 days from today.
-    thirty_days_from_now = datetime.now() + timedelta(days=30)
+    thirty_days_from_now: datetime = datetime.now() + timedelta(days=30)
     request.forecast_period.end_date = thirty_days_from_now.strftime("%Y-%m-%d")
 
-    response = keyword_plan_idea_service.generate_keyword_forecast_metrics(
+    response: Any = keyword_plan_idea_service.generate_keyword_forecast_metrics(
         request=request
     )
 
-    metrics = response.campaign_forecast_metrics
+    metrics: Any = response.campaign_forecast_metrics
     print(f"Estimated daily clicks: {metrics.clicks}")
     print(f"Estimated daily impressions: {metrics.impressions}")
     print(f"Estimated daily average CPC: {metrics.average_cpc_micros}")
@@ -169,11 +174,13 @@ def generate_forecast_metrics(client, customer_id, campaign_to_forecast):
         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="v19")
+    googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage(
+        version="v19"
+    )
 
     try:
         main(googleads_client, args.customer_id)

examples/planning/generate_historical_metrics.py

@@ -20,13 +20,14 @@
 
 import argparse
 import sys
+from typing import Any
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
 
 
 # [START generate_historical_metrics]
-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:
@@ -36,16 +37,16 @@ def main(client, customer_id):
     generate_historical_metrics(client, customer_id)
 
 
-def generate_historical_metrics(client, customer_id):
+def generate_historical_metrics(client: GoogleAdsClient, customer_id: str) -> None:
     """Generates historical metrics and prints the results.
 
     Args:
         client: an initialized GoogleAdsClient instance.
         customer_id: a client customer ID.
     """
-    googleads_service = client.get_service("GoogleAdsService")
-    keyword_plan_idea_service = client.get_service("KeywordPlanIdeaService")
-    request = client.get_type("GenerateKeywordHistoricalMetricsRequest")
+    googleads_service: Any = client.get_service("GoogleAdsService")
+    keyword_plan_idea_service: Any = client.get_service("KeywordPlanIdeaService")
+    request: Any = client.get_type("GenerateKeywordHistoricalMetricsRequest")
     request.customer_id = customer_id
     request.keywords = ["mars cruise", "cheap cruise", "jupiter cruise"]
     # Geo target constant 2840 is for USA.
@@ -60,12 +61,12 @@ def generate_historical_metrics(client, customer_id):
     # https://developers.google.com/google-ads/api/reference/data/codes-formats#languages
     request.language = googleads_service.language_constant_path("1000")
 
-    response = keyword_plan_idea_service.generate_keyword_historical_metrics(
+    response: Any = keyword_plan_idea_service.generate_keyword_historical_metrics(
         request=request
     )
 
     for result in response.results:
-        metrics = result.keyword_metrics
+        metrics: Any = result.keyword_metrics
         # These metrics include those for both the search query and any variants
         # included in the response.
         print(
@@ -123,11 +124,13 @@ def generate_historical_metrics(client, customer_id):
         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="v19")
+    googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage(
+        version="v19"
+    )
 
     try:
         main(googleads_client, args.customer_id)