sqlspec 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/core/parameters.py

@@ -20,12 +20,13 @@ Processing:
 """
 
 import re
-from collections.abc import Mapping, Sequence
+from collections import OrderedDict
+from collections.abc import Callable, Mapping, Sequence
 from datetime import date, datetime
 from decimal import Decimal
 from enum import Enum
 from functools import singledispatch
-from typing import Any, Callable, Optional
+from typing import Any
 
 from mypy_extensions import mypyc_attr
 
@@ -107,7 +108,7 @@ class TypedParameter:
 
     __slots__ = ("_hash", "original_type", "semantic_name", "value")
 
-    def __init__(self, value: Any, original_type: Optional[type] = None, semantic_name: Optional[str] = None) -> None:
+    def __init__(self, value: Any, original_type: type | None = None, semantic_name: str | None = None) -> None:
         """Initialize typed parameter wrapper.
 
         Args:
@@ -118,7 +119,7 @@ class TypedParameter:
         self.value = value
         self.original_type = original_type or type(value)
         self.semantic_name = semantic_name
-        self._hash: Optional[int] = None
+        self._hash: int | None = None
 
     def __hash__(self) -> int:
         """Cached hash value."""
@@ -144,7 +145,7 @@ class TypedParameter:
 
 
 @singledispatch
-def _wrap_parameter_by_type(value: Any, semantic_name: Optional[str] = None) -> Any:
+def _wrap_parameter_by_type(value: Any, semantic_name: str | None = None) -> Any:
     """Type-specific parameter wrapping using singledispatch.
 
     Args:
@@ -158,31 +159,31 @@ def _wrap_parameter_by_type(value: Any, semantic_name: Optional[str] = None) ->
 
 
 @_wrap_parameter_by_type.register
-def _(value: bool, semantic_name: Optional[str] = None) -> TypedParameter:
+def _(value: bool, semantic_name: str | None = None) -> TypedParameter:
     """Wrap boolean values to prevent SQLGlot parsing issues."""
     return TypedParameter(value, bool, semantic_name)
 
 
 @_wrap_parameter_by_type.register
-def _(value: Decimal, semantic_name: Optional[str] = None) -> TypedParameter:
+def _(value: Decimal, semantic_name: str | None = None) -> TypedParameter:
     """Wrap Decimal values to preserve precision."""
     return TypedParameter(value, Decimal, semantic_name)
 
 
 @_wrap_parameter_by_type.register
-def _(value: datetime, semantic_name: Optional[str] = None) -> TypedParameter:
+def _(value: datetime, semantic_name: str | None = None) -> TypedParameter:
     """Wrap datetime values for database-specific formatting."""
     return TypedParameter(value, datetime, semantic_name)
 
 
 @_wrap_parameter_by_type.register
-def _(value: date, semantic_name: Optional[str] = None) -> TypedParameter:
+def _(value: date, semantic_name: str | None = None) -> TypedParameter:
     """Wrap date values for database-specific formatting."""
     return TypedParameter(value, date, semantic_name)
 
 
 @_wrap_parameter_by_type.register
-def _(value: bytes, semantic_name: Optional[str] = None) -> TypedParameter:
+def _(value: bytes, semantic_name: str | None = None) -> TypedParameter:
     """Wrap bytes values to prevent string conversion issues in ADBC/Arrow."""
     return TypedParameter(value, bytes, semantic_name)
 
@@ -204,7 +205,7 @@ class ParameterInfo:
     __slots__ = ("name", "ordinal", "placeholder_text", "position", "style")
 
     def __init__(
-        self, name: Optional[str], style: ParameterStyle, position: int, ordinal: int, placeholder_text: str
+        self, name: str | None, style: ParameterStyle, position: int, ordinal: int, placeholder_text: str
     ) -> None:
         """Initialize parameter information.
 
