garf-core 0.0.11__tar.gz → 0.1.0__tar.gz

{garf_core-0.0.11 → garf_core-0.1.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: garf-core
-Version: 0.0.11
+Version: 0.1.0
 Summary: Abstracts fetching data from API based on provided SQL-like query.
-Author-email: "Google Inc. (gTech gPS CSE team)" <no-reply@google.com>
+Author-email: "Google Inc. (gTech gPS CSE team)" <no-reply@google.com>, Andrei Markin <andrey.markin.ppc@gmail.com>
 License: Apache 2.0
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.8
@@ -22,6 +22,7 @@ Requires-Dist: jinja2
 Requires-Dist: typing-extensions
 Requires-Dist: requests
 Requires-Dist: pyyaml
+Requires-Dist: pydantic
 Provides-Extra: pandas
 Requires-Dist: pandas; extra == "pandas"
 Provides-Extra: polars
@@ -39,15 +40,13 @@ Requires-Dist: garf-core[pandas,polars]; extra == "all"
 
 These abstractions are designed to be as modular and simple as possible:
 
-* `BaseApiClient` - an interface for connecting to APIs.
-* `BaseQuery` - encapsulates SQL-like request.
+* `BaseApiClient` - an interface for connecting to APIs. Check [default implementations](docs/builtin-functionality.md#apiclients)
+* `BaseParser` - an interface to parse results from the API. Check [default implementations](docs/builtin-functionality.md#parsers)
+* `ApiReportFetcher` - responsible for fetching and parsing data from reporting API. [Default implementations](docs/builtin-functionality.md#apireportfetchers)
+
 * `QuerySpecification` - parsed SQL-query into various elements.
-* `BaseParser` - an interface to parse results from the API. Have a couple of default implementations:
-    * `ListParser` - returns results from API as a raw list.
-    * `DictParser` - returns results from API as a formatted dict.
-        * `NumericDictParser` - returns results from API as a formatted dict with converted numeric values.
+* `BaseQuery` - protocol for all class based queries.
 * `GarfReport` - contains data from API in a format that is easy to write and interact with.
-* `ApiReportFetcher` - responsible for fetching and parsing data from reporting API.
 
 ## Installation
 

{garf_core-0.0.11 → garf_core-0.1.0}/README.md

@@ -8,15 +8,13 @@
 
 These abstractions are designed to be as modular and simple as possible:
 
-* `BaseApiClient` - an interface for connecting to APIs.
-* `BaseQuery` - encapsulates SQL-like request.
+* `BaseApiClient` - an interface for connecting to APIs. Check [default implementations](docs/builtin-functionality.md#apiclients)
+* `BaseParser` - an interface to parse results from the API. Check [default implementations](docs/builtin-functionality.md#parsers)
+* `ApiReportFetcher` - responsible for fetching and parsing data from reporting API. [Default implementations](docs/builtin-functionality.md#apireportfetchers)
+
 * `QuerySpecification` - parsed SQL-query into various elements.
-* `BaseParser` - an interface to parse results from the API. Have a couple of default implementations:
-    * `ListParser` - returns results from API as a raw list.
-    * `DictParser` - returns results from API as a formatted dict.
-        * `NumericDictParser` - returns results from API as a formatted dict with converted numeric values.
+* `BaseQuery` - protocol for all class based queries.
 * `GarfReport` - contains data from API in a format that is easy to write and interact with.
-* `ApiReportFetcher` - responsible for fetching and parsing data from reporting API.
 
 ## Installation
 

{garf_core-0.0.11 → garf_core-0.1.0}/garf_core/__init__.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = '0.0.11'
+__version__ = '0.1.0'

garf_core-0.1.0/garf_core/api_clients.py

@@ -0,0 +1,172 @@
+# 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.
+"""Module for defining client to interact with API."""
+
+from __future__ import annotations
+
+import abc
+import contextlib
+import csv
+import dataclasses
+import json
+import os
+import pathlib
+from collections.abc import Sequence
+from typing import Any
+
+import requests
+from typing_extensions import override
+
+from garf_core import exceptions
+
+
+@dataclasses.dataclass
+class GarfApiRequest:
+  """Base class for specifying request."""
+
+
+@dataclasses.dataclass
+class GarfApiResponse:
+  """Base class for specifying response."""
+
+  results: list
+
+
+class GarfApiError(exceptions.GarfError):
+  """API specific exception."""
+
+
+class BaseClient(abc.ABC):
+  """Base API client class."""
+
+  @abc.abstractmethod
+  def get_response(
+    self, request: GarfApiRequest = GarfApiRequest(), **kwargs: str
+  ) -> GarfApiResponse:
+    """Method for getting response."""
+
+
+class RestApiClient(BaseClient):
+  """Specifies REST client."""
+
+  OK = 200
+
+  def __init__(self, endpoint: str, **kwargs: str) -> None:
+    """Initializes RestApiClient."""
+    self.endpoint = endpoint
+    self.query_args = kwargs
+
+  @override
+  def get_response(
+    self, request: GarfApiRequest = GarfApiRequest(), **kwargs: str
+  ) -> GarfApiResponse:
+    response = requests.get(f'{self.endpoint}/{request.resource_name}')
+    if response.status_code == self.OK:
+      return GarfApiResponse(response.json())
+    raise GarfApiError('Failed to get data from API')
+
+
+class FakeApiClient(BaseClient):
+  """Fake class for specifying API client."""
+
+  def __init__(self, results: Sequence[dict[str, Any]], **kwargs: str) -> None:
+    """Initializes FakeApiClient."""
+    self.results = list(results)
+    self.kwargs = kwargs
+
+  @override
+  def get_response(
+    self, request: GarfApiRequest = GarfApiRequest(), **kwargs: str
+  ) -> GarfApiResponse:
+    del request
+    return GarfApiResponse(results=self.results)
+
+  @classmethod
+  def from_file(cls, file_location: str | os.PathLike[str]) -> FakeApiClient:
+    """Initializes FakeApiClient from json or csv files.
+
+    Args:
+      file_location: Path of file with data.
+
+    Returns:
+      Initialized client.
+
+    Raises:
+      GarfApiError: When file with unsupported extension is provided.
+    """
+    if str(file_location).endswith('.json'):
+      return FakeApiClient.from_json(file_location)
+    if str(file_location).endswith('.csv'):
+      return FakeApiClient.from_csv(file_location)
+    raise GarfApiError(
+      'Unsupported file extension, only csv and json are supported.'
+    )
+
+  @classmethod
+  def from_json(cls, file_location: str | os.PathLike[str]) -> FakeApiClient:
+    """Initializes FakeApiClient from json file.
+
+    Args:
+      file_location: Path of file with data.
+
+    Returns:
+      Initialized client.
+
+    Raises:
+      GarfApiError: When file with data not found.
+    """
+    try:
+      with pathlib.Path.open(file_location, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+        return FakeApiClient(data)
+    except FileNotFoundError as e:
+      raise GarfApiError(f'Failed to open {file_location}') from e
+
+  @classmethod
+  def from_csv(cls, file_location: str | os.PathLike[str]) -> FakeApiClient:
+    """Initializes FakeApiClient from csv file.
+
+    Args:
+      file_location: Path of file with data.
+
+    Returns:
+      Initialized client.
+
+    Raises:
+      GarfApiError: When file with data not found.
+    """
+    try:
+      with pathlib.Path.open(file_location, 'r', encoding='utf-8') as f:
+        reader = csv.DictReader(f)
+        data = []
+        for row in reader:
+          data.append(
+            {key: _field_converter(value) for key, value in row.items()}
+          )
+        return FakeApiClient(data)
+    except FileNotFoundError as e:
+      raise GarfApiError(f'Failed to open {file_location}') from e
+
+
+def _field_converter(field: str):
+  if isinstance(field, str) and (lower_field := field.lower()) in (
+    'true',
+    'false',
+  ):
+    return lower_field == 'true'
+  with contextlib.suppress(ValueError):
+    return int(field)
+  with contextlib.suppress(ValueError):
+    return float(field)
+  return field

garf_core-0.1.0/garf_core/fetchers/__init__.py

@@ -0,0 +1,23 @@
+# 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.
+
+"""Built-in fetchers."""
+
+from garf_core.fetchers.fake import FakeApiReportFetcher
+from garf_core.fetchers.rest import RestApiReportFetcher
+
+__all__ = [
+  'FakeApiReportFetcher',
+  'RestApiReportFetcher',
+]

garf_core-0.1.0/garf_core/fetchers/fake.py

@@ -0,0 +1,74 @@
+# Copyright 2025 Google LLf
+#
+# 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.
+
+# pylint: disable=C0330, g-bad-import-order, g-multiple-import
+
+"""Getting fake data from memory or a file."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from garf_core import (
+  api_clients,
+  parsers,
+  query_editor,
+  report_fetcher,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class FakeApiReportFetcher(report_fetcher.ApiReportFetcher):
+  """Returns simulated data."""
+
+  def __init__(
+    self,
+    data: list[dict[str, parsers.ApiRowElement]] | None = None,
+    parser: parsers.BaseParser = parsers.DictParser,
+    query_specification_builder: query_editor.QuerySpecification = (
+      query_editor.QuerySpecification
+    ),
+    data_location: str | os.PathLike[str] | None = None,
+    csv_location: str | os.PathLike[str] | None = None,
+    json_location: str | os.PathLike[str] | None = None,
+    **kwargs: str,
+  ) -> None:
+    if not data and not (
+      data_location := json_location or csv_location or data_location
+    ):
+      raise report_fetcher.ApiReportFetcherError(
+        'Missing fake data for the fetcher.'
+      )
+    api_client = (
+      api_clients.FakeApiClient(data)
+      if data
+      else api_clients.FakeApiClient.from_file(data_location)
+    )
+    super().__init__(api_client, parser, query_specification_builder, **kwargs)
+
+  @classmethod
+  def from_csv(
+    cls, file_location: str | os.PathLike[str]
+  ) -> FakeApiReportFetcher:
+    """Initialized FakeApiReportFetcher from a csv file."""
+    return FakeApiReportFetcher(csv_location=file_location)
+
+  @classmethod
+  def from_json(
+    cls, file_location: str | os.PathLike[str]
+  ) -> FakeApiReportFetcher:
+    """Initialized FakeApiReportFetcher from a json file."""
+    return FakeApiReportFetcher(json_location=file_location)

garf_core-0.1.0/garf_core/fetchers/rest.py

@@ -0,0 +1,58 @@
+# Copyright 2025 Google LLf
+#
+# 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.
+
+# pylint: disable=C0330, g-bad-import-order, g-multiple-import
+
+"""Module for getting data from Rest APIs based on a query."""
+
+from __future__ import annotations
+
+import logging
+
+from garf_core import (
+  api_clients,
+  parsers,
+  query_editor,
+  report_fetcher,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class RestApiReportFetcher(report_fetcher.ApiReportFetcher):
+  """Fetches data from an REST API endpoint.
+
+  Attributes:
+    api_client: Initialized RestApiClient.
+    parser: Type of parser to convert API response.
+  """
+
+  def __init__(
+    self,
+    endpoint: str,
+    parser: parsers.BaseParser = parsers.DictParser,
+    query_specification_builder: query_editor.QuerySpecification = (
+      query_editor.QuerySpecification
+    ),
+    **kwargs: str,
+  ) -> None:
+    """Instantiates RestApiReportFetcher.
+
+    Args:
+      endpoint: URL of API endpoint.
+      parser: Type of parser to convert API response.
+      query_specification_builder: Class to perform query parsing.
+    """
+    api_client = api_clients.RestApiClient(endpoint)
+    super().__init__(api_client, parser, query_specification_builder, **kwargs)

{garf_core-0.0.11 → garf_core-0.1.0}/garf_core/query_editor.py

@@ -23,11 +23,27 @@ import re
 from typing import Generator
 
 import jinja2
+import pydantic
 from dateutil import relativedelta
 from typing_extensions import Self
 
 from garf_core import exceptions
 
+QueryParameters = dict[str, str | float | int]
+
+
+class GarfQueryParameters(pydantic.BaseModel):
+  """Parameters for dynamically changing text of a query."""
+
+  macro: QueryParameters | None = None
+  template: QueryParameters | None = None
+
+  def model_post_init(self, __context__) -> None:
+    if self.macro is None:
+      self.macro = {}
+    if self.template is None:
+      self.template = {}
+
 
 class GarfQueryError(exceptions.GarfError):
   """Base exception for Garf queries."""
@@ -53,9 +69,12 @@ class GarfResourceError(GarfQueryError):
   """Specifies incorrect resource name in the query."""
 
 
-@dataclasses.dataclass
-class ProcessedField:
-  """Helper class to store fields with its customizers.
+class GarfBuiltInQueryError(GarfQueryError):
+  """Specifies non-existing builtin query."""
+
+
+class ProcessedField(pydantic.BaseModel):
+  """Sore field with its customizers.
 
   Attributes:
     field: Extractable field.
@@ -136,7 +155,7 @@ class VirtualColumn:
   substitute_expression: str | None = None
 
   @classmethod
-  def from_raw(cls, field: str, macros: dict) -> VirtualColumn:
+  def from_raw(cls, field: str, macros: QueryParameters) -> VirtualColumn:
     """Converts a field to virtual column."""
     if field.isdigit():
       field = int(field)
@@ -189,16 +208,16 @@ class ExtractedLineElements:
 
   @classmethod
   def from_query_line(
-    cls, line: str, macros: dict = {}
+    cls,
+    line: str,
+    macros: QueryParameters | None = None,
   ) -> ExtractedLineElements:
+    if macros is None:
+      macros = {}
     field, *alias = re.split(' [Aa][Ss] ', line)
     processed_field = ProcessedField.from_raw(field)
     field = processed_field.field
-    if field:
-      # if field.is_valid:
-      virtual_column = None
-    else:
-      virtual_column = VirtualColumn.from_raw(field, macros)
+    virtual_column = None if field else VirtualColumn.from_raw(field, macros)
     if alias and processed_field.customizer_type:
       customizer = {
         'type': processed_field.customizer_type,
@@ -300,11 +319,11 @@ class CommonParametersMixin:
 
 class TemplateProcessorMixin:
   def replace_params_template(
-    self, query_text: str, params: dict | None = None
+    self, query_text: str, params: GarfQueryParameters | None = None
   ) -> str:
     logging.debug('Original query text:\n%s', query_text)
     if params:
-      if templates := params.get('template'):
+      if templates := params.template:
         query_templates = {
           name: value for name, value in templates.items() if name in query_text
         }
@@ -315,7 +334,7 @@ class TemplateProcessorMixin:
           query_text = self.expand_jinja(query_text, {})
       else:
         query_text = self.expand_jinja(query_text, {})
-      if macros := params.get('macro'):
+      if macros := params.macro:
         query_text = query_text.format(**macros)
         logging.debug('Query text after macro substitution:\n%s', query_text)
     else:
@@ -323,7 +342,7 @@ class TemplateProcessorMixin:
     return query_text
 
   def expand_jinja(
-    self, query_text: str, template_params: dict | None = None
+    self, query_text: str, template_params: QueryParameters | None = None
   ) -> str:
     file_inclusions = ('% include', '% import', '% extend')
     if any(file_inclusion in query_text for file_inclusion in file_inclusions):
@@ -360,7 +379,7 @@ class QuerySpecification(CommonParametersMixin, TemplateProcessorMixin):
     self,
     text: str,
     title: str | None = None,
-    args: dict | None = None,
+    args: GarfQueryParameters | None = GarfQueryParameters(),
     **kwargs: str,
   ) -> None:
     """Instantiates QuerySpecification based on text, title and optional args.
@@ -371,35 +390,40 @@ class QuerySpecification(CommonParametersMixin, TemplateProcessorMixin):
       args: Optional parameters to be dynamically injected into query text.
       api_version: Version of Google Ads API.
     """
-    self.args = args or {}
+    self.args = args or GarfQueryParameters()
     self.query = BaseQueryElements(title=title, text=text)
 
   @property
-  def macros(self) -> dict[str, str]:
+  def macros(self) -> QueryParameters:
     """Returns macros with injected common parameters."""
     common_params = dict(self.common_params)
-    if macros := self.args.get('macro'):
+    if macros := self.args.macro:
       common_params.update(macros)
     return common_params
 
   def generate(self) -> BaseQueryElements:
-    return (
-      self.remove_comments()
-      .expand()
-      .extract_resource_name()
-      .remove_trailing_comma()
+    self.remove_comments().expand().extract_resource_name()
+    if self.query.resource_name.startswith('builtin'):
+      return BaseQueryElements(
+        title=self.query.resource_name.replace('builtin.', ''),
+        text=self.query.text,
+        resource_name=self.query.resource_name,
+        is_builtin_query=True,
+      )
+    (
+      self.remove_trailing_comma()
       .extract_fields()
       .extract_filters()
       .extract_sorts()
       .extract_column_names()
       .extract_virtual_columns()
       .extract_customizers()
-      .query
     )
+    return self.query
 
   def expand(self) -> Self:
     """Applies necessary transformations to query."""
-    query_text = self.expand_jinja(self.query.text, self.args.get('template'))
+    query_text = self.expand_jinja(self.query.text, self.args.template)
     try:
       self.query.text = query_text.format(**self.macros).strip()
     except KeyError as e:

{garf_core-0.0.11 → garf_core-0.1.0}/garf_core/report_fetcher.py

@@ -11,20 +11,22 @@
 # 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.
+
+# pylint: disable=C0330, g-bad-import-order, g-multiple-import
+
 """Module for getting data from API based on a query.
 
-ApiReportFetcher performs fetching data from API, parsing it
-  and returning GarfReport.
+ApiReportFetcher fetches data from API, parses it and returns GarfReport.
 """
-# pylint: disable=C0330, g-bad-import-order, g-multiple-import
 
 from __future__ import annotations
 
 import logging
-from typing import Any
+from typing import Callable
 
 from garf_core import (
   api_clients,
+  exceptions,
   parsers,
   query_editor,
   report,
@@ -33,6 +35,10 @@ from garf_core import (
 logger = logging.getLogger(__name__)
 
 
+class ApiReportFetcherError(exceptions.GarfError):
+  """Base exception for all ApiReportFetchers."""
+
+
 class ApiReportFetcher:
   """Class responsible for getting data from report API.
 
@@ -45,10 +51,12 @@ class ApiReportFetcher:
   def __init__(
     self,
     api_client: api_clients.BaseApiClient,
-    parser: parsers.BaseParser = parsers.ListParser,
+    parser: parsers.BaseParser = parsers.DictParser,
     query_specification_builder: query_editor.QuerySpecification = (
       query_editor.QuerySpecification
     ),
+    builtin_queries: dict[str, Callable[[ApiReportFetcher], report.GarfReport]]
+    | None = None,
     **kwargs: str,
   ) -> None:
     """Instantiates ApiReportFetcher based on provided api client.
@@ -57,16 +65,26 @@ class ApiReportFetcher:
       api_client: Instantiated api client.
       parser: Type of parser to convert API response.
       query_specification_builder: Class to perform query parsing.
+      builtin_queries:
+        Mapping between query name and function for generating GarfReport.
     """
     self.api_client = api_client
     self.parser = parser()
     self.query_specification_builder = query_specification_builder
     self.query_args = kwargs
+    self.builtin_queries = builtin_queries or {}
+
+  def add_builtin_queries(
+    self,
+    builtin_queries: dict[str, Callable[[ApiReportFetcher], report.GarfReport]],
+  ) -> None:
+    """Adds new built-in queries to the fetcher."""
+    self.builtin_queries.update(builtin_queries)
 
   async def afetch(
     self,
     query_specification: str | query_editor.QueryElements,
-    args: dict[str, Any] | None = None,
+    args: query_editor.GarfQueryParameters | None = None,
     **kwargs: str,
   ) -> report.GarfReport:
     """Asynchronously fetches data from API based on query_specification.
@@ -84,7 +102,7 @@ class ApiReportFetcher:
   def fetch(
     self,
     query_specification: str | query_editor.QuerySpecification,
-    args: dict[str, Any] | None = None,
+    args: query_editor.GarfQueryParameters | None = None,
     **kwargs: str,
   ) -> report.GarfReport:
     """Fetches data from API based on query_specification.
@@ -101,42 +119,23 @@ class ApiReportFetcher:
       GarfExecutorException:
         When customer_ids are not provided or API returned error.
     """
+    if args is None:
+      args = query_editor.GarfQueryParameters()
     if not isinstance(query_specification, query_editor.QuerySpecification):
       query_specification = self.query_specification_builder(
         text=str(query_specification),
         args=args,
       )
     query = query_specification.generate()
+    if query.is_builtin_query:
+      if not (builtin_report := self.builtin_queries.get(query.title)):
+        raise query_editor.GarfBuiltInQueryError(
+          f'Cannot find the built-in query "{query.title}"'
+        )
+      return builtin_report(self, **kwargs)
+
     response = self.api_client.get_response(query, **kwargs)
     parsed_response = self.parser.parse_response(response, query)
     return report.GarfReport(
       results=parsed_response, column_names=query.column_names
     )
-
-
-class RestApiReportFetcher(ApiReportFetcher):
-  """Fetches data from an REST API endpoint.
-
-  Attributes:
-    api_client: Initialized RestApiClient.
-    parser: Type of parser to convert API response.
-  """
-
-  def __init__(
-    self,
-    endpoint: str,
-    parser: parsers.BaseParser = parsers.DictParser,
-    query_specification_builder: query_editor.QuerySpecification = (
-      query_editor.QuerySpecification
-    ),
-    **kwargs: str,
-  ) -> None:
-    """Instantiates RestApiReportFetcher.
-
-    Args:
-      endpoint: URL of API endpoint.
-      parser: Type of parser to convert API response.
-      query_specification_builder: Class to perform query parsing.
-    """
-    api_client = api_clients.RestApiClient(endpoint)
-    super().__init__(api_client, parser, query_specification_builder, **kwargs)

{garf_core-0.0.11 → garf_core-0.1.0}/garf_core.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: garf-core
-Version: 0.0.11
+Version: 0.1.0
 Summary: Abstracts fetching data from API based on provided SQL-like query.
-Author-email: "Google Inc. (gTech gPS CSE team)" <no-reply@google.com>
+Author-email: "Google Inc. (gTech gPS CSE team)" <no-reply@google.com>, Andrei Markin <andrey.markin.ppc@gmail.com>
 License: Apache 2.0
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.8
@@ -22,6 +22,7 @@ Requires-Dist: jinja2
 Requires-Dist: typing-extensions
 Requires-Dist: requests
 Requires-Dist: pyyaml
+Requires-Dist: pydantic
 Provides-Extra: pandas
 Requires-Dist: pandas; extra == "pandas"
 Provides-Extra: polars
@@ -39,15 +40,13 @@ Requires-Dist: garf-core[pandas,polars]; extra == "all"
 
 These abstractions are designed to be as modular and simple as possible:
 
-* `BaseApiClient` - an interface for connecting to APIs.
-* `BaseQuery` - encapsulates SQL-like request.
+* `BaseApiClient` - an interface for connecting to APIs. Check [default implementations](docs/builtin-functionality.md#apiclients)
+* `BaseParser` - an interface to parse results from the API. Check [default implementations](docs/builtin-functionality.md#parsers)
+* `ApiReportFetcher` - responsible for fetching and parsing data from reporting API. [Default implementations](docs/builtin-functionality.md#apireportfetchers)
+
 * `QuerySpecification` - parsed SQL-query into various elements.
-* `BaseParser` - an interface to parse results from the API. Have a couple of default implementations:
-    * `ListParser` - returns results from API as a raw list.
-    * `DictParser` - returns results from API as a formatted dict.
-        * `NumericDictParser` - returns results from API as a formatted dict with converted numeric values.
+* `BaseQuery` - protocol for all class based queries.
 * `GarfReport` - contains data from API in a format that is easy to write and interact with.
-* `ApiReportFetcher` - responsible for fetching and parsing data from reporting API.
 
 ## Installation
 

{garf_core-0.0.11 → garf_core-0.1.0}/garf_core.egg-info/SOURCES.txt

@@ -13,4 +13,7 @@ garf_core.egg-info/SOURCES.txt
 garf_core.egg-info/dependency_links.txt
 garf_core.egg-info/entry_points.txt
 garf_core.egg-info/requires.txt
-garf_core.egg-info/top_level.txt
+garf_core.egg-info/top_level.txt
+garf_core/fetchers/__init__.py
+garf_core/fetchers/fake.py
+garf_core/fetchers/rest.py

garf_core-0.1.0/garf_core.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[garf]
+fake = garf_core.fetchers.fake
+rest = garf_core.fetchers.rest

{garf_core-0.0.11 → garf_core-0.1.0}/garf_core.egg-info/requires.txt

@@ -3,6 +3,7 @@ jinja2
 typing-extensions
 requests
 pyyaml
+pydantic
 
 [all]
 garf-core[pandas,polars]

{garf_core-0.0.11 → garf_core-0.1.0}/pyproject.toml

@@ -10,9 +10,11 @@ dependencies = [
     "typing-extensions",
     "requests",
     "pyyaml",
+    "pydantic",
 ]
 authors = [
   {name = "Google Inc. (gTech gPS CSE team)", email = "no-reply@google.com"},
+  {name = "Andrei Markin", email = "andrey.markin.ppc@gmail.com"},
 ]
 requires-python = ">=3.8"
 description = "Abstracts fetching data from API based on provided SQL-like query."
@@ -37,7 +39,8 @@ dynamic=["version"]
 version = {attr = "garf_core.__version__"}
 
 [project.entry-points.garf]
-rest = "garf_core.report_fetcher"
+rest = "garf_core.fetchers.rest"
+fake = "garf_core.fetchers.fake"
 
 [project.optional-dependencies]
 pandas=[

garf_core-0.0.11/garf_core/api_clients.py

@@ -1,86 +0,0 @@
-# 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.
-"""Module for defining client to interact with API."""
-
-from __future__ import annotations
-
-import abc
-import dataclasses
-from collections.abc import Sequence
-
-import requests
-from typing_extensions import override
-
-from garf_core import exceptions
-
-
-@dataclasses.dataclass
-class GarfApiRequest:
-  """Base class for specifying request."""
-
-
-@dataclasses.dataclass
-class GarfApiResponse:
-  """Base class for specifying response."""
-
-  results: list
-
-
-class GarfApiError(exceptions.GarfError):
-  """API specific exception."""
-
-
-class BaseClient(abc.ABC):
-  """Base API client class."""
-
-  @abc.abstractmethod
-  def get_response(
-    self, request: GarfApiRequest = GarfApiRequest(), **kwargs: str
-  ) -> GarfApiResponse:
-    """Method for getting response."""
-
-
-class RestApiClient(BaseClient):
-  """Specifies REST client."""
-
-  OK = 200
-
-  def __init__(self, endpoint: str, **kwargs: str) -> None:
-    """Initializes RestApiClient."""
-    self.endpoint = endpoint
-    self.query_args = kwargs
-
-  @override
-  def get_response(
-    self, request: GarfApiRequest = GarfApiRequest(), **kwargs: str
-  ) -> GarfApiResponse:
-    response = requests.get(f'{self.endpoint}/{request.resource_name}')
-    if response.status_code == self.OK:
-      return GarfApiResponse(response.json())
-    raise GarfApiError('Failed to get data from API')
-
-
-class FakeApiClient(BaseClient):
-  """Fake class for specifying API client."""
-
-  def __init__(self, results: Sequence) -> None:
-    """Initializes FakeApiClient."""
-    self.results = list(results)
-
-  @override
-  def get_response(
-    self, request: GarfApiRequest = GarfApiRequest()
-  ) -> GarfApiResponse:
-    del request
-    return GarfApiResponse(results=self.results)

garf_core-0.0.11/garf_core.egg-info/entry_points.txt

@@ -1,2 +0,0 @@
-[garf]
-rest = garf_core.report_fetcher