feat: Add type hints and annotations to audience_insights example

This commit introduces type hints for function arguments, return values,
and local variables in `examples/audience_insights/generate_audience_insights.py`.

Key changes include:
- Added type hints to all function signatures and return types.
- Added inline type hints for variables within functions.
- Imported necessary types from `typing`, Google Ads client libraries,
  services, enums, and types modules.
- Ensured proper organization and removal of unused or duplicate imports.
- Updated some variable assignments to use specific Enum members for clarity
  (e.g., `AudienceInsightsDimensionEnum`).
- Replaced some string formatting with f-strings in exception handling.

These changes improve code readability, maintainability, and help with
static analysis, making your example code more robust and easier to understand.

Author: google-labs-jules[bot]

examples/audience_insights/generate_audience_insights.py

@@ -14,28 +14,54 @@
 # limitations under the License.
 """This example illustrates how to generate audience insights."""
 
-import argparse
 import argparse
 import sys
+from typing import Any
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v19.enums.types import (
+    AudienceInsightsDimensionEnum,
+)
+from google.ads.googleads.v19.services.services.audience_insights_service import (
+    AudienceInsightsServiceClient,
+)
+from google.ads.googleads.v19.services.services.google_ads_service import (
+    GoogleAdsServiceClient,
+)
+from google.ads.googleads.v19.types.audience_insights_service import (
+    AudienceInsightsAttribute,
+    GenerateAudienceCompositionInsightsRequest,
+    GenerateAudienceCompositionInsightsResponse,
+    GenerateSuggestedTargetingInsightsRequest,
+    GenerateSuggestedTargetingInsightsResponse,
+    InsightsAudienceAttributeGroup,
+    ListAudienceInsightsAttributesRequest,
+    ListAudienceInsightsAttributesResponse,
+)
+from google.ads.googleads.v19.types.common import LocationInfo
 
 
-def main(client, customer_id, custom_name):
+def main(
+    client: GoogleAdsClient, customer_id: str, custom_name: 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.
         custom_name: custom name to define audience.
     """
-    location_id = "2840"  # US
-    product_name = "Google"
-    user_interest_category = "92948"  # Technology
+    location_id: str = "2840"  # US
+    product_name: str = "Google"
+    user_interest_category: str = "92948"  # Technology
     # Initialize appropriate services.
-    audience_insights_service = client.get_service("AudienceInsightsService")
-    googleads_service = client.get_service("GoogleAdsService")
+    audience_insights_service: AudienceInsightsServiceClient = client.get_service(
+        "AudienceInsightsService"
+    )
+    googleads_service: GoogleAdsServiceClient = client.get_service(
+        "GoogleAdsService"
+    )
 
     audience_composition_insights(
         client,
@@ -44,35 +70,35 @@ def main(client, customer_id, custom_name):
         customer_id,
         location_id,
         user_interest_category,
-        custom_name
+        custom_name,
     )
     generate_suggested_targeting_insights(
         client,
         audience_insights_service,
         googleads_service,
         customer_id,
         location_id,
-        custom_name
+        custom_name,
     )
     list_audience_insights_attributes(
         client,
         audience_insights_service,
         customer_id,
         product_name,
-        custom_name
+        custom_name,
     )
 
 
 # [START composition_insights]
 def audience_composition_insights(
-    client,
-    audience_insights_service,
-    googleads_service,
-    customer_id,
-    location_id,
-    user_interest,
-    custom_name
-):
+    client: GoogleAdsClient,
+    audience_insights_service: AudienceInsightsServiceClient,
+    googleads_service: GoogleAdsServiceClient,
+    customer_id: str,
+    location_id: str,
+    user_interest: str,
+    custom_name: str,
+) -> None:
     """Returns a collection of attributes represented in an audience of interest.
 
         Please refere here for more:
@@ -88,46 +114,54 @@ def audience_composition_insights(
         user_interest: The criterion ID of the category.
         custom_name: custom defined name.
     """
-    request = client.get_type("GenerateAudienceCompositionInsightsRequest")
+    request: GenerateAudienceCompositionInsightsRequest = client.get_type(
+        "GenerateAudienceCompositionInsightsRequest"
+    )
     request.customer_id = customer_id
 
-    insights_info = client.get_type("InsightsAudienceAttributeGroup")
-    attributes = client.get_type("AudienceInsightsAttribute")
-    attributes.user_interest.user_interest_category = googleads_service.user_interest_path(
-        customer_id, user_interest
+    insights_info: InsightsAudienceAttributeGroup = client.get_type(
+        "InsightsAudienceAttributeGroup"
+    )
+    attributes: AudienceInsightsAttribute = client.get_type(
+        "AudienceInsightsAttribute"
+    )
+    attributes.user_interest.user_interest_category = (
+        googleads_service.user_interest_path(customer_id, user_interest)
     )
 
     insights_info.attributes.append(attributes)
     request.audience.topic_audience_combinations.append(insights_info)
 
-    location_info = client.get_type("LocationInfo")
+    location_info: LocationInfo = client.get_type("LocationInfo")
     location_info.geo_target_constant = (
         googleads_service.geo_target_constant_path(location_id)
     )
     request.audience.country_locations.append(location_info)
 
     request.customer_insights_group = custom_name
-    request.dimensions = (
-        "AFFINITY_USER_INTEREST",
-        "IN_MARKET_USER_INTEREST",
-        "YOUTUBE_CHANNEL",
-    )
-    response = audience_insights_service.generate_audience_composition_insights(
-        request=request
+    request.dimensions = [
+        client.enums.AudienceInsightsDimensionEnum.AFFINITY_USER_INTEREST,
+        client.enums.AudienceInsightsDimensionEnum.IN_MARKET_USER_INTEREST,
+        client.enums.AudienceInsightsDimensionEnum.YOUTUBE_CHANNEL,
+    ]
+    response: GenerateAudienceCompositionInsightsResponse = (
+        audience_insights_service.generate_audience_composition_insights(
+            request=request
+        )
     )
     print(response)
     # [END composition_insights]
 
 
 # [START targeted_insights]
 def generate_suggested_targeting_insights(
-    client,
-    audience_insights_service,
-    googleads_service,
-    customer_id,
-    location_id,
-    custom_name
-):
+    client: GoogleAdsClient,
+    audience_insights_service: AudienceInsightsServiceClient,
+    googleads_service: GoogleAdsServiceClient,
+    customer_id: str,
+    location_id: str,
+    custom_name: str,
+) -> None:
     """Returns a collection of targeting insights (e.g.targetable audiences)
         that are relevant to the requested audience.
 
@@ -140,30 +174,38 @@ def generate_suggested_targeting_insights(
         location_id: The location ID for the audience of interest.
         custom_name: custom defined name.
     """
-    request = client.get_type("GenerateSuggestedTargetingInsightsRequest")
+    request: GenerateSuggestedTargetingInsightsRequest = client.get_type(
+        "GenerateSuggestedTargetingInsightsRequest"
+    )
 
     request.customer_id = customer_id
     request.customer_insights_group = custom_name
 
-    audience_definition = request.audience_definition
-    location_info = client.get_type("LocationInfo")
+    audience_definition: Any = request.audience_definition
+    location_info: LocationInfo = client.get_type("LocationInfo")
     location_info.geo_target_constant = (
         googleads_service.geo_target_constant_path(location_id)
     )
     audience_definition.audience.country_locations.append(location_info)
 
     request.audience_definition = audience_definition
-    response = audience_insights_service.generate_suggested_targeting_insights(
-        request=request
+    response: GenerateSuggestedTargetingInsightsResponse = (
+        audience_insights_service.generate_suggested_targeting_insights(
+            request=request
+        )
     )
     print(response)
     # [END targeted_insights]
 
 
 # [START insights_attributes]
 def list_audience_insights_attributes(
-    client, audience_insights_service, customer_id, product_name, custom_name
-):
+    client: GoogleAdsClient,
+    audience_insights_service: AudienceInsightsServiceClient,
+    customer_id: str,
+    product_name: str,
+    custom_name: str,
+) -> None:
     """Searches for audience attributes that can be used to generate insights.
 
     Args:
@@ -174,25 +216,38 @@ def list_audience_insights_attributes(
         product_name: The brand/product for which insights are expected.
         custom_name: custom defined name.
     """
-    request = client.get_type("ListAudienceInsightsAttributesRequest")
+    request: ListAudienceInsightsAttributesRequest = client.get_type(
+        "ListAudienceInsightsAttributesRequest"
+    )
 
     request.customer_id = customer_id
     request.query_text = product_name
-    category_dimension = client.enums.AudienceInsightsDimensionEnum.CATEGORY
-    kg_dimension = client.enums.AudienceInsightsDimensionEnum.KNOWLEDGE_GRAPH
+    category_dimension: AudienceInsightsDimensionEnum.AudienceInsightsDimension = (
+        client.enums.AudienceInsightsDimensionEnum.CATEGORY
+    )
+    kg_dimension: AudienceInsightsDimensionEnum.AudienceInsightsDimension = (
+        client.enums.AudienceInsightsDimensionEnum.KNOWLEDGE_GRAPH
+    )
     request.dimensions = [category_dimension, kg_dimension]
     request.customer_insights_group = custom_name
-    response = audience_insights_service.list_audience_insights_attributes(
-        request=request
+    response: ListAudienceInsightsAttributesResponse = (
+        audience_insights_service.list_audience_insights_attributes(
+            request=request
+        )
     )
     for attribute in response.attributes:
-        if attribute.dimension == 3:
+        if (
+            attribute.dimension
+            == client.enums.AudienceInsightsDimensionEnum.KNOWLEDGE_GRAPH
+        ):
             print(attribute.attribute.entity.knowledge_graph_machine_id)
             # [END insights_attributes]
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Create audience insights.")
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
+        description="Create audience insights."
+    )
 
     # The following argument(s) should be provided to run the example.
     parser.add_argument(
@@ -211,24 +266,26 @@ def list_audience_insights_attributes(
         help="Custom name to indentify audiences",
     )
     parser.add_argument
-    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, args.custom_name)
     except GoogleAdsException as ex:
         print(
-            'Request with ID "{}" failed with status "%s" and includes the '
-            "following errors:".format(ex.request_id, ex.error.code().name)
+            f'Request with ID "{ex.request_id}" failed with status '
+            f'"{ex.error.code().name}" and includes the following errors:'
         )
         for error in ex.failure.errors:
-            print('\tError with message "{}".'.format(error.message))
+            print(f'\tError with message "{error.message}".')
             if error.location:
                 for field_path_element in error.location.field_path_elements:
                     print(
-                        "\t\tOn field: {}".format(field_path_element.field_name)
+                        f"\t\tOn field: {field_path_element.field_name}"
                     )
         sys.exit(1)