sqlspec 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl

sqlspec/driver/parameters.py

@@ -0,0 +1,138 @@
+"""Consolidated parameter processing utilities for database drivers.
+
+This module provides centralized parameter handling logic to avoid duplication
+across sync and async driver implementations.
+"""
+
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+from sqlspec.statement.filters import StatementFilter
+from sqlspec.utils.type_guards import is_sync_transaction_capable
+
+if TYPE_CHECKING:
+    from sqlspec.typing import StatementParameters
+
+__all__ = (
+    "convert_parameters_to_positional",
+    "normalize_parameter_sequence",
+    "process_execute_many_parameters",
+    "separate_filters_and_parameters",
+    "should_use_transaction",
+)
+
+
+def separate_filters_and_parameters(
+    parameters: "tuple[Union[StatementParameters, StatementFilter], ...]",
+) -> "tuple[list[StatementFilter], list[Any]]":
+    """Separate filters from parameters in a mixed parameter tuple.
+
+    Args:
+        parameters: Mixed tuple of parameters and filters
+
+    Returns:
+        Tuple of (filters, parameters) lists
+    """
+
+    filters: list[StatementFilter] = []
+    param_values: list[Any] = []
+
+    for param in parameters:
+        if isinstance(param, StatementFilter):
+            filters.append(param)
+        else:
+            param_values.append(param)
+
+    return filters, param_values
+
+
+def process_execute_many_parameters(
+    parameters: "tuple[Union[StatementParameters, StatementFilter], ...]",
+) -> "tuple[list[StatementFilter], Optional[list[Any]]]":
+    """Process parameters for execute_many operations.
+
+    Args:
+        parameters: Mixed tuple of parameters and filters
+
+    Returns:
+        Tuple of (filters, parameter_sequence)
+    """
+    filters, param_values = separate_filters_and_parameters(parameters)
+
+    # Use first parameter as the sequence for execute_many
+    param_sequence = param_values[0] if param_values else None
+
+    # Normalize the parameter sequence
+    param_sequence = normalize_parameter_sequence(param_sequence)
+
+    return filters, param_sequence
+
+
+def normalize_parameter_sequence(params: Any) -> Optional[list[Any]]:
+    """Normalize a parameter sequence to a list format.
+
+    Args:
+        params: Parameter sequence in various formats
+
+    Returns:
+        Normalized list of parameters or None
+    """
+    if params is None:
+        return None
+
+    if isinstance(params, list):
+        return params
+
+    if isinstance(params, tuple):
+        return list(params)
+
+    # Check if it's iterable (but not string or dict)
+    # Use duck typing to check for iterable protocol
+    try:
+        iter(params)
+        if not isinstance(params, (str, dict)):
+            return list(params)
+    except TypeError:
+        pass
+
+    # Single parameter, wrap in list
+    return [params]
+
+
+def convert_parameters_to_positional(params: "dict[str, Any]", parameter_info: "list[Any]") -> list[Any]:
+    """Convert named parameters to positional based on SQL order.
+
+    Args:
+        params: Dictionary of named parameters
+        parameter_info: List of parameter info from SQL parsing
+
+    Returns:
+        List of positional parameters
+    """
+    if not params:
+        return []
+
+    # Handle param_0, param_1, etc. pattern
+    if all(key.startswith("param_") for key in params):
+        return [params[f"param_{i}"] for i in range(len(params))]
+
+    # Convert based on parameter info order
+    # Check for name attribute using getattr with default
+    result = []
+    for info in parameter_info:
+        param_name = getattr(info, "name", None)
+        if param_name is not None:
+            result.append(params.get(param_name, None))
+    return result
+
+
+def should_use_transaction(connection: Any, auto_commit: bool = True) -> bool:
+    """Determine if a transaction should be used.
+
+    Args:
+        connection: Database connection object
+        auto_commit: Whether auto-commit is enabled
+
+    Returns:
+        True if transaction capabilities are available and should be used
+    """
+    return False if auto_commit else is_sync_transaction_capable(connection)

sqlspec/exceptions.py

@@ -19,6 +19,7 @@ __all__ = (
     "RepositoryError",
     "RiskLevel",
     "SQLBuilderError",
+    "SQLCompilationError",
     "SQLConversionError",
     "SQLFileNotFoundError",
     "SQLFileParseError",
@@ -122,6 +123,15 @@ class SQLBuilderError(SQLSpecError):
         super().__init__(message)
 
 
+class SQLCompilationError(SQLSpecError):
+    """Issues Compiling SQL statements."""
+
+    def __init__(self, message: Optional[str] = None) -> None:
+        if message is None:
+            message = "Issues compiling SQL statement."
+        super().__init__(message)
+
+
 class SQLConversionError(SQLSpecError):
     """Issues converting SQL statements."""
 
@@ -374,7 +384,6 @@ def wrap_exceptions(
         yield
 
     except Exception as exc:
-        # Handle suppression first
         if suppress is not None and (
             (isinstance(suppress, type) and isinstance(exc, suppress))
             or (isinstance(suppress, tuple) and isinstance(exc, suppress))
@@ -385,7 +394,6 @@ def wrap_exceptions(
         if isinstance(exc, SQLSpecError):
             raise
 
-        # Handle wrapping
         if wrap_exceptions is False:
             raise
         msg = "An error occurred during the operation."

sqlspec/extensions/aiosql/adapter.py

@@ -40,11 +40,9 @@ def _normalize_dialect(dialect: "Union[str, Any, None]") -> str:
     Returns:
         Normalized dialect name
     """
-    # Handle different dialect types
     if dialect is None:
         return "sql"
 
-    # Extract string from dialect class or instance
     if hasattr(dialect, "__name__"):  # It's a class
         dialect_str = str(dialect.__name__).lower()  # pyright: ignore
     elif hasattr(dialect, "name"):  # It's an instance with name attribute
@@ -134,7 +132,6 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
                 "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
             )
 
-        # Create SQL object and apply filters
         sql_obj = self._create_sql_object(sql, parameters)
         # Execute using SQLSpec driver
         result = self.driver.execute(sql_obj, connection=conn)
@@ -192,12 +189,9 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
             return None
 
         if isinstance(row, dict):
-            # Return first value from dict
             return next(iter(row.values())) if row else None
         if hasattr(row, "__getitem__"):
-            # Handle tuple/list-like objects
             return row[0] if len(row) > 0 else None
-        # Handle scalar or object with attributes
         return row
 
     @contextmanager
@@ -216,7 +210,6 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         sql_obj = self._create_sql_object(sql, parameters)
         result = self.driver.execute(sql_obj, connection=conn)
 
-        # Create a cursor-like object
         class CursorLike:
             def __init__(self, result: Any) -> None:
                 self.result = result
@@ -386,12 +379,9 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
             return None
 
         if isinstance(row, dict):
-            # Return first value from dict
             return next(iter(row.values())) if row else None
         if hasattr(row, "__getitem__"):
-            # Handle tuple/list-like objects
             return row[0] if len(row) > 0 else None
-        # Handle scalar or object with attributes
         return row
 
     @asynccontextmanager

sqlspec/extensions/litestar/handlers.py

@@ -246,7 +246,6 @@ def session_provider_maker(
 
     conn_type_annotation = config.connection_type
 
-    # Import Dependency at function level to avoid circular imports
     from litestar.params import Dependency
 
     db_conn_param = inspect.Parameter(

sqlspec/extensions/litestar/plugin.py

@@ -69,7 +69,6 @@ class SQLSpec(InitPluginProtocol, SQLSpecBase):
             [SQLSpec, ConnectionT, PoolT, DriverT, DatabaseConfig, DatabaseConfigProtocol, SyncConfigT, AsyncConfigT]
         )
 
-        # Create signature namespace for connection types
         signature_namespace = {}
 
         for c in self._plugin_configs:
@@ -78,7 +77,6 @@ class SQLSpec(InitPluginProtocol, SQLSpecBase):
             app_config.signature_types.append(c.config.connection_type)  # type: ignore[union-attr]
             app_config.signature_types.append(c.config.driver_type)  # type: ignore[union-attr]
 
-            # Get signature namespace from the config
             if hasattr(c.config, "get_signature_namespace"):
                 config_namespace = c.config.get_signature_namespace()  # type: ignore[attr-defined]
                 signature_namespace.update(config_namespace)
@@ -93,7 +91,6 @@ class SQLSpec(InitPluginProtocol, SQLSpecBase):
                 }
             )
 
-        # Update app config with signature namespace
         if signature_namespace:
             app_config.signature_namespace.update(signature_namespace)
 

sqlspec/extensions/litestar/providers.py

@@ -173,7 +173,6 @@ def _make_hashable(value: Any) -> HashableType:
         A hashable version of the value.
     """
     if isinstance(value, dict):
-        # Convert dict to tuple of tuples with sorted keys
         items = []
         for k in sorted(value.keys()):  # pyright: ignore
             v = value[k]  # pyright: ignore
@@ -261,7 +260,6 @@ def _create_statement_filters(
                 required=False,
             ),
         ) -> SearchFilter:
-            # Handle both string and set input types for search fields
             field_names = set(search_fields.split(",")) if isinstance(search_fields, str) else set(search_fields)
 
             return SearchFilter(
@@ -286,9 +284,7 @@ def _create_statement_filters(
 
         filters[dep_defaults.ORDER_BY_FILTER_DEPENDENCY_KEY] = Provide(provide_order_by, sync_to_thread=False)
 
-    # Add not_in filter providers
     if not_in_fields := config.get("not_in_fields"):
-        # Get all field names, handling both strings and FieldNameType objects
         not_in_fields = {not_in_fields} if isinstance(not_in_fields, (str, FieldNameType)) else not_in_fields
 
         for field_def in not_in_fields:
@@ -313,9 +309,7 @@ def _create_statement_filters(
             provider = create_not_in_filter_provider(field_def)  # pyright: ignore
             filters[f"{field_def.name}_not_in_filter"] = Provide(provider, sync_to_thread=False)  # pyright: ignore
 
-    # Add in filter providers
     if in_fields := config.get("in_fields"):
-        # Get all field names, handling both strings and FieldNameType objects
         in_fields = {in_fields} if isinstance(in_fields, (str, FieldNameType)) else in_fields
 
         for field_def in in_fields:
@@ -361,7 +355,6 @@ def _create_filter_aggregate_function(config: FilterConfig) -> Callable[..., lis
     parameters: dict[str, inspect.Parameter] = {}
     annotations: dict[str, Any] = {}
 
-    # Build parameters based on config
     if cls := config.get("id_filter"):
         parameters["id_filter"] = inspect.Parameter(
             name="id_filter",
@@ -416,7 +409,6 @@ def _create_filter_aggregate_function(config: FilterConfig) -> Callable[..., lis
         )
         annotations["order_by_filter"] = OrderByFilter
 
-    # Add parameters for not_in filters
     if not_in_fields := config.get("not_in_fields"):
         for field_def in not_in_fields:
             field_def = FieldNameType(name=field_def, type_hint=str) if isinstance(field_def, str) else field_def
@@ -428,7 +420,6 @@ def _create_filter_aggregate_function(config: FilterConfig) -> Callable[..., lis
             )
             annotations[f"{field_def.name}_not_in_filter"] = NotInCollectionFilter[field_def.type_hint]  # type: ignore
 
-    # Add parameters for in filters
     if in_fields := config.get("in_fields"):
         for field_def in in_fields:
             field_def = FieldNameType(name=field_def, type_hint=str) if isinstance(field_def, str) else field_def
@@ -472,9 +463,7 @@ def _create_filter_aggregate_function(config: FilterConfig) -> Callable[..., lis
         ):
             filters.append(order_by)
 
-        # Add not_in filters
         if not_in_fields := config.get("not_in_fields"):
-            # Get all field names, handling both strings and FieldNameType objects
             not_in_fields = {not_in_fields} if isinstance(not_in_fields, (str, FieldNameType)) else not_in_fields
             for field_def in not_in_fields:
                 field_def = FieldNameType(name=field_def, type_hint=str) if isinstance(field_def, str) else field_def
@@ -482,9 +471,7 @@ def _create_filter_aggregate_function(config: FilterConfig) -> Callable[..., lis
                 if filter_ is not None:
                     filters.append(filter_)
 
-        # Add in filters
         if in_fields := config.get("in_fields"):
-            # Get all field names, handling both strings and FieldNameType objects
             in_fields = {in_fields} if isinstance(in_fields, (str, FieldNameType)) else in_fields
             for field_def in in_fields:
                 field_def = FieldNameType(name=field_def, type_hint=str) if isinstance(field_def, str) else field_def
@@ -493,7 +480,6 @@ def _create_filter_aggregate_function(config: FilterConfig) -> Callable[..., lis
                     filters.append(filter_)
         return filters
 
-    # Set both signature and annotations
     provide_filters.__signature__ = inspect.Signature(  # type: ignore
         parameters=list(parameters.values()), return_annotation=list[FilterTypes]
     )

sqlspec/loader.py

@@ -26,7 +26,7 @@ logger = get_logger("loader")
 # Matches: -- name: query_name (supports hyphens and special suffixes)
 # We capture the name plus any trailing special characters
 QUERY_NAME_PATTERN = re.compile(r"^\s*--\s*name\s*:\s*([\w-]+[^\w\s]*)\s*$", re.MULTILINE | re.IGNORECASE)
-
+TRIM_TRAILING_SPECIAL_CHARS = re.compile(r"[^\w-]+$")
 MIN_QUERY_PARTS = 3
 
 
@@ -42,10 +42,8 @@ def _normalize_query_name(name: str) -> str:
     Returns:
         Normalized query name suitable as Python identifier
     """
-    # First strip any trailing special characters
-    name = re.sub(r"[^\w-]+$", "", name)
-    # Then replace hyphens with underscores
-    return name.replace("-", "_")
+    # Strip trailing non-alphanumeric characters (excluding underscore) and replace hyphens
+    return TRIM_TRAILING_SPECIAL_CHARS.sub("", name).replace("-", "_")
 
 
 @dataclass
@@ -127,8 +125,6 @@ class SQLFileLoader:
         path_str = str(path)
 
         try:
-            # Always use storage backend for consistent behavior
-            # Pass the original path object to allow storage registry to handle Path -> file:// conversion
             backend = self.storage_registry.get(path)
             return backend.read_text(path_str, encoding=self.encoding)
         except KeyError as e:
@@ -151,48 +147,27 @@ class SQLFileLoader:
 
     @staticmethod
     def _parse_sql_content(content: str, file_path: str) -> dict[str, str]:
-        """Parse SQL content and extract named queries.
-
-        Args:
-            content: SQL file content.
-            file_path: Path to the file (for error messages).
-
-        Returns:
-            Dictionary mapping query names to SQL text.
-
-        Raises:
-            SQLFileParseError: If no named queries found.
-        """
+        """Parse SQL content and extract named queries."""
         queries: dict[str, str] = {}
-
-        # Split content by query name patterns
-        parts = QUERY_NAME_PATTERN.split(content)
-
-        if len(parts) < MIN_QUERY_PARTS:
-            # No named queries found
+        matches = list(QUERY_NAME_PATTERN.finditer(content))
+        if not matches:
             raise SQLFileParseError(
                 file_path, file_path, ValueError("No named SQL statements found (-- name: query_name)")
             )
 
-        # Process each named query
-        for i in range(1, len(parts), 2):
-            if i + 1 >= len(parts):
-                break
-
-            raw_query_name = parts[i].strip()
-            sql_text = parts[i + 1].strip()
+        for i, match in enumerate(matches):
+            raw_query_name = match.group(1).strip()
+            start_pos = match.end()
+            end_pos = matches[i + 1].start() if i + 1 < len(matches) else len(content)
 
+            sql_text = content[start_pos:end_pos].strip()
             if not raw_query_name or not sql_text:
                 continue
 
             clean_sql = SQLFileLoader._strip_leading_comments(sql_text)
-
             if clean_sql:
-                # Normalize to Python-compatible identifier
                 query_name = _normalize_query_name(raw_query_name)
-
                 if query_name in queries:
-                    # Duplicate query name
                     raise SQLFileParseError(file_path, file_path, ValueError(f"Duplicate query name: {raw_query_name}"))
                 queries[query_name] = clean_sql
 
@@ -221,19 +196,13 @@ class SQLFileLoader:
         try:
             for path in paths:
                 path_str = str(path)
-
-                # Check if it's a URI
                 if "://" in path_str:
-                    # URIs are always treated as files, not directories
                     self._load_single_file(path, None)
                     loaded_count += 1
                 else:
-                    # Local path - check if it's a directory or file
                     path_obj = Path(path)
                     if path_obj.is_dir():
-                        file_count_before = len(self._files)
-                        self._load_directory(path_obj)
-                        loaded_count += len(self._files) - file_count_before
+                        loaded_count += self._load_directory(path_obj)
                     else:
                         self._load_single_file(path_obj, None)
                         loaded_count += 1
@@ -267,31 +236,18 @@ class SQLFileLoader:
             )
             raise
 
-    def _load_directory(self, dir_path: Path) -> None:
-        """Load all SQL files from a directory with namespacing.
-
-        Args:
-            dir_path: Directory path to scan for SQL files.
-
-        Raises:
-            SQLFileParseError: If directory contains no SQL files.
-        """
+    def _load_directory(self, dir_path: Path) -> int:
+        """Load all SQL files from a directory with namespacing."""
         sql_files = list(dir_path.rglob("*.sql"))
-
         if not sql_files:
-            raise SQLFileParseError(
-                str(dir_path), str(dir_path), ValueError(f"No SQL files found in directory: {dir_path}")
-            )
+            return 0
 
         for file_path in sql_files:
-            # Calculate namespace based on relative path from base directory
             relative_path = file_path.relative_to(dir_path)
             namespace_parts = relative_path.parent.parts
-
-            # Create namespace (empty for root-level files)
             namespace = ".".join(namespace_parts) if namespace_parts else None
-
             self._load_single_file(file_path, namespace)
+        return len(sql_files)
 
     def _load_single_file(self, file_path: Union[str, Path], namespace: Optional[str]) -> None:
         """Load a single SQL file with optional namespace.
@@ -302,42 +258,24 @@ class SQLFileLoader:
         """
         path_str = str(file_path)
 
-        # Check if already loaded
         if path_str in self._files:
-            # File already loaded, just ensure queries are in the main dict
-            file_obj = self._files[path_str]
-            queries = self._parse_sql_content(file_obj.content, path_str)
-            for name in queries:
-                namespaced_name = f"{namespace}.{name}" if namespace else name
-                if namespaced_name not in self._queries:
-                    self._queries[namespaced_name] = queries[name]
-                    self._query_to_file[namespaced_name] = path_str
-            return
-
-        # Read file content
-        content = self._read_file_content(file_path)
+            return  # Already loaded
 
-        # Create SQLFile object
+        content = self._read_file_content(file_path)
         sql_file = SQLFile(content=content, path=path_str)
-
-        # Cache the file
         self._files[path_str] = sql_file
 
-        # Parse and cache queries
         queries = self._parse_sql_content(content, path_str)
-
-        # Merge into main query dictionary with namespace
         for name, sql in queries.items():
             namespaced_name = f"{namespace}.{name}" if namespace else name
-
-            if namespaced_name in self._queries and self._query_to_file.get(namespaced_name) != path_str:
-                # Query name exists from a different file
+            if namespaced_name in self._queries:
                 existing_file = self._query_to_file.get(namespaced_name, "unknown")
-                raise SQLFileParseError(
-                    path_str,
-                    path_str,
-                    ValueError(f"Query name '{namespaced_name}' already exists in file: {existing_file}"),
-                )
+                if existing_file != path_str:
+                    raise SQLFileParseError(
+                        path_str,
+                        path_str,
+                        ValueError(f"Query name '{namespaced_name}' already exists in file: {existing_file}"),
+                    )
             self._queries[namespaced_name] = sql
             self._query_to_file[namespaced_name] = path_str
 
@@ -357,7 +295,6 @@ class SQLFileLoader:
             raise ValueError(msg)
 
         self._queries[name] = sql.strip()
-        # Use special marker for directly added queries
         self._query_to_file[name] = "<directly added>"
 
     def get_sql(self, name: str, parameters: "Optional[Any]" = None, **kwargs: "Any") -> "SQL":
@@ -405,12 +342,10 @@ class SQLFileLoader:
             )
             raise SQLFileNotFoundError(name, path=f"Query '{name}' not found. Available queries: {available}")
 
-        # Merge parameters and kwargs for SQL object creation
         sql_kwargs = dict(kwargs)
         if parameters is not None:
             sql_kwargs["parameters"] = parameters
 
-        # Get source file for additional context
         source_file = self._query_to_file.get(safe_name, "unknown")
 
         logger.debug(