garf-core 0.0.8__tar.gz → 0.0.10__tar.gz

{garf_core-0.0.8 → garf_core-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: garf-core
-Version: 0.0.8
+Version: 0.0.10
 Summary: Abstracts fetching data from API based on provided SQL-like query.
 Author-email: "Google Inc. (gTech gPS CSE team)" <no-reply@google.com>
 License: Apache 2.0
@@ -10,6 +10,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Operating System :: OS Independent
@@ -17,8 +18,10 @@ Classifier: License :: OSI Approved :: Apache Software License
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: python-dateutil
-Requires-Dist: jinja2==3.1.4
+Requires-Dist: jinja2
 Requires-Dist: typing-extensions
+Requires-Dist: requests
+Requires-Dist: pyyaml
 Provides-Extra: pandas
 Requires-Dist: pandas; extra == "pandas"
 Provides-Extra: polars

{garf_core-0.0.8 → garf_core-0.0.10}/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.8'
+__version__ = '0.0.10'

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core/api_clients.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# 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.
@@ -22,6 +22,8 @@ from collections.abc import Sequence
 import requests
 from typing_extensions import override
 
+from garf_core import exceptions
+
 
 @dataclasses.dataclass
 class GarfApiRequest:
@@ -35,7 +37,7 @@ class GarfApiResponse:
   results: list
 
 
-class GarfApiError(Exception):
+class GarfApiError(exceptions.GarfError):
   """API specific exception."""
 
 

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core/base_query.py

@@ -1,4 +1,4 @@
-# Copyright 2022 Google LLC
+# 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.

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core/exceptions.py

@@ -22,38 +22,10 @@
 # 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 exceptions."""
+"""Defines common exceptions for the garf-core library."""
 
 from __future__ import annotations
 
 
 class GarfError(Exception):
   """Base exception."""
-
-
-class GarfQueryException(GarfError):
-  """Base exception for Garf queries."""
-
-
-class GarfParserException(GarfError):
-  """Base exception for Garf parsers."""
-
-
-class GarfCustomizerException(GarfParserException):
-  """Specifies incorrect customizer."""
-
-
-class GarfVirtualColumnException(GarfParserException):
-  """Specifies incorrect virtual column type."""
-
-
-class GarfFieldException(GarfQueryException):
-  """Specifies incorrect Google Ads API field."""
-
-
-class GarfMacroException(GarfQueryException):
-  """Specifies incorrect macro in Garf query."""
-
-
-class GarfResourceException(GarfQueryException):
-  """Specifies incorrect resource name in Google Ads API."""

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core/parsers.py

@@ -1,4 +1,4 @@
-# Copyright 2022 Google LLC
+# 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.
@@ -11,11 +11,7 @@
 # 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 various parsing strategy for GoogleAdsRow elements.
-
-GoogleAdsRowParser parses a single GoogleAdsRow and applies different parsing
-strategies to each element of the row.
-"""
+"""Module for defining various parsing strategy for API response."""
 
 from __future__ import annotations
 
@@ -24,7 +20,7 @@ import contextlib
 import functools
 import operator
 from collections.abc import Mapping, MutableSequence
-from typing import Union
+from typing import Any, Union
 
 from typing_extensions import TypeAlias, override
 
@@ -34,44 +30,56 @@ ApiRowElement: TypeAlias = Union[int, float, str, bool, list, None]
 
 
 class BaseParser(abc.ABC):
-  @abc.abstractmethod
+  """An interface for all parsers to implement."""
+
   def parse_response(
-    self, response: api_clients.GarfApiResponse
+    self,
+    response: api_clients.GarfApiResponse,
+    query_specification: query_editor.BaseQueryElements,
   ) -> list[list[ApiRowElement]]:
     """Parses response."""
+    if not response.results:
+      return [[]]
+    results = []
+    for result in response.results:
+      results.append(self.parse_row(result, query_specification))
+    return results
+
+  @abc.abstractmethod
+  def parse_row(self, row, query_specification):
+    """Parses single row from response."""
 
 
 class ListParser(BaseParser):
+  """Returns API results as is."""
+
   @override
-  def parse_response(
+  def parse_row(
     self,
-    response: api_clients.GarfApiResponse,
+    row: list,
     query_specification: query_editor.BaseQueryElements,
   ) -> list[list[ApiRowElement]]:
-    del query_specification
-    return response.results
+    return row
 
 
 class DictParser(BaseParser):
+  """Extracts nested dict elements."""
+
   @override
-  def parse_response(
+  def parse_row(
     self,
-    response: api_clients.GarfApiResponse,
+    row: list,
     query_specification: query_editor.BaseQueryElements,
   ) -> list[list[ApiRowElement]]:
-    if not response.results:
-      return [[]]
-    if not isinstance(response.results[0], Mapping):
-      return GarfParserError
-    results = []
-    for result in response.results:
-      row = []
-      for field in query_specification.fields:
-        row.append(self.get_nested_field(result, field))
-      results.append(row)
-    return results
-
-  def get_nested_field(self, dictionary, key):
+    if not isinstance(row, Mapping):
+      raise GarfParserError
+    result = []
+    for field in query_specification.fields:
+      result.append(self.get_nested_field(row, field))
+    return result
+
+  def get_nested_field(self, dictionary: dict[str, Any], key: str):
+    """Returns nested fields from a dictionary."""
     key = key.split('.')
     try:
       return functools.reduce(operator.getitem, key, dictionary)
@@ -80,7 +88,11 @@ class DictParser(BaseParser):
 
 
 class NumericConverterDictParser(DictParser):
-  def get_nested_field(self, dictionary, key):
+  """Extracts nested dict elements with numerical conversions."""
+
+  def get_nested_field(self, dictionary: dict[str, Any], key: str):
+    """Extract nested field with int/float conversion."""
+
     def convert_field(value):
       for type_ in (int, float):
         with contextlib.suppress(ValueError):

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core/query_editor.py

@@ -29,6 +29,30 @@ from typing_extensions import Self
 from garf_core import exceptions
 
 
+class GarfQueryError(exceptions.GarfError):
+  """Base exception for Garf queries."""
+
+
+class GarfCustomizerError(GarfQueryError):
+  """Specifies incorrect customizer."""
+
+
+class GarfVirtualColumnError(GarfQueryError):
+  """Specifies incorrect virtual column type."""
+
+
+class GarfFieldError(GarfQueryError):
+  """Specifies incorrect fields from API."""
+
+
+class GarfMacroError(GarfQueryError):
+  """Specifies incorrect macro in Garf query."""
+
+
+class GarfResourceError(GarfQueryError):
+  """Specifies incorrect resource name in the query."""
+
+
 @dataclasses.dataclass
 class ProcessedField:
   """Helper class to store fields with its customizers.
@@ -141,7 +165,7 @@ class VirtualColumn:
         substitute_expression=substitute_expression.replace('.', '_'),
       )
     if not _is_quoted_string(field):
-      raise exceptions.GarfFieldException(f"Incorrect field '{field}'.")
+      raise GarfFieldError(f"Incorrect field '{field}'.")
     field = field.replace("'", '').replace('"', '')
     field = field.format(**macros) if macros else field
     return VirtualColumn(type='built-in', value=field)
@@ -183,9 +207,7 @@ class ExtractedLineElements:
     else:
       customizer = {}
     if virtual_column and not alias:
-      raise exceptions.GarfVirtualColumnException(
-        'Virtual attributes should be aliased'
-      )
+      raise GarfVirtualColumnError('Virtual attributes should be aliased')
     return ExtractedLineElements(
       field=_format_type_field_name(field)
       if not virtual_column and field
@@ -209,15 +231,14 @@ class BaseQueryElements:
   """Contains raw query and parsed elements.
 
   Attributes:
-      query_title: Title of the query that needs to be parsed.
-      query_text: Text of the query that needs to be parsed.
+      title: Title of the query that needs to be parsed.
+      text: Text of the query that needs to be parsed.
       resource_name: Name of Google Ads API reporting resource.
       fields: Ads API fields that need to be fetched.
       column_names: Friendly names for fields which are used when saving data
       column_names: Friendly names for fields which are used when saving data
       customizers: Attributes of fields that need to be be extracted.
       virtual_columns: Attributes of fields that need to be be calculated.
-      is_constant_resource: Whether resource considered a constant one.
       is_builtin_query: Whether query is built-in.
   """
 
@@ -234,6 +255,7 @@ class BaseQueryElements:
   virtual_columns: dict[str, VirtualColumn] = dataclasses.field(
     default_factory=dict
   )
+  is_builtin_query: bool = False
 
   def __eq__(self, other: BaseQueryElements) -> bool:  # noqa: D105
     return (
@@ -381,9 +403,7 @@ class QuerySpecification(CommonParametersMixin, TemplateProcessorMixin):
     try:
       self.query.text = query_text.format(**self.macros).strip()
     except KeyError as e:
-      raise exceptions.GarfMacroException(
-        f'No value provided for macro {str(e)}.'
-      ) from e
+      raise GarfMacroError(f'No value provided for macro {str(e)}.') from e
     return self
 
   def remove_comments(self) -> Self:
@@ -424,9 +444,7 @@ class QuerySpecification(CommonParametersMixin, TemplateProcessorMixin):
     ):
       self.query.resource_name = str(resource_name[0]).strip()
       return self
-    raise exceptions.GarfResourceException(
-      f'No resource found in query: {self.query.text}'
-    )
+    raise GarfResourceError(f'No resource found in query: {self.query.text}')
 
   def extract_fields(self) -> Self:
     for line in self._extract_query_lines():

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core/report.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# 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.
@@ -27,7 +27,7 @@ import json
 import warnings
 from collections import defaultdict
 from collections.abc import MutableSequence, Sequence
-from typing import Generator, Literal
+from typing import Generator, Literal, get_args
 
 from garf_core import exceptions, parsers, query_editor
 
@@ -414,8 +414,8 @@ class GarfReport:
       import polars as pl
     except ImportError as e:
       raise ImportError(
-        'Please install garf-io with Polars support '
-        '- `pip install garf-io[polars]`'
+        'Please install garf-core with Polars support '
+        '- `pip install garf-core[polars]`'
       ) from e
     return cls(
       results=df.to_numpy().tolist(), column_names=list(df.schema.keys())
@@ -438,11 +438,63 @@ class GarfReport:
       import pandas as pd
     except ImportError as e:
       raise ImportError(
-        'Please install garf-io with Pandas support '
-        '- `pip install garf-io[pandas]`'
+        'Please install garf-core with Pandas support '
+        '- `pip install garf-core[pandas]`'
       ) from e
     return cls(results=df.values.tolist(), column_names=list(df.columns.values))
 
+  @classmethod
+  def from_json(cls, json_str: str) -> GarfReport:
+    """Creates a GarfReport object from a JSON string.
+
+    Args:
+        json_str: JSON string representation of the data.
+
+    Returns:
+        Report build from a json string.
+
+    Raises:
+        TypeError: If any value in the JSON data is not a supported type.
+        ValueError: If `data` is a list but not all dictionaries
+        have the same keys.
+    """
+    data = json.loads(json_str)
+
+    def validate_value(value):
+      if not isinstance(value, get_args(parsers.ApiRowElement)):
+        raise TypeError(
+          f'Unsupported type {type(value)} for value {value}. '
+          'Expected types: int, float, str, bool, list, or None.'
+        )
+      return value
+
+    # Case 1: `data` is a dictionary
+    if isinstance(data, dict):
+      column_names = list(data.keys())
+      if not data.values():
+        results = []
+      else:
+        results = [[validate_value(value) for value in data.values()]]
+
+    # Case 2: `data` is a list of dictionaries, each representing a row
+    elif isinstance(data, list):
+      column_names = list(data[0].keys()) if data else []
+      for row in data:
+        if not isinstance(row, dict):
+          raise TypeError('All elements in the list must be dictionaries.')
+        if list(row.keys()) != column_names:
+          raise ValueError(
+            'All dictionaries must have consistent keys in the same order.'
+          )
+      results = [
+        [validate_value(value) for value in row.values()] for row in data
+      ]
+    else:
+      raise TypeError(
+        'Input JSON must be a dictionary or a list of dictionaries.'
+      )
+    return cls(results=results, column_names=column_names)
+
 
 class GarfRow:
   """Helper class to simplify iteration of GarfReport.

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core/report_fetcher.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLf
+# 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.
@@ -126,12 +126,17 @@ class RestApiReportFetcher(ApiReportFetcher):
     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.
     """
-    self.api_client = api_clients.RestApiClient(endpoint)
-    self.parser = parser()
+    api_client = api_clients.RestApiClient(endpoint)
+    super().__init__(api_client, parser, query_specification_builder, **kwargs)

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: garf-core
-Version: 0.0.8
+Version: 0.0.10
 Summary: Abstracts fetching data from API based on provided SQL-like query.
 Author-email: "Google Inc. (gTech gPS CSE team)" <no-reply@google.com>
 License: Apache 2.0
@@ -10,6 +10,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Operating System :: OS Independent
@@ -17,8 +18,10 @@ Classifier: License :: OSI Approved :: Apache Software License
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: python-dateutil
-Requires-Dist: jinja2==3.1.4
+Requires-Dist: jinja2
 Requires-Dist: typing-extensions
+Requires-Dist: requests
+Requires-Dist: pyyaml
 Provides-Extra: pandas
 Requires-Dist: pandas; extra == "pandas"
 Provides-Extra: polars

{garf_core-0.0.8 → garf_core-0.0.10}/garf_core.egg-info/requires.txt

@@ -1,6 +1,8 @@
 python-dateutil
-jinja2==3.1.4
+jinja2
 typing-extensions
+requests
+pyyaml
 
 [all]
 garf-core[pandas,polars]

{garf_core-0.0.8 → garf_core-0.0.10}/pyproject.toml

@@ -6,8 +6,10 @@ build-backend = "setuptools.build_meta"
 name = "garf-core"
 dependencies = [
     "python-dateutil",
-    "jinja2==3.1.4",
+    "jinja2",
     "typing-extensions",
+    "requests",
+    "pyyaml",
 ]
 authors = [
   {name = "Google Inc. (gTech gPS CSE team)", email = "no-reply@google.com"},
@@ -23,6 +25,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Operating System :: OS Independent",