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

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

@@ -5,6 +5,29 @@ 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
+
+- reorganize documentation navigation for better learning flow
+- comprehensive SEO optimization for better search visibility
+- restrict CodeCov uploads to master branch only
+- enable CodeCov carryforward for all coverage flags
+
+### Fix
+
+- add support for Python 3.10+ pipe-none (X | None) union syntax (#133)
+- sanitize CTE aliases and sync package version (#132)
+- align robots.txt and sitemap with Google's official guidelines
+- shorten page titles for better readability and display
+- optimize robots.txt for better Google Search Console compatibility
+
 ## 0.18.0 (2025-12-01)
 
 ### Feat

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-testing-library
-Version: 0.18.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.18.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.18.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.18.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>"]
@@ -306,3 +306,6 @@ update_changelog_on_bump = true
 major_version_zero = true
 changelog_merge_prerelease = true
 changelog_start_rev = "0.1.0"
+version_files = [
+    "src/sql_testing_library/__init__.py:__version__"
+]

{sql_testing_library-0.18.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.3.0"
+__version__ = "0.20.0"
 __all__.extend(
     [
         "SQLTestFramework",
         "TestCase",
         "BaseMockTable",
+        "BigQueryMockTable",
         "DatabaseAdapter",
         "sql_test",
         "SQLTestingError",

{sql_testing_library-0.18.0 → sql_testing_library-0.20.0}/src/sql_testing_library/_adapters/bigquery.py

@@ -10,7 +10,6 @@ from typing import (
     Optional,
     Tuple,
     Type,
-    Union,
     get_args,
     get_type_hints,
 )
@@ -22,7 +21,7 @@ if TYPE_CHECKING:
 
 # Heavy imports moved to function level for better performance
 from .._mock_table import BaseMockTable
-from .._types import BaseTypeConverter
+from .._types import BaseTypeConverter, is_union_type
 from .base import DatabaseAdapter
 
 
@@ -247,9 +246,9 @@ class BigQueryAdapter(DatabaseAdapter):
 
         schema = []
         for col_name, col_type in column_types.items():
-            # Handle Optional types
-            if hasattr(col_type, "__origin__") and col_type.__origin__ is Union:
-                # Extract the non-None type from Optional[T]
+            # Handle Optional types (both Optional[X] and X | None)
+            if is_union_type(col_type):
+                # Extract the non-None type from Optional[T] or T | None
                 non_none_types = [arg for arg in get_args(col_type) if arg is not type(None)]
                 if non_none_types:
                     col_type = non_none_types[0]
@@ -319,9 +318,9 @@ class BigQueryAdapter(DatabaseAdapter):
         type_hints = get_type_hints(struct_type)
 
         for field_name, field_type in type_hints.items():
-            # Handle Optional types
-            if hasattr(field_type, "__origin__") and field_type.__origin__ is Union:
-                # Extract the non-None type from Optional[T]
+            # Handle Optional types (both Optional[X] and X | None)
+            if is_union_type(field_type):
+                # Extract the non-None type from Optional[T] or T | None
                 non_none_types = [arg for arg in get_args(field_type) if arg is not type(None)]
                 if non_none_types:
                     field_type = non_none_types[0]
@@ -388,9 +387,9 @@ class BigQueryAdapter(DatabaseAdapter):
         column_types = mock_table.get_column_types()
 
         for col_name, col_type in column_types.items():
-            # Handle Optional types
-            if hasattr(col_type, "__origin__") and col_type.__origin__ is Union:
-                # Extract the non-None type from Optional[T]
+            # Handle Optional types (both Optional[X] and X | None)
+            if is_union_type(col_type):
+                # Extract the non-None type from Optional[T] or T | None
                 non_none_types = [arg for arg in get_args(col_type) if arg is not type(None)]
                 if non_none_types:
                     col_type = non_none_types[0]

{sql_testing_library-0.18.0 → sql_testing_library-0.20.0}/src/sql_testing_library/_adapters/duckdb.py

@@ -10,7 +10,6 @@ from typing import (
     Optional,
     Tuple,
     Type,
-    Union,
     get_args,
     get_type_hints,
 )
@@ -22,7 +21,7 @@ if TYPE_CHECKING:
 
 # Heavy imports moved to function level for better performance
 from .._mock_table import BaseMockTable
-from .._types import BaseTypeConverter
+from .._types import BaseTypeConverter, is_union_type
 from .base import DatabaseAdapter
 
 
@@ -237,9 +236,9 @@ class DuckDBAdapter(DatabaseAdapter):
 
         column_defs = []
         for col_name, col_type in column_types.items():
-            # Handle Optional types
-            if hasattr(col_type, "__origin__") and col_type.__origin__ is Union:
-                # Extract the non-None type from Optional[T]
+            # Handle Optional types (both Optional[X] and X | None)
+            if is_union_type(col_type):
+                # Extract the non-None type from Optional[T] or T | None
                 non_none_types = [arg for arg in get_args(col_type) if arg is not type(None)]
                 if non_none_types:
                     col_type = non_none_types[0]
@@ -301,9 +300,9 @@ class DuckDBAdapter(DatabaseAdapter):
         field_defs = []
 
         for field_name, field_type in type_hints.items():
-            # Handle Optional types
-            if hasattr(field_type, "__origin__") and field_type.__origin__ is Union:
-                # Extract the non-None type from Optional[T]
+            # Handle Optional types (both Optional[X] and X | None)
+            if is_union_type(field_type):
+                # Extract the non-None type from Optional[T] or T | None
                 non_none_types = [arg for arg in get_args(field_type) if arg is not type(None)]
                 if non_none_types:
                     field_type = non_none_types[0]
@@ -360,9 +359,9 @@ class DuckDBAdapter(DatabaseAdapter):
         column_types = mock_table.get_column_types()
 
         for col_name, col_type in column_types.items():
-            # Handle Optional types
-            if hasattr(col_type, "__origin__") and col_type.__origin__ is Union:
-                # Extract the non-None type from Optional[T]
+            # Handle Optional types (both Optional[X] and X | None)
+            if is_union_type(col_type):
+                # Extract the non-None type from Optional[T] or T | None
                 non_none_types = [arg for arg in get_args(col_type) if arg is not type(None)]
                 if non_none_types:
                     col_type = non_none_types[0]

{sql_testing_library-0.18.0 → sql_testing_library-0.20.0}/src/sql_testing_library/_adapters/presto.py

@@ -2,10 +2,10 @@
 
 from datetime import date, datetime
 from decimal import Decimal
-from typing import Any, List, Tuple, Type, Union, get_args
+from typing import Any, List, Tuple, Type, get_args
 
 from .._mock_table import BaseMockTable
-from .._types import BaseTypeConverter, is_struct_type
+from .._types import BaseTypeConverter, is_struct_type, is_union_type
 from .base import DatabaseAdapter
 
 
@@ -77,9 +77,9 @@ class PrestoBaseAdapter(DatabaseAdapter):
         """Convert Python type to SQL type string."""
         from .._sql_utils import get_sql_type_string
 
-        # Handle Optional types
-        if hasattr(python_type, "__origin__") and python_type.__origin__ is Union:
-            # Extract the non-None type from Optional[T]
+        # Handle Optional types (both Optional[X] and X | None)
+        if is_union_type(python_type):
+            # Extract the non-None type from Optional[T] or T | None
             non_none_types = [arg for arg in get_args(python_type) if arg is not type(None)]
             if non_none_types:
                 python_type = non_none_types[0]
@@ -164,8 +164,8 @@ class PrestoBaseAdapter(DatabaseAdapter):
 
             # Handle Optional types by extracting the non-None type for proper formatting
             actual_type = col_type
-            if hasattr(col_type, "__origin__") and col_type.__origin__ is Union:
-                # Extract the non-None type from Optional[T]
+            if is_union_type(col_type):
+                # Extract the non-None type from Optional[T] or T | None
                 non_none_types = [arg for arg in get_args(col_type) if arg is not type(None)]
                 if non_none_types:
                     actual_type = non_none_types[0]
@@ -186,8 +186,8 @@ class PrestoBaseAdapter(DatabaseAdapter):
 
                 # Handle Optional types by extracting the non-None type for proper formatting
                 actual_type = col_type
-                if hasattr(col_type, "__origin__") and col_type.__origin__ is Union:
-                    # Extract the non-None type from Optional[T]
+                if is_union_type(col_type):
+                    # Extract the non-None type from Optional[T] or T | None
                     non_none_types = [arg for arg in get_args(col_type) if arg is not type(None)]
                     if non_none_types:
                         actual_type = non_none_types[0]

{sql_testing_library-0.18.0 → sql_testing_library-0.20.0}/src/sql_testing_library/_adapters/redshift.py

@@ -2,7 +2,7 @@
 
 from datetime import date, datetime
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Type, Union, get_args
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Type, get_args
 
 
 if TYPE_CHECKING:
@@ -12,7 +12,7 @@ if TYPE_CHECKING:
 
 # Heavy import moved to function level for better performance
 from .._mock_table import BaseMockTable
-from .._types import BaseTypeConverter
+from .._types import BaseTypeConverter, is_union_type
 from .base import DatabaseAdapter
 
 
@@ -202,9 +202,9 @@ class RedshiftAdapter(DatabaseAdapter):
             # Generate column definitions
             column_defs = []
             for col_name, col_type in column_types.items():
-                # Handle Optional types
-                if hasattr(col_type, "__origin__") and col_type.__origin__ is Union:
-                    # Extract the non-None type from Optional[T]
+                # Handle Optional types (both Optional[X] and X | None)
+                if is_union_type(col_type):
+                    # Extract the non-None type from Optional[T] or T | None
                     non_none_types = [arg for arg in get_args(col_type) if arg is not type(None)]
                     if non_none_types:
                         col_type = non_none_types[0]

{sql_testing_library-0.18.0 → sql_testing_library-0.20.0}/src/sql_testing_library/_adapters/snowflake.py

@@ -13,7 +13,6 @@ from typing import (
     Optional,
     Tuple,
     Type,
-    Union,
     get_args,
 )
 
@@ -23,7 +22,7 @@ if TYPE_CHECKING:
 
 # Heavy import moved to function level for better performance
 from .._mock_table import BaseMockTable
-from .._types import BaseTypeConverter
+from .._types import BaseTypeConverter, is_union_type
 from .base import DatabaseAdapter
 
 
@@ -364,9 +363,9 @@ class SnowflakeAdapter(DatabaseAdapter):
             # Generate column definitions
             column_defs = []
             for col_name, col_type in column_types.items():
-                # Handle Optional types
-                if hasattr(col_type, "__origin__") and col_type.__origin__ is Union:
-                    # Extract the non-None type from Optional[T]
+                # Handle Optional types (both Optional[X] and X | None)
+                if is_union_type(col_type):
+                    # Extract the non-None type from Optional[T] or T | None
                     non_none_types = [arg for arg in get_args(col_type) if arg is not type(None)]
                     if non_none_types:
                         col_type = non_none_types[0]

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

@@ -196,5 +196,102 @@ class BaseMockTable(ABC):
         return df
 
     def get_cte_alias(self) -> str:
-        """Get the CTE alias name (database__tablename)."""
-        return f"{self.get_database_name().replace('-', '_').replace('.', '_')}__{self.get_table_name()}"  # noqa: E501
+        """Get the CTE alias name (database__tablename).
+
+        Replaces '-' and '.' with '_' to ensure valid BigQuery CTE names,
+        as BigQuery CTEs cannot contain hyphens or dots.
+        """
+        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}"

{sql_testing_library-0.18.0 → sql_testing_library-0.20.0}/src/sql_testing_library/_types.py

@@ -29,6 +29,35 @@ except ImportError:
     pydantic_available = False
 
 
+def is_union_type(type_hint: Type) -> bool:
+    """Check if a type is a Union type (including Optional).
+
+    This function handles both:
+    - typing.Optional[X] / typing.Union[X, None] (Python 3.9+)
+    - X | None syntax (Python 3.10+)
+
+    Args:
+        type_hint: The type to check
+
+    Returns:
+        True if the type is a union type, False otherwise
+    """
+    origin = get_origin(type_hint)
+    if origin is None:
+        return False
+
+    # Handle typing.Union (used by Optional[X])
+    if origin is Union:
+        return True
+
+    # Handle types.UnionType (used by X | None in Python 3.10+)
+    # We check the name because types.UnionType may not be available in Python 3.9
+    if hasattr(origin, "__name__") and origin.__name__ == "UnionType":
+        return True
+
+    return False
+
+
 def is_pydantic_model_class(cls: Type) -> bool:
     """Check if a class is a Pydantic model class."""
     if not pydantic_available or BaseModel is None:
@@ -42,9 +71,9 @@ def is_pydantic_model_class(cls: Type) -> bool:
 
 def is_struct_type(type_hint: Type) -> bool:
     """Check if a type is a struct type (dataclass or Pydantic model)."""
-    # Handle Optional types
-    if hasattr(type_hint, "__origin__") and type_hint.__origin__ is Union:
-        # Extract the non-None type from Optional[T]
+    # Handle Optional types (both Optional[X] and X | None)
+    if is_union_type(type_hint):
+        # Extract the non-None type from Optional[T] or T | None
         non_none_types = [arg for arg in get_args(type_hint) if arg is not type(None)]
         if non_none_types:
             type_hint = non_none_types[0]
@@ -427,15 +456,17 @@ class BaseTypeConverter:
 
 
 def unwrap_optional_type(col_type: Type[Any]) -> Type[Any]:
-    """Unwrap Optional[T] to T, leave other types unchanged.
+    """Unwrap Optional[T] or T | None to T, leave other types unchanged.
 
     This is a utility function that can be used by adapters and mock tables
-    to handle Optional types consistently.
+    to handle Optional types consistently. Supports both:
+    - typing.Optional[T] / typing.Union[T, None] (Python 3.9+)
+    - T | None syntax (Python 3.10+)
     """
-    # Check if this is a Union type (which Optional[T] is)
-    if get_origin(col_type) is Union:
+    # Check if this is a Union type (which Optional[T] and T | None both are)
+    if is_union_type(col_type):
         args = get_args(col_type)
-        # Optional[T] is Union[T, None], so filter out NoneType
+        # Optional[T] or T | None is Union[T, None], so filter out NoneType
         non_none_types = [arg for arg in args if arg is not type(None)]
         if non_none_types:
             return cast(Type[Any], non_none_types[0])  # Return the first non-None type