garf-core 0.0.12__py3-none-any.whl → 0.1.1__py3-none-any.whl

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.1'

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 @@ class RestApiClient(BaseClient):
 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

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/fetchers/fake.py

@@ -0,0 +1,80 @@
+# 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 collections.abc import Sequence
+from typing import Any
+
+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,
+    api_client: api_clients.FakeApiClient | 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 api_client and not (
+      data_location := json_location or csv_location or data_location
+    ):
+      raise report_fetcher.ApiReportFetcherError(
+        'Missing fake data for the fetcher.'
+      )
+    if not api_client:
+      api_client = api_clients.FakeApiClient.from_file(data_location)
+    super().__init__(api_client, parser, query_specification_builder, **kwargs)
+
+  @classmethod
+  def from_data(cls, data: Sequence[dict[str, Any]]) -> FakeApiReportFetcher:
+    """Initializes FakeApiReportFetcher from a sequence of data."""
+    return FakeApiReportFetcher(
+      api_client=api_clients.FakeApiClient(results=data)
+    )
+
+  @classmethod
+  def from_csv(
+    cls, file_location: str | os.PathLike[str]
+  ) -> FakeApiReportFetcher:
+    """Initializes FakeApiReportFetcher from a csv file."""
+    return FakeApiReportFetcher(csv_location=file_location)
+
+  @classmethod
+  def from_json(
+    cls, file_location: str | os.PathLike[str]
+  ) -> FakeApiReportFetcher:
+    """Initializes FakeApiReportFetcher from a json file."""
+    return FakeApiReportFetcher(json_location=file_location)

garf_core/fetchers/rest.py

@@ -0,0 +1,71 @@
+# 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,
+    api_client: api_clients.RestApiClient | None = None,
+    parser: parsers.BaseParser = parsers.DictParser,
+    query_specification_builder: query_editor.QuerySpecification = (
+      query_editor.QuerySpecification
+    ),
+    endpoint: str | None = None,
+    **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.
+    """
+    if not api_client and not endpoint:
+      raise report_fetcher.ApiReportFetcherError(
+        'Missing api_client or endpoint for the fetcher.'
+      )
+    if not api_client:
+      api_client = api_clients.RestApiClient(endpoint)
+    super().__init__(api_client, parser, query_specification_builder, **kwargs)
+
+  @classmethod
+  def from_endpoint(cls, endpoint: str) -> RestApiReportFetcher:
+    """Initializes RestApiReportFetcher: from an API endpoint."""
+    return RestApiReportFetcher(
+      api_client=api_clients.RestApiClient(endpoint=endpoint)
+    )

garf_core/report_fetcher.py

@@ -16,17 +16,17 @@
 
 """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.
 """
 
 from __future__ import annotations
 
 import logging
-from typing import Any, Callable
+from typing import Callable
 
 from garf_core import (
   api_clients,
+  exceptions,
   parsers,
   query_editor,
   report,
@@ -35,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.
 
@@ -47,7 +51,7 @@ 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
     ),
@@ -135,31 +139,3 @@ class ApiReportFetcher:
     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.12.dist-info → garf_core-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: garf-core
-Version: 0.0.12
+Version: 0.1.1
 Summary: Abstracts fetching data from API based on provided SQL-like query.
 Author-email: "Google Inc. (gTech gPS CSE team)" <no-reply@google.com>, Andrei Markin <andrey.markin.ppc@gmail.com>
 License: Apache 2.0
@@ -40,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.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+garf_core/__init__.py,sha256=5D5GNZp_18xDdFHuq7q1jn0HbR0-HD0s4vn0qzAAGKo,598
+garf_core/api_clients.py,sha256=k4vjFsA3JOx7Hp_pXIQNwzMXqq4u4dDcz-ddkJC0JhI,4651
+garf_core/base_query.py,sha256=ZDAw2ojmismXRO0HXEvKDukpS7OAc7390LnM8kvCSCY,1201
+garf_core/exceptions.py,sha256=Gzvkl2M-rA_XQRAMd3CC62KHeFQE_b6uby0fD0pouw4,1269
+garf_core/parsers.py,sha256=Uj7aT7roYUofivrBKVKWfcSeG37oYGGLIJ-op2C3hZc,3238
+garf_core/query_editor.py,sha256=lA1aMFc_1wo6e2CyVISarnZxtH2jnKkuZfJecQqslDg,17191
+garf_core/report.py,sha256=2z4tUR5mg29CkwodGaFIXs8Vpo2DCyyzwJWXhBrT0R4,19910
+garf_core/report_fetcher.py,sha256=o6YT_o0t9EPutiJk9R637lQabkHSaOrzoF2ciOmpQPA,4560
+garf_core/fetchers/__init__.py,sha256=_cSjg1D5RhUKxaVeVbaDdb8AAoI9glKJXgN5H4qXFkw,783
+garf_core/fetchers/fake.py,sha256=fgJjxuHyd6EIUflUtj8r_HfaMS1YTDrOqDlaj6Kvbjs,2584
+garf_core/fetchers/rest.py,sha256=-5B2-Ck_t3hG99ym59AKwlzctiDxRFI2Nnc8STBxRDo,2201
+garf_core-0.1.1.dist-info/METADATA,sha256=OY4D0XX-hTCKypRrrea9bBYuqpR87Z58Y5WK35X31zo,2443
+garf_core-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+garf_core-0.1.1.dist-info/entry_points.txt,sha256=u4h-ujHO1hbxVXRQzwcC4ftju9_KBYtq5mCLKEBHMj0,69
+garf_core-0.1.1.dist-info/top_level.txt,sha256=Gj-Zp7fM2turGut5vTJuo5xEcKfow7cTLX3y3WFfNgA,10
+garf_core-0.1.1.dist-info/RECORD,,

garf_core-0.1.1.dist-info/entry_points.txt

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

garf_core-0.0.12.dist-info/RECORD

@@ -1,13 +0,0 @@
-garf_core/__init__.py,sha256=ctwikDDSLAUSKCYv_lF4MLeza_na29fMcepnV6sNJrY,599
-garf_core/api_clients.py,sha256=S7Ldmgf0H9Vew2BdfG3Yh6imkhdnr8ix_YHKJmGln-U,2280
-garf_core/base_query.py,sha256=ZDAw2ojmismXRO0HXEvKDukpS7OAc7390LnM8kvCSCY,1201
-garf_core/exceptions.py,sha256=Gzvkl2M-rA_XQRAMd3CC62KHeFQE_b6uby0fD0pouw4,1269
-garf_core/parsers.py,sha256=Uj7aT7roYUofivrBKVKWfcSeG37oYGGLIJ-op2C3hZc,3238
-garf_core/query_editor.py,sha256=lA1aMFc_1wo6e2CyVISarnZxtH2jnKkuZfJecQqslDg,17191
-garf_core/report.py,sha256=2z4tUR5mg29CkwodGaFIXs8Vpo2DCyyzwJWXhBrT0R4,19910
-garf_core/report_fetcher.py,sha256=JK0k-svFQYCbSBYppgHCwuov5mW6_6CgYQhWusHlgXI,5269
-garf_core-0.0.12.dist-info/METADATA,sha256=UZaXQ3kk5mtm9c7-V6dgRicEIOLjW3CcWoMtz5givu4,2494
-garf_core-0.0.12.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-garf_core-0.0.12.dist-info/entry_points.txt,sha256=ODxSZXwWEIXQAjRwBQsBJ6GYw8oPK6DYTo0oDVkKCpo,39
-garf_core-0.0.12.dist-info/top_level.txt,sha256=Gj-Zp7fM2turGut5vTJuo5xEcKfow7cTLX3y3WFfNgA,10
-garf_core-0.0.12.dist-info/RECORD,,

garf_core-0.0.12.dist-info/entry_points.txt

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