sqlspec 0.14.1__py3-none-any.whl → 0.16.0__py3-none-any.whl

sqlspec/extensions/aiosql/adapter.py

@@ -10,13 +10,13 @@ from collections.abc import AsyncGenerator, Generator
 from contextlib import asynccontextmanager, contextmanager
 from typing import TYPE_CHECKING, Any, ClassVar, Optional, TypeVar, Union, cast
 
+from sqlspec.core.result import SQLResult
+from sqlspec.core.statement import SQL, StatementConfig
 from sqlspec.exceptions import MissingDependencyError
-from sqlspec.statement.result import SQLResult
-from sqlspec.statement.sql import SQL, SQLConfig
-from sqlspec.typing import AIOSQL_INSTALLED, RowT
+from sqlspec.typing import AIOSQL_INSTALLED
 
 if TYPE_CHECKING:
-    from sqlspec.driver import AsyncDriverAdapterProtocol, SyncDriverAdapterProtocol
+    from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
 
 logger = logging.getLogger("sqlspec.extensions.aiosql")
 
@@ -25,6 +25,34 @@ __all__ = ("AiosqlAsyncAdapter", "AiosqlSyncAdapter")
 T = TypeVar("T")
 
 
+class AsyncCursorLike:
+    def __init__(self, result: Any) -> None:
+        self.result = result
+
+    async def fetchall(self) -> list[Any]:
+        if isinstance(self.result, SQLResult) and self.result.data is not None:
+            return list(self.result.data)
+        return []
+
+    async def fetchone(self) -> Optional[Any]:
+        rows = await self.fetchall()
+        return rows[0] if rows else None
+
+
+class CursorLike:
+    def __init__(self, result: Any) -> None:
+        self.result = result
+
+    def fetchall(self) -> list[Any]:
+        if isinstance(self.result, SQLResult) and self.result.data is not None:
+            return list(self.result.data)
+        return []
+
+    def fetchone(self) -> Optional[Any]:
+        rows = self.fetchall()
+        return rows[0] if rows else None
+
+
 def _check_aiosql_available() -> None:
     if not AIOSQL_INSTALLED:
         msg = "aiosql"
@@ -38,21 +66,20 @@ def _normalize_dialect(dialect: "Union[str, Any, None]") -> str:
         dialect: Original dialect name (can be str, Dialect, type[Dialect], or None)
 
     Returns:
-        converted dialect name
+        Converted dialect name compatible with SQLGlot
     """
     if dialect is None:
         return "sql"
 
-    if hasattr(dialect, "__name__"):  # It's a class
+    if hasattr(dialect, "__name__"):
         dialect_str = str(dialect.__name__).lower()  # pyright: ignore
-    elif hasattr(dialect, "name"):  # It's an instance with name attribute
+    elif hasattr(dialect, "name"):
         dialect_str = str(dialect.name).lower()  # pyright: ignore
     elif isinstance(dialect, str):
         dialect_str = dialect.lower()
     else:
         dialect_str = str(dialect).lower()
 
-    # Map common dialect aliases to SQLGlot names
     dialect_mapping = {
         "postgresql": "postgres",
         "psycopg": "postgres",
@@ -65,11 +92,9 @@ def _normalize_dialect(dialect: "Union[str, Any, None]") -> str:
 
 
 class _AiosqlAdapterBase:
-    """Base adapter for common logic."""
+    """Base adapter class providing common functionality for aiosql integration."""
 
-    def __init__(
-        self, driver: "Union[SyncDriverAdapterProtocol[Any, Any], AsyncDriverAdapterProtocol[Any, Any]]"
-    ) -> None:
+    def __init__(self, driver: "Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]") -> None:
         """Initialize the base adapter.
 
         Args:
@@ -79,27 +104,46 @@ class _AiosqlAdapterBase:
         self.driver = driver
 
     def process_sql(self, query_name: str, op_type: "Any", sql: str) -> str:
-        """Process SQL for aiosql compatibility."""
+        """Process SQL string for aiosql compatibility.
+
+        Args:
+            query_name: Name of the query
+            op_type: Operation type
+            sql: SQL string to process
+
+        Returns:
+            Processed SQL string
+        """
         return sql
 
     def _create_sql_object(self, sql: str, parameters: "Any" = None) -> SQL:
-        """Create SQL object with proper configuration."""
-        config = SQLConfig(enable_validation=False)
-        converted_dialect = _normalize_dialect(self.driver.dialect)
-        return SQL(sql, parameters, config=config, dialect=converted_dialect)
+        """Create SQL object with proper configuration.
 
+        Args:
+            sql: SQL string
+            parameters: Query parameters
 
-class AiosqlSyncAdapter(_AiosqlAdapterBase):
-    """Sync adapter that implements aiosql protocol using SQLSpec drivers.
+        Returns:
+            Configured SQL object
+        """
+        return SQL(
+            sql,
+            parameters,
+            config=StatementConfig(enable_validation=False),
+            dialect=_normalize_dialect(getattr(self.driver, "dialect", "sqlite")),
+        )
 
-    This adapter bridges aiosql's sync driver protocol with SQLSpec's sync drivers,
-    enabling all of SQLSpec's drivers to work with queries loaded by aiosql.
 
+class AiosqlSyncAdapter(_AiosqlAdapterBase):
+    """Synchronous adapter that implements aiosql protocol using SQLSpec drivers.
+
+    This adapter bridges aiosql's synchronous driver protocol with SQLSpec's sync drivers,
+    enabling queries loaded by aiosql to be executed with SQLSpec drivers.
     """
 
     is_aio_driver: ClassVar[bool] = False
 
-    def __init__(self, driver: "SyncDriverAdapterProtocol[Any, Any]") -> None:
+    def __init__(self, driver: "SyncDriverAdapterBase") -> None:
         """Initialize the sync adapter.
 
         Args:
@@ -123,8 +167,8 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
             Query result rows
 
         Note:
-            record_class parameter is ignored. Use schema_type in driver.execute
-            or _sqlspec_schema_type in parameters for type mapping.
+            The record_class parameter is ignored for compatibility. Use schema_type
+            in driver.execute or _sqlspec_schema_type in parameters for type mapping.
         """
         if record_class is not None:
             logger.warning(
@@ -132,16 +176,14 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
                 "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
             )
 
-        sql_obj = self._create_sql_object(sql, parameters)
-        # Execute using SQLSpec driver
-        result = self.driver.execute(sql_obj, connection=conn)
+        result = self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
         if isinstance(result, SQLResult) and result.data is not None:
             yield from result.data
 
     def select_one(
         self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
-    ) -> Optional[RowT]:
+    ) -> Optional[dict[str, Any]]:
         """Execute a SELECT query and return first result.
 
         Args:
@@ -155,8 +197,8 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
             First result row or None
 
         Note:
-            record_class parameter is ignored. Use schema_type in driver.execute
-            or _sqlspec_schema_type in parameters for type mapping.
+            The record_class parameter is ignored for compatibility. Use schema_type
+            in driver.execute or _sqlspec_schema_type in parameters for type mapping.
         """
         if record_class is not None:
             logger.warning(
@@ -164,12 +206,10 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
                 "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
             )
 
-        sql_obj = self._create_sql_object(sql, parameters)
-
-        result = cast("SQLResult[RowT]", self.driver.execute(sql_obj, connection=conn))
+        result = cast("SQLResult", self.driver.execute(self._create_sql_object(sql, parameters), connection=conn))
 
         if hasattr(result, "data") and result.data and isinstance(result, SQLResult):
-            return cast("Optional[RowT]", result.data[0])
+            return cast("Optional[dict[str, Any]]", result.data[0])
         return None
 
     def select_value(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
@@ -207,21 +247,7 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         Yields:
             Cursor-like object with results
         """
-        sql_obj = self._create_sql_object(sql, parameters)
-        result = self.driver.execute(sql_obj, connection=conn)
-
-        class CursorLike:
-            def __init__(self, result: Any) -> None:
-                self.result = result
-
-            def fetchall(self) -> list[Any]:
-                if isinstance(result, SQLResult) and result.data is not None:
-                    return list(result.data)
-                return []
-
-            def fetchone(self) -> Optional[Any]:
-                rows = self.fetchall()
-                return rows[0] if rows else None
+        result = self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
         yield CursorLike(result)
 
