Google provider docstring improvements (apache#31731)

airflow/providers/google/ads/hooks/ads.py

@@ -36,14 +36,13 @@
 
 
 class GoogleAdsHook(BaseHook):
-    """
-    Hook for the Google Ads API.
+    """Interact with Google Ads API.
 
     This hook requires two connections:
 
-        - gcp_conn_id - provides service account details (like any other GCP connection)
-        - google_ads_conn_id - which contains information from Google Ads config.yaml file
-          in the ``extras``. Example of the ``extras``:
+    - gcp_conn_id - provides service account details (like any other GCP connection)
+    - google_ads_conn_id - which contains information from Google Ads config.yaml file
+        in the ``extras``. Example of the ``extras``:
 
         .. code-block:: json
 
@@ -69,8 +68,6 @@ class GoogleAdsHook(BaseHook):
     :param gcp_conn_id: The connection ID with the service account details.
     :param google_ads_conn_id: The connection ID with the details of Google Ads config.yaml file.
     :param api_version: The Google Ads API version to use.
-
-    :return: list of Google Ads Row object(s)
     """
 
     default_api_version = "v14"
@@ -90,10 +87,10 @@ def __init__(
     def search(
         self, client_ids: list[str], query: str, page_size: int = 10000, **kwargs
     ) -> list[GoogleAdsRow]:
-        """
-        Pulls data from the Google Ads API and returns it as native protobuf
-        message instances (those seen in versions prior to 10.0.0 of the
-        google-ads library).
+        """Pull data from the Google Ads API.
+
+        Native protobuf message instances are returned (those seen in versions
+        prior to 10.0.0 of the google-ads library).
 
         This method is for backwards compatibility with older versions of the
         google_ads_hook.
@@ -105,7 +102,7 @@ def search(
         :param client_ids: Google Ads client ID(s) to query the API for.
         :param query: Google Ads Query Language query.
         :param page_size: Number of results to return per page. Max 10000.
-        :return: Google Ads API response, converted to Google Ads Row objects
+        :return: Google Ads API response, converted to Google Ads Row objects.
         """
         data_proto_plus = self._search(client_ids, query, page_size, **kwargs)
         data_native_pb = [row._pb for row in data_proto_plus]
@@ -115,9 +112,10 @@ def search(
     def search_proto_plus(
         self, client_ids: list[str], query: str, page_size: int = 10000, **kwargs
     ) -> list[GoogleAdsRow]:
-        """
-        Pulls data from the Google Ads API and returns it as proto-plus-python
-        message instances that behave more like conventional python objects.
+        """Pull data from the Google Ads API.
+
+        Instances of proto-plus-python message are returned, which behave more
+        like conventional Python objects.
 
         :param client_ids: Google Ads client ID(s) to query the API for.
         :param query: Google Ads Query Language query.
@@ -127,12 +125,14 @@ def search_proto_plus(
         return self._search(client_ids, query, page_size, **kwargs)
 
     def list_accessible_customers(self) -> list[str]:
-        """
-        Returns resource names of customers directly accessible by the user authenticating the call.
-        The resulting list of customers is based on your OAuth credentials. The request returns a list
-        of all accounts that you are able to act upon directly given your current credentials. This will
-        not necessarily include all accounts within the account hierarchy; rather, it will only include
-        accounts where your authenticated user has been added with admin or other rights in the account.
+        """List resource names of customers.
+
+        The resulting list of customers is based on your OAuth credentials. The
+        request returns a list of all accounts that you are able to act upon
+        directly given your current credentials. This will not necessarily
+        include all accounts within the account hierarchy; rather, it will only
+        include accounts where your authenticated user has been added with admin
+        or other rights in the account.
 
         ..seealso::
             https://developers.google.com/google-ads/api/reference/rpc
@@ -152,7 +152,7 @@ def list_accessible_customers(self) -> list[str]:
 
     @cached_property
     def _get_service(self) -> GoogleAdsServiceClient:
-        """Connects and authenticates with the Google Ads API using a service account."""
+        """Connect and authenticate with the Google Ads API using a service account."""
         client = self._get_client
         return client.get_service("GoogleAdsService", version=self.api_version)
 
@@ -170,7 +170,7 @@ def _get_client(self) -> GoogleAdsClient:
 
     @cached_property
     def _get_customer_service(self) -> CustomerServiceClient:
-        """Connects and authenticates with the Google Ads API using a service account."""
+        """Connect and authenticate with the Google Ads API using a service account."""
         with NamedTemporaryFile("w", suffix=".json") as secrets_temp:
             self._get_config()
             self._update_config_with_secret(secrets_temp)
@@ -182,9 +182,10 @@ def _get_customer_service(self) -> CustomerServiceClient:
                 raise
 
     def _get_config(self) -> None:
-        """
-        Gets google ads connection from meta db and sets google_ads_config attribute with returned config
-        file.
+        """Set up Google Ads config from Connection.
+
+        This pulls the connections from db, and uses it to set up
+        ``google_ads_config``.
         """
         conn = self.get_connection(self.google_ads_conn_id)
         if "google_ads_client" not in conn.extra_dejson:
@@ -193,10 +194,11 @@ def _get_config(self) -> None:
         self.google_ads_config = conn.extra_dejson["google_ads_client"]
 
     def _update_config_with_secret(self, secrets_temp: IO[str]) -> None:
-        """
-        Gets Google Cloud secret from connection and saves the contents to the temp file
-        Updates google ads config with file path of the temp file containing the secret
-        Note, the secret must be passed as a file path for Google Ads API.
+        """Set up Google Cloud config secret from Connection.
+
+        This pulls the connection, saves the contents to a temp file, and point
+        the config to the path containing the secret. Note that the secret must
+        be passed as a file path for Google Ads API.
         """
         extras = self.get_connection(self.gcp_conn_id).extra_dejson
         secret = get_field(extras, "keyfile_dict")
@@ -210,8 +212,7 @@ def _update_config_with_secret(self, secrets_temp: IO[str]) -> None:
     def _search(
         self, client_ids: list[str], query: str, page_size: int = 10000, **kwargs
     ) -> list[GoogleAdsRow]:
-        """
-        Pulls data from the Google Ads API.
+        """Pull data from the Google Ads API.
 
         :param client_ids: Google Ads client ID(s) to query the API for.
         :param query: Google Ads Query Language query.
@@ -231,11 +232,9 @@ def _search(
         return self._extract_rows(iterators)
 
     def _extract_rows(self, iterators: list[GRPCIterator]) -> list[GoogleAdsRow]:
-        """
-        Convert Google Page Iterator (GRPCIterator) objects to Google Ads Rows.
+        """Convert Google Page Iterator (GRPCIterator) objects to Google Ads Rows.
 
         :param iterators: List of Google Page Iterator (GRPCIterator) objects
-
         :return: API response for all clients in the form of Google Ads Row object(s)
         """
         try:

airflow/providers/google/ads/transfers/ads_to_gcs.py

@@ -30,10 +30,10 @@
 
 
 class GoogleAdsToGcsOperator(BaseOperator):
-    """
-    Fetches the daily results from the Google Ads API for 1-n clients
-    Converts and saves the data as a temporary CSV file
-    Uploads the CSV to Google Cloud Storage.
+    """Fetch daily results from the Google Ads API for 1-n clients.
+
+    Converts and saves the data as a temporary CSV file Uploads the CSV to
+    Google Cloud Storage.
 
     .. seealso::
         For more information on the Google Ads API, take a look at the API docs:

airflow/providers/google/cloud/_internal_client/secret_manager_client.py

@@ -30,11 +30,11 @@
 
 
 class _SecretManagerClient(LoggingMixin):
-    """
-    Retrieves Secrets object from Google Cloud Secrets Manager. This is a common class reused between
-    SecretsManager and Secrets Hook that provides the shared authentication and verification mechanisms.
-    This class should not be used directly, use SecretsManager or SecretsHook instead.
+    """Retrieve Secrets object from Google Cloud Secrets Manager.
 
+    This is a common class reused between SecretsManager and Secrets Hook that
+    provides the shared authentication and verification mechanisms. This class
+    should not be used directly; use SecretsManager or SecretsHook instead.
 
     :param credentials: Credentials used to authenticate to GCP
     """
@@ -48,11 +48,9 @@ def __init__(
 
     @staticmethod
     def is_valid_secret_name(secret_name: str) -> bool:
-        """
-        Returns true if the secret name is valid.
+        """Whether the secret name is valid.
 
         :param secret_name: name of the secret
-        :return:
         """
         return bool(re.match(SECRET_ID_PATTERN, secret_name))
 
@@ -63,8 +61,7 @@ def client(self) -> SecretManagerServiceClient:
         return _client
 
     def get_secret(self, secret_id: str, project_id: str, secret_version: str = "latest") -> str | None:
-        """
-        Get secret value from the Secret Manager.
+        """Get secret value from the Secret Manager.
 
         :param secret_id: Secret Key
         :param project_id: Project id to use