garf-google-ads 0.0.3__py3-none-any.whl

garf_google_ads/__init__.py

@@ -0,0 +1,25 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Library for getting reports from Google Ads API."""
+
+from garf_google_ads.api_clients import GoogleAdsApiClient
+from garf_google_ads.report_fetcher import GoogleAdsApiReportFetcher
+
+__all__ = [
+  'GoogleAdsApiClient',
+  'GoogleAdsApiReportFetcher',
+]
+
+__version__ = '0.0.3'

garf_google_ads/api_clients.py

@@ -0,0 +1,206 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the 'License');
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an 'AS IS' BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Creates API client for Google Ads API."""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+from pathlib import Path
+from typing import Final
+
+import google.auth
+import smart_open
+import tenacity
+import yaml
+from garf_core import api_clients
+from google.ads.googleads import client as googleads_client
+from google.api_core import exceptions as google_exceptions
+from typing_extensions import override
+
+from garf_google_ads import exceptions, query_editor
+
+GOOGLE_ADS_API_VERSION: Final = googleads_client._DEFAULT_VERSION
+google_ads_service = importlib.import_module(
+  f'google.ads.googleads.{GOOGLE_ADS_API_VERSION}.'
+  'services.types.google_ads_service'
+)
+
+
+class GoogleAdsApiClientError(exceptions.GoogleAdsApiError):
+  """Google Ads API client specific error."""
+
+
+class GoogleAdsApiClient(api_clients.BaseClient):
+  """Client to interact with Google Ads API.
+
+  Attributes:
+    default_google_ads_yaml: Default location for google-ads.yaml file.
+    client: GoogleAdsClient to perform stream and mutate operations.
+    ads_service: GoogleAdsService to perform stream operations.
+  """
+
+  default_google_ads_yaml = str(Path.home() / 'google-ads.yaml')
+
+  def __init__(
+    self,
+    path_to_config: str | os.PathLike[str] = os.getenv(
+      'GOOGLE_ADS_CONFIGURATION_FILE_PATH', default_google_ads_yaml
+    ),
+    config_dict: dict[str, str] | None = None,
+    yaml_str: str | None = None,
+    version: str = GOOGLE_ADS_API_VERSION,
+    use_proto_plus: bool = True,
+    ads_client: googleads_client.GoogleAdsClient | None = None,
+    **kwargs: str,
+  ) -> None:
+    """Initializes GoogleAdsApiClient based on one of the methods.
+
+    Args:
+      path_to_config: Path to google-ads.yaml file.
+      config_dict: A dictionary containing authentication details.
+      yaml_str: Strings representation of google-ads.yaml.
+      version: Ads API version.
+      use_proto_plus: Whether to convert Enums to names in response.
+      ads_client: Instantiated GoogleAdsClient.
+
+    Raises:
+      GoogleAdsApiClientError:
+         When GoogleAdsClient cannot be instantiated due to missing
+         credentials.
+    """
+    self.api_version = (
+      str(version) if str(version).startswith('v') else f'v{version}'
+    )
+    self.client = ads_client or self._init_client(
+      path=path_to_config, config_dict=config_dict, yaml_str=yaml_str
+    )
+    self.client.use_proto_plus = use_proto_plus
+    self.ads_service = self.client.get_service('GoogleAdsService')
+    self.kwargs = kwargs
+
+  @override
+  @tenacity.retry(
+    stop=tenacity.stop_after_attempt(3),
+    wait=tenacity.wait_exponential(),
+    retry=tenacity.retry_if_exception_type(
+      google_exceptions.InternalServerError
+    ),
+    reraise=True,
+  )
+  def get_response(
+    self, request: query_editor.GoogleAdsApiQuery, account: int, **kwargs: str
+  ) -> api_clients.GarfApiResponse:
+    """Executes query for a given entity_id (customer_id).
+
+    Args:
+        account: Google Ads customer_id.
+        query_text: GAQL query text.
+
+    Returns:
+        SearchGoogleAdsStreamResponse for a given API version.
+
+    Raises:
+        google_exceptions.InternalServerError:
+            When data cannot be fetched from Ads API.
+    """
+    response = self.ads_service.search_stream(
+      customer_id=account, query=request.text
+    )
+    results = [result for batch in response for result in batch.results]
+    return api_clients.GarfApiResponse(results=results)
+
+  def _init_client(
+    self,
+    path: str | None = None,
+    config_dict: dict[str, str] | None = None,
+    yaml_str: str | None = None,
+  ) -> googleads_client.GoogleAdsClient | None:
+    """Initializes GoogleAdsClient based on one of the methods.
+
+    Args:
+      path: Path to google-ads.yaml file.
+      config_dict: A dictionary containing authentication details.
+      yaml_str: Strings representation of google-ads.yaml.
+
+    Returns:
+      Instantiated GoogleAdsClient;
+      None if instantiation hasn't been done.
+
+    Raises:
+      GoogleAdsApiClientError:
+        if google-ads.yaml wasn't found or missing crucial parts.
+    """
+    if config_dict:
+      if not (developer_token := config_dict.get('developer_token')):
+        raise GoogleAdsApiClientError('developer_token is missing.')
+      if (
+        'refresh_token' not in config_dict
+        and 'json_key_file_path' not in config_dict
+      ):
+        credentials, _ = google.auth.default(
+          scopes=['https://www.googleapis.com/auth/adwords']
+        )
+        if login_customer_id := config_dict.get('login_customer_id'):
+          login_customer_id = str(login_customer_id)
+
+        return googleads_client.GoogleAdsClient(
+          credentials=credentials,
+          developer_token=developer_token,
+          login_customer_id=login_customer_id,
+        )
+      return googleads_client.GoogleAdsClient.load_from_dict(
+        config_dict, self.api_version
+      )
+    if yaml_str:
+      return googleads_client.GoogleAdsClient.load_from_string(
+        yaml_str, self.api_version
+      )
+    if path:
+      with smart_open.open(path, 'r', encoding='utf-8') as f:
+        google_ads_config_dict = yaml.safe_load(f)
+      return self._init_client(config_dict=google_ads_config_dict)
+    try:
+      return googleads_client.GoogleAdsClient.load_from_env(self.api_version)
+    except ValueError as e:
+      raise GoogleAdsApiClientError(
+        f'Cannot instantiate GoogleAdsClient: {str(e)}'
+      ) from e
+
+  @classmethod
+  def from_googleads_client(
+    cls,
+    ads_client: googleads_client.GoogleAdsClient,
+    use_proto_plus: bool = True,
+  ) -> GoogleAdsApiClient:
+    """Builds GoogleAdsApiClient from instantiated GoogleAdsClient.
+
+    ads_client: Instantiated GoogleAdsClient.
+    use_proto_plus: Whether to convert Enums to names in response.
+
+    Returns:
+      Instantiated GoogleAdsApiClient.
+    """
+    if use_proto_plus != ads_client.use_proto_plus:
+      logging.warning(
+        'Mismatch between values of "use_proto_plus" in '
+        'GoogleAdsClient and GoogleAdsApiClient, setting '
+        f'"use_proto_plus={use_proto_plus}"'
+      )
+    return cls(
+      ads_client=ads_client,
+      version=ads_client.version,
+      use_proto_plus=use_proto_plus,
+    )

