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

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: garf-core
-Version: 0.0.10
+Version: 0.0.12
 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

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

{garf_core-0.0.10 → garf_core-0.0.12}/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.10 → garf_core-0.0.12}/garf_core/report.py

@@ -213,13 +213,22 @@ class GarfReport:
       ) from e
     return pd.DataFrame(data=self.results, columns=self.column_names)
 
-  def to_json(self) -> str:
+  def to_jsonl(self) -> str:
+    """Converts report to JSON Lines."""
+    return self.to_json(output='jsonl')
+
+  def to_json(self, output: Literal['json', 'jsonl'] = 'json') -> str:
     """Converts report to JSON.
 
+    Args:
+      output: Format of json file (json or jsonl).
+
     Returns:
         JSON from report results and column_names.
     """
-    return json.dumps(self.to_list(row_type='dict'))
+    if output == 'json':
+      return json.dumps(self.to_list(row_type='dict'))
+    return '\n'.join(json.dumps(row) for row in self.to_list(row_type='dict'))
 
   def get_value(
     self, column_index: int = 0, row_index: int = 0

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

@@ -11,17 +11,19 @@
 # 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.
 """
-# pylint: disable=C0330, g-bad-import-order, g-multiple-import
 
 from __future__ import annotations
 
 import logging
-from typing import Any
+from typing import Any, Callable
 
 from garf_core import (
   api_clients,
@@ -49,6 +51,8 @@ class ApiReportFetcher:
     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 +61,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 +98,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,12 +115,21 @@ 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(

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: garf-core
-Version: 0.0.10
+Version: 0.0.12
 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

{garf_core-0.0.10 → garf_core-0.0.12}/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.10 → garf_core-0.0.12}/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."