From d8e16f8e0abd5e2a6d93f6a43ba99b46e4414492 Mon Sep 17 00:00:00 2001 From: Cody Fincher Date: Fri, 29 Nov 2024 18:33:51 +0000 Subject: [PATCH] fix: correct additional AA references --- docs/conf.py | 29 +++++-------------- .../01-modeling-and-features.rst | 5 ++-- .../plugins/sqlalchemy_init_plugin.rst | 28 +++++++++--------- .../sqlalchemy/plugins/sqlalchemy_plugin.rst | 10 +++---- .../sqlalchemy_serialization_plugin.rst | 2 +- docs/usage/dto/1-abstract-dto.rst | 4 +-- docs/usage/plugins/index.rst | 8 ++--- 7 files changed, 36 insertions(+), 50 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c47306c634..99e508fd42 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,8 @@ 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 +169,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"), @@ -247,7 +232,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"), @@ -259,6 +243,7 @@ "litestar.concurrency.set_asyncio_executor": {"ThreadPoolExecutor"}, "litestar.concurrency.get_asyncio_executor": {"ThreadPoolExecutor"}, re.compile(r"litestar\.channels\.backends\.asyncpg.*"): {"asyncpg.connection.Connection", "asyncpg.Connection"}, + } # Do not warn about broken links to the following: diff --git a/docs/tutorials/repository-tutorial/01-modeling-and-features.rst b/docs/tutorials/repository-tutorial/01-modeling-and-features.rst index ce66ea2979..273666d72b 100644 --- a/docs/tutorials/repository-tutorial/01-modeling-and-features.rst +++ b/docs/tutorials/repository-tutorial/01-modeling-and-features.rst @@ -70,10 +70,11 @@ Additional features provided by the built-in base models include: - A :class:`GUID ` database type that establishes a native UUID in supported engines or a ``Binary(16)`` as a fallback. - A ``BigInteger`` variant - :class:`BigIntIdentity ` that + :obj:`BigIntIdentity ` that reverts to an ``Integer`` for unsupported variants. -- A custom :class:`JsonB ` type that uses +- A custom :obj:`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/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin.rst b/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_init_plugin.rst index 49bd1d15d3..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 cfd0b0482c..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/databases/sqlalchemy/plugins/sqlalchemy_serialization_plugin.rst b/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_serialization_plugin.rst index 985f2cd333..8b65a3d3c4 100644 --- a/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_serialization_plugin.rst +++ b/docs/usage/databases/sqlalchemy/plugins/sqlalchemy_serialization_plugin.rst @@ -26,7 +26,7 @@ Example How it works ============ -The plugin works by defining a :class:`SQLAlchemyDTO ` class for each +The plugin works by defining a :class:`SQLAlchemyDTO ` class for each handler ``data`` or return annotation that is a SQLAlchemy model, or collection of SQLAlchemy models, that isn't otherwise managed by an explicitly defined DTO class. diff --git a/docs/usage/dto/1-abstract-dto.rst b/docs/usage/dto/1-abstract-dto.rst index 14d7263ef9..5c8d8995d9 100644 --- a/docs/usage/dto/1-abstract-dto.rst +++ b/docs/usage/dto/1-abstract-dto.rst @@ -11,7 +11,7 @@ The following factories are currently available: - :class:`DataclassDTO ` - :class:`MsgspecDTO ` - :class:`PydanticDTO ` -- :class:`SQLAlchemyDTO ` +- :class:`SQLAlchemyDTO ` Using DTO Factories ------------------- @@ -25,7 +25,7 @@ a DTO for use with a SQLAlchemy model: Here we see that a SQLAlchemy model is used as both the ``data`` and return annotation for the handler, and while Litestar does not natively support encoding/decoding to/from SQLAlchemy models, through -:class:`SQLAlchemyDTO ` we can do this. +:class:`SQLAlchemyDTO ` we can do this. However, we do have some issues with the above example. Firstly, the user's password has been returned to them in the response from the handler. Secondly, the user is able to set the ``created_at`` field on the model, which should only diff --git a/docs/usage/plugins/index.rst b/docs/usage/plugins/index.rst index 9e9bbd5620..5eb27c9d32 100644 --- a/docs/usage/plugins/index.rst +++ b/docs/usage/plugins/index.rst @@ -91,20 +91,20 @@ 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 +:class:`SQLAlchemyDTO ` subclass and includes some logic that may be interesting to potential serialization plugin authors. The first thing the method does is check if the parsed type is a collection of SQLAlchemy models or a single SQLAlchemy model, retrieves the model type in either case and assigns it to the ``annotation`` variable. The method then checks if ``annotation`` is already in the ``_type_dto_map`` dictionary. If it is, it returns the -corresponding DTO type. This is done to ensure that multiple :class:`SQLAlchemyDTO ` +corresponding DTO type. This is done to ensure that multiple :class:`SQLAlchemyDTO ` subtypes are not created for the same model. If the annotation is not in the ``_type_dto_map`` dictionary, the method creates a new DTO type for the annotation,