Google provider docstring improvements (#31731)

apache · Jun 22, 2023 · fd116cc · fd116cc
1 parent 5a4106d
commit fd116cc
Show file tree

Hide file tree

Showing 25 changed files with 1,521 additions and 1,604 deletions.
diff --git a/airflow/providers/google/ads/hooks/ads.py b/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:

diff --git a/airflow/providers/google/ads/transfers/ads_to_gcs.py b/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:

diff --git a/airflow/providers/google/cloud/_internal_client/secret_manager_client.py b/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