Skip to content

Commit fd116cc

Browse files
uranusjruranusjr
authored
Google provider docstring improvements (#31731)
1 parent 5a4106d commit fd116cc

25 files changed

Lines changed: 1521 additions & 1604 deletions

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

Lines changed: 34 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -36,14 +36,13 @@
3636

3737

3838
class GoogleAdsHook(BaseHook):
39-
"""
40-
Hook for the Google Ads API.
39+
"""Interact with Google Ads API.
4140
4241
This hook requires two connections:
4342
44-
- gcp_conn_id - provides service account details (like any other GCP connection)
45-
- google_ads_conn_id - which contains information from Google Ads config.yaml file
46-
in the ``extras``. Example of the ``extras``:
43+
- gcp_conn_id - provides service account details (like any other GCP connection)
44+
- google_ads_conn_id - which contains information from Google Ads config.yaml file
45+
in the ``extras``. Example of the ``extras``:
4746
4847
.. code-block:: json
4948
@@ -69,8 +68,6 @@ class GoogleAdsHook(BaseHook):
6968
:param gcp_conn_id: The connection ID with the service account details.
7069
:param google_ads_conn_id: The connection ID with the details of Google Ads config.yaml file.
7170
:param api_version: The Google Ads API version to use.
72-
73-
:return: list of Google Ads Row object(s)
7471
"""
7572

7673
default_api_version = "v14"
@@ -90,10 +87,10 @@ def __init__(
9087
def search(
9188
self, client_ids: list[str], query: str, page_size: int = 10000, **kwargs
9289
) -> list[GoogleAdsRow]:
93-
"""
94-
Pulls data from the Google Ads API and returns it as native protobuf
95-
message instances (those seen in versions prior to 10.0.0 of the
96-
google-ads library).
90+
"""Pull data from the Google Ads API.
91+
92+
Native protobuf message instances are returned (those seen in versions
93+
prior to 10.0.0 of the google-ads library).
9794
9895
This method is for backwards compatibility with older versions of the
9996
google_ads_hook.
@@ -105,7 +102,7 @@ def search(
105102
:param client_ids: Google Ads client ID(s) to query the API for.
106103
:param query: Google Ads Query Language query.
107104
:param page_size: Number of results to return per page. Max 10000.
108-
:return: Google Ads API response, converted to Google Ads Row objects
105+
:return: Google Ads API response, converted to Google Ads Row objects.
109106
"""
110107
data_proto_plus = self._search(client_ids, query, page_size, **kwargs)
111108
data_native_pb = [row._pb for row in data_proto_plus]
@@ -115,9 +112,10 @@ def search(
115112
def search_proto_plus(
116113
self, client_ids: list[str], query: str, page_size: int = 10000, **kwargs
117114
) -> list[GoogleAdsRow]:
118-
"""
119-
Pulls data from the Google Ads API and returns it as proto-plus-python
120-
message instances that behave more like conventional python objects.
115+
"""Pull data from the Google Ads API.
116+
117+
Instances of proto-plus-python message are returned, which behave more
118+
like conventional Python objects.
121119
122120
:param client_ids: Google Ads client ID(s) to query the API for.
123121
:param query: Google Ads Query Language query.
@@ -127,12 +125,14 @@ def search_proto_plus(
127125
return self._search(client_ids, query, page_size, **kwargs)
128126

129127
def list_accessible_customers(self) -> list[str]:
130-
"""
131-
Returns resource names of customers directly accessible by the user authenticating the call.
132-
The resulting list of customers is based on your OAuth credentials. The request returns a list
133-
of all accounts that you are able to act upon directly given your current credentials. This will
134-
not necessarily include all accounts within the account hierarchy; rather, it will only include
135-
accounts where your authenticated user has been added with admin or other rights in the account.
128+
"""List resource names of customers.
129+
130+
The resulting list of customers is based on your OAuth credentials. The
131+
request returns a list of all accounts that you are able to act upon
132+
directly given your current credentials. This will not necessarily
133+
include all accounts within the account hierarchy; rather, it will only
134+
include accounts where your authenticated user has been added with admin
135+
or other rights in the account.
136136
137137
..seealso::
138138
https://developers.google.com/google-ads/api/reference/rpc
@@ -152,7 +152,7 @@ def list_accessible_customers(self) -> list[str]:
152152

153153
@cached_property
154154
def _get_service(self) -> GoogleAdsServiceClient:
155-
"""Connects and authenticates with the Google Ads API using a service account."""
155+
"""Connect and authenticate with the Google Ads API using a service account."""
156156
client = self._get_client
157157
return client.get_service("GoogleAdsService", version=self.api_version)
158158

@@ -170,7 +170,7 @@ def _get_client(self) -> GoogleAdsClient:
170170

171171
@cached_property
172172
def _get_customer_service(self) -> CustomerServiceClient:
173-
"""Connects and authenticates with the Google Ads API using a service account."""
173+
"""Connect and authenticate with the Google Ads API using a service account."""
174174
with NamedTemporaryFile("w", suffix=".json") as secrets_temp:
175175
self._get_config()
176176
self._update_config_with_secret(secrets_temp)
@@ -182,9 +182,10 @@ def _get_customer_service(self) -> CustomerServiceClient:
182182
raise
183183

184184
def _get_config(self) -> None:
185-
"""
186-
Gets google ads connection from meta db and sets google_ads_config attribute with returned config
187-
file.
185+
"""Set up Google Ads config from Connection.
186+
187+
This pulls the connections from db, and uses it to set up
188+
``google_ads_config``.
188189
"""
189190
conn = self.get_connection(self.google_ads_conn_id)
190191
if "google_ads_client" not in conn.extra_dejson:
@@ -193,10 +194,11 @@ def _get_config(self) -> None:
193194
self.google_ads_config = conn.extra_dejson["google_ads_client"]
194195

195196
def _update_config_with_secret(self, secrets_temp: IO[str]) -> None:
196-
"""
197-
Gets Google Cloud secret from connection and saves the contents to the temp file
198-
Updates google ads config with file path of the temp file containing the secret
199-
Note, the secret must be passed as a file path for Google Ads API.
197+
"""Set up Google Cloud config secret from Connection.
198+
199+
This pulls the connection, saves the contents to a temp file, and point
200+
the config to the path containing the secret. Note that the secret must
201+
be passed as a file path for Google Ads API.
200202
"""
201203
extras = self.get_connection(self.gcp_conn_id).extra_dejson
202204
secret = get_field(extras, "keyfile_dict")
@@ -210,8 +212,7 @@ def _update_config_with_secret(self, secrets_temp: IO[str]) -> None:
210212
def _search(
211213
self, client_ids: list[str], query: str, page_size: int = 10000, **kwargs
212214
) -> list[GoogleAdsRow]:
213-
"""
214-
Pulls data from the Google Ads API.
215+
"""Pull data from the Google Ads API.
215216
216217
:param client_ids: Google Ads client ID(s) to query the API for.
217218
:param query: Google Ads Query Language query.
@@ -231,11 +232,9 @@ def _search(
231232
return self._extract_rows(iterators)
232233

233234
def _extract_rows(self, iterators: list[GRPCIterator]) -> list[GoogleAdsRow]:
234-
"""
235-
Convert Google Page Iterator (GRPCIterator) objects to Google Ads Rows.
235+
"""Convert Google Page Iterator (GRPCIterator) objects to Google Ads Rows.
236236
237237
:param iterators: List of Google Page Iterator (GRPCIterator) objects
238-
239238
:return: API response for all clients in the form of Google Ads Row object(s)
240239
"""
241240
try:

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,10 @@
3030

3131

3232
class GoogleAdsToGcsOperator(BaseOperator):
33-
"""
34-
Fetches the daily results from the Google Ads API for 1-n clients
35-
Converts and saves the data as a temporary CSV file
36-
Uploads the CSV to Google Cloud Storage.
33+
"""Fetch daily results from the Google Ads API for 1-n clients.
34+
35+
Converts and saves the data as a temporary CSV file Uploads the CSV to
36+
Google Cloud Storage.
3737
3838
.. seealso::
3939
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‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,11 @@
3030

3131

3232
class _SecretManagerClient(LoggingMixin):
33-
"""
34-
Retrieves Secrets object from Google Cloud Secrets Manager. This is a common class reused between
35-
SecretsManager and Secrets Hook that provides the shared authentication and verification mechanisms.
36-
This class should not be used directly, use SecretsManager or SecretsHook instead.
33+
"""Retrieve Secrets object from Google Cloud Secrets Manager.
3734
35+
This is a common class reused between SecretsManager and Secrets Hook that
36+
provides the shared authentication and verification mechanisms. This class
37+
should not be used directly; use SecretsManager or SecretsHook instead.
3838
3939
:param credentials: Credentials used to authenticate to GCP
4040
"""
@@ -48,11 +48,9 @@ def __init__(
4848

4949
@staticmethod
5050
def is_valid_secret_name(secret_name: str) -> bool:
51-
"""
52-
Returns true if the secret name is valid.
51+
"""Whether the secret name is valid.
5352
5453
:param secret_name: name of the secret
55-
:return:
5654
"""
5755
return bool(re.match(SECRET_ID_PATTERN, secret_name))
5856

@@ -63,8 +61,7 @@ def client(self) -> SecretManagerServiceClient:
6361
return _client
6462

6563
def get_secret(self, secret_id: str, project_id: str, secret_version: str = "latest") -> str | None:
66-
"""
67-
Get secret value from the Secret Manager.
64+
"""Get secret value from the Secret Manager.
6865
6966
:param secret_id: Secret Key
7067
:param project_id: Project id to use

0 commit comments

Comments
 (0)