feat: deprecate litestar.repository in favor of advanced_alchemy by cofin · Pull Request #4758 · litestar-org/litestar

cofin · 2026-05-09T18:21:28Z

This deprecates litestar.repository in favor of advanced_alchemy. The litestar.repository module — including its filters, exceptions, handlers, abc, and testing submodules — will be removed before 3.0.0, and this lands the deprecation on the v2 line so users have a release to migrate against.

The new home for everything is advanced_alchemy:

advanced_alchemy.filters for the filter types
advanced_alchemy.exceptions for the repository exceptions
advanced_alchemy.repository.SQLAlchemyAsyncRepository / SQLAlchemySyncRepository for the abstract base classes
advanced_alchemy.repository.memory.SQLAlchemyAsyncMockRepository / SQLAlchemySyncMockRepository for the generic mock under litestar.repository.testing

Each public symbol's warning text spells out exactly what to import instead, so users get a one-line fix from the DeprecationWarning itself.

Under the hood this is PEP 562 __getattr__ shims at every submodule entry point. Importing litestar.repository is silent; only attribute access fires the warning, so test runs that touch the package transitively don't get spammed.

Documentation gets a .. deprecated:: 2.22.0 notice on each of the three reference pages, and there's a changelog entry under a new 2.22.0 block. A parametrized test in tests/unit/test_deprecations.py asserts every public symbol fires DeprecationWarning and that the message names the advanced_alchemy target.

Note on `nitpick_ignore`

The deprecation notes cross-reference advanced_alchemy classes via :class: directives. Those can't be resolved through intersphinx right now — advanced-alchemy's objects.inv is missing py:class entries for everything under advanced_alchemy.repository and advanced_alchemy.repository.memory (only py:parameter entries are indexed). Filed upstream as advanced-alchemy#729.

As a temporary workaround, this PR adds three entries to nitpick_ignore in docs/conf.py, matching the existing entry for SQLAlchemyAsyncRepository:

advanced_alchemy.repository.SQLAlchemySyncRepository
advanced_alchemy.repository.memory.SQLAlchemyAsyncMockRepository
advanced_alchemy.repository.memory.SQLAlchemySyncMockRepository

Once the upstream fix ships and the v3.x line picks up the new inventory, those entries can be removed.

Closes #4721 once merged. The main-side migration of in-tree callers landed in #4735.

📚 Documentation preview 📚: https://litestar-org.github.io/litestar-docs-preview/4758

codecov · 2026-05-09T18:55:16Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.12%. Comparing base (49093b0) to head (d8ed676).
⚠️ Report is 1 commits behind head on v2.

Additional details and impacted files

@@            Coverage Diff             @@
##               v2    #4758      +/-   ##
==========================================
- Coverage   98.20%   98.12%   -0.08%     
==========================================
  Files         349      355       +6     
  Lines       16044    16177     +133     
  Branches     1783     1792       +9     
==========================================
+ Hits        15756    15874     +118     
- Misses        146      160      +14     
- Partials      142      143       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@xronocode

