sql-testing-library 0.19.0__tar.gz → 0.20.0__tar.gz

{sql_testing_library-0.19.0 → sql_testing_library-0.20.0}/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.20.0 (2025-12-07)
+
+### Feat
+
+- add BigQueryMockTable class for explicit three-part naming (#134)
+
 ## 0.19.0 (2025-12-07)
 
 ### Feat

{sql_testing_library-0.19.0 → sql_testing_library-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-testing-library
-Version: 0.19.0
+Version: 0.20.0
 Summary: SQL Testing Framework for Python: Unit test SQL queries with mock data injection for BigQuery, Snowflake, Redshift, Athena, Trino, and DuckDB. Simplify data engineering ETL testing and analytics validation.
 License: MIT
 License-File: LICENSE
@@ -570,8 +570,16 @@ TestCase(
 #### Example Mock Table Implementations:
 
 ```python
-# BigQuery Mock Table
-class UsersMockTable(BaseMockTable):
+# BigQuery Mock Table (Recommended: Use BigQueryMockTable for clearer three-part naming)
+from sql_testing_library import BigQueryMockTable
+
+class UsersMockTable(BigQueryMockTable):
+    project_name = "test-project"
+    dataset_name = "test_dataset"
+    table_name = "users"
+
+# BigQuery Mock Table (Alternative: Use BaseMockTable with combined project.dataset)
+class UsersMockTableAlternative(BaseMockTable):
     def get_database_name(self) -> str:
         return "test-project.test_dataset"  # project.dataset format
 
@@ -1047,6 +1055,7 @@ The adapter_type parameter will use the configuration from the corresponding sec
 - Supports Google Cloud BigQuery service
 - Uses UNION ALL pattern for CTE creation with complex data types
 - Handles authentication via service account or application default credentials
+- **Special Feature**: `BigQueryMockTable` class for explicit three-part naming (project.dataset.table)
 
 #### Athena Adapter
 - Supports Amazon Athena service for querying data in S3
@@ -1085,6 +1094,94 @@ The adapter_type parameter will use the configuration from the corresponding sec
 - No authentication required - perfect for local development and testing
 - Excellent performance for analytical workloads
 
+### BigQuery-Specific: BigQueryMockTable
+
+BigQuery uses a three-part naming scheme (`project.dataset.table`) which doesn't fit naturally into the two-part `database.table` model used by most databases. The `BigQueryMockTable` class provides explicit support for BigQuery's naming convention.
+
+#### The Problem with BaseMockTable
+
+Using `BaseMockTable` for BigQuery requires awkwardly cramming the project and dataset together:
+
+```python
+# Awkward: Combines project.dataset into database_name
+class UsersMockTable(BaseMockTable):
+    def get_database_name(self) -> str:
+        return "test-project.test_dataset"  # Confusing!
+
+    def get_table_name(self) -> str:
+        return "users"
+```
+
+#### The Solution: BigQueryMockTable
+
+`BigQueryMockTable` makes BigQuery's three-part naming explicit and clear:
+
+```python
+from sql_testing_library import BigQueryMockTable
+
+class UsersMockTable(BigQueryMockTable):
+    project_name = "test-project"
+    dataset_name = "test_dataset"
+    table_name = "users"
+```
+
+#### Usage Examples
+
+**Basic Usage:**
+```python
+from sql_testing_library import BigQueryMockTable
+
+class UsersMockTable(BigQueryMockTable):
+    project_name = "my-project"
+    dataset_name = "analytics"
+    table_name = "users"
+
+class OrdersMockTable(BigQueryMockTable):
+    project_name = "my-project"
+    dataset_name = "analytics"
+    table_name = "orders"
+```
+
+**Avoid Repetition with Inheritance:**
+```python
+# Base class for all tables in the same project
+class MyProjectTable(BigQueryMockTable):
+    project_name = "my-project"
+
+# Subclasses only specify dataset and table
+class UsersTable(MyProjectTable):
+    dataset_name = "analytics"
+    table_name = "users"
+
+class OrdersTable(MyProjectTable):
+    dataset_name = "analytics"
+    table_name = "orders"
+```
+
+**Available Methods:**
+```python
+table = UsersMockTable([...])
+
+# BigQuery-specific methods
+table.get_project_name()           # "my-project"
+table.get_dataset_name()           # "analytics"
+table.get_fully_qualified_name()   # "my-project.analytics.users"
+
+# Backwards compatible methods (from BaseMockTable)
+table.get_database_name()          # "my-project.analytics"
+table.get_table_name()             # "users"
+table.get_qualified_name()         # "my-project.analytics.users"
+table.get_cte_alias()              # "my_project_analytics__users"
+```
+
+**Benefits:**
+- ✅ **Clear Semantics**: Each BigQuery component is explicit
+- ✅ **No Confusion**: No more cramming project.dataset together
+- ✅ **Type Safe**: Full type hints and IDE autocomplete
+- ✅ **Backwards Compatible**: Still implements all `BaseMockTable` methods
+- ✅ **Simple**: Just 3 class variables to set
+- ✅ **Flexible**: Use inheritance to share common properties
+
 **Default Behavior:**
 - If adapter_type is not specified in the TestCase or decorator, the library will use the adapter specified in the `[sql_testing]` section's `adapter` setting.
 - If no adapter is specified in the `[sql_testing]` section, it defaults to "bigquery".
@@ -1291,7 +1388,7 @@ The library automatically:
 - Injects mock data via CTEs or temp tables
 - Deserializes results to typed Python objects
 
-For detailed usage and configuration options, see the example files included.
+For detailed usage and configuration options, see the [documentation](https://gurmeetsaran.github.io/sqltesting/).
 
 ## Integration with Mocksmith
 
@@ -1326,7 +1423,7 @@ class Customer:
 customers = [Customer.mock() for _ in range(100)]
 ```
 
-See the [Mocksmith Integration Guide](docs/mocksmith_integration.md) and [examples](examples/mocksmith_integration_example.py) for detailed usage patterns.
+See the [Mocksmith Integration Guide](docs/mocksmith_integration.md) for detailed usage patterns.
 
 ## Known Limitations and TODOs
 

{sql_testing_library-0.19.0 → sql_testing_library-0.20.0}/README.md

@@ -510,8 +510,16 @@ TestCase(
 #### Example Mock Table Implementations:
 
 ```python
-# BigQuery Mock Table
-class UsersMockTable(BaseMockTable):
+# BigQuery Mock Table (Recommended: Use BigQueryMockTable for clearer three-part naming)
+from sql_testing_library import BigQueryMockTable
+
+class UsersMockTable(BigQueryMockTable):
+    project_name = "test-project"
+    dataset_name = "test_dataset"
+    table_name = "users"
+
+# BigQuery Mock Table (Alternative: Use BaseMockTable with combined project.dataset)
+class UsersMockTableAlternative(BaseMockTable):
     def get_database_name(self) -> str:
         return "test-project.test_dataset"  # project.dataset format
 
@@ -987,6 +995,7 @@ The adapter_type parameter will use the configuration from the corresponding sec
 - Supports Google Cloud BigQuery service
 - Uses UNION ALL pattern for CTE creation with complex data types
 - Handles authentication via service account or application default credentials
+- **Special Feature**: `BigQueryMockTable` class for explicit three-part naming (project.dataset.table)
 
 #### Athena Adapter
 - Supports Amazon Athena service for querying data in S3
@@ -1025,6 +1034,94 @@ The adapter_type parameter will use the configuration from the corresponding sec
 - No authentication required - perfect for local development and testing
 - Excellent performance for analytical workloads
 
+### BigQuery-Specific: BigQueryMockTable
+
+BigQuery uses a three-part naming scheme (`project.dataset.table`) which doesn't fit naturally into the two-part `database.table` model used by most databases. The `BigQueryMockTable` class provides explicit support for BigQuery's naming convention.
+
+#### The Problem with BaseMockTable
+
+Using `BaseMockTable` for BigQuery requires awkwardly cramming the project and dataset together:
+
+```python
+# Awkward: Combines project.dataset into database_name
+class UsersMockTable(BaseMockTable):
+    def get_database_name(self) -> str:
+        return "test-project.test_dataset"  # Confusing!
+
+    def get_table_name(self) -> str:
+        return "users"
+```
+
+#### The Solution: BigQueryMockTable
+
+`BigQueryMockTable` makes BigQuery's three-part naming explicit and clear:
+
+```python
+from sql_testing_library import BigQueryMockTable
+
+class UsersMockTable(BigQueryMockTable):
+    project_name = "test-project"
+    dataset_name = "test_dataset"
+    table_name = "users"
+```
+
+#### Usage Examples
+
+**Basic Usage:**
+```python
+from sql_testing_library import BigQueryMockTable
+
+class UsersMockTable(BigQueryMockTable):
+    project_name = "my-project"
+    dataset_name = "analytics"
+    table_name = "users"
+
+class OrdersMockTable(BigQueryMockTable):
+    project_name = "my-project"
+    dataset_name = "analytics"
+    table_name = "orders"
+```
+
+**Avoid Repetition with Inheritance:**
+```python
+# Base class for all tables in the same project
+class MyProjectTable(BigQueryMockTable):
+    project_name = "my-project"
+
+# Subclasses only specify dataset and table
+class UsersTable(MyProjectTable):
+    dataset_name = "analytics"
+    table_name = "users"
+
+class OrdersTable(MyProjectTable):
+    dataset_name = "analytics"
+    table_name = "orders"
+```
+
+**Available Methods:**
+```python
+table = UsersMockTable([...])
+
+# BigQuery-specific methods
+table.get_project_name()           # "my-project"
+table.get_dataset_name()           # "analytics"
+table.get_fully_qualified_name()   # "my-project.analytics.users"
+
+# Backwards compatible methods (from BaseMockTable)
+table.get_database_name()          # "my-project.analytics"
+table.get_table_name()             # "users"
+table.get_qualified_name()         # "my-project.analytics.users"
+table.get_cte_alias()              # "my_project_analytics__users"
+```
+
+**Benefits:**
+- ✅ **Clear Semantics**: Each BigQuery component is explicit
+- ✅ **No Confusion**: No more cramming project.dataset together
+- ✅ **Type Safe**: Full type hints and IDE autocomplete
+- ✅ **Backwards Compatible**: Still implements all `BaseMockTable` methods
+- ✅ **Simple**: Just 3 class variables to set
+- ✅ **Flexible**: Use inheritance to share common properties
+
 **Default Behavior:**
 - If adapter_type is not specified in the TestCase or decorator, the library will use the adapter specified in the `[sql_testing]` section's `adapter` setting.
 - If no adapter is specified in the `[sql_testing]` section, it defaults to "bigquery".
@@ -1231,7 +1328,7 @@ The library automatically:
 - Injects mock data via CTEs or temp tables
 - Deserializes results to typed Python objects
 
-For detailed usage and configuration options, see the example files included.
+For detailed usage and configuration options, see the [documentation](https://gurmeetsaran.github.io/sqltesting/).
 
 ## Integration with Mocksmith
 
@@ -1266,7 +1363,7 @@ class Customer:
 customers = [Customer.mock() for _ in range(100)]
 ```
 
-See the [Mocksmith Integration Guide](docs/mocksmith_integration.md) and [examples](examples/mocksmith_integration_example.py) for detailed usage patterns.
+See the [Mocksmith Integration Guide](docs/mocksmith_integration.md) for detailed usage patterns.
 
 ## Known Limitations and TODOs
 

{sql_testing_library-0.19.0 → sql_testing_library-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "sql-testing-library"
-version = "0.19.0"
+version = "0.20.0"
 description = "SQL Testing Framework for Python: Unit test SQL queries with mock data injection for BigQuery, Snowflake, Redshift, Athena, Trino, and DuckDB. Simplify data engineering ETL testing and analytics validation."
 authors = ["Gurmeet Saran <gurmeetx@gmail.com>", "Kushal Thakkar <kushal.thakkar@gmail.com>"]
 maintainers = ["Gurmeet Saran <gurmeetx@gmail.com>", "Kushal Thakkar <kushal.thakkar@gmail.com>"]

{sql_testing_library-0.19.0 → sql_testing_library-0.20.0}/src/sql_testing_library/__init__.py

@@ -10,7 +10,7 @@ from ._exceptions import (
     SQLTestingError,  # noqa: F401
     TypeConversionError,  # noqa: F401
 )
-from ._mock_table import BaseMockTable  # noqa: F401
+from ._mock_table import BaseMockTable, BigQueryMockTable  # noqa: F401
 from ._pytest_plugin import sql_test  # noqa: F401
 
 
@@ -27,12 +27,13 @@ try:
 except ImportError:
     __all__ = []
 
-__version__ = "0.19.0"
+__version__ = "0.20.0"
 __all__.extend(
     [
         "SQLTestFramework",
         "TestCase",
         "BaseMockTable",
+        "BigQueryMockTable",
         "DatabaseAdapter",
         "sql_test",
         "SQLTestingError",

{sql_testing_library-0.19.0 → sql_testing_library-0.20.0}/src/sql_testing_library/_mock_table.py

@@ -204,3 +204,94 @@ class BaseMockTable(ABC):
         db_name = self.get_database_name().replace("-", "_").replace(".", "_")
         table_name = self.get_table_name().replace("-", "_").replace(".", "_")
         return f"{db_name}__{table_name}"
+
+
+class BigQueryMockTable(BaseMockTable):
+    """Mock table specifically for BigQuery with three-part naming support.
+
+    BigQuery uses a three-part naming scheme: project.dataset.table
+    This class makes it explicit and provides better semantics than cramming
+    project and dataset into the generic database_name field.
+
+    Two usage patterns are supported:
+
+    Usage - Class variables for table definition:
+        >>> class UsersMockTable(BigQueryMockTable):
+        ...     project_name = "my-project"
+        ...     dataset_name = "analytics"
+        ...     table_name = "users"
+    """
+
+    # Class variables that subclasses must set (mandatory)
+    project_name: str
+    dataset_name: str
+    table_name: str
+
+    def get_bigquery_project(self) -> str:
+        """Return the BigQuery project name from class variable.
+
+        Returns:
+            BigQuery project ID
+
+        Raises:
+            AttributeError: If project_name class variable not set
+        """
+        return self.project_name
+
+    def get_bigquery_dataset(self) -> str:
+        """Return the BigQuery dataset name from class variable.
+
+        Returns:
+            BigQuery dataset name
+
+        Raises:
+            AttributeError: If dataset_name class variable not set
+        """
+        return self.dataset_name
+
+    def get_bigquery_table(self) -> str:
+        """Return the BigQuery table name from class variable.
+
+        Returns:
+            BigQuery table name
+
+        Raises:
+            AttributeError: If table_name class variable not set
+        """
+        return self.table_name
+
+    def get_project_name(self) -> str:
+        """Return the BigQuery project name (alias for get_bigquery_project)."""
+        return self.get_bigquery_project()
+
+    def get_dataset_name(self) -> str:
+        """Return the BigQuery dataset name (alias for get_bigquery_dataset)."""
+        return self.get_bigquery_dataset()
+
+    def get_database_name(self) -> str:
+        """Return database name (for BigQuery, this is project.dataset).
+
+        This implements the BaseMockTable abstract method by combining
+        project and dataset to maintain backwards compatibility with
+        the two-part naming assumption in the base class.
+        """
+        return f"{self.get_bigquery_project()}.{self.get_bigquery_dataset()}"
+
+    def get_table_name(self) -> str:
+        """Return the table name (alias for get_bigquery_table)."""
+        return self.get_bigquery_table()
+
+    def get_fully_qualified_name(self) -> str:
+        """Return the three-part BigQuery table reference.
+
+        Returns:
+            Fully qualified table name in format: project.dataset.table
+
+        Example:
+            >>> table.get_fully_qualified_name()
+            'my-project.analytics.users'
+        """
+        project = self.get_bigquery_project()
+        dataset = self.get_bigquery_dataset()
+        table = self.get_bigquery_table()
+        return f"{project}.{dataset}.{table}"