garf_google_ads/builtins/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from garf_google_ads.builtins import ocid_mapping
+
+BUILTIN_QUERIES = {
+  'ocid_mapping': ocid_mapping.get_ocid_mapping,
+}

garf_google_ads/builtins/ocid_mapping.py

@@ -0,0 +1,58 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import re
+
+import garf_core
+
+
+def get_ocid_mapping(
+  report_fetcher: 'garf_google_ads.GoogleAdsApiReportFetcher',
+  account: str | list[str],
+  **kwargs: str,
+):
+  """Returns mapping between external customer_id and OCID parameter.
+
+  OCID parameter is used to build links to Google Ads entities in UI.
+
+  Args:
+    report_fetcher: An instance of GoogleAdsApiReportFetcher.
+    accounts: Google Ads accounts to get data on OCID mapping.
+
+  Returns:
+      Report with mapping between external customer_id and OCID parameter.
+  """
+  query = (
+    'SELECT customer.id AS account_id, '
+    'metrics.optimization_score_url  AS url FROM customer'
+  )
+  mapping = []
+  if isinstance(account, str):
+    account = account.split(',')
+  for acc in account:
+    if report := report_fetcher.fetch(query_specification=query, account=acc):
+      for row in report:
+        if ocid := re.findall(r'ocid=(\w+)', row.url):
+          mapping.append([row.account_id, ocid[0]])
+          break
+      if not ocid:
+        mapping.append([int(acc), '0'])
+    else:
+      mapping.append([int(acc), '0'])
+  return garf_core.GarfReport(
+    results=mapping,
+    column_names=[
+      'account_id',
+      'ocid',
+    ],
+  )