…ns.minijinja (#4760) Moves the MiniJinja template engine integration from `litestar.contrib.minijinja` to `litestar.plugins.minijinja`, and removes the contrib path on `main`. A follow-up PR onto `v2` will add a deprecation shim covering both public and private symbols. Same shape as the OTel split (#4691 + #4759) and the repository split (#4735 + #4758). `litestar/plugins/flash.py` lazily imports the private `_transform_state` from MiniJinja, so any deprecation shim has to forward private symbols. That diagnosis came from @xronocode's audit in #4754; this PR preserves it by migrating flash.py before deleting contrib, so every intermediate commit keeps the dependency graph valid. Salvages the contrib tests into `tests/unit/test_plugins/test_minijinja.py` (98% coverage), migrates every internal call site, and adds `docs/reference/plugins/minijinja.rst`. Closes #4718. Co-authored-by: xronocode <myevdokimov@gmail.com>

@xronocode

…4764) Moves the Mako template engine integration from `litestar.contrib.mako` to `litestar.plugins.mako`, and removes the contrib path on `main`. A follow-up PR onto `v2` will add a deprecation shim, giving 2.x users a migration window. Same shape as the OTel split (#4691 + #4759) and the repository split (#4735 + #4758). Implementation reference: PR #4753 by @xronocode. Every commit carries a co-author trailer. Salvages the contrib tests into `tests/unit/test_plugins/test_mako.py`, migrates every internal call site (csrf middleware, flash, template suite), and adds `docs/reference/plugins/mako.rst`. Closes #4717. Co-authored-by: xronocode <myevdokimov@gmail.com>

@xronocode

…#4762) Moves the Jinja2 template engine integration from `litestar.contrib.jinja` to `litestar.plugins.jinja`, and removes the contrib path on `main`. A follow-up PR onto `v2` will add a deprecation shim, giving 2.x users a migration window. Same shape as the OTel split (#4691 + #4759) and the repository split (#4735 + #4758). Implementation reference: PR #4752 by @xronocode. Every commit carries a co-author trailer. Salvages the contrib tests into `tests/unit/test_plugins/test_jinja.py`, migrates every internal call site (csrf middleware, flash, template suite, htmx examples), and adds `docs/reference/plugins/jinja.rst`. Closes #4716. Co-authored-by: xronocode <myevdokimov@gmail.com>

Add PEP 562 __getattr__ shims to every public entry under litestar.repository.* matching the v2 contrib.repository deprecation style: minimal __getattr__ that lazy-imports from the canonical destination (advanced_alchemy.X) with a fallback to the existing private _filters/_exceptions modules when advanced_alchemy is not installed. Files touched (no new internal modules introduced): - litestar/repository/__init__.py (Pattern A shim) - litestar/repository/exceptions.py - litestar/repository/filters.py - litestar/repository/handlers.py (lazy build inside __getattr__) - litestar/repository/abc/__init__.py - litestar/repository/testing/__init__.py - litestar/repository/abc/_async.py / _sync.py (rebound to advanced_alchemy.exceptions to avoid self-triggering the shim) - litestar/repository/testing/generic_mock_repository.py (same) version='2.22.0', removal_in='3.0.0' on every warn_deprecation call; matching '.. deprecated:: 2.22.0' directives on the three RST reference pages. v2 changelog entry under a new 2.22.0 release block. Tests inline in tests/unit/test_deprecations.py — added a parametrized test_litestar_repository_deprecations covering all 25 public entry points (each one fires DeprecationWarning, names the alternative, and resolves to the same object as the canonical advanced_alchemy target).

…build (1) Remove two 'type: ignore[assignment]' suppressions that mypy now flags as unused: in litestar/repository/__init__.py and in testing/generic_mock_repository.py. Both fallbacks are reached only when advanced_alchemy is not installed (covered by 'pragma: no cover'). (2) Replace the broken intersphinx reference ':ref:`advanced-alchemy:usage/frameworks/litestar:Session Middleware`' with literal prose. The label does not exist in the advanced-alchemy docs and was failing 'build-docs -W'. The reference was already failing on 2.21.x but only surfaced under -W; both v2 cherry-pick PRs need it clean for CI.

- generic_mock_repository.py: move FilterTypes import to TYPE_CHECKING block (TC001) and add type: ignore on the _exceptions fallback so the fallback's RepositoryError type assignment matches the advanced_alchemy branch. - changelog: change :type: deprecation to :type: misc since the v2 changelog directive only accepts feature/bugfix/misc; reference PR 4758. - test_opentelemetry.py: suppress pyright's pre-existing reportGeneralTypeIssues errors on the after_exception_hook tuple-unpack assertions (older pyright on v2 can't narrow Exception/Scope through tuple destructuring).

- abc.rst, handlers.rst: 'removed before 3.0.0 GA' -> 'removed before 3.0.0'. - changelog.rst: 'removed in Litestar 3.0.0' -> 'removed before 3.0.0' to match the directives. - test_deprecations.py: parametrized AttributeError test across all six shim modules so codecov's patch target stops missing the 'attr_name not in __all__' branch on litestar.repository.abc and litestar.repository.testing.

advanced_alchemy ships SQLAlchemyAsyncMockRepository / SQLAlchemySyncMockRepository under advanced_alchemy.repository.memory, so the testing shim isn't a no-replacement deprecation — name the AA classes in the warning message and the docs. - testing/__init__.py: add _ALTERNATIVES mapping, pass alternative= to warn_deprecation so the warning text includes the AA path. - testing.rst: replace 'no replacement' note with the AA class references. - changelog: replace the 'no replacement; rewrite tests' sentence with the AA class references. - test_deprecations.py: assert the warning text names the AA path for the testing items, and keep the identity check for items where the shim genuinely returns the AA class (not the testing items, which still hand back the litestar mock during the deprecation window).

…refs advanced_alchemy's intersphinx inventory only exposes parameters under its repository module, not the classes themselves. Following the same pattern already in place for SQLAlchemyAsyncRepository, add nitpick ignores for SQLAlchemySyncRepository plus the two MockRepository classes referenced from docs/reference/repository/{abc,testing}.rst.

cofin requested review from a team as code owners May 9, 2026 18:21

github-actions Bot added area/docs This PR involves changes to the documentation area/private-api This PR involves changes to the privatized API area/repository size: medium type/feat pr/internal labels May 9, 2026

cofin added the cherry-pick v2 Automatically create a cherry-pick PR against the `v2` branch when this Pull Request is merged label May 9, 2026

cofin marked this pull request as draft May 9, 2026 18:39

cofin force-pushed the chore/v2-repository-deprecation branch from fcc763c to 7c84ed6 Compare May 9, 2026 18:46

cofin marked this pull request as ready for review May 9, 2026 19:01

cofin commented May 9, 2026

View reviewed changes

Comment thread docs/release-notes/changelog.rst Outdated

cofin requested review from JacobCoffee and provinzkraut as code owners May 9, 2026 19:21

cofin enabled auto-merge (squash) May 9, 2026 19:25

cofin linked an issue May 10, 2026 that may be closed by this pull request

chore(repository): deprecate litestar.repository in favor of advanced_alchemy #4721

Closed

provinzkraut reviewed May 11, 2026

View reviewed changes

Comment thread docs/release-notes/changelog.rst

provinzkraut approved these changes May 14, 2026

View reviewed changes

cofin added 8 commits May 17, 2026 14:20

fix(tests): remove noqa directive for deprecated attribute test

ec62db5

docs(repository): remove manual v2 changelog entry

303b6c4

chore(repository): normalize v2 changelog eof

d8ed676

provinzkraut force-pushed the chore/v2-repository-deprecation branch from 078fb14 to d8ed676 Compare May 17, 2026 12:20

cofin merged commit bcddce9 into litestar-org:v2 May 17, 2026
28 of 29 checks passed

provinzkraut mentioned this pull request May 20, 2026

chore(repository): deprecate litestar.repository in favor of advanced_alchemy #4721

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: deprecate litestar.repository in favor of advanced_alchemy#4758

feat: deprecate litestar.repository in favor of advanced_alchemy#4758
cofin merged 9 commits into
litestar-org:v2from
cofin:chore/v2-repository-deprecation

cofin commented May 9, 2026 •

edited by github-actions Bot

Loading

Uh oh!

codecov Bot commented May 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

cofin commented May 9, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Note on nitpick_ignore

Uh oh!

codecov Bot commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cofin commented May 9, 2026 •

edited by github-actions Bot

Loading

Note on `nitpick_ignore`

codecov Bot commented May 9, 2026 •

edited

Loading