@@ -234,17 +235,8 @@ class ParameterInfo:
 class ParameterStyleConfig:
     """Configuration for parameter style processing.
 
-    Provides configuration for parameter processing operations.
-
-    Attributes:
-        default_parameter_style: Primary parsing style
-        supported_parameter_styles: All input styles supported
-        supported_execution_parameter_styles: Styles driver can execute
-        default_execution_parameter_style: Target execution format
-        type_coercion_map: Type conversions
-        output_transformer: Final SQL/parameter transformation hook
-        preserve_parameter_format: Maintain original parameter structure
-        needs_static_script_compilation: Embed parameters in SQL
+    Provides configuration for parameter processing operations including
+    style conversion, type coercion, and parameter format preservation.
     """
 
     __slots__ = (
@@ -265,17 +257,17 @@ class ParameterStyleConfig:
     def __init__(
         self,
         default_parameter_style: ParameterStyle,
-        supported_parameter_styles: Optional[set[ParameterStyle]] = None,
-        supported_execution_parameter_styles: Optional[set[ParameterStyle]] = None,
-        default_execution_parameter_style: Optional[ParameterStyle] = None,
-        type_coercion_map: Optional[dict[type, Callable[[Any], Any]]] = None,
+        supported_parameter_styles: set[ParameterStyle] | None = None,
+        supported_execution_parameter_styles: set[ParameterStyle] | None = None,
+        default_execution_parameter_style: ParameterStyle | None = None,
+        type_coercion_map: dict[type, Callable[[Any], Any]] | None = None,
         has_native_list_expansion: bool = False,
         needs_static_script_compilation: bool = False,
         allow_mixed_parameter_styles: bool = False,
         preserve_parameter_format: bool = True,
         preserve_original_params_for_many: bool = False,
-        output_transformer: Optional[Callable[[str, Any], tuple[str, Any]]] = None,
-        ast_transformer: Optional[Callable[[Any, Any], tuple[Any, Any]]] = None,
+        output_transformer: Callable[[str, Any], tuple[str, Any]] | None = None,
+        ast_transformer: Callable[[Any, Any], tuple[Any, Any]] | None = None,
     ) -> None:
         """Initialize parameter style configuration.
 
@@ -343,13 +335,18 @@ class ParameterValidator:
     compatibility with target dialects.
     """
 
-    __slots__ = ("_parameter_cache",)
+    __slots__ = ("_cache_max_size", "_parameter_cache")
 
-    def __init__(self) -> None:
-        """Initialize validator with parameter cache."""
-        self._parameter_cache: dict[str, list[ParameterInfo]] = {}
+    def __init__(self, cache_max_size: int = 5000) -> None:
+        """Initialize validator with bounded LRU cache.
 
-    def _extract_parameter_style(self, match: "re.Match[str]") -> "tuple[Optional[ParameterStyle], Optional[str]]":
+        Args:
+            cache_max_size: Maximum number of SQL strings to cache (default: 5000)
+        """
+        self._parameter_cache: OrderedDict[str, list[ParameterInfo]] = OrderedDict()
+        self._cache_max_size = cache_max_size
+
+    def _extract_parameter_style(self, match: "re.Match[str]") -> "tuple[ParameterStyle | None, str | None]":
         """Extract parameter style and name from regex match.
 
         Args:
@@ -396,8 +393,15 @@ class ParameterValidator:
         """
         cached_result = self._parameter_cache.get(sql)
         if cached_result is not None:
+            self._parameter_cache.move_to_end(sql)
             return cached_result
 
+        if not any(c in sql for c in ("?", "%", ":", "@", "$")):
+            if len(self._parameter_cache) >= self._cache_max_size:
+                self._parameter_cache.popitem(last=False)
+            self._parameter_cache[sql] = []
+            return []
+
         parameters: list[ParameterInfo] = []
         ordinal = 0
 
@@ -425,10 +429,13 @@ class ParameterValidator:
                 )
                 ordinal += 1
 