garf_google_ads/exceptions.py

@@ -0,0 +1,19 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from garf_core import exceptions
+
+
+class GoogleAdsApiError(exceptions.GarfError):
+  """Base class for all library exceptions."""

garf_google_ads/parsers.py

@@ -0,0 +1,288 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+import operator
+import re
+from collections import abc
+from typing import Union, get_args
+
+import proto  # type: ignore
+from garf_core import parsers
+from google import protobuf
+from proto.marshal.collections import repeated
+from typing_extensions import Self, TypeAlias
+
+from garf_google_ads import api_clients, query_editor
+
+google_ads_service = importlib.import_module(
+  f'google.ads.googleads.{api_clients.GOOGLE_ADS_API_VERSION}.'
+  'services.types.google_ads_service'
+)
+
+GoogleAdsRowElement: TypeAlias = Union[int, float, str, bool, list, None]
+
+_REPEATED: TypeAlias = Union[
+  repeated.Repeated,
+  protobuf.internal.containers.RepeatedScalarFieldContainer,
+]
+_REPEATED_COMPOSITE: TypeAlias = Union[
+  repeated.RepeatedComposite,
+  protobuf.internal.containers.RepeatedCompositeFieldContainer,
+]
+
+_NESTED_FIELD: TypeAlias = Union[
+  _REPEATED,
+  _REPEATED_COMPOSITE,
+]
+
+
+class BaseParser:
+  """Base class for defining parsers.
+
+  Attributes:
+      _successor: Indicates the previous parser in the chain.
+  """
+
+  def __init__(self, successor: type[Self]) -> None:
+    self._successor = successor
+
+  def parse(self, element: GoogleAdsRowElement) -> GoogleAdsRowElement:
+    """Parses GoogleAdsRow by using a successor parser.
+
+    Args:
+        element: An element of a GoogleAdsRow.
+
+    Returns:
+        Parsed GoogleAdsRow element.
+    """
+    if self._successor:
+      return self._successor.parse(element)
+    return None
+
+
+class RepeatedParser(BaseParser):
+  """Parses repeated.Repeated resources."""
+
+  def parse(self, element: GoogleAdsRowElement) -> GoogleAdsRowElement:
+    """Parses only repeated elements from GoogleAdsRow.
+
+    If there a repeated resource, applies transformations to each element;
+    otherwise delegates parsing of the element to the next parser
+    in the chain.
+
+    Args:
+        element: An element of a GoogleAdsRow.
+
+    Returns:
+        Parsed GoogleAdsRow element.
+    """
+    if isinstance(element, get_args(_REPEATED)) and 'customer' in str(element):
+      items: list[GoogleAdsRowElement] = []
+      for item in element:
+        items.append(
+          ResourceFormatter(item).get_resource_id().clean_resource_id().format()
+        )
+      return items
+    return super().parse(element)
+
+
+class RepeatedCompositeParser(BaseParser):
+  """Parses repeated.RepeatedComposite elements."""
+
+  def parse(self, element):
+    """Parses only repeated composite resources from GoogleAdsRow.
+
+    If there a repeated composited resource, applies transformations
+    to each element; otherwise delegates parsing of the element
+    to the next parser in the chain.
+
+    Args:
+        element: An element of a GoogleAdsRow.
+
+    Returns:
+        Parsed GoogleAdsRow element.
+    """
+    if isinstance(element, get_args(_REPEATED_COMPOSITE)):
+      items = []
+      for item in element:
+        items.append(
+          ResourceFormatter(item)
+          .get_nested_resource()
+          .get_resource_id()
+          .clean_resource_id()
+          .format()
+        )
+      return items
+    return super().parse(element)
+
+
+class AttributeParser(BaseParser):
+  """Parses elements that have attributes."""
+
+  def parse(self, element: GoogleAdsRowElement) -> GoogleAdsRowElement:
+    """Parses only elements that have attributes.
+
+    If there a repeated composited resource, applies transformations
+    to each element; otherwise delegates parsing of the element
+    to the next parser in the chain.
+
+    Args:
+        element: An element of a GoogleAdsRow.
+
+    Returns:
+        Parsed GoogleAdsRow element.
+    """
+    if hasattr(element, 'name'):
+      return element.name
+    if hasattr(element, 'text'):
+      return element.text
+    if hasattr(element, 'asset'):
+      return element.asset
+    if hasattr(element, 'value'):
+      return element.value
+    return super().parse(element)
+
+
+class EmptyMessageParser(BaseParser):
+  """Generates placeholder for empty Message objects."""
+
+  def parse(self, element: GoogleAdsRowElement) -> GoogleAdsRowElement:
+    """Checks if an element is an empty proto.Message.
+
+    If an element is empty message, returns 'Not set' placeholder;
+    otherwise delegates parsing of the element to the next parser
+    in the chain.
+
+    Args:
+        element: An element of a GoogleAdsRow.
+
+    Returns:
+        Parsed GoogleAdsRow element.
+    """
+    if issubclass(type(element), proto.Message):
+      return 'Not set'
+    return super().parse(element)
+
+
+class GoogleAdsRowParser(parsers.ProtoParser):
+  """Performs parsing of a single GoogleAdsRow.
+
+  Attributes:
+      fields: Expected fields in GoogleAdsRow.
+      customizers: Customizing behaviour performed on a field.
+      virtual_columns: Elements that are not directly present in GoogleAdsRow.
+      parser: Chain of parsers to execute on a single GoogleAdsRow.
+      row_getter: Helper to easily extract fields from GogleAdsRow.
+      respect_nulls: Whether or not convert nulls to zeros.
+  """
+
+  def __init__(
+    self, query_specification: query_editor.QueryElements, **kwargs: str
+  ) -> None:
+    """Initializes GoogleAdsRowParser.
+
+    Args:
+        query_specification: All elements forming gaarf query.
+    """
+    super().__init__(query_specification, **kwargs)
+    self.fields = query_specification.fields
+    self.customizers = query_specification.customizers
+    self.virtual_columns = query_specification.virtual_columns
+    self.column_names = query_specification.column_names
+    self.parser_chain = self._init_parsers_chain()
+    self.row_getter = operator.attrgetter(*query_specification.fields)
+    # Some segments are automatically converted to 0 when not present
+    # For this case we specify attribute `respect_null` which converts
+    # such attributes to None rather than 0
+    self.respect_nulls = (
+      'segments.sk_ad_network_conversion_value' in self.fields
+    )
+
+  def _init_parsers_chain(self):
+    """Initializes chain of parsers."""
+    parser_chain = BaseParser(None)
+    for parser in [
+      EmptyMessageParser,
+      AttributeParser,
+      RepeatedCompositeParser,
+      RepeatedParser,
+    ]:
+      new_parser = parser(parser_chain)
+      parser_chain = new_parser
+    return parser_chain
+
+  def parse_row_element(
+    self, row: GoogleAdsRowElement, key: str
+  ) -> GoogleAdsRowElement:
+    """Parses a single element from row.
+
+    Args:
+        extracted_attribute: A single element from GoogleAdsRow.
+        column: Corresponding name of the element.
+
+    Returns:
+        Parsed element.
+    """
+    getter = operator.attrgetter(key)
+    row = getter(row)
+    if isinstance(row, abc.MutableSequence):
+      parsed_element = [
+        self.parser_chain.parse(element) or element for element in row
+      ]
+    else:
+      parsed_element = self.parser_chain.parse(row) or row
+
+    return parsed_element
+
+
+class ResourceFormatter:
+  """Helper class for formatting resources strings."""
+
+  def __init__(self, element: str) -> None:
+    """Initializes ResourceFormatter based on element."""
+    self.element = str(element).strip()
+
+  def get_nested_resource(self) -> Self:
+    """Extract nested resources from the API response field."""
+    self.element = re.split(': ', self.element)[1]
+    return self
+
+  def get_resource_id(self) -> Self:
+    """Extracts last id of resource_name.
+
+    Resource name looks like `customer/123/campaigns/321`.
+    `get_resource_id` returns `321`.
+    """
+    self.element = re.split('/', self.element)[-1]
+    return self
+
+  def clean_resource_id(self) -> Self:
+    """Ensures that resource_id is cleaned up and converted to int."""
+    self.element = re.sub('"', '', self.element)
+    with contextlib.suppress(ValueError):
+      self.element = int(self.element)
+    return self
+
+  def format(self) -> str | int:
+    """Final method to return formatted resource.
+
+    Returns:
+      Formatted resource.
+    """
+    return self.element

