SQLAlchemy 2.0 InitPluginProtocol implementation.

docs/conf.py

@@ -82,8 +82,8 @@
     # intentionally undocumented
     ("py:class", "NoneType"),
     ("py:class", "starlite._signature.models.SignatureField"),
-    ("py:class", "starlite.contrib.sqlalchemy.init_plugin.config.common.GenericSessionConfig"),
-    ("py:class", "starlite.contrib.sqlalchemy.init_plugin.config.common.GenericSQLAlchemyConfig"),
+    ("py:class", "starlite.contrib.sqlalchemy.init_plugin.config._common.GenericSessionConfig"),
+    ("py:class", "starlite.contrib.sqlalchemy.init_plugin.config._common.GenericSQLAlchemyConfig"),
 ]
 nitpick_ignore_regex = [
     (r"py:.*", r"starlite\.types.*"),

starlite/contrib/sqlalchemy/init_plugin/config/common.py → starlite/contrib/sqlalchemy/init_plugin/config/_common.py

@@ -44,16 +44,41 @@ class GenericSessionConfig(Generic[ConnectionT, EngineT, SessionT]):
     """SQLAlchemy async session config."""
 
     autobegin: bool | EmptyType = Empty
+    """Automatically start transactions when database access is requested by an operation."""
     autoflush: bool | EmptyType = Empty
+    """When ``True``, all query operations will issue a flush call to this :class:`Session <sqlalchemy.orm.Session>`
+    before proceeding"""
     bind: EngineT | ConnectionT | None | EmptyType = Empty
+    """The :class:`Engine <sqlalchemy.engine.Engine>` or :class:`Connection <sqlalchemy.engine.Connection>` that new
+    :class:`Session <sqlalchemy.orm.Session>` objects will be bound to."""
     binds: dict[type[Any] | Mapper[Any] | TableClause | str, EngineT | ConnectionT] | None | EmptyType = Empty
+    """A dictionary which may specify any number of :class:`Engine <sqlalchemy.engine.Engine>` or :class:`Connection
+    <sqlalchemy.engine.Connection>` objects as the source of connectivity for SQL operations on a per-entity basis. The
+    keys of the dictionary consist of any series of mapped classes, arbitrary Python classes that are bases for mapped
+    classes, :class:`Table <sqlalchemy.schema.Table>` objects and :class:`Mapper <sqlalchemy.orm.Mapper>` objects. The
+    values of the dictionary are then instances of :class:`Engine <sqlalchemy.engine.Engine>` or less commonly
+    :class:`Connection<sqlalchemy.engine.Connection>` objects."""
     class_: type[SessionT] | EmptyType = Empty
-    enable_baked_queries: bool | EmptyType = Empty
+    """Class to use in order to create new :class:`Session <sqlalchemy.orm.Session>` objects."""
     expire_on_commit: bool | EmptyType = Empty
+    """If ``True``, all instances will be expired after each commit."""
     info: dict[str, Any] | None | EmptyType = Empty
+    """Optional dictionary of information that will be available via the
+    :attr:`Session.info <sqlalchemy.orm.Session.info>`"""
     join_transaction_mode: JoinTransactionMode | EmptyType = Empty
+    """Describes the transactional behavior to take when a given bind is a Connection that has already begun a
+    transaction outside the scope of this Session; in other words the
+    :attr:`Connection.in_transaction()<sqlalchemy.Connection.in_transaction>` method returns True."""
     query_cls: type[Query] | None | EmptyType = Empty
+    """Class which should be used to create new Query objects, as returned by the
+    :attr:`Session.query()<sqlalchemy.orm.Session.query>` method."""
     twophase: bool | EmptyType = Empty
+    """When ``True``, all transactions will be started as a “two phase” transaction, i.e. using the “two phase”
+    semantics of the database in use along with an XID. During a :attr:`commit()<sqlalchemy.orm.Session.commit>`, after
+    :attr:`flush()<sqlalchemy.orm.Session.flush>` has been issued for all attached databases, the
+    :attr:`TwoPhaseTransaction.prepare()<sqlalchemy.engine.TwoPhaseTransaction.prepare>` method on each database`s
+    :class:`TwoPhaseTransaction<sqlalchemy.engine.TwoPhaseTransaction>` will be called. This allows each database to
+    roll back the entire transaction, before each transaction is committed."""
 
 
 @dataclass

starlite/contrib/sqlalchemy/init_plugin/config/asyncio.py

@@ -11,7 +11,7 @@
     get_starlite_scope_state,
 )
 
-from .common import SESSION_SCOPE_KEY, SESSION_TERMINUS_ASGI_EVENTS, GenericSessionConfig, GenericSQLAlchemyConfig
+from ._common import SESSION_SCOPE_KEY, SESSION_TERMINUS_ASGI_EVENTS, GenericSessionConfig, GenericSQLAlchemyConfig
 
 if TYPE_CHECKING:
     from typing import Any, Callable

starlite/contrib/sqlalchemy/init_plugin/config/sync.py

@@ -11,7 +11,7 @@
     get_starlite_scope_state,
 )
 
-from .common import SESSION_SCOPE_KEY, SESSION_TERMINUS_ASGI_EVENTS, GenericSessionConfig, GenericSQLAlchemyConfig
+from ._common import SESSION_SCOPE_KEY, SESSION_TERMINUS_ASGI_EVENTS, GenericSessionConfig, GenericSQLAlchemyConfig
 
 if TYPE_CHECKING:
     from typing import Any, Callable

tests/contrib/sqlalchemy/init_plugin/config/test_common.py

@@ -8,7 +8,7 @@
 
 from starlite.constants import SCOPE_STATE_NAMESPACE
 from starlite.contrib.sqlalchemy.init_plugin.config import SQLAlchemyAsyncConfig, SQLAlchemySyncConfig
-from starlite.contrib.sqlalchemy.init_plugin.config.common import SESSION_SCOPE_KEY
+from starlite.contrib.sqlalchemy.init_plugin.config._common import SESSION_SCOPE_KEY
 from starlite.datastructures import State
 from starlite.exceptions import ImproperlyConfiguredException
 
@@ -131,7 +131,7 @@ def test_create_session_instance_if_session_already_in_scope_state(
 ) -> None:
     """Test provide_session if session already in scope state."""
     with patch(
-        "starlite.contrib.sqlalchemy.init_plugin.config.common.get_starlite_scope_state"
+        "starlite.contrib.sqlalchemy.init_plugin.config._common.get_starlite_scope_state"
     ) as get_starlite_scope_state_mock:
         session_mock = MagicMock()
         get_starlite_scope_state_mock.return_value = session_mock
@@ -144,7 +144,7 @@ def test_create_session_instance_if_session_not_in_scope_state(
 ) -> None:
     """Test provide_session if session not in scope state."""
     with patch(
-        "starlite.contrib.sqlalchemy.init_plugin.config.common.get_starlite_scope_state"
+        "starlite.contrib.sqlalchemy.init_plugin.config._common.get_starlite_scope_state"
     ) as get_starlite_scope_state_mock:
         get_starlite_scope_state_mock.return_value = None
         config = config_cls()