+        if len(self._parameter_cache) >= self._cache_max_size:
+            self._parameter_cache.popitem(last=False)
+
         self._parameter_cache[sql] = parameters
         return parameters
 
-    def get_sqlglot_incompatible_styles(self, dialect: Optional[str] = None) -> "set[ParameterStyle]":
+    def get_sqlglot_incompatible_styles(self, dialect: str | None = None) -> "set[ParameterStyle]":
         """Get parameter styles incompatible with SQLGlot for dialect.
 
         Args:
@@ -491,7 +498,7 @@ class ParameterConverter:
             ParameterStyle.POSITIONAL_PYFORMAT: lambda _: "%s",
         }
 
-    def normalize_sql_for_parsing(self, sql: str, dialect: Optional[str] = None) -> "tuple[str, list[ParameterInfo]]":
+    def normalize_sql_for_parsing(self, sql: str, dialect: str | None = None) -> "tuple[str, list[ParameterInfo]]":
         """Convert SQL to parsable format.
 
         Takes raw SQL with potentially incompatible parameter styles and converts
@@ -619,7 +626,9 @@ class ParameterConverter:
 
         return converted_sql
 
-    def _convert_sequence_to_dict(self, parameters: Sequence, param_info: "list[ParameterInfo]") -> "dict[str, Any]":
+    def _convert_sequence_to_dict(
+        self, parameters: "Sequence[Any]", param_info: "list[ParameterInfo]"
+    ) -> "dict[str, Any]":
         """Convert sequence parameters to dictionary for named styles.
 
         Args:
@@ -637,7 +646,7 @@ class ParameterConverter:
         return param_dict
 
     def _extract_param_value_mixed_styles(
-        self, param: ParameterInfo, parameters: Mapping, param_keys: "list[str]"
+        self, param: ParameterInfo, parameters: "Mapping[str, Any]", param_keys: "list[str]"
     ) -> "tuple[Any, bool]":
         """Extract parameter value for mixed style parameters.
 
@@ -670,7 +679,9 @@ class ParameterConverter:
 
         return None, False
 
-    def _extract_param_value_single_style(self, param: ParameterInfo, parameters: Mapping) -> "tuple[Any, bool]":
+    def _extract_param_value_single_style(
+        self, param: ParameterInfo, parameters: "Mapping[str, Any]"
+    ) -> "tuple[Any, bool]":
         """Extract parameter value for single style parameters.
 
         Args:
@@ -998,13 +1009,37 @@ class ParameterProcessor:
         target_style = self._determine_target_execution_style(original_styles, config)
         return self._converter.convert_placeholder_style(sql, parameters, target_style, is_many)
 
+    def _generate_processor_cache_key(
+        self, sql: str, parameters: Any, config: ParameterStyleConfig, is_many: bool, dialect: "str | None"
+    ) -> str:
+        """Generate optimized cache key for parameter processing.
+
+        Uses parameter fingerprint (type + structure) instead of repr()
+        for better performance on large parameter sets.
+
+        Args:
+            sql: SQL string
+            parameters: Parameter values
+            config: Parameter style configuration
+            is_many: Whether this is execute_many
+            dialect: SQL dialect
+
+        Returns:
+            Cache key string
+        """
+        param_fingerprint = (
+            "none"
+            if parameters is None
+            else f"seq_{len(parameters)}_{type(parameters).__name__}"
+            if isinstance(parameters, (list, tuple))
+            else f"map_{len(parameters)}"
+            if isinstance(parameters, dict)
+            else f"scalar_{type(parameters).__name__}"
+        )
+        return f"{sql}:{param_fingerprint}:{config.default_parameter_style}:{is_many}:{dialect}"
+
     def process(
-        self,
-        sql: str,
-        parameters: Any,
-        config: ParameterStyleConfig,
-        dialect: Optional[str] = None,
-        is_many: bool = False,
+        self, sql: str, parameters: Any, config: ParameterStyleConfig, dialect: str | None = None, is_many: bool = False
     ) -> "tuple[str, Any]":
         """Process parameters through the complete pipeline.
 