@@ -237,10 +263,8 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         Returns:
             Number of affected rows
         """
-        sql_obj = self._create_sql_object(sql, parameters)
-        result = cast("SQLResult[Any]", self.driver.execute(sql_obj, connection=conn))
+        result = cast("SQLResult", self.driver.execute(self._create_sql_object(sql, parameters), connection=conn))
 
-        # SQLResult has rows_affected attribute
         return result.rows_affected if hasattr(result, "rows_affected") else 0
 
     def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> int:
@@ -255,12 +279,10 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         Returns:
             Number of affected rows
         """
-        # For executemany, we don't extract sqlspec filters from individual parameter sets
-        sql_obj = self._create_sql_object(sql)
-
-        result = cast("SQLResult[Any]", self.driver.execute_many(sql_obj, parameters=parameters, connection=conn))
+        result = cast(
+            "SQLResult", self.driver.execute_many(self._create_sql_object(sql), parameters=parameters, connection=conn)
+        )
 
-        # SQLResult has rows_affected attribute
         return result.rows_affected if hasattr(result, "rows_affected") else 0
 
     def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
@@ -275,20 +297,19 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         Returns:
             Returned value or None
         """
-        # INSERT RETURNING is treated like a select that returns data
         return self.select_one(conn, query_name, sql, parameters)
 
 
 class AiosqlAsyncAdapter(_AiosqlAdapterBase):
-    """Async adapter that implements aiosql protocol using SQLSpec drivers.
+    """Asynchronous adapter that implements aiosql protocol using SQLSpec drivers.
 
     This adapter bridges aiosql's async driver protocol with SQLSpec's async drivers,
-    enabling all of SQLSpec's features to work with queries loaded by aiosql.
+    enabling queries loaded by aiosql to be executed with SQLSpec async drivers.
     """
 
     is_aio_driver: ClassVar[bool] = True
 
-    def __init__(self, driver: "AsyncDriverAdapterProtocol[Any, Any]") -> None:
+    def __init__(self, driver: "AsyncDriverAdapterBase") -> None:
         """Initialize the async adapter.
 
         Args:
@@ -312,8 +333,8 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
             List of query result rows
 
         Note:
-            record_class parameter is ignored. Use schema_type in driver.execute
-            or _sqlspec_schema_type in parameters for type mapping.
+            The record_class parameter is ignored for compatibility. Use schema_type
+            in driver.execute or _sqlspec_schema_type in parameters for type mapping.
         """
         if record_class is not None:
             logger.warning(
@@ -321,9 +342,7 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
                 "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
             )
 
-        sql_obj = self._create_sql_object(sql, parameters)
-
-        result = await self.driver.execute(sql_obj, connection=conn)  # type: ignore[misc]
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
 
         if hasattr(result, "data") and result.data is not None and isinstance(result, SQLResult):
             return list(result.data)
@@ -345,8 +364,8 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
             First result row or None
 
         Note:
-            record_class parameter is ignored. Use schema_type in driver.execute
-            or _sqlspec_schema_type in parameters for type mapping.
+            The record_class parameter is ignored for compatibility. Use schema_type
+            in driver.execute or _sqlspec_schema_type in parameters for type mapping.
         """
         if record_class is not None:
             logger.warning(
@@ -354,9 +373,7 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
                 "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
             )
 
-        sql_obj = self._create_sql_object(sql, parameters)
-
-        result = await self.driver.execute(sql_obj, connection=conn)  # type: ignore[misc]
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
 
         if hasattr(result, "data") and result.data and isinstance(result, SQLResult):
             return result.data[0]
@@ -397,22 +414,7 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
         Yields:
             Cursor-like object with results
         """
-        sql_obj = self._create_sql_object(sql, parameters)
-        result = await self.driver.execute(sql_obj, connection=conn)  # type: ignore[misc]
-
-        class AsyncCursorLike:
-            def __init__(self, result: Any) -> None:
-                self.result = result
-
-            @staticmethod
-            async def fetchall() -> list[Any]:
-                if isinstance(result, SQLResult) and result.data is not None:
-                    return list(result.data)
-                return []
-
-            async def fetchone(self) -> Optional[Any]:
-                rows = await self.fetchall()
-                return rows[0] if rows else None
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
 
         yield AsyncCursorLike(result)
 
