docs: fix advanced alchemy references (litestar-org#3881)

* docs: fix advanced alchemy references

* fix: correct additional AA references

* fix: references

* fix: docs building

* fix: linting

Author: cofin

docs/conf.py

@@ -29,9 +29,9 @@
 
 extensions = [
     "sphinx.ext.intersphinx",
-    "sphinx.ext.autosectionlabel",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
     "sphinx_design",
     "auto_pytabs.sphinx_ext",
     "tools.sphinx_ext",
@@ -48,6 +48,7 @@
     "msgspec": ("https://jcristharif.com/msgspec/", None),
     "anyio": ("https://anyio.readthedocs.io/en/stable/", None),
     "multidict": ("https://multidict.aio-libs.org/en/stable/", None),
+    "cryptography": ("https://cryptography.io/en/latest/", None),
     "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
     "alembic": ("https://alembic.sqlalchemy.org/en/latest/", None),
     "click": ("https://click.palletsprojects.com/en/8.1.x/", None),
@@ -60,6 +61,8 @@
     "advanced-alchemy": ("https://docs.advanced-alchemy.litestar.dev/latest/", None),
     "jinja2": ("https://jinja.palletsprojects.com/en/latest/", None),
     "trio": ("https://trio.readthedocs.io/en/stable/", None),
+    "pydantic": ("https://docs.pydantic.dev/latest/", None),
+    "typing_extensions": ("https://typing-extensions.readthedocs.io/en/stable/", None),
 }
 
 napoleon_google_docstring = True
@@ -74,6 +77,7 @@
 autodoc_default_options = {"special-members": "__init__", "show-inheritance": True, "members": True}
 autodoc_member_order = "bysource"
 autodoc_typehints_format = "short"
+autodoc_mock_imports = []
 
 nitpicky = True
 nitpick_ignore = [
@@ -164,27 +168,7 @@
     (PY_METH, "litestar.dto.factory.DTOData.create_instance"),
     (PY_METH, "litestar.dto.interface.DTOInterface.data_to_encodable_type"),
     (PY_CLASS, "MetaData"),
-    (PY_CLASS, "advanced_alchemy.repository.typing.ModelT"),
-    (PY_OBJ, "advanced_alchemy.config.common.SessionMakerT"),
-    (PY_OBJ, "advanced_alchemy.config.common.ConnectionT"),
-    (PY_CLASS, "advanced_alchemy.extensions.litestar.plugins._slots_base.SlotsBase"),
-    (PY_CLASS, "advanced_alchemy.config.EngineConfig"),
-    (PY_CLASS, "advanced_alchemy.config.common.GenericAlembicConfig"),
-    (PY_CLASS, "advanced_alchemy.extensions.litestar.SQLAlchemyDTO"),
-    (PY_CLASS, "advanced_alchemy.extensions.litestar.dto.SQLAlchemyDTO"),
-    (PY_CLASS, "advanced_alchemy.extensions.litestar.plugins.SQLAlchemyPlugin"),
-    (PY_CLASS, "advanced_alchemy.extensions.litestar.plugins.SQLAlchemySerializationPlugin"),
-    (PY_CLASS, "advanced_alchemy.extensions.litestar.plugins.SQLAlchemyInitPlugin"),
-    (PY_CLASS, "advanced_alchemy.extensions.litestar.config.SQLAlchemySyncConfig"),
-    (PY_CLASS, "advanced_alchemy.extensions.litestar.config.SQLAlchemyAsyncConfig"),
-    (PY_METH, "advanced_alchemy.extensions.litestar.plugins.SQLAlchemySerializationPlugin.create_dto_for_type"),
-    (PY_CLASS, "advanced_alchemy.base.BasicAttributes"),
-    (PY_CLASS, "advanced_alchemy.config.AsyncSessionConfig"),
-    (PY_CLASS, "advanced_alchemy.config.SyncSessionConfig"),
-    (PY_CLASS, "advanced_alchemy.types.JsonB"),
-    (PY_CLASS, "advanced_alchemy.types.BigIntIdentity"),
     (PY_FUNC, "sqlalchemy.get_engine"),
-    (PY_ATTR, "advanced_alchemy.repository.AbstractAsyncRepository.id_attribute"),
     (PY_OBJ, "litestar.template.base.T_co"),
     ("py:exc", "RepositoryError"),
     ("py:exc", "InternalServerError"),
@@ -204,6 +188,9 @@
     (PY_CLASS, "typing.Self"),
     (PY_CLASS, "attr.AttrsInstance"),
     (PY_CLASS, "typing_extensions.TypeGuard"),
+    (PY_CLASS, "advanced_alchemy.types.BigIntIdentity"),
+    (PY_CLASS, "advanced_alchemy.types.JsonB"),
+    (PY_CLASS, "advanced_alchemy.repository.SQLAlchemyAsyncRepository"),
 ]
 
 nitpick_ignore_regex = [
@@ -247,7 +234,6 @@
     "litestar.template": {"litestar.template.base.T_co"},
     "litestar.openapi.OpenAPIController.security": {"SecurityRequirement"},
     "litestar.response.file.async_file_iterator": {"FileSystemAdapter"},
-    "advanced_alchemy._listeners.touch_updated_timestamp": {"Session"},
     re.compile("litestar.response.redirect.*"): {"RedirectStatusType"},
     re.compile(r"litestar\.plugins.*"): re.compile(".*ModelT"),
     re.compile(r"litestar\.(contrib|repository)\.*"): re.compile(".*T"),

docs/examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_plugin.py

@@ -1,6 +1,5 @@
 from typing import AsyncGenerator, List, Optional
 
-from advanced_alchemy.extensions.litestar.plugins.init.config.asyncio import autocommit_before_send_handler
 from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError, NoResultFound
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -74,7 +73,7 @@ async def update_item(item_title: str, data: TodoItem, transaction: AsyncSession
     connection_string="sqlite+aiosqlite:///todo.sqlite",
     metadata=Base.metadata,
     create_all=True,
-    before_send_handler=autocommit_before_send_handler,
+    before_send_handler="autocommit",
 )
 
 app = Litestar(

docs/tutorials/repository-tutorial/01-modeling-and-features.rst

@@ -74,6 +74,7 @@ Additional features provided by the built-in base models include:
   reverts to an ``Integer`` for unsupported variants.
 - A custom :class:`JsonB <advanced_alchemy.types.JsonB>` type that uses
   native ``JSONB`` where possible and ``Binary`` or ``Blob`` as an alternative.
+- A custom :class:`EncryptedString <advanced_alchemy.types.EncryptedString>` encrypted string that supports multiple cryptography backends.
 
 Let's build on this as we look at the repository classes.
 

docs/tutorials/sqlalchemy/4-final-touches-and-recap.rst

@@ -59,7 +59,7 @@ engine and session lifecycle, and register our ``transaction`` dependency.
 .. literalinclude:: /examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_plugin.py
     :language: python
     :linenos:
-    :lines: 80-84
+    :lines: 80-83
 
 .. seealso::
 

docs/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin.rst

@@ -1,7 +1,7 @@
 SQLAlchemy Init Plugin
 ----------------------
 
-The :class:`SQLAlchemyInitPlugin <advanced_alchemy.extensions.litestar.plugins.SQLAlchemyInitPlugin>` adds functionality to the
+The :class:`SQLAlchemyInitPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyInitPlugin>` adds functionality to the
 application that supports using Litestar with `SQLAlchemy <http://www.sqlalchemy.org/>`_.
 
 The plugin:
@@ -39,8 +39,8 @@ Renaming the dependencies
 #########################
 
 You can change the name that the engine and session are bound to by setting the
-:attr:`engine_dependency_key <advanced_alchemy.extensions.litestar.plugins.init.config.asyncio.SQLAlchemyAsyncConfig.engine_dependency_key>`
-and :attr:`session_dependency_key <advanced_alchemy.extensions.litestar.plugins.init.config.asyncio.SQLAlchemyAsyncConfig.session_dependency_key>`
+:attr:`engine_dependency_key <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig.engine_dependency_key>`
+and :attr:`session_dependency_key <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig.session_dependency_key>`
 attributes on the plugin configuration.
 
 Configuring the before send handler
@@ -50,7 +50,7 @@ The plugin configures a ``before_send`` handler that is called before sending a
 session and removes it from the connection scope.
 
 You can change the handler by setting the
-:attr:`before_send_handler <advanced_alchemy.extensions.litestar.plugins.init.config.asyncio.SQLAlchemyAsyncConfig.before_send_handler>`
+:attr:`before_send_handler <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig.before_send_handler>`
 attribute on the configuration object. For example, an alternate handler is available that will also commit the session
 on success and rollback upon failure.
 
@@ -73,21 +73,21 @@ on success and rollback upon failure.
 Configuring the plugins
 #######################
 
-Both the :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.config.SQLAlchemyAsyncConfig>` and the
-:class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.config.SQLAlchemySyncConfig>` have an ``engine_config``
+Both the :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig>` and the
+:class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemySyncConfig>` have an ``engine_config``
 attribute that is used to configure the engine. The ``engine_config`` attribute is an instance of
-:class:`EngineConfig <advanced_alchemy.config.EngineConfig>` and exposes all of the configuration options
+:class:`EngineConfig <advanced_alchemy.extensions.litestar.EngineConfig>` and exposes all of the configuration options
 available to the SQLAlchemy engine.
 
-The :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.config.SQLAlchemyAsyncConfig>` class and the
-:class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.config.SQLAlchemySyncConfig>` class also have a
+The :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig>` class and the
+:class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemySyncConfig>` class also have a
 ``session_config`` attribute that is used to configure the session. This is either an instance of
-:class:`AsyncSessionConfig <advanced_alchemy.config.AsyncSessionConfig>` or
-:class:`SyncSessionConfig <advanced_alchemy.config.SyncSessionConfig>` depending on the type of config
+:class:`AsyncSessionConfig <advanced_alchemy.extensions.litestar.AsyncSessionConfig>` or
+:class:`SyncSessionConfig <advanced_alchemy.extensions.litestar.SyncSessionConfig>` depending on the type of config
 object. These classes expose all of the configuration options available to the SQLAlchemy session.
 
-Finally, the :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.config.SQLAlchemyAsyncConfig>` class and the
-:class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.config.SQLAlchemySyncConfig>` class expose configuration
+Finally, the :class:`SQLAlchemyAsyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemyAsyncConfig>` class and the
+:class:`SQLAlchemySyncConfig <advanced_alchemy.extensions.litestar.SQLAlchemySyncConfig>` class expose configuration
 options to control their behavior.
 
 Consult the reference documentation for more information.
@@ -98,7 +98,7 @@ Example
 The below example is a complete demonstration of use of the init plugin. Readers who are familiar with the prior section
 may note the additional complexity involved in managing the conversion to and from SQLAlchemy objects within the
 handlers. Read on to see how this increased complexity is efficiently handled by the
-:class:`SQLAlchemySerializationPlugin <advanced_alchemy.extensions.litestar.plugins.SQLAlchemySerializationPlugin>`.
+:class:`SQLAlchemySerializationPlugin <advanced_alchemy.extensions.litestar.SQLAlchemySerializationPlugin>`.
 
 .. tab-set::
 

docs/usage/databases/sqlalchemy/plugins/sqlalchemy_plugin.rst

@@ -1,18 +1,18 @@
 SQLAlchemy Plugin
 -----------------
 
-The :class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.plugins.SQLAlchemyPlugin>` provides complete support for
+The :class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyPlugin>` provides complete support for
 working with `SQLAlchemy <https://www.sqlalchemy.org/>`_ in Litestar applications.
 
 .. note::
 
     This plugin is only compatible with SQLAlchemy 2.0+.
 
-The :class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.plugins.SQLAlchemyPlugin>` combines the functionality of
-:class:`SQLAlchemyInitPlugin <advanced_alchemy.extensions.litestar.plugins.SQLAlchemyInitPlugin>` and
-:class:`SQLAlchemySerializationPlugin <advanced_alchemy.extensions.litestar.plugins.SQLAlchemySerializationPlugin>`, each of
+The :class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyPlugin>` combines the functionality of
+:class:`SQLAlchemyInitPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyInitPlugin>` and
+:class:`SQLAlchemySerializationPlugin <advanced_alchemy.extensions.litestar.SQLAlchemySerializationPlugin>`, each of
 which are examined in detail in the following sections. As such, this section describes a complete example of using the
-:class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.plugins.SQLAlchemyPlugin>` with a Litestar application and a
+:class:`SQLAlchemyPlugin <advanced_alchemy.extensions.litestar.SQLAlchemyPlugin>` with a Litestar application and a
 SQLite database.
 
 Or, skip ahead to :doc:`/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin` or

docs/usage/plugins/index.rst

@@ -91,11 +91,11 @@ The following example shows the actual implementation of the ``SerializationPlug
    :language: python
    :caption: ``SerializationPluginProtocol`` implementation example
 
-:meth:`supports_type(self, field_definition: FieldDefinition) -> bool: <advanced_alchemy.extensions.litestar.plugins.serialization.SQLAlchemySerializationPlugin.supports_type>`
+:meth:`supports_type(self, field_definition: FieldDefinition) -> bool: <advanced_alchemy.extensions.litestar.SQLAlchemySerializationPlugin.supports_type>`
 returns a :class:`bool` indicating whether the plugin supports serialization for the given type. Specifically, we return
 ``True`` if the parsed type is either a collection of SQLAlchemy models or a single SQLAlchemy model.
 
-:meth:`create_dto_for_type(self, field_definition: FieldDefinition) -> type[AbstractDTO]: <advanced_alchemy.extensions.litestar.plugins.SQLAlchemySerializationPlugin.create_dto_for_type>`
+:meth:`create_dto_for_type(self, field_definition: FieldDefinition) -> type[AbstractDTO]: <advanced_alchemy.extensions.litestar.SQLAlchemySerializationPlugin.create_dto_for_type>`
 takes a :class:`FieldDefinition <litestar.typing.FieldDefinition>` instance as an argument and returns a
 :class:`SQLAlchemyDTO <advanced_alchemy.extensions.litestar.dto.SQLAlchemyDTO>` subclass and includes some logic that may be
 interesting to potential serialization plugin authors.