@@ -1025,7 +1060,7 @@ class ParameterProcessor:
         Returns:
             Tuple of (final_sql, execution_parameters)
         """
-        cache_key = f"{sql}:{hash(repr(parameters))}:{config.default_parameter_style}:{is_many}:{dialect}"
+        cache_key = self._generate_processor_cache_key(sql, parameters, config, is_many, dialect)
         if cache_key in self._cache:
             return self._cache[cache_key]
 
@@ -1078,7 +1113,7 @@ class ParameterProcessor:
         return processed_sql, processed_parameters
 
     def get_sqlglot_compatible_sql(
-        self, sql: str, parameters: Any, config: ParameterStyleConfig, dialect: Optional[str] = None
+        self, sql: str, parameters: Any, config: ParameterStyleConfig, dialect: str | None = None
     ) -> "tuple[str, Any]":
         """Get SQL normalized for parsing only (Phase 1 only).
 
@@ -1135,7 +1170,7 @@ class ParameterProcessor:
 
         return True
 
-    def _needs_sqlglot_normalization(self, param_info: "list[ParameterInfo]", dialect: Optional[str] = None) -> bool:
+    def _needs_sqlglot_normalization(self, param_info: "list[ParameterInfo]", dialect: str | None = None) -> bool:
         """Check if SQLGlot normalization is needed for this SQL."""
         incompatible_styles = self._validator.get_sqlglot_incompatible_styles(dialect)
         return any(p.style in incompatible_styles for p in param_info)
@@ -1248,7 +1283,7 @@ def is_iterable_parameters(obj: Any) -> bool:
     )
 
 
-def wrap_with_type(value: Any, semantic_name: Optional[str] = None) -> Any:
+def wrap_with_type(value: Any, semantic_name: str | None = None) -> Any:
     """Public API for type wrapping.
 
     Args:

sqlspec/core/result.py

@@ -10,17 +10,19 @@ Classes:
 """
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Optional, cast, overload
 
 from mypy_extensions import mypyc_attr
 from typing_extensions import TypeVar
 
 from sqlspec.core.compiler import OperationType
+from sqlspec.utils.schema import to_schema
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
     from sqlspec.core.statement import SQL
+    from sqlspec.typing import SchemaT
 
 
 __all__ = ("ArrowResult", "SQLResult", "StatementResult")
@@ -52,8 +54,8 @@ class StatementResult(ABC):
         statement: "SQL",
         data: Any = None,
         rows_affected: int = 0,
