Fix: Correct enum import paths in examples/planning files

This change corrects the import paths for enums in the Python files under the `examples/planning/` directory. The previous import paths were incorrect, and this commit fixes them to use the `google.ads.googleads.v20.enums.types` path.

The following files were modified:
- `examples/planning/forecast_reach.py`
- `examples/planning/generate_forecast_metrics.py`
- `examples/planning/generate_historical_metrics.py`
- `examples/planning/generate_keyword_ideas.py`

Author: google-labs-jules[bot]

examples/planning/forecast_reach.py

@@ -20,11 +20,34 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.enums.types.reach_plan_age_range import (
+    ReachPlanAgeRangeEnum,
+)
+from google.ads.googleads.v20.enums.types.gender_type import GenderTypeEnum
+from google.ads.googleads.v20.enums.types.device import DeviceEnum
+from google.ads.googleads.v20.common.types.criteria import (
+    GenderInfo,
+    DeviceInfo,
+)
+from google.ads.googleads.v20.services.services.reach_plan_service.client import (
+    ReachPlanServiceClient,
+)
+from google.ads.googleads.v20.services.types.reach_plan_service import (
+    ListPlannableLocationsResponse,
+    PlannableLocation,
+    ListPlannableProductsResponse,
+    ProductMetadata,
+    GenerateReachForecastRequest,
+    GenerateReachForecastResponse,
+    ReachForecast,
+    PlannedProductReachForecast,
+    PlannedProduct,
+)
 
 ONE_MILLION = 1.0e6
 
 
-def main(client, customer_id):
+def main(client: GoogleAdsClient, customer_id: str):
     """The main method that creates all necessary entities for the example.
 
     Args:
@@ -43,60 +66,77 @@ def main(client, customer_id):
     forecast_manual_mix(client, customer_id, location_id, currency_code, budget)
 
 
-def show_plannable_locations(client):
+def show_plannable_locations(client: GoogleAdsClient):
     """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: ReachPlanServiceClient = client.get_service(
+        "ReachPlanService"
+    )
+    response: ListPlannableLocationsResponse = (
+        reach_plan_service.list_plannable_locations()
+    )
 
     print("Plannable Locations")
     print("Name,\tId,\tParentCountryId")
+    location: PlannableLocation
     for location in response.plannable_locations:
         print(
             f"'{location.name}',\t{location.id},\t{location.parent_country_id}"
         )
 
 
 # [START forecast_reach_2]
-def show_plannable_products(client, location_id):
+def show_plannable_products(client: GoogleAdsClient, location_id: str):
     """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(
-        plannable_location_id=location_id
+    reach_plan_service: ReachPlanServiceClient = client.get_service(
+        "ReachPlanService"
+    )
+    response: ListPlannableProductsResponse = (
+        reach_plan_service.list_plannable_products(
+            plannable_location_id=location_id
+        )
     )
     print(f"Plannable Products for Location ID {location_id}")
 
+    product_metadata: ProductMetadata
     for product_metadata in response.product_metadata:
         print(
             f"{product_metadata.plannable_product_code} : "
             f"{product_metadata.plannable_product_name}"
         )
 
         print("Age Ranges:")
+        age_range: ReachPlanAgeRangeEnum
         for age_range in product_metadata.plannable_targeting.age_ranges:
             print(f"\t- {age_range.name}")
 
         print("Genders:")
+        gender: GenderInfo
         for gender in product_metadata.plannable_targeting.genders:
             print(f"\t- {gender.type_.name}")
 
         print("Devices:")
+        device: DeviceInfo
         for device in product_metadata.plannable_targeting.devices:
             print(f"\t- {device.type_.name}")
         # [END forecast_reach_2]
 
 
 # [START forecast_reach]
 def request_reach_curve(
-    client, customer_id, product_mix, location_id, currency_code
+    client: GoogleAdsClient,
+    customer_id: str,
+    product_mix: list[PlannedProduct],
+    location_id: str,
+    currency_code: str,
 ):
     """Creates a sample request for a given product mix.
 
@@ -109,7 +149,9 @@ 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: GenerateReachForecastRequest = client.get_type(
+        "GenerateReachForecastRequest"
+    )
     request.customer_id = customer_id
     # Valid durations are between 1 and 90 days.
     request.campaign_duration.duration_in_days = 28
@@ -124,33 +166,41 @@ def request_reach_curve(
     )
 
     # Add gender targeting to the request.
+    gender_type: GenderTypeEnum
     for gender_type in [
         client.enums.GenderTypeEnum.FEMALE,
         client.enums.GenderTypeEnum.MALE,
     ]:
-        gender = client.get_type("GenderInfo")
+        gender: GenderInfo = client.get_type("GenderInfo")
         gender.type_ = gender_type
         request.targeting.genders.append(gender)
 
     # Add device targeting to the request.
+    device_type: DeviceEnum
     for device_type in [
         client.enums.DeviceEnum.DESKTOP,
         client.enums.DeviceEnum.MOBILE,
         client.enums.DeviceEnum.TABLET,
     ]:
-        device = client.get_type("DeviceInfo")
+        device: DeviceInfo = 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: ReachPlanServiceClient = client.get_service(
+        "ReachPlanService"
+    )
+    response: GenerateReachForecastResponse = (
+        reach_plan_service.generate_reach_forecast(request=request)
+    )
 
     print(
         "Currency, Cost, On-Target Reach, On-Target Imprs, Total Reach,"
         " Total Imprs, Products"
     )
+    point: ReachForecast
     for point in response.reach_curve.reach_forecasts:
         product_splits = []
+        p: PlannedProductReachForecast
         for p in point.planned_product_reach_forecasts:
             product_splits.append(
                 {p.plannable_product_code: p.cost_micros / ONE_MILLION}
@@ -171,27 +221,32 @@ 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,
 ):
     """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 = []
+    product_mix: list[PlannedProduct] = []
     trueview_allocation = 0.15
     bumper_allocation = 1 - trueview_allocation
     product_splits = [
         ("TRUEVIEW_IN_STREAM", trueview_allocation),
         ("BUMPER", bumper_allocation),
     ]
+    product: str
+    split: float
     for product, split in product_splits:
-        planned_product = client.get_type("PlannedProduct")
+        planned_product: PlannedProduct = 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)

examples/planning/generate_forecast_metrics.py

@@ -24,21 +24,44 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.enums.types.keyword_plan_network import (
+    KeywordPlanNetworkEnum,
+)
+from google.ads.googleads.v20.enums.types.keyword_match_type import (
+    KeywordMatchTypeEnum,
+)
+from google.ads.googleads.v20.services.services.google_ads_service.client import (
+    GoogleAdsServiceClient,
+)
+from google.ads.googleads.v20.services.services.keyword_plan_idea_service.client import (
+    KeywordPlanIdeaServiceClient,
+)
+from google.ads.googleads.v20.services.types.keyword_plan_idea_service import (
+    CampaignToForecast,
+    CriterionBidModifier,
+    ForecastAdGroup,
+    BiddableKeyword,
+    KeywordInfo,
+    GenerateKeywordForecastMetricsRequest,
+    GenerateKeywordForecastMetricsResponse,
+)
 
 
 # [START generate_forecast_metrics]
-def main(client, customer_id):
+def main(client: GoogleAdsClient, customer_id: str):
     """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: CampaignToForecast = 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) -> CampaignToForecast:
     """Creates the campaign to forecast.
 
     A campaign to forecast lets you try out various configurations and keywords
@@ -53,9 +76,13 @@ def create_campaign_to_forecast(client):
     Returns:
         An CampaignToForecast instance.
     """
-    googleads_service = client.get_service("GoogleAdsService")
+    googleads_service: GoogleAdsServiceClient = client.get_service(
+        "GoogleAdsService"
+    )
     # Create a campaign to forecast.
-    campaign_to_forecast = client.get_type("CampaignToForecast")
+    campaign_to_forecast: CampaignToForecast = client.get_type(
+        "CampaignToForecast"
+    )
     campaign_to_forecast.keyword_plan_network = (
         client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH
     )
@@ -67,7 +94,9 @@ 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: CriterionBidModifier = 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 +112,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: ForecastAdGroup = client.get_type("ForecastAdGroup")
 
     # Create and configure three BiddableKeyword instances.
-    biddable_keyword_1 = client.get_type("BiddableKeyword")
+    biddable_keyword_1: BiddableKeyword = 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: BiddableKeyword = 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: BiddableKeyword = 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 +143,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: KeywordInfo = 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,16 +153,24 @@ 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: CampaignToForecast,
+):
     """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: KeywordPlanIdeaServiceClient = client.get_service(
+        "KeywordPlanIdeaService"
+    )
+    request: GenerateKeywordForecastMetricsRequest = 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
@@ -145,8 +182,10 @@ def generate_forecast_metrics(client, customer_id, campaign_to_forecast):
     thirty_days_from_now = 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(
-        request=request
+    response: GenerateKeywordForecastMetricsResponse = (
+        keyword_plan_idea_service.generate_keyword_forecast_metrics(
+            request=request
+        )
     )
 
     metrics = response.campaign_forecast_metrics