garf_google_ads/query_editor.py

@@ -0,0 +1,83 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Defines Google Ads API specific query parser."""
+
+import re
+
+from garf_core import query_editor
+
+
+class GoogleAdsApiQuery(query_editor.QuerySpecification):
+  """Query to Google Ads API."""
+
+  def generate(self):
+    base_query = super().generate()
+    for field in base_query.fields:
+      field = _format_type_field_name(field)
+    for customizer in base_query.customizers.values():
+      if customizer.type == 'nested_field':
+        customizer.value = _format_type_field_name(customizer.value)
+    base_query.text = self._create_gaql_query()
+    return base_query
+
+  def _create_gaql_query(
+    self,
+  ) -> str:
+    """Generate valid GAQL query.
+
+    Based on original query text, a set of field and virtual columns
+    constructs new GAQL query to be sent to Ads API.
+
+    Returns:
+      Valid GAQL query.
+    """
+    virtual_fields = [
+      field
+      for name, column in self.query.virtual_columns.items()
+      if column.type == 'expression'
+      for field in column.fields
+    ]
+    fields = self.query.fields
+    if virtual_fields:
+      fields = self.query.fields + virtual_fields
+    joined_fields = ', '.join(fields)
+    if filters := self.query.filters:
+      filter_conditions = ' AND '.join(filters)
+      filters = f'WHERE {filter_conditions}'
+    else:
+      filters = ''
+    if sorts := self.query.sorts:
+      sort_conditions = ' AND '.join(sorts)
+      sorts = f'ORDER BY {sort_conditions}'
+    else:
+      sorts = ''
+    query_text = (
+      f'SELECT {joined_fields} '
+      f'FROM {self.query.resource_name} '
+      f'{filters} {sorts}'
+    )
+    query_text = _unformat_type_field_name(query_text)
+    return re.sub(r'\s+', ' ', query_text).strip()
+
+
+def _unformat_type_field_name(query: str) -> str:
+  if query == 'type_':
+    return 'type'
+  return re.sub(r'\.type_', '.type', query)
+
+
+def _format_type_field_name(query: str) -> str:
+  if query == 'type':
+    return 'type_'
+  return re.sub(r'\.type', '.type_', query)

garf_google_ads/report_fetcher.py

@@ -0,0 +1,192 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines report fetcher for Google Ads API."""
+
+import asyncio
+import functools
+import operator
+
+import garf_core
+
+from garf_google_ads import (
+  GoogleAdsApiClient,
+  builtins,
+  exceptions,
+  parsers,
+  query_editor,
+)
+
+
+class GoogleAdsApiReportFetcherError(exceptions.GoogleAdsApiError):
+  """Report fetcher specific error."""
+
+
+class GoogleAdsApiReportFetcher(garf_core.ApiReportFetcher):
+  """Defines report fetcher."""
+
+  def __init__(
+    self,
+    api_client: GoogleAdsApiClient | None = None,
+    parser: garf_core.parsers.ProtoParser = parsers.GoogleAdsRowParser,
+    query_spec: query_editor.GoogleAdsApiQuery = (
+      query_editor.GoogleAdsApiQuery
+    ),
+    builtin_queries=builtins.BUILTIN_QUERIES,
+    parallel_threshold: int = 10,
+    **kwargs: str,
+  ) -> None:
+    """Initializes GoogleAdsApiReportFetcher."""
+    if not api_client:
+      api_client = GoogleAdsApiClient(**kwargs)
+    self.parallel_threshold = parallel_threshold
+    super().__init__(api_client, parser, query_spec, builtin_queries, **kwargs)
+
+  def fetch(
+    self,
+    query_specification: str | query_editor.GoogleAdsApiQuery,
+    args: garf_core.query_editor.GarfQueryParameters | None = None,
+    account: str | list[str] | None = None,
+    expand_mcc: bool = False,
+    customer_ids_query: str | None = None,
+    **kwargs: str,
+  ) -> garf_core.GarfReport:
+    """Fetches data from Google Ads API.
+
+    Args:
+      query_specification: Query to execute.
+      args: Optional parameters to fine-tune the query.
+      account: Account(s) to get data from.
+      expand_mcc: Whether to perform account expansion (MCC to Account).
+      customer_ids_query: Query to reduce number of accounts based a condition.
+
+    Returns:
+      Fetched report for provided accounts.
+
+    Raises:
+      GoogleAdsApiReportFetcherError: If not account provided or found.
+    """
+    if not account:
+      raise GoogleAdsApiReportFetcherError(
+        'Provide an account to get data from.'
+      )
+    if isinstance(account, str):
+      account = account.replace('-', '')
+      account = account.split(',')
+    else:
+      account = [a.replace('-', '') for a in account]
+    if not args:
+      args = {}
+    if expand_mcc or customer_ids_query:
+      account = self.expand_mcc(
+        customer_ids=account, customer_ids_query=customer_ids_query
+      )
+      if not account:
+        raise GoogleAdsApiReportFetcherError(
+          'No account found satisfying the condition {customer_ids_query}.'
+        )
+    if len(account) == 1:
+      return super().fetch(
+        query_specification=query_specification,
+        args=args,
+        account=str(account[0]),
+        **kwargs,
+      )
+    reports = asyncio.run(
+      self._process_accounts(
+        query=query_specification,
+        account=account,
+        args=args,
+      )
+    )
+    return functools.reduce(operator.add, reports)
+
+  async def _process_accounts(
+    self,
+    query,
+    account: list[str],
+    args,
+  ):
+    semaphore = asyncio.Semaphore(value=self.parallel_threshold)
+
+    async def run_with_semaphore(fn):
+      async with semaphore:
+        return await fn
+
+    tasks = [
+      self.afetch(query_specification=query, account=str(acc), args=args)
+      for acc in account
+    ]
+    return await asyncio.gather(*(run_with_semaphore(task) for task in tasks))
+
+  def expand_mcc(
+    self,
+    customer_ids: str | list[str],
+    customer_ids_query: str | None = None,
+  ) -> list[str]:
+    """Performs Manager account(s) expansion to child accounts.
+
+    Args:
+      customer_ids: Manager account(s) to be expanded.
+      customer_ids_query: GAQL query used to reduce the number of customer_ids.
+
+    Returns:
+      All child accounts under provided customer_ids.
+    """
+    return self._get_customer_ids(
+      seed_customer_ids=customer_ids, customer_ids_query=customer_ids_query
+    )
+
+  def _get_customer_ids(
+    self,
+    seed_customer_ids: str | list[str],
+    customer_ids_query: str | None = None,
+  ) -> list[str]:
+    """Gets list of customer_ids from an MCC account.
+
+    Args:
+      seed_customer_ids: MCC account_id(s).
+      customer_ids_query: GAQL query used to reduce the number of customer_ids.
+
+    Returns:
+      All customer_ids from MCC satisfying the condition.
+    """
+    query = """
+        SELECT customer_client.id FROM customer_client
+        WHERE customer_client.manager = FALSE
+        AND customer_client.status = ENABLED
+        AND customer_client.hidden = FALSE
+        """
+    if isinstance(seed_customer_ids, str):
+      seed_customer_ids = seed_customer_ids.split(',')
+    child_customer_ids = self.fetch(
+      query_specification=query, account=seed_customer_ids
+    ).to_list()
+    if customer_ids_query:
+      child_customer_ids = self.fetch(
+        query_specification=customer_ids_query,
+        account=[str(a) for a in child_customer_ids],
+      )
+      child_customer_ids = [
+        row[0] if isinstance(row, garf_core.report.GarfRow) else row
+        for row in child_customer_ids
+      ]
+
+    return list(
+      {
+        str(customer_id)
+        for customer_id in child_customer_ids
+        if customer_id != 0
+      }
+    )

