Add annotations to examples/recommendations (#949)

Author: bobhancockg

examples/recommendations/detect_and_apply_recommendations.py

@@ -31,12 +31,20 @@
 
 import argparse
 import sys
+from typing import List, Iterable
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.services.types.google_ads_service import (
+    GoogleAdsRow,
+)
+from google.ads.googleads.v20.services.types.recommendation_service import (
+    ApplyRecommendationOperation,
+    ApplyRecommendationResult,
+)
 
 
-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:
@@ -46,7 +54,9 @@ def main(client, customer_id):
     detect_and_apply_recommendations(client, customer_id)
 
 
-def detect_and_apply_recommendations(client, customer_id):
+def detect_and_apply_recommendations(
+    client: GoogleAdsClient, customer_id: str
+) -> None:
     """Detects recommendations and applies them.
 
     Args:
@@ -56,7 +66,7 @@ def detect_and_apply_recommendations(client, customer_id):
 
     # [START detect_keyword_recommendations]
     googleads_service = client.get_service("GoogleAdsService")
-    query = f"""
+    query: str = f"""
         SELECT
           recommendation.campaign,
           recommendation.keyword_recommendation
@@ -65,10 +75,12 @@ def detect_and_apply_recommendations(client, customer_id):
           recommendation.type = KEYWORD"""
 
     # Detects keyword recommendations that exist for the customer account.
-    response = googleads_service.search(customer_id=customer_id, query=query)
+    response: Iterable[GoogleAdsRow] = googleads_service.search(
+        customer_id=customer_id, query=query
+    )
 
-    operations = []
-    for row in response.results:
+    operations: List[ApplyRecommendationOperation] = []
+    for row in response:
         recommendation = row.recommendation
         print(
             f"Keyword recommendation ('{recommendation.resource_name}') "
@@ -94,12 +106,13 @@ def detect_and_apply_recommendations(client, customer_id):
 
 
 # [START build_apply_recommendation_operation]
-def build_recommendation_operation(client, recommendation):
+def build_recommendation_operation(
+    client: GoogleAdsClient, recommendation: str
+) -> ApplyRecommendationOperation:
     """Creates a ApplyRecommendationOperation to apply the given recommendation.
 
     Args:
         client: an initialized GoogleAdsClient instance.
-        customer_id: a client customer ID.
         recommendation: a resource name for the recommendation to be applied.
     """
     # If you have a recommendation ID instead of a resource name, you can create
@@ -110,7 +123,9 @@ def build_recommendation_operation(client, recommendation):
     #   customer_id, recommendation.id
     # )
 
-    operation = client.get_type("ApplyRecommendationOperation")
+    operation: ApplyRecommendationOperation = client.get_type(
+        "ApplyRecommendationOperation"
+    )
 
     # Each recommendation type has optional parameters to override the
     # recommended values. Below is an example showing how to override a
@@ -127,7 +142,11 @@ def build_recommendation_operation(client, recommendation):
 
 
 # [START apply_recommendation]
-def apply_recommendations(client, customer_id, operations):
+def apply_recommendations(
+    client: GoogleAdsClient,
+    customer_id: str,
+    operations: List[ApplyRecommendationOperation],
+) -> None:
     """Applies a batch of recommendations.
 
     Args:
@@ -137,20 +156,22 @@ def apply_recommendations(client, customer_id, operations):
     """
     # Issues a mutate request to apply the recommendations.
     recommendation_service = client.get_service("RecommendationService")
-    response = recommendation_service.apply_recommendation(
-        customer_id=customer_id, operations=operations
+    response: ApplyRecommendationResult = (
+        recommendation_service.apply_recommendation(
+            customer_id=customer_id, operations=operations
+        )
     )
 
     for result in response.results:
         print(
             "Applied a recommendation with resource name: "
-            f"'{result[0].resource_name}'."
+            f"'{result.resource_name}'."
         )
         # [END apply_recommendation]
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
         description=(
             "Retrieves keyword recommendations for specified customer and "
             "applies them."
@@ -164,11 +185,13 @@ def apply_recommendations(client, customer_id, operations):
         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(googleads_client, args.customer_id)

examples/recommendations/dismiss_recommendation.py

@@ -23,19 +23,34 @@
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
+from google.ads.googleads.v20.services.services.recommendation_service import (
+    RecommendationServiceClient,
+)
+from google.ads.googleads.v20.services.types.recommendation_service import (
+    DismissRecommendationRequest,
+    DismissRecommendationResponse,
+)
 
 
-def main(client, customer_id, recommendation_id):
-    recommendation_service = client.get_service("RecommendationService")
-    request = client.get_type("DismissRecommendationRequest")
+def main(
+    client: GoogleAdsClient, customer_id: str, recommendation_id: str
+) -> None:
+    recommendation_service: RecommendationServiceClient = client.get_service(
+        "RecommendationService"
+    )
+    request: DismissRecommendationRequest = client.get_type(
+        "DismissRecommendationRequest"
+    )
     operation = request.DismissRecommendationOperation()
     operation.resource_name = recommendation_service.recommendation_path(
         customer_id, recommendation_id
     )
     request.customer_id = customer_id
     request.operations.append(operation)
 
-    response = recommendation_service.dismiss_recommendation(request=request)
+    response: DismissRecommendationResponse = (
+        recommendation_service.dismiss_recommendation(request=request)
+    )
 
     print(
         "Dismissed recommendation with resource name: "
@@ -44,7 +59,7 @@ def main(client, customer_id, recommendation_id):
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
         description=("Dismisses a recommendation with the given ID.")
     )
     # The following argument(s) should be provided to run the example.
@@ -62,11 +77,13 @@ def main(client, customer_id, recommendation_id):
         required=True,
         help="The recommendation 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.recommendation_id)

examples/recommendations/generate_budget_recommendations.py

@@ -27,20 +27,35 @@
 
 import argparse
 import sys
+from typing import List, Dict, Any
 
 from google.ads.googleads.client import GoogleAdsClient
 from google.ads.googleads.errors import GoogleAdsException
-
-
-def main(client, customer_id):
+from google.ads.googleads.v20.services.services.recommendation_service import (
+    RecommendationServiceClient,
+)
+from google.ads.googleads.v20.services.types.recommendation_service import (
+    GenerateRecommendationsRequest,
+    GenerateRecommendationsResponse,
+)
+from google.ads.googleads.v20.resources.types.recommendation import (
+    Recommendation,
+)
+
+
+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.
     """
-    recommendation_service = client.get_service("RecommendationService")
-    request = client.get_type("GenerateRecommendationsRequest")
+    recommendation_service: RecommendationServiceClient = client.get_service(
+        "RecommendationService"
+    )
+    request: GenerateRecommendationsRequest = client.get_type(
+        "GenerateRecommendationsRequest"
+    )
 
     request.customer_id = customer_id
     request.recommendation_types = ["CAMPAIGN_BUDGET"]
@@ -51,14 +66,16 @@ def main(client, customer_id):
     request.positive_locations_ids = [2840]  # 2840 is for United States
     request.asset_group_info = [{"final_url": "https://www.your-company.com/"}]
 
-    results = recommendation_service.generate_recommendations(request)
+    results: GenerateRecommendationsResponse = (
+        recommendation_service.generate_recommendations(request)
+    )
 
-    recommendations = results.recommendations
+    recommendations: List[Recommendation] = results.recommendations
 
     # Initialize a list to store all budget recommendations with impact metrics.
-    budget_recommendations_list = []
+    budget_recommendations_list: List[Dict[str, Any]] = []
     # Initialize a list to store budget recommendation amounts.
-    budget_amounts = []
+    budget_amounts: List[float] = []
 
     # Get budget recommendations with their associated impact metrics.
     for rec in recommendations:
@@ -70,14 +87,16 @@ def main(client, customer_id):
         # budget amount best aligns with their goals.
         for budget_option in campaign_budget_rec.budget_options:
             impact = budget_option.impact
-            budget_amount = budget_option.budget_amount_micros
-            if budget_amount > 0:
-                budget_data = {
-                    "budget_amount": round((budget_amount / 1000000), 2),
+            budget_amount_micros = budget_option.budget_amount_micros
+            if budget_amount_micros > 0:
+                budget_data: Dict[str, Any] = {
+                    "budget_amount": round((budget_amount_micros / 1000000), 2),
                     "potential_metrics": impact.potential_metrics,
                 }
                 budget_recommendations_list.append(budget_data)
-                budget_amounts.append(round((budget_amount / 1000000), 2))
+                budget_amounts.append(
+                    round((budget_amount_micros / 1000000), 2)
+                )
 
     print(f"budget_recommendations_list:\n{budget_recommendations_list}")
     """
@@ -96,7 +115,7 @@ def main(client, customer_id):
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
         description=(
             "Generate budget recommendations for a Performance Max campaign."
         )
@@ -110,11 +129,13 @@ def main(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="v20")
+    googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage(
+        version="v20"
+    )
 
     try:
         main(googleads_client, args.customer_id)