diff --git a/docs/conf.py b/docs/conf.py index c47306c634..be6d8017ac 100644 --- a/docs/conf.py +++ b/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"), diff --git a/docs/examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_plugin.py b/docs/examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_plugin.py index fd55548c1f..aec569996d 100644 --- a/docs/examples/contrib/sqlalchemy/plugins/tutorial/full_app_with_plugin.py +++ b/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( diff --git a/docs/tutorials/repository-tutorial/01-modeling-and-features.rst b/docs/tutorials/repository-tutorial/01-modeling-and-features.rst index ce66ea2979..849d7cc4f9 100644 --- a/docs/tutorials/repository-tutorial/01-modeling-and-features.rst +++ b/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 ` type that uses native ``JSONB`` where possible and ``Binary`` or ``Blob`` as an alternative. +- A custom :class:`EncryptedString ` encrypted string that supports multiple cryptography backends. Let's build on this as we look at the repository classes. diff --git a/docs/tutorials/sqlalchemy/4-final-touches-and-recap.rst b/docs/tutorials/sqlalchemy/4-final-touches-and-recap.rst index 9b70b8f776..a619dff114 100644 --- a/docs/tutorials/sqlalchemy/4-final-touches-and-recap.rst +++ b/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:: diff --git a/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin.rst b/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin.rst index 2ebd069f6a..581e39fe53 100644 --- a/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin.rst +++ b/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin.rst @@ -1,7 +1,7 @@ SQLAlchemy Init Plugin ---------------------- -The :class:`SQLAlchemyInitPlugin ` adds functionality to the +The :class:`SQLAlchemyInitPlugin ` adds functionality to the application that supports using Litestar with `SQLAlchemy `_. 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 ` -and :attr:`session_dependency_key ` +:attr:`engine_dependency_key ` +and :attr:`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 ` +:attr:`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 ` and the -:class:`SQLAlchemySyncConfig ` have an ``engine_config`` +Both the :class:`SQLAlchemyAsyncConfig ` and the +:class:`SQLAlchemySyncConfig ` have an ``engine_config`` attribute that is used to configure the engine. The ``engine_config`` attribute is an instance of -:class:`EngineConfig ` and exposes all of the configuration options +:class:`EngineConfig ` and exposes all of the configuration options available to the SQLAlchemy engine. -The :class:`SQLAlchemyAsyncConfig ` class and the -:class:`SQLAlchemySyncConfig ` class also have a +The :class:`SQLAlchemyAsyncConfig ` class and the +:class:`SQLAlchemySyncConfig ` class also have a ``session_config`` attribute that is used to configure the session. This is either an instance of -:class:`AsyncSessionConfig ` or -:class:`SyncSessionConfig ` depending on the type of config +:class:`AsyncSessionConfig ` or +:class:`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 ` class and the -:class:`SQLAlchemySyncConfig ` class expose configuration +Finally, the :class:`SQLAlchemyAsyncConfig ` class and the +:class:`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 `. +:class:`SQLAlchemySerializationPlugin `. .. tab-set:: diff --git a/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_plugin.rst b/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_plugin.rst index 8b0a702a85..c28b5e654b 100644 --- a/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_plugin.rst +++ b/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_plugin.rst @@ -1,18 +1,18 @@ SQLAlchemy Plugin ----------------- -The :class:`SQLAlchemyPlugin ` provides complete support for +The :class:`SQLAlchemyPlugin ` provides complete support for working with `SQLAlchemy `_ in Litestar applications. .. note:: This plugin is only compatible with SQLAlchemy 2.0+. -The :class:`SQLAlchemyPlugin ` combines the functionality of -:class:`SQLAlchemyInitPlugin ` and -:class:`SQLAlchemySerializationPlugin `, each of +The :class:`SQLAlchemyPlugin ` combines the functionality of +:class:`SQLAlchemyInitPlugin ` and +:class:`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 ` with a Litestar application and a +:class:`SQLAlchemyPlugin ` with a Litestar application and a SQLite database. Or, skip ahead to :doc:`/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin` or diff --git a/docs/usage/plugins/index.rst b/docs/usage/plugins/index.rst index 13076750de..5eb27c9d32 100644 --- a/docs/usage/plugins/index.rst +++ b/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: ` +:meth:`supports_type(self, field_definition: FieldDefinition) -> bool: ` 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]: ` +:meth:`create_dto_for_type(self, field_definition: FieldDefinition) -> type[AbstractDTO]: ` takes a :class:`FieldDefinition ` instance as an argument and returns a :class:`SQLAlchemyDTO ` subclass and includes some logic that may be interesting to potential serialization plugin authors.