docs: restore SerializationPlugin implementation example#4711
Merged
cofin merged 2 commits intoApr 25, 2026
Conversation
github-actions
Bot
added
area/docs
cofin
approved these changes
Apr 25, 2026
The SerializationPlugin section in `docs/usage/plugins/index.rst` described the caching pattern used by a plugin implementation but no longer pointed at any code. The original `literalinclude` referenced `litestar/contrib/sqlalchemy/plugins/serialization.py`, which was removed when SQLAlchemy plugins moved to advanced-alchemy, leaving the prose orphaned. Add a minimal standalone example `docs/examples/plugins/serialization_plugin_protocol.py` that mirrors advanced-alchemy's `SQLAlchemySerializationPlugin` pattern using a dataclass-backed model and `DataclassDTO`, and rewire the docs section to include it and summarise its behaviour. Point readers at the advanced-alchemy library docs for a production-grade SQLAlchemy implementation. Fixes litestar-org#3778
Sphinx docs build fails with nitpicky mode: docs/usage/plugins/index.rst:85: WARNING: py:class reference target not found: litestar.dto.DataclassDTO [ref.class] The class is documented from its defining module (litestar.dto.dataclass_dto) via automodule, which is the path Sphinx resolves. Other prose in docs/usage/dto and docs/tutorials uses the same full path for the same reason.
cofin
force-pushed
the
docs/serialization-plugin-example
branch
from
April 25, 2026 21:08
e9175f2 to
88ad272
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #3778.
The
SerializationPluginsection ofdocs/usage/plugins/index.rstcurrently describes the caching pattern used by a serialization plugin ("check the_type_dto_mapdictionary, add it to the dictionary, return it") but does not actually show any code. The originalliteralincludedirective pointed atlitestar/contrib/sqlalchemy/plugins/serialization.py, which was removed when the SQLAlchemy plugin moved toadvanced-alchemy(08297fd), leaving the prose orphaned.Changes
docs/examples/plugins/serialization_plugin_protocol.pythat implementsSerializationPluginfor aCompanydataclass. It mirrors the exact caching pattern used byadvanced-alchemy'sSQLAlchemySerializationPlugin(unwrap collection annotations, check a_type_dto_mapcache, parametriseDataclassDTOon first encounter).docs/usage/plugins/index.rstSerializationPlugin→Exampletoliteralincludethe new example and describe its behaviour in terms of the concrete implementation shown. Keep a pointer to advanced-alchemy for production SQLAlchemy usage.The example is standalone and doesn't require any external dependencies;
ruff check/ruff formatpass locally.Test plan
literalincludedirective resolves (example path exists)python docs/examples/plugins/serialization_plugin_protocol.pyimports cleanly📚 Documentation preview 📚: https://litestar-org.github.io/litestar-docs-preview/4711