garf_google_ads-0.0.3.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: garf-google-ads
+Version: 0.0.3
+Summary: Garf implementation for Google Ads API
+Author-email: Andrei Markin <amarkin@google.com>, "Google Inc. (gTech gPS CSE team)" <no-reply@google.com>
+License: Apache 2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: garf-core
+Requires-Dist: garf-io
+Requires-Dist: google-ads
+Requires-Dist: tenacity
+
+# `garf` for Google Ads API
+
+[![PyPI](https://img.shields.io/pypi/v/garf-google-ads?logo=pypi&logoColor=white&style=flat-square)](https://pypi.org/project/garf-google-ads)
+[![Downloads PyPI](https://img.shields.io/pypi/dw/garf-google-ads?logo=pypi)](https://pypi.org/project/garf-google-ads/)
+
+`garf-google-ads` simplifies fetching data from Google Ads API using SQL-like queries.
+
+## Prerequisites
+
+* [Google Ads API](https://console.cloud.google.com/apis/library/googleads.googleapis.com) enabled.
+
+## Installation
+
+`pip install garf-google-ads`
+
+## Usage
+
+### Run as a library
+```
+import os
+
+from garf_io import writer
+from garf_google_ads import GoogleAdsApiReportFetcher
+
+query = """
+SELECT
+  campaign.id,
+  metrics.clicks AS clicks
+FROM campaign
+WHERE segments.date DURING LAST_7_DAYS
+"""
+
+fetched_report = (
+  GoogleAdsApiReportFetcher(
+    path_to_config=os.getenv('GOOGLE_ADS_CONFIGURATION_FILE_PATH')
+  )
+  .fetch(query, account=os.getenv('GOOGLE_ADS_ACCOUNT'))
+)
+
+console_writer = writer.create_writer('console')
+console_writer.write(fetched_report, 'query')
+```
+
+### Run via CLI
+
+> Install `garf-executors` package to run queries via CLI (`pip install garf-executors`).
+
+```
+garf <PATH_TO_QUERIES> --source google-ads \
+  --output <OUTPUT_TYPE> \
+  --source.account=GOOGLE_ADS_ACCOUNT \
+  --source.path-to-config=./google-ads.yaml
+```
+
+where:
+
+* `<PATH_TO_QUERIES>` - local or remove files containing queries
+* `<OUTPUT_TYPE>` - output supported by [`garf-io` library](../garf_io/README.md).
+* `<SOURCE_PARAMETER=VALUE` - key-value pairs to refine fetching, check [available source parameters](#available-source-parameters).
+
+###  Available source parameters
+
+| name | values| comments |
+|----- | ----- | -------- |
+| `account`   | Account(s) to get data from | Can be MCC(s) as well |
+| `path-to-config`   | Path to `google-ads.yaml` file | `~/google-ads.yaml` is a default location |
+| `expand-mcc`   | Whether to force account expansion if MCC is provided | `False` by default |
+| `customer-ids-query`   | Optional query to find account satisfying specific condition | |
+| `version`   | Version of Google Ads API |  |

garf_google_ads-0.0.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+garf_google_ads/__init__.py,sha256=OQ3zpFOx3vo4bQpvL6Zw1bB-mWarn5SorH7PVfQkSmY,853
+garf_google_ads/api_clients.py,sha256=PbGka-vHJtpry_1vSojNUhpVFU9c8mucq7APKB9Mn1k,6794
+garf_google_ads/exceptions.py,sha256=CJ0n3kwYP2wLLZ7TGtlaIxWWXXxcKEkZXZtvfvoCQmI,705
+garf_google_ads/parsers.py,sha256=bPgUqbND8YCfKpV7yv97gKx-N44y5bqYPsnZbAGcTsY,8485
+garf_google_ads/query_editor.py,sha256=0ScKZJ-_FMCZDcnDjdk3lY0Nzs8KQXMJT5sZJf8gOAk,2525
+garf_google_ads/report_fetcher.py,sha256=I8S3G-AIDWhB7RI5uXCxKuu9qnTPL630C8gDU84jNog,5708
+garf_google_ads/builtins/__init__.py,sha256=8cU6UJo1BQYQ6gYfZwkbtBfmAGhclH3yDjvwdnR8J5Y,697
+garf_google_ads/builtins/ocid_mapping.py,sha256=VWuISWmnHXhX-jf22Di1V5-fIPCe2rr_D-JrL63e8aU,1773
+garf_google_ads-0.0.3.dist-info/METADATA,sha256=GYKn6JS2NG5SwyMiiZpn0RIJ9tLrCVSw5d8PWh47gJk,2620
+garf_google_ads-0.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+garf_google_ads-0.0.3.dist-info/entry_points.txt,sha256=X59pHlYZJu4SDH9YIQccab4bvUBR17wKBYhhn1NL8wk,51
+garf_google_ads-0.0.3.dist-info/top_level.txt,sha256=q_Pd36wShRJUtFmU8b9dEkThSefbXPOMBjgIZyU46N4,16
+garf_google_ads-0.0.3.dist-info/RECORD,,

garf_google_ads-0.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

garf_google_ads-0.0.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[garf]
+google-ads = garf_google_ads.report_fetcher

garf_google_ads-0.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+garf_google_ads