@@ -426,11 +428,9 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
             parameters: Query parameters
 
         Note:
-            Async version returns None per aiosql protocol
+            Returns None per aiosql async protocol
         """
-        sql_obj = self._create_sql_object(sql, parameters)
-
-        await self.driver.execute(sql_obj, connection=conn)  # type: ignore[misc]
+        await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
 
     async def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> None:
         """Execute INSERT/UPDATE/DELETE with many parameter sets.
@@ -442,11 +442,9 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
             parameters: Sequence of parameter sets
 
         Note:
-            Async version returns None per aiosql protocol
+            Returns None per aiosql async protocol
         """
-        # For executemany, we don't extract sqlspec filters from individual parameter sets
-        sql_obj = self._create_sql_object(sql)
-        await self.driver.execute_many(sql_obj, parameters=parameters, connection=conn)  # type: ignore[misc]
+        await self.driver.execute_many(self._create_sql_object(sql), parameters=parameters, connection=conn)  # type: ignore[misc]
 
     async def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
         """Execute INSERT with RETURNING and return result.
@@ -460,5 +458,4 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
         Returns:
             Returned value or None
         """
-        # INSERT RETURNING is treated like a select that returns data
         return await self.select_one(conn, query_name, sql, parameters)

sqlspec/extensions/litestar/cli.py

@@ -39,7 +39,7 @@ def get_database_migration_plugin(app: "Litestar") -> "SQLSpec":
     raise ImproperConfigurationError(msg)
 
 
-@click.group(cls=LitestarGroup, name="database")
+@click.group(cls=LitestarGroup, name="db")
 def database_group(ctx: "click.Context") -> None:
     """Manage SQLSpec database components."""
     ctx.obj = {"app": ctx.obj, "configs": get_database_migration_plugin(ctx.obj.app).config}

sqlspec/extensions/litestar/config.py

@@ -62,7 +62,6 @@ class DatabaseConfig:
 
     def __post_init__(self) -> None:
         if not self.config.supports_connection_pooling and self.pool_key == DEFAULT_POOL_KEY:  # type: ignore[union-attr,unused-ignore]
-            """If the database configuration does not support connection pooling, the pool key must be unique.  We just automatically generate a unique identify so it won't conflict with other configs that may get added"""
             self.pool_key = f"_{self.pool_key}_{id(self.config)}"
         if self.commit_mode == "manual":
             self.before_send_handler = manual_handler_maker(connection_scope_key=self.connection_key)

sqlspec/extensions/litestar/handlers.py

@@ -25,7 +25,6 @@ if TYPE_CHECKING:
     from sqlspec.typing import ConnectionT, PoolT
 
 SESSION_TERMINUS_ASGI_EVENTS = {HTTP_RESPONSE_START, HTTP_DISCONNECT, WEBSOCKET_DISCONNECT, WEBSOCKET_CLOSE}