-        last_inserted_id: Optional[Union[int, str]] = None,
-        execution_time: Optional[float] = None,
+        last_inserted_id: int | str | None = None,
+        execution_time: float | None = None,
         metadata: Optional["dict[str, Any]"] = None,
     ) -> None:
         """Initialize statement result.
@@ -129,19 +131,6 @@ class SQLResult(StatementResult):
     The operation_type attribute indicates the nature of the operation.
 
     For script execution, tracks multiple statement results and errors.
-
-    Attributes:
-        column_names: Names of columns in the result set.
-        error: Exception that occurred during execution.
-        errors: List of error messages for script execution.
-        has_more: Whether there are additional result pages available.
-        inserted_ids: List of IDs from INSERT operations.
-        operation_index: Index of operation in a script.
-        parameters: Parameters used for the query.
-        statement_results: Results from individual statements in a script.
-        successful_statements: Count of successful statements in a script.
-        total_count: Total number of rows in the complete result set.
-        total_statements: Total number of statements in a script.
     """
 
     __slots__ = (
@@ -164,19 +153,19 @@ class SQLResult(StatementResult):
     def __init__(
         self,
         statement: "SQL",
-        data: Optional[list[dict[str, Any]]] = None,
+        data: list[dict[str, Any]] | None = None,
         rows_affected: int = 0,
-        last_inserted_id: Optional[Union[int, str]] = None,
-        execution_time: Optional[float] = None,
+        last_inserted_id: int | str | None = None,
+        execution_time: float | None = None,
         metadata: Optional["dict[str, Any]"] = None,
-        error: Optional[Exception] = None,
+        error: Exception | None = None,
         operation_type: OperationType = "SELECT",
-        operation_index: Optional[int] = None,
-        parameters: Optional[Any] = None,
+        operation_index: int | None = None,
+        parameters: Any | None = None,
         column_names: Optional["list[str]"] = None,
-        total_count: Optional[int] = None,
+        total_count: int | None = None,
         has_more: bool = False,
-        inserted_ids: Optional["list[Union[int, str]]"] = None,
+        inserted_ids: Optional["list[int | str]"] = None,
         statement_results: Optional["list[SQLResult]"] = None,
         errors: Optional["list[str]"] = None,
         total_statements: int = 0,
@@ -280,15 +269,25 @@ class SQLResult(StatementResult):
 
         return False
 
-    def get_data(self) -> "list[dict[str,Any]]":
+    @overload
+    def get_data(self, *, schema_type: "type[SchemaT]") -> "list[SchemaT]": ...
+
+    @overload
+    def get_data(self, *, schema_type: None = None) -> "list[dict[str, Any]]": ...
+
+    def get_data(self, *, schema_type: "type[SchemaT] | None" = None) -> "list[SchemaT] | list[dict[str, Any]]":
         """Get the data from the result.
 
         For regular operations, returns the list of rows.
         For script operations, returns a summary dictionary containing
         execution statistics and results.
 
+        Args:
+            schema_type: Optional schema type to transform the data into.
+                Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
+
         Returns:
-            List of result rows or script summary.
+            List of result rows (optionally transformed to schema_type) or script summary.
         """
         op_type_upper = self.operation_type.upper()
         if op_type_upper == "SCRIPT":
@@ -303,7 +302,10 @@ class SQLResult(StatementResult):
                     "total_rows_affected": self.get_total_rows_affected(),
                 }
             ]
-        return self.data or []
+        data = cast("list[dict[str, Any]]", self.data or [])
+        if schema_type:
+            return cast("list[SchemaT]", to_schema(data, schema_type=schema_type))
+        return data
 
     def add_statement_result(self, result: "SQLResult") -> None:
         """Add a statement result to the script execution results.
@@ -348,13 +350,28 @@ class SQLResult(StatementResult):
         """
         return len(self.column_names) if self.column_names else 0
 
-    def get_first(self) -> "Optional[dict[str, Any]]":
+    @overload
+    def get_first(self, *, schema_type: "type[SchemaT]") -> "SchemaT | None": ...
+
+    @overload
+    def get_first(self, *, schema_type: None = None) -> "dict[str, Any] | None": ...
+
+    def get_first(self, *, schema_type: "type[SchemaT] | None" = None) -> "SchemaT | dict[str, Any] | None":
         """Get the first row from the result, if any.
 
+        Args:
+            schema_type: Optional schema type to transform the data into.
+                Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
+
         Returns:
-            First row or None if no data.
+            First row (optionally transformed to schema_type) or None if no data.
         """
-        return self.data[0] if self.data else None
+        if not self.data:
+            return None
+        row = cast("dict[str, Any]", self.data[0])
+        if schema_type:
+            return to_schema(row, schema_type=schema_type)
+        return row
 
     def get_count(self) -> int:
         """Get the number of rows in the current result set (e.g., a page of data).
@@ -434,19 +451,42 @@ class SQLResult(StatementResult):
         """
         return iter(self.data or [])
 
-    def all(self) -> list[dict[str, Any]]:
+    @overload
+    def all(self, *, schema_type: "type[SchemaT]") -> "list[SchemaT]": ...
+
+    @overload
+    def all(self, *, schema_type: None = None) -> list[dict[str, Any]]: ...
+
+    def all(self, *, schema_type: "type[SchemaT] | None" = None) -> "list[SchemaT] | list[dict[str, Any]]":
         """Return all rows as a list.
 
+        Args:
+            schema_type: Optional schema type to transform the data into.
+                Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
+
         Returns:
-            List of all rows in the result
+            List of all rows (optionally transformed to schema_type)
         """
