[core] feat: add fake report fetcher

* Update FakeApiClient to support initializating from csv and json files
* Add FakeApiReportFetcher class and expose with with `fake` alias
* Ensure that default parsers is DictParser for all ApiReportFetchers
* Add tests for fake report fetcher and api client
* Bump library to version 0.1.0

Author: AndreyMarkinPPC

libs/garf_core/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
 

libs/garf_core/docs/builtin-functionality.md

@@ -0,0 +1,53 @@
+# `garf_core` built-in funtionality
+
+Apart from defining such interfaces as `BaseApiClient`, `BaseParser`, `ApiReportFetcher`, etc.
+`garf_core` comes with several built-in implementations.
+
+## Parsers
+
+* `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.
+
+## ApiClients
+
+* `FakeApiClient` - initializes API responses based on some predefined set of data. \
+  You can either pass data to it directly (as a list of dicts) or load them from JSON / CSV file.
+
+  ```python
+  from garf_core.api_clients import FakeApiClient
+
+
+  api_client = FakeApiClient(data=[{'field': 'value'}]
+  api_client = FakeApiClient.from_csv('path/to/csv')
+  api_client = FakeApiClient.from_json('path/to/json')
+  ```
+
+* `RestApiClient` - gets data from remote / local API endpoint.
+  ```python
+  from garf_core.api_clients import RestApiClient
+
+
+  api_client = RestApiClient(endpoint='http://localhost:3000/api/resource')
+  ```
+
+## ApiReportFetchers
+
+* `FakeApiReportFetcher` - fetches data based on provided data or load them from csv / json file.
+
+  ```python
+  from garf_core.fetchers import FakeApiReportFetcher
+
+
+  fetcher = FakeApiApiReportFetcher(data=[{'field': 'value'}]
+  fetcher = FakeApiApiReportFetcher.from_csv('path/to/csv')
+  fetcher = FakeApiApiReportFetcher.from_json('path/to/json')
+  ```
+* `RestApiReportFetcher` - fetches data from specified API endpoint.
+
+  ```python
+  from garf_core.fetchers import RestApiReportFetcher
+
+
+  fetcher = RestApiApiReportFetcher(endpoint='http://localhost:8000/api/resource')
+  ```

libs/garf_core/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.12'
+__version__ = '0.1.0'

libs/garf_core/garf_core/api_clients.py

@@ -16,8 +16,14 @@
 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
@@ -74,13 +80,93 @@ def get_response(
 class FakeApiClient(BaseClient):
   """Fake class for specifying API client."""
 
-  def __init__(self, results: Sequence) -> None:
+  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()
+    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

libs/garf_core/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',
+]

libs/garf_core/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)

libs/garf_core/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)