-"""ASGI events that terminate a session scope."""
 
 __all__ = (
     "SESSION_TERMINUS_ASGI_EVENTS",
@@ -39,7 +38,7 @@ __all__ = (
 
 
 def manual_handler_maker(connection_scope_key: str) -> "Callable[[Message, Scope], Coroutine[Any, Any, None]]":
-    """Set up the handler to close the connection.
+    """Create handler for manual connection management.
 
     Args:
         connection_scope_key: The key used to store the connection in the ASGI scope.
@@ -70,7 +69,7 @@ def autocommit_handler_maker(
     extra_commit_statuses: "Optional[set[int]]" = None,
     extra_rollback_statuses: "Optional[set[int]]" = None,
 ) -> "Callable[[Message, Scope], Coroutine[Any, Any, None]]":
-    """Set up the handler to issue a transaction commit or rollback based on response status codes.
+    """Create handler for automatic transaction commit/rollback based on response status.
 
     Args:
         connection_scope_key: The key used to store the connection in the ASGI scope.
@@ -125,27 +124,25 @@ def autocommit_handler_maker(
 def lifespan_handler_maker(
     config: "DatabaseConfigProtocol[Any, Any, Any]", pool_key: str
 ) -> "Callable[[Litestar], AbstractAsyncContextManager[None]]":
-    """Build the lifespan handler for managing the database connection pool.
-
-    The pool is created on application startup and closed on shutdown.
+    """Create lifespan handler for managing database connection pool lifecycle.
 
     Args:
         config: The database configuration object.
         pool_key: The key under which the connection pool will be stored in `app.state`.
 
     Returns:
-        The generated lifespan handler.
+        The lifespan handler function.
     """
 
     @contextlib.asynccontextmanager
     async def lifespan_handler(app: "Litestar") -> "AsyncGenerator[None, None]":
-        """Manages the database pool lifecycle.
+        """Manage database pool lifecycle for the application.
 
         Args:
             app: The Litestar application instance.
 
         Yields:
-            The generated lifespan handler.
+            Control to application during pool lifetime.
         """
         db_pool = await ensure_async_(config.create_pool)()
         app.state.update({pool_key: db_pool})
@@ -156,7 +153,7 @@ def lifespan_handler_maker(
             try:
                 await ensure_async_(config.close_pool)()
             except Exception as e:
-                if app.logger:  # pragma: no cover
+                if app.logger:
                     app.logger.warning("Error closing database pool for %s. Error: %s", pool_key, e)
 
     return lifespan_handler
@@ -165,35 +162,30 @@ def lifespan_handler_maker(
 def pool_provider_maker(
     config: "DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]", pool_key: str
 ) -> "Callable[[State, Scope], Awaitable[PoolT]]":
-    """Build the pool provider to inject the application-level database pool.
+    """Create provider for injecting the application-level database pool.
 
     Args:
         config: The database configuration object.
         pool_key: The key used to store the connection pool in `app.state`.
 
     Returns:
-        The generated pool provider.
+        The pool provider function.
     """
 
     async def provide_pool(state: "State", scope: "Scope") -> "PoolT":
-        """Provides the database pool from `app.state`.
+        """Provide the database pool from application state.
 
         Args:
             state: The Litestar application State object.
             scope: The ASGI scope (unused for app-level pool).
 
-
         Returns:
             The database connection pool.
 
         Raises:
             ImproperConfigurationError: If the pool is not found in `app.state`.
         """
-        # The pool is stored in app.state by the lifespan handler.
-        # state.get(key) accesses app.state[key]
-        db_pool = state.get(pool_key)
-        if db_pool is None:
-            # This case should ideally not happen if the lifespan handler ran correctly.
+        if (db_pool := state.get(pool_key)) is None:
             msg = (
                 f"Database pool with key '{pool_key}' not found in application state. "
                 "Ensure the SQLSpec lifespan handler is correctly configured and has run."
@@ -208,8 +200,7 @@ def connection_provider_maker(
     config: "DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]", pool_key: str, connection_key: str
 ) -> "Callable[[State, Scope], AsyncGenerator[ConnectionT, None]]":
     async def provide_connection(state: "State", scope: "Scope") -> "AsyncGenerator[ConnectionT, None]":
-        db_pool = state.get(pool_key)
-        if db_pool is None:
+        if (db_pool := state.get(pool_key)) is None:
             msg = f"Database pool with key '{pool_key}' not found. Cannot create a connection."
             raise ImproperConfigurationError(msg)
 
@@ -225,15 +216,13 @@ def connection_provider_maker(
             yield conn_instance
             return
 
-        entered_connection: Optional[ConnectionT] = None
+        entered_connection = await connection_cm.__aenter__()
         try:
-            entered_connection = await connection_cm.__aenter__()
             set_sqlspec_scope_state(scope, connection_key, entered_connection)
             yield entered_connection
         finally:
-            if entered_connection is not None:
-                await connection_cm.__aexit__(None, None, None)
-                delete_sqlspec_scope_state(scope, connection_key)  # Clear from scope
+            await connection_cm.__aexit__(None, None, None)
+            delete_sqlspec_scope_state(scope, connection_key)
 
     return provide_connection
 

sqlspec/extensions/litestar/plugin.py

@@ -1,7 +1,7 @@
 from typing import TYPE_CHECKING, Any, Union
 
 from litestar.di import Provide
-from litestar.plugins import InitPluginProtocol
+from litestar.plugins import CLIPlugin, InitPluginProtocol
 
 from sqlspec.base import SQLSpec as SQLSpecBase
 from sqlspec.config import AsyncConfigT, DatabaseConfigProtocol, DriverT, SyncConfigT
@@ -17,16 +17,16 @@ if TYPE_CHECKING:
 logger = get_logger("extensions.litestar")
 
 
-class SQLSpec(InitPluginProtocol, SQLSpecBase):
-    """SQLSpec plugin."""
+class SQLSpec(InitPluginProtocol, CLIPlugin, SQLSpecBase):
+    """Litestar plugin for SQLSpec database integration."""
 
     __slots__ = ("_config", "_plugin_configs")
 
     def __init__(self, config: Union["SyncConfigT", "AsyncConfigT", "DatabaseConfig", list["DatabaseConfig"]]) -> None:
-        """Initialize ``SQLSpecPlugin``.
+        """Initialize SQLSpec plugin.
 
         Args:
-            config: configure SQLSpec plugin for use with Litestar.
+            config: Database configuration for SQLSpec plugin.
         """
         self._configs: dict[Any, DatabaseConfigProtocol[Any, Any, Any]] = {}
         if isinstance(config, DatabaseConfigProtocol):
@@ -38,27 +38,31 @@ class SQLSpec(InitPluginProtocol, SQLSpecBase):
 
     @property
     def config(self) -> "list[DatabaseConfig]":  # pyright: ignore[reportInvalidTypeVarUse]
-        """Return the plugin config.
+        """Return the plugin configuration.
 
         Returns:
-            ConfigManager.
+            List of database configurations.
         """
         return self._plugin_configs
 
     def on_cli_init(self, cli: "Group") -> None:
-        """Configure the CLI for use with SQLSpec."""
+        """Configure CLI commands for SQLSpec database operations.
+
+        Args:
+            cli: The Click command group to add commands to.
+        """
         from sqlspec.extensions.litestar.cli import database_group
 
         cli.add_command(database_group)
 
     def on_app_init(self, app_config: "AppConfig") -> "AppConfig":
-        """Configure application for use with SQLSpec.
+        """Configure Litestar application with SQLSpec database integration.
 
         Args:
-            app_config: The :class:`AppConfig <.config.app.AppConfig>` instance.
+            app_config: The Litestar application configuration instance.
 
         Returns:
-            The updated :class:`AppConfig <.config.app.AppConfig>` instance.
+            The updated application configuration instance.
         """
 
         self._validate_dependency_keys()
@@ -67,7 +71,6 @@ class SQLSpec(InitPluginProtocol, SQLSpecBase):
             app_config.state.sqlspec = self
 
         app_config.on_startup.append(store_sqlspec_in_state)
-        # Register types for injection
         app_config.signature_types.extend(
             [SQLSpec, ConnectionT, PoolT, DriverT, DatabaseConfig, DatabaseConfigProtocol, SyncConfigT, AsyncConfigT]
         )
@@ -81,8 +84,7 @@ class SQLSpec(InitPluginProtocol, SQLSpecBase):
             app_config.signature_types.append(c.config.driver_type)  # type: ignore[union-attr]
 
             if hasattr(c.config, "get_signature_namespace"):
-                config_namespace = c.config.get_signature_namespace()  # type: ignore[attr-defined]
-                signature_namespace.update(config_namespace)
+                signature_namespace.update(c.config.get_signature_namespace())  # type: ignore[attr-defined]
 
             app_config.before_send.append(c.before_send_handler)
             app_config.lifespan.append(c.lifespan_handler)  # pyright: ignore[reportUnknownMemberType]
@@ -128,10 +130,10 @@ class SQLSpec(InitPluginProtocol, SQLSpecBase):
         raise KeyError(msg)
 
     def _validate_dependency_keys(self) -> None:
-        """Verify uniqueness of ``connection_key`` and ``pool_key``.
+        """Validate that connection and pool keys are unique across configurations.
 
         Raises:
-            ImproperConfigurationError: If session keys or pool keys are not unique.
+            ImproperConfigurationError: If connection keys or pool keys are not unique.
         """
         connection_keys = [c.connection_key for c in self.config]
         pool_keys = [c.pool_key for c in self.config]