-        return self.data or []
+        data = cast("list[dict[str, Any]]", self.data or [])
+        if schema_type:
+            return cast("list[SchemaT]", to_schema(data, schema_type=schema_type))
+        return data
+
+    @overload
+    def one(self, *, schema_type: "type[SchemaT]") -> "SchemaT": ...
+
+    @overload
+    def one(self, *, schema_type: None = None) -> "dict[str, Any]": ...
 
-    def one(self) -> "dict[str, Any]":
+    def one(self, *, schema_type: "type[SchemaT] | None" = None) -> "SchemaT | dict[str, Any]":
         """Return exactly one row.
 
+        Args:
+            schema_type: Optional schema type to transform the data into.
+                Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
+
         Returns:
-            The single row
+            The single row (optionally transformed to schema_type)
 
         Raises:
             ValueError: If no results or more than one result
@@ -463,13 +503,26 @@ class SQLResult(StatementResult):
             msg = f"Multiple results found ({data_len}), exactly one row expected"
             raise ValueError(msg)
 
-        return cast("dict[str, Any]", self.data[0])
+        row = cast("dict[str, Any]", self.data[0])
+        if schema_type:
+            return to_schema(row, schema_type=schema_type)
+        return row
+
+    @overload
+    def one_or_none(self, *, schema_type: "type[SchemaT]") -> "SchemaT | None": ...
 
-    def one_or_none(self) -> "Optional[dict[str, Any]]":
+    @overload
+    def one_or_none(self, *, schema_type: None = None) -> "dict[str, Any] | None": ...
+
+    def one_or_none(self, *, schema_type: "type[SchemaT] | None" = None) -> "SchemaT | dict[str, Any] | None":
         """Return at most one row.
 
+        Args:
+            schema_type: Optional schema type to transform the data into.
+                Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
+
         Returns:
-            The single row or None if no results
+            The single row (optionally transformed to schema_type) or None if no results
 
         Raises:
             ValueError: If more than one result
@@ -484,7 +537,10 @@ class SQLResult(StatementResult):
             msg = f"Multiple results found ({data_len}), at most one row expected"
             raise ValueError(msg)
 
-        return cast("dict[str, Any]", self.data[0])
+        row = cast("dict[str, Any]", self.data[0])
+        if schema_type:
+            return to_schema(row, schema_type=schema_type)
+        return row
 
     def scalar(self) -> Any:
         """Return the first column of the first row.
@@ -527,8 +583,8 @@ class ArrowResult(StatementResult):
         statement: "SQL",
         data: Any,
         rows_affected: int = 0,
-        last_inserted_id: Optional[Union[int, str]] = None,
-        execution_time: Optional[float] = None,
+        last_inserted_id: int | str | None = None,
+        execution_time: float | None = None,
         metadata: Optional["dict[str, Any]"] = None,
         schema: Optional["dict[str, Any]"] = None,
     ) -> None:
@@ -627,10 +683,10 @@ class ArrowResult(StatementResult):
 
 def create_sql_result(
     statement: "SQL",
-    data: Optional[list[dict[str, Any]]] = None,
+    data: list[dict[str, Any]] | None = None,
     rows_affected: int = 0,
-    last_inserted_id: Optional[Union[int, str]] = None,
-    execution_time: Optional[float] = None,
+    last_inserted_id: int | str | None = None,
+    execution_time: float | None = None,
     metadata: Optional["dict[str, Any]"] = None,
     **kwargs: Any,
 ) -> SQLResult:
@@ -663,8 +719,8 @@ def create_arrow_result(
     statement: "SQL",
     data: Any,
     rows_affected: int = 0,
-    last_inserted_id: Optional[Union[int, str]] = None,
-    execution_time: Optional[float] = None,
+    last_inserted_id: int | str | None = None,
+    execution_time: float | None = None,
     metadata: Optional["dict[str, Any]"] = None,
     schema: Optional["dict[str, Any]"] = None,
 ) -> ArrowResult:

sqlspec/core/splitter.py

@@ -16,13 +16,12 @@ MySQL, SQLite, DuckDB, and BigQuery.
 import re
 import threading
 from abc import ABC, abstractmethod
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from enum import Enum
 from re import Pattern
-from typing import Any, Callable, Final, Optional, Union, cast
+from typing import Any, Final, TypeAlias, cast
 
 from mypy_extensions import mypyc_attr
-from typing_extensions import TypeAlias
 
 from sqlspec.core.cache import CacheKey, UnifiedCache
 from sqlspec.utils.logging import get_logger
@@ -98,9 +97,9 @@ class Token:
         return f"Token({self.type.value}, {self.value!r}, {self.line}:{self.column})"
 
 
-TokenHandler: TypeAlias = Callable[[str, int, int, int], Optional[Token]]
-TokenPattern: TypeAlias = Union[str, TokenHandler]
-CompiledTokenPattern: TypeAlias = Union[Pattern[str], TokenHandler]
+TokenHandler: TypeAlias = Callable[[str, int, int, int], Token | None]
+TokenPattern: TypeAlias = str | TokenHandler
+CompiledTokenPattern: TypeAlias = Pattern[str] | TokenHandler
 
 
 @mypyc_attr(allow_interpreted_subclasses=False)
@@ -111,13 +110,13 @@ class DialectConfig(ABC):
 
     def __init__(self) -> None:
         """Initialize dialect configuration."""
-        self._name: Optional[str] = None
-        self._block_starters: Optional[set[str]] = None
-        self._block_enders: Optional[set[str]] = None
-        self._statement_terminators: Optional[set[str]] = None
-        self._batch_separators: Optional[set[str]] = None
-        self._special_terminators: Optional[dict[str, Callable[[list[Token], int], bool]]] = None
-        self._max_nesting_depth: Optional[int] = None
+        self._name: str | None = None
+        self._block_starters: set[str] | None = None
+        self._block_enders: set[str] | None = None
+        self._statement_terminators: set[str] | None = None
+        self._batch_separators: set[str] | None = None
+        self._special_terminators: dict[str, Callable[[list[Token], int], bool]] | None = None
+        self._max_nesting_depth: int | None = None
 
     @property
     @abstractmethod
@@ -436,7 +435,7 @@ class PostgreSQLDialectConfig(DialectConfig):
         return [(TokenType.STRING_LITERAL, self._handle_dollar_quoted_string)]
 
     @staticmethod
-    def _handle_dollar_quoted_string(text: str, position: int, line: int, column: int) -> Optional[Token]:
+    def _handle_dollar_quoted_string(text: str, position: int, line: int, column: int) -> Token | None:
         """Handle PostgreSQL dollar-quoted string literals.
 
         Parses dollar-quoted strings in the format $tag$content$tag$
@@ -613,8 +612,8 @@ class BigQueryDialectConfig(DialectConfig):
         return self._statement_terminators
 
 
-_pattern_cache: Optional[UnifiedCache] = None
-_result_cache: Optional[UnifiedCache] = None
+_pattern_cache: UnifiedCache | None = None
+_result_cache: UnifiedCache | None = None
 _cache_lock = threading.Lock()
 
 
@@ -878,7 +877,7 @@ class StatementSplitter:
         return False
 
 
-def split_sql_script(script: str, dialect: Optional[str] = None, strip_trailing_terminator: bool = False) -> list[str]:
+def split_sql_script(script: str, dialect: str | None = None, strip_trailing_terminator: bool = False) -> list[str]:
     """Split SQL script into individual statements.
 
     Args: