sqlspec 0.18.0__py3-none-any.whl → 0.20.0__py3-none-any.whl

sqlspec/adapters/psqlpy/driver.py

@@ -1,7 +1,7 @@
-"""Psqlpy driver implementation.
+"""Psqlpy driver implementation for PostgreSQL connectivity.
 
-Provides PostgreSQL connectivity with parameter style conversion,
-type coercion, error handling, and transaction management.
+Provides parameter style conversion, type coercion, error handling,
+and transaction management.
 """
 
 import datetime
@@ -39,7 +39,7 @@ psqlpy_statement_config = StatementConfig(
         default_execution_parameter_style=ParameterStyle.NUMERIC,
         supported_execution_parameter_styles={ParameterStyle.NUMERIC},
         type_coercion_map={tuple: list, decimal.Decimal: float},
-        has_native_list_expansion=True,
+        has_native_list_expansion=False,
         needs_static_script_compilation=False,
         allow_mixed_parameter_styles=False,
         preserve_parameter_format=True,
@@ -72,8 +72,8 @@ SPECIAL_TYPE_REGEX: Final[re.Pattern[str]] = re.compile(
 def _detect_postgresql_type(value: str) -> Optional[str]:
     """Detect PostgreSQL data type from string value.
 
-    Detects common PostgreSQL types including UUID, IP addresses,
-    timestamps, JSON, and arrays.
+    Args:
+        value: String value to analyze
 
     Returns:
         Type name if detected, None otherwise.
@@ -101,7 +101,14 @@ def _detect_postgresql_type(value: str) -> Optional[str]:
 
 
 def _convert_uuid(value: str) -> Any:
-    """Convert UUID string to UUID object."""
+    """Convert UUID string to UUID object.
+
+    Args:
+        value: UUID string to convert
+
+    Returns:
+        UUID object or original value if conversion fails
+    """
     try:
         clean_uuid = value.replace("-", "").lower()
         uuid_length = 32
@@ -114,7 +121,14 @@ def _convert_uuid(value: str) -> Any:
 
 
 def _convert_iso_datetime(value: str) -> Any:
-    """Convert ISO datetime string to datetime object."""
+    """Convert ISO datetime string to datetime object.
+
+    Args:
+        value: ISO datetime string to convert
+
+    Returns:
+        datetime object or original value if conversion fails
+    """
     try:
         normalized = value.replace("Z", "+00:00")
         return datetime.datetime.fromisoformat(normalized)
@@ -123,7 +137,14 @@ def _convert_iso_datetime(value: str) -> Any:
 
 
 def _convert_iso_date(value: str) -> Any:
-    """Convert ISO date string to date object."""
+    """Convert ISO date string to date object.
+
+    Args:
+        value: ISO date string to convert
+
+    Returns:
+        date object or original value if conversion fails
+    """
     try:
         return datetime.date.fromisoformat(value)
     except ValueError:
@@ -131,7 +152,14 @@ def _convert_iso_date(value: str) -> Any:
 
 
 def _validate_json(value: str) -> str:
-    """Validate JSON string but keep as string for psqlpy."""
+    """Validate JSON string format.
+
+    Args:
+        value: JSON string to validate
+
+    Returns:
+        Original string value
+    """
     from sqlspec.utils.serializers import from_json
 
     try:
@@ -142,7 +170,14 @@ def _validate_json(value: str) -> str:
 
 
 def _passthrough(value: str) -> str:
-    """Pass value through unchanged."""
+    """Pass value through unchanged.
+
+    Args:
+        value: String value to pass through
+
+    Returns:
+        Original value unchanged
+    """
     return value
 
 
@@ -161,15 +196,13 @@ _PSQLPY_TYPE_CONVERTERS: dict[str, Any] = {
 
 
 def _convert_psqlpy_parameters(value: Any) -> Any:
-    """Convert parameters for Psqlpy compatibility.
-
-    Performs type conversions based on detected PostgreSQL types.
+    """Convert parameters for psqlpy compatibility.
 
     Args:
         value: Parameter value to convert
 
     Returns:
-        Converted value suitable for psqlpy/PostgreSQL
+        Converted value suitable for psqlpy execution
     """
     if isinstance(value, str):
         detected_type = _detect_postgresql_type(value)
@@ -188,7 +221,7 @@ def _convert_psqlpy_parameters(value: Any) -> Any:
 
 
 class PsqlpyCursor:
-    """Context manager for Psqlpy cursor management."""
+    """Context manager for psqlpy cursor management."""
 
     __slots__ = ("_in_use", "connection")
 
@@ -197,22 +230,36 @@ class PsqlpyCursor:
         self._in_use = False
 
     async def __aenter__(self) -> "PsqlpyConnection":
-        """Enter cursor context."""
+        """Enter cursor context.
+
+        Returns:
+            Psqlpy connection object
+        """
         self._in_use = True
         return self.connection
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
-        """Exit cursor context."""
+        """Exit cursor context.
+
+        Args:
+            exc_type: Exception type
+            exc_val: Exception value
+            exc_tb: Exception traceback
+        """
         _ = (exc_type, exc_val, exc_tb)
         self._in_use = False
 
     def is_in_use(self) -> bool:
-        """Check if cursor is currently in use."""
+        """Check if cursor is currently in use.
+
+        Returns:
+            True if cursor is in use, False otherwise
+        """
         return self._in_use
 
 
 class PsqlpyExceptionHandler:
-    """Custom async context manager for handling Psqlpy database exceptions."""
+    """Async context manager for handling psqlpy database exceptions."""
 
     __slots__ = ()
 
@@ -250,10 +297,10 @@ class PsqlpyExceptionHandler:
 
 
 class PsqlpyDriver(AsyncDriverAdapterBase):
-    """Psqlpy driver implementation.
+    """PostgreSQL driver implementation using psqlpy.
 
-    Provides PostgreSQL connectivity through psqlpy with parameter style
-    conversion, type coercion, error handling, and transaction management.
+    Provides parameter style conversion, type coercion, error handling,
+    and transaction management.
     """
 
     __slots__ = ()
@@ -277,11 +324,22 @@ class PsqlpyDriver(AsyncDriverAdapterBase):
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
 
     def with_cursor(self, connection: "PsqlpyConnection") -> "PsqlpyCursor":
-        """Create context manager for psqlpy cursor."""
+        """Create context manager for psqlpy cursor.
+
+        Args:
+            connection: Psqlpy connection object
+
+        Returns:
+            PsqlpyCursor context manager
+        """
         return PsqlpyCursor(connection)
 
     def handle_database_exceptions(self) -> "AbstractAsyncContextManager[None]":
-        """Handle database-specific exceptions and wrap them appropriately."""
+        """Handle database-specific exceptions.
+
+        Returns:
+            Exception handler context manager
+        """
         return PsqlpyExceptionHandler()
 
     async def _try_special_handling(self, cursor: "PsqlpyConnection", statement: SQL) -> "Optional[SQLResult]":
@@ -292,13 +350,13 @@ class PsqlpyDriver(AsyncDriverAdapterBase):
             statement: SQL statement to analyze
 
         Returns:
-            None for standard execution
+            SQLResult if special handling applied, None otherwise
         """
         _ = (cursor, statement)
         return None
 
     async def _execute_script(self, cursor: "PsqlpyConnection", statement: SQL) -> "ExecutionResult":
-        """Execute SQL script with statement splitting and parameter handling.
+        """Execute SQL script with statement splitting.
 
         Args:
             cursor: Psqlpy connection object
@@ -329,7 +387,7 @@ class PsqlpyDriver(AsyncDriverAdapterBase):
         )
 
     async def _execute_many(self, cursor: "PsqlpyConnection", statement: SQL) -> "ExecutionResult":
-        """Execute SQL with multiple parameter sets using batch processing.
+        """Execute SQL with multiple parameter sets.
 
         Args:
             cursor: Psqlpy connection object
@@ -358,7 +416,7 @@ class PsqlpyDriver(AsyncDriverAdapterBase):
         return self.create_execution_result(cursor, rowcount_override=rows_affected, is_many_result=True)
 
     async def _execute_statement(self, cursor: "PsqlpyConnection", statement: SQL) -> "ExecutionResult":
-        """Execute single SQL statement with data handling.
+        """Execute single SQL statement.
 
         Args:
             cursor: Psqlpy connection object
@@ -396,7 +454,7 @@ class PsqlpyDriver(AsyncDriverAdapterBase):
             result: Psqlpy execution result object
 
         Returns:
-            Number of rows affected, or -1 if unable to determine
+            Number of rows affected, -1 if unable to determine
         """
         try:
             if hasattr(result, "tag") and result.tag:
@@ -416,7 +474,7 @@ class PsqlpyDriver(AsyncDriverAdapterBase):
             tag: PostgreSQL command tag string
 
         Returns:
-            Number of rows affected, or -1 if unable to parse
+            Number of rows affected, -1 if unable to parse
         """
         if not tag:
             return -1

sqlspec/adapters/psycopg/driver.py

@@ -180,17 +180,11 @@ class PsycopgSyncExceptionHandler:
 class PsycopgSyncDriver(SyncDriverAdapterBase):
     """PostgreSQL psycopg synchronous driver.
 
-    Provides synchronous database operations for PostgreSQL using psycopg3:
-    - SQL statement execution with parameter binding
-    - Transaction management (begin, commit, rollback)
-    - Result processing with column metadata
-    - PostgreSQL-specific features support
-
-    PostgreSQL Features:
-    - Parameter styles ($1, %s, %(name)s)
-    - PostgreSQL arrays and JSON handling
-    - COPY operations for bulk data transfer
-    - PostgreSQL-specific error handling
+    Provides synchronous database operations for PostgreSQL using psycopg3.
+    Supports SQL statement execution with parameter binding, transaction
+    management, result processing with column metadata, parameter style
+    conversion, PostgreSQL arrays and JSON handling, COPY operations for
+    bulk data transfer, and PostgreSQL-specific error handling.
     """
 
     __slots__ = ()
@@ -486,18 +480,12 @@ class PsycopgAsyncExceptionHandler:
 class PsycopgAsyncDriver(AsyncDriverAdapterBase):
     """PostgreSQL psycopg asynchronous driver.
 
-    Provides asynchronous database operations for PostgreSQL using psycopg3:
-    - Async SQL statement execution with parameter binding
-    - Async transaction management (begin, commit, rollback)
-    - Async result processing with column metadata
-    - PostgreSQL-specific features support
-
-    PostgreSQL Features:
-    - Parameter styles ($1, %s, %(name)s)
-    - PostgreSQL arrays and JSON handling
-    - COPY operations for bulk data transfer
-    - PostgreSQL-specific error handling
-    - Async pub/sub support (LISTEN/NOTIFY)
+    Provides asynchronous database operations for PostgreSQL using psycopg3.
+    Supports async SQL statement execution with parameter binding, async
+    transaction management, async result processing with column metadata,
+    parameter style conversion, PostgreSQL arrays and JSON handling, COPY
+    operations for bulk data transfer, PostgreSQL-specific error handling,
+    and async pub/sub support.
     """
 
     __slots__ = ()

sqlspec/adapters/sqlite/driver.py

@@ -50,19 +50,39 @@ sqlite_statement_config = StatementConfig(
 
 
 class SqliteCursor:
-    """Context manager for SQLite cursor management."""
+    """Context manager for SQLite cursor management.
+
+    Provides automatic cursor creation and cleanup for SQLite database operations.
+    """
 
     __slots__ = ("connection", "cursor")
 
     def __init__(self, connection: "SqliteConnection") -> None:
+        """Initialize cursor manager.
+
+        Args:
+            connection: SQLite database connection
+        """
         self.connection = connection
         self.cursor: Optional[sqlite3.Cursor] = None
 
     def __enter__(self) -> "sqlite3.Cursor":
+        """Create and return a new cursor.
+
+        Returns:
+            Active SQLite cursor object
+        """
         self.cursor = self.connection.cursor()
         return self.cursor
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Clean up cursor resources.
+
+        Args:
+            exc_type: Exception type if an exception occurred
+            exc_val: Exception value if an exception occurred
+            exc_tb: Exception traceback if an exception occurred
+        """
         _ = (exc_type, exc_val, exc_tb)
         if self.cursor is not None:
             with contextlib.suppress(Exception):
@@ -70,14 +90,33 @@ class SqliteCursor:
 
 
 class SqliteExceptionHandler:
-    """Context manager for handling SQLite database exceptions."""
+    """Context manager for handling SQLite database exceptions.
+
+    Catches SQLite-specific exceptions and converts them to appropriate SQLSpec exceptions.
+    """
 
     __slots__ = ()
 
     def __enter__(self) -> None:
-        return None
+        """Enter exception handling context.
+
+        Returns:
+            None
+        """
+        return
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Handle exceptions and convert to SQLSpec exceptions.
+
+        Args:
+            exc_type: Exception type if an exception occurred
+            exc_val: Exception value if an exception occurred
+            exc_tb: Exception traceback if an exception occurred
+
+        Raises:
+            SQLSpecError: For general database errors
+            SQLParsingError: For SQL syntax or parsing errors
+        """
         if exc_type is None:
             return
 
@@ -129,6 +168,13 @@ class SqliteDriver(SyncDriverAdapterBase):
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
     ) -> None:
+        """Initialize SQLite driver.
+
+        Args:
+            connection: SQLite database connection
+            statement_config: Statement configuration settings
+            driver_features: Driver-specific feature flags
+        """
         if statement_config is None:
             cache_config = get_cache_config()
             statement_config = sqlite_statement_config.replace(
@@ -141,11 +187,22 @@ class SqliteDriver(SyncDriverAdapterBase):
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
 
     def with_cursor(self, connection: "SqliteConnection") -> "SqliteCursor":
-        """Create context manager for SQLite cursor."""
+        """Create context manager for SQLite cursor.
+
+        Args:
+            connection: SQLite database connection
+
+        Returns:
+            Cursor context manager for safe cursor operations
+        """
         return SqliteCursor(connection)
 
     def handle_database_exceptions(self) -> "AbstractContextManager[None]":
-        """Handle database-specific exceptions and wrap them appropriately."""
+        """Handle database-specific exceptions and wrap them appropriately.
+
+        Returns:
+            Context manager that converts SQLite exceptions to SQLSpec exceptions
+        """
         return SqliteExceptionHandler()
 
     def _try_special_handling(self, cursor: "sqlite3.Cursor", statement: "SQL") -> "Optional[SQLResult]":
@@ -233,7 +290,11 @@ class SqliteDriver(SyncDriverAdapterBase):
         return self.create_execution_result(cursor, rowcount_override=affected_rows)
 
     def begin(self) -> None:
-        """Begin a database transaction."""
+        """Begin a database transaction.
+
+        Raises:
+            SQLSpecError: If transaction cannot be started
+        """
         try:
             if not self.connection.in_transaction:
                 self.connection.execute("BEGIN")
@@ -242,7 +303,11 @@ class SqliteDriver(SyncDriverAdapterBase):
             raise SQLSpecError(msg) from e
 
     def rollback(self) -> None:
-        """Rollback the current transaction."""
+        """Rollback the current transaction.
+
+        Raises:
+            SQLSpecError: If transaction cannot be rolled back
+        """
         try:
             self.connection.rollback()
         except sqlite3.Error as e:
@@ -250,7 +315,11 @@ class SqliteDriver(SyncDriverAdapterBase):
             raise SQLSpecError(msg) from e
 
     def commit(self) -> None:
-        """Commit the current transaction."""
+        """Commit the current transaction.
+
+        Raises:
+            SQLSpecError: If transaction cannot be committed
+        """
         try:
             self.connection.commit()
         except sqlite3.Error as e:

sqlspec/base.py

@@ -125,7 +125,7 @@ class SQLSpec:
             config: The configuration instance to add.
 
         Returns:
-            The type of the added configuration, annotated with its ID for potential use in type systems.
+            The type of the added configuration for use as a registry key.
         """
         config_type = type(config)
         if config_type in self._configs:
@@ -331,7 +331,6 @@ class SQLSpec:
             *args: Positional arguments to pass to the config's provide_connection.
             **kwargs: Keyword arguments to pass to the config's provide_connection.
 
-
         Returns:
             A sync or async context manager yielding a connection.
         """
@@ -564,12 +563,12 @@ class SQLSpec:
         """Update cache configuration with partial values.
 
         Args:
-            sql_cache_size: Size of the SQL statement cache
-            fragment_cache_size: Size of the AST fragment cache
-            optimized_cache_size: Size of the optimized expression cache
-            sql_cache_enabled: Enable/disable SQL cache
-            fragment_cache_enabled: Enable/disable fragment cache
-            optimized_cache_enabled: Enable/disable optimized cache
+            sql_cache_size: Size of the SQL statement cache.
+            fragment_cache_size: Size of the AST fragment cache.
+            optimized_cache_size: Size of the optimized expression cache.
+            sql_cache_enabled: Enable/disable SQL cache.
+            fragment_cache_enabled: Enable/disable fragment cache.
+            optimized_cache_enabled: Enable/disable optimized cache.
         """
         current_config = get_cache_config()
         update_cache_config(
@@ -593,22 +592,18 @@ class SQLSpec:
             )
         )
 
-    def _ensure_sql_loader(self) -> "SQLFileLoader":
-        """Ensure SQL loader is initialized lazily."""
-        if self._sql_loader is None:
-            from sqlspec.loader import SQLFileLoader
-
-            self._sql_loader = SQLFileLoader()
-        return self._sql_loader
-
     def load_sql_files(self, *paths: "Union[str, Path]") -> None:
         """Load SQL files from paths or directories.
 
         Args:
             *paths: One or more file paths or directory paths to load.
         """
-        loader = self._ensure_sql_loader()
-        loader.load_sql(*paths)
+        if self._sql_loader is None:
+            from sqlspec.loader import SQLFileLoader
+
+            self._sql_loader = SQLFileLoader()
+
+        self._sql_loader.load_sql(*paths)
         logger.debug("Loaded SQL files: %s", paths)
 
     def add_named_sql(self, name: str, sql: str, dialect: "Optional[str]" = None) -> None:
@@ -619,22 +614,30 @@ class SQLSpec:
             sql: Raw SQL content.
             dialect: Optional dialect for the SQL statement.
         """
-        loader = self._ensure_sql_loader()
-        loader.add_named_sql(name, sql, dialect)
+        if self._sql_loader is None:
+            from sqlspec.loader import SQLFileLoader
+
+            self._sql_loader = SQLFileLoader()
+
+        self._sql_loader.add_named_sql(name, sql, dialect)
         logger.debug("Added named SQL: %s", name)
 
     def get_sql(self, name: str) -> "SQL":
         """Get a SQL object by name.
 
         Args:
-            name: Name of the statement (from -- name: in SQL file).
+            name: Name of the statement from SQL file comments.
                   Hyphens in names are converted to underscores.
 
         Returns:
             SQL object ready for execution.
         """
-        loader = self._ensure_sql_loader()
-        return loader.get_sql(name)
+        if self._sql_loader is None:
+            from sqlspec.loader import SQLFileLoader
+
+            self._sql_loader = SQLFileLoader()
+
+        return self._sql_loader.get_sql(name)
 
     def list_sql_queries(self) -> "list[str]":
         """List all available query names.
@@ -653,7 +656,7 @@ class SQLSpec:
             name: Query name to check.
 
         Returns:
-            True if query exists.
+            True if the query exists in the loader.
         """
         if self._sql_loader is None:
             return False
@@ -668,7 +671,8 @@ class SQLSpec:
     def reload_sql_files(self) -> None:
         """Reload all SQL files.
 
-        Note: This clears the cache and requires calling load_sql_files again.
+        Note:
+            This clears the cache and requires calling load_sql_files again.
         """
         if self._sql_loader is not None:
             self._sql_loader.clear_cache()

sqlspec/builder/__init__.py

@@ -1,6 +1,6 @@
 """SQL query builders for safe SQL construction.
 
-This package provides fluent interfaces for building SQL queries with
+Provides fluent interfaces for building SQL queries with
 parameter binding and validation.
 """
 

sqlspec/builder/_base.py

@@ -1,7 +1,6 @@
-"""Safe SQL query builder with validation and parameter binding.
+"""Base query builder with validation and parameter binding.
 
-This module provides a fluent interface for building SQL queries with
-parameter binding and validation.
+Provides abstract base classes and core functionality for SQL query builders.
 """
 
 from abc import ABC, abstractmethod
@@ -31,7 +30,7 @@ logger = get_logger(__name__)
 
 
 class SafeQuery:
-    """A safely constructed SQL query with bound parameters."""
+    """SQL query with bound parameters."""
 
     __slots__ = ("dialect", "parameters", "sql")
 
@@ -44,7 +43,7 @@ class SafeQuery:
 
 
 class QueryBuilder(ABC):
-    """Abstract base class for SQL query builders with SQLGlot optimization.
+    """Abstract base class for SQL query builders.
 
     Provides common functionality for dialect handling, parameter management,
     and query construction using SQLGlot.

sqlspec/builder/_column.py

@@ -1,7 +1,7 @@
-"""Pythonic column expressions for query building.
+"""Column expressions for query building.
 
-This module provides Column objects that support native Python operators
-for building SQL conditions with type safety and parameter binding.
+Provides Column objects that support Python operators for building
+SQL conditions with parameter binding.
 """
 
 from collections.abc import Iterable

sqlspec/builder/_ddl.py

@@ -1,4 +1,8 @@
-"""DDL builders for SQLSpec: DROP, CREATE INDEX, TRUNCATE, etc."""
+"""DDL statement builders.
+
+Provides builders for DDL operations including CREATE, DROP, ALTER,
+TRUNCATE, and other schema manipulation statements.
+"""
 
 from typing import TYPE_CHECKING, Any, Optional, Union
 

sqlspec/builder/_delete.py

@@ -1,7 +1,7 @@
-"""Safe SQL query builder with validation and parameter binding.
+"""DELETE statement builder.
 
-This module provides a fluent interface for building SQL queries safely,
-with automatic parameter binding and validation.
+Provides a fluent interface for building SQL DELETE queries with
+parameter binding and validation.
 """
 
 from typing import Any, Optional
@@ -19,9 +19,8 @@ __all__ = ("Delete",)
 class Delete(QueryBuilder, WhereClauseMixin, ReturningClauseMixin, DeleteFromClauseMixin):
     """Builder for DELETE statements.
 
-    This builder provides a fluent interface for constructing SQL DELETE statements
-    with automatic parameter binding and validation. It does not support JOIN
-    operations to maintain cross-dialect compatibility and safety.
+    Constructs SQL DELETE statements with parameter binding and validation.
+    Does not support JOIN operations to maintain cross-dialect compatibility.
     """
 
     __slots__ = ("_table",)