garf-core 0.0.12__tar.gz → 0.1.1__tar.gz

{garf_core-0.0.12 → garf_core-0.1.1}/PKG-INFO

@@ -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.0.12 → garf_core-0.1.1}/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.12 → garf_core-0.1.1}/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-0.1.1/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.1/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.1/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-0.1.1/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-0.0.12 → garf_core-0.1.1}/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 → garf_core-0.1.1}/garf_core.egg-info/PKG-INFO

@@ -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.0.12 → garf_core-0.1.1}/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.1/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.12 → garf_core-0.1.1}/pyproject.toml

@@ -39,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.12/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.12/garf_core.egg-info/entry_points.txt

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