[core] tests: add tests for base_query

* Ensure that pydantic initialization is supported
* Update documentation to add pydantic initialization and remove old style initialization

Author: AndreyMarkinPPC

docs/usage/queries.md

@@ -141,7 +141,7 @@ WHERE
     segments.date BETWEEN "{start_date}" AND "{end_date}"
 ```
 
-When this query is executed it's expected that two macros `--macros.start_date=...` and `--macros.end_date=...` are supplied to `garf`.
+When this query is executed it's expected that two macros `--macro.start_date=...` and `--macro.end_date=...` are supplied to `garf`.
 
 ### Macros in virtual columns
 
@@ -216,62 +216,94 @@ SELECT * FROM builtin.builtin_query_name
 
 ## Queries as Python objects
 
-```python
-from garf_core.base_query import BaseQuery
-from garf_io import reader
+You can define queries in multiple ways.
 
+### As strings
 
-# 1. define query as a string an save in a variable
+```python
 query_string = "SELECT campaign.id FROM campaign"
+```
+### As files
+
+#### Local
+```python
+from garf_io import reader
 
-# 2. define path to a query file and read from it
-# path can be local
 query_path = "path/to/query.sql"
-# or remote
+
+# Instantiate reader
+reader_client = reader.FileReader()
+# And read from the path
+query = reader_client.read(query_path)
+```
+#### Remote
+```python
+from garf_io import reader
+
 query_path = "gs://PROJECT_ID/path/to/query.sql"
 
 # Instantiate reader
 reader_client = reader.FileReader()
 # And read from the path
 query = reader_client.read(query_path)
+```
 
-# 3. define query as a class
+### As dataclasses
+```python
+from dataclasses import dataclass
+
+from garf_core.base_query import BaseQuery
 
-# Native style
+@dataclass
 class Campaigns(BaseQuery):
   query_text  = """
     SELECT
       campaign.id
     FROM campaign
     WHERE campaign.status = {status}
     """
+  status: str = "ENABLED"
 
-  def __init__(self, status: str = "ENABLED") -> None:
-    self.status = status
+query = Campaigns(status='DISABLED')
+```
 
-# Dataclass style
-from dataclasses import dataclass
 
-@dataclass
-class Campaigns(BaseQuery):
-  query_text  = """
+### As Pydantic objects
+
+```python
+from typing import ClassVar
+from pydantic import BaseModel
+
+from garf_core.base_query import BaseQuery
+
+class Campaigns(BaseModel, BaseQuery):
+  query_text: ClassVar[str]  = """
     SELECT
       campaign.id
     FROM campaign
     WHERE campaign.status = {status}
     """
   status: str = "ENABLED"
 
-# Old style
+query = Campaigns(status='DISABLED')
+```
+
+### As plain python classes
+
+```python
+from garf_core.base_query import BaseQuery
+from garf_io import reader
+
 class Campaigns(BaseQuery):
-  def __init__(self, status: str = "ENABLED"):
-    self.query_text = f"""
+  query_text  = """
     SELECT
       campaign.id
     FROM campaign
     WHERE campaign.status = {status}
     """
 
-active_campaigns = report_fetcher.fetch(Campaigns())
-inactive_campaigns = report_fetcher.fetch(Campaigns("INACTIVE"))
+  def __init__(self, status: str = "ENABLED") -> None:
+    self.status = status
+
+query = Campaigns(status='DISABLED')
 ```

libs/core/tests/unit/test_base_query.py

@@ -0,0 +1,71 @@
+# 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.
+
+import dataclasses
+from typing import ClassVar
+
+import pydantic
+from garf_core import base_query
+
+
+class TestBaseQuery:
+  def test_native_initialization(self):
+    class TestQuery(base_query.BaseQuery):
+      query_text = 'SELECT metric FROM resource WHERE status = {status}'
+
+      def __init__(self, status: str = 'ENABLED'):
+        self.status = status
+
+    test_query = TestQuery()
+
+    assert (
+      str(test_query) == 'SELECT metric FROM resource WHERE status = ENABLED'
+    )
+
+  def test_dataclass_initialization(self):
+    @dataclasses.dataclass
+    class TestQuery(base_query.BaseQuery):
+      query_text = 'SELECT metric FROM resource WHERE status = {status}'
+      status: str = 'ENABLED'
+
+    test_query = TestQuery()
+
+    assert (
+      str(test_query) == 'SELECT metric FROM resource WHERE status = ENABLED'
+    )
+
+  def test_old_initialization(self):
+    class TestQuery(base_query.BaseQuery):
+      def __init__(self, status: str = 'ENABLED'):
+        self.query_text = 'SELECT metric FROM resource WHERE status = {status}'
+        self.status = status
+
+    test_query = TestQuery()
+
+    assert (
+      str(test_query) == 'SELECT metric FROM resource WHERE status = ENABLED'
+    )
+
+  def test_pydantic_initialization(self):
+    class TestQuery(base_query.BaseQuery, pydantic.BaseModel):
+      query_text: ClassVar[str] = (
+        'SELECT metric FROM resource WHERE status = {status}'
+      )
+      status: str = 'ENABLED'
+
+    test_query = TestQuery()
+
+    assert (
+      str(test_query) == 'SELECT metric FROM resource WHERE status = ENABLED'
+    )