sqlmodel-ext 0.5.0__tar.gz → 0.5.1__tar.gz

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/.github/workflows/ci.yml

@@ -52,7 +52,8 @@ jobs:
   # -------------------------------------------------------------------
   # Job 1b: static type check. basedpyright reads pyrightconfig.json from
   # the repository root (src only, pythonVersion 3.12 = lowest supported).
-  # The gate is 0 errors; warnings are printed but do not fail the job.
+  # The gate is 0 errors and 0 warnings: pyrightconfig.json sets failOnWarnings,
+  # so any warning makes basedpyright exit non-zero and fails the job.
   # The alembic extra is installed so the optional-import module
   # `mixins/migration_cache_invalidation.py` resolves its imports.
   # "0 errors" is also what an empty scan prints, so the job additionally

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/CHANGELOG.md

@@ -7,6 +7,96 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 > there is no stability or backward-compatibility guarantee between versions, and
 > you use it at your own risk. Pin the exact version you depend on.
 
+## [0.5.1]
+
+### Added
+
+- **`query_dependency(Model)`**: FastAPI dependency for query-parameter DTOs
+  (`TableViewRequest`, `PaginationRequest`, `PageWindowRequest`, `TimeFilterRequest`,
+  `TrgmSearchRequest`, your subclasses):
+  `Annotated[TableViewRequest, Depends(query_dependency(TableViewRequest))]`. It declares
+  one query parameter per field carrying the field's type, constraints, default, `title`,
+  description, `examples`, `deprecated`, `json_schema_extra` and `discriminator` (each
+  parameter's OpenAPI schema is the field's JSON schema; a callable `json_schema_extra`
+  or a `Discriminator` object is a `TypeError`), builds the model itself and
+  re-raises a failed construction as `RequestValidationError` with locations prefixed by
+  `'query'`, so FastAPI answers 422. Requires the `fastapi` extra when called. See
+  [Paginate a list endpoint](docs/en/how-to/paginate-a-list-endpoint.md).
+
+### Fixed
+
+- A bare mutation of a cached model that was flushed before the enhanced `commit()` -- inside
+  a savepoint (`begin_nested()` + `flush()`), by a manual `session.flush()`, or by an
+  autoflush -- was never invalidated: the cache kept serving the pre-commit row after the
+  commit. Pending invalidations were collected by scanning `new` / `dirty` / `deleted`
+  right before the commit, and a flushed object is no longer in those sets. Every flush
+  now registers the cached instances it writes (`after_flush`); an outermost rollback
+  drops them, a savepoint rollback keeps them (at most one extra invalidation). Also
+  present in 0.5.0.
+- A table class inheriting a field declared with a type alias and a right-hand
+  `Field(...)` (`language: Str64 = Field(index=True)` in a non-table base) lost that
+  `Field`'s attributes: the column had no index / unique constraint / primary key /
+  foreign key / `nullable` / `sa_type` / `sa_column_kwargs` / `ondelete`, and the
+  Pydantic field could lose attributes set only there (e.g. `title`). The metaclass
+  rebuilt the inherited field from the alias's `Field` alone. The inherited field is now
+  the base class's resolved field (`Base.model_fields[name]`, in which Pydantic has
+  already merged the alias's `Field` and the right-hand one): its Pydantic attributes
+  (`default`, `alias`, `validation_alias`, `title`, `description`, ...) are taken as-is,
+  `None` included, so a base `Field(alias=None)` still clears the alias's `alias` in the
+  table class. Only the SQLModel column attributes are completed: the alias's and the
+  right-hand `Field`'s column settings are folded into one (the right-hand side wins on
+  conflicts; `False` never switches off `True`), and constraints of an alias nested in
+  a union (`Alias | None = Field(...)`), which Pydantic does not merge at field level,
+  are added. Plain-typed inherited fields (`int = Field(index=True)`) were not affected.
+  Also present in 0.5.0.
+- A cross-field validation failure of `TableViewRequest` (and the other query DTOs) used
+  as a FastAPI dependency (`after_id` with a non-zero `offset`, `after_id` with a mutable
+  `order`, an inverted time range) was a 500. Declared through `query_dependency()` it is
+  a 422 located at the offending query parameter; the documented `ValidationError`
+  exception-handler workaround is no longer needed.
+- Every commit of a cached model through the enhanced `AsyncSession` logged a spurious
+  `WARNING` "fallback compensation triggered: ..." and invalidated the cache a second
+  time. The `after_commit` event now hands the committed pendings over to the enhanced
+  `commit()`, which invalidates each of them once. Commits that bypass the enhanced
+  `commit()` (a plain SQLAlchemy / SQLModel session, `run_sync(lambda s: s.commit())`)
+  keep the fire-and-forget compensation and its `WARNING`; it now also takes over when
+  the enhanced `commit()` fails or is cancelled after the database committed.
+
+### Changed
+
+- A table class field declared with a type alias **and** a right-hand `Field(...)`
+  (`name: Alias = Field(...)`) now gets its Pydantic attributes exactly as Pydantic
+  resolves that declaration -- the same field plain SQLModel builds, and the same field
+  a table class gets when it inherits the declaration from a base. The right-hand
+  `Field` overrides the alias's Pydantic attributes, `None` included; sqlmodel's
+  `Field()` passes every one of them explicitly, so with a right-hand `Field` the
+  alias's `alias` / `validation_alias` / `serialization_alias` / `title` /
+  `description` no longer apply (`Field(alias=None)` clears the alias's `alias`;
+  previously the metaclass skipped `None` and kept the alias's values). The alias's
+  `default` still applies unless the right-hand `Field` sets one -- except for an alias
+  nested in a union (`Alias | None = Field(...)`), whose `Field` Pydantic does not
+  merge: such a field is required unless the right-hand `Field` sets a default. Of the
+  bundled aliases only the `Optional*Decimal*` ones carry a Pydantic attribute
+  (`default=None`), so `OptionalNonNegativeDecimal38_18 | None = Field(index=True)` is
+  now required; drop the redundant `| None` or add `default=None`. Column attributes are
+  unchanged: the alias's and the right-hand `Field`'s column settings are still folded
+  together.
+- The cross-field rules of `PaginationRequest` and `TimeFilterRequest` are field validators:
+  a violation is still a `ValidationError` with the same message, but located at the
+  field the rule constrains (`after_id`, `created_before_datetime`,
+  `updated_before_datetime`) instead of the model root, and independent violations are
+  reported together. `TimeFilterRequest` no longer overrides `model_post_init`.
+- `PolymorphicBaseMixin._is_joined_table_inheritance()` is renamed
+  `is_joined_table_inheritance()` (it was documented and called across modules; the
+  underscore was not a real boundary). Update direct callers.
+- `get(table_view=...)` is annotated `TableViewArgument` (`TimeFilterRequest |
+  PageWindowRequest`), matching what it already accepted at runtime (e.g. a bare
+  `PageWindowRequest`). The `join=(Model, onclause)` ON clause is annotated with the
+  new `OnClauseArgument` alias (SQLAlchemy's public `OnClauseRole`) instead of
+  SQLAlchemy's private `_OnClauseArgument`.
+- The type-check gate of the repository is now 0 errors **and 0 warnings**
+  (`failOnWarnings: true`).
+
 ## [0.5.0]
 
 Upgrade guide: [Migrate from 0.4.x to 0.5.0](docs/en/how-to/migrate-to-0-5.md)
@@ -164,14 +254,6 @@ Upgrade guide: [Migrate from 0.4.x to 0.5.0](docs/en/how-to/migrate-to-0-5.md)
   database has already committed): the affected cache entries keep serving
   pre-commit data until their TTL expires. Use `no_cache=True` for reads that must
   not rely on the cache.
-- Every commit of a cached model through the enhanced `AsyncSession` logs a spurious
-  `WARNING` "fallback compensation triggered: ..." (pre-existing in 0.4.x). The only
-  effect is one redundant cache invalidation; correctness is unaffected.
-- When `TableViewRequest` is used as a `Depends()` dependency, a cross-field validation
-  failure (e.g. `after_id` with a non-zero `offset`) surfaces as a 500 instead of a 422,
-  because FastAPI constructs the object outside its per-parameter validation. Register
-  the `ValidationError` → 422 handler shown in
-  [Paginate a list endpoint](docs/en/how-to/paginate-a-list-endpoint.md).
 - On Python 3.12, `JSON100K | None` as a `table=True` field raises
   `has no matching SQLAlchemy type`; declare the column explicitly with
   `Field(default=None, sa_type=JSONB)` (pre-existing).

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlmodel-ext
-Version: 0.5.0
+Version: 0.5.1
 Summary: Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types.
 Project-URL: Homepage, https://github.com/Foxerine/sqlmodel-ext
 Project-URL: Repository, https://github.com/Foxerine/sqlmodel-ext
@@ -399,7 +399,7 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlmodel import Field
 from sqlmodel_ext import (
     AsyncSession, SQLModelBase, UUIDTableBaseMixin, Str64, Text10K,
-    ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin,
+    ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin, query_dependency,
 )
 
 # ── Dependency-injection layer: declare once (e.g. in a shared
@@ -415,9 +415,10 @@ async def get_session() -> AsyncGenerator[AsyncSession, None]:
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
 """Request-scoped AsyncSession. The single way endpoints touch the DB."""
 
-# TableViewRequest is a Pydantic model → FastAPI binds its fields as
-# query params automatically. No hand-written offset/limit/order plumbing.
-TableViewRequestDep = Annotated[TableViewRequest, Depends()]
+# query_dependency() binds every TableViewRequest field as a query param
+# (no hand-written offset/limit/order plumbing) and turns cross-field errors
+# (e.g. after_id + offset) into a 422 instead of a 500.
+TableViewRequestDep = Annotated[TableViewRequest, Depends(query_dependency(TableViewRequest))]
 
 async def get_current_user(session: SessionDep) -> "User":
     ...  # decode the bearer token, load the user — your auth, unchanged
@@ -1177,7 +1178,7 @@ mapping = Tool.get_identity_to_class_map()
 # {'websearchtool': WebSearchTool, 'calculatortool': CalculatorTool}
 
 # Check inheritance type
-Tool._is_joined_table_inheritance()  # True for JTI, False for STI
+Tool.is_joined_table_inheritance()  # True for JTI, False for STI
 ```
 
 ---

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/README.md

@@ -343,7 +343,7 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlmodel import Field
 from sqlmodel_ext import (
     AsyncSession, SQLModelBase, UUIDTableBaseMixin, Str64, Text10K,
-    ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin,
+    ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin, query_dependency,
 )
 
 # ── Dependency-injection layer: declare once (e.g. in a shared
@@ -359,9 +359,10 @@ async def get_session() -> AsyncGenerator[AsyncSession, None]:
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
 """Request-scoped AsyncSession. The single way endpoints touch the DB."""
 
-# TableViewRequest is a Pydantic model → FastAPI binds its fields as
-# query params automatically. No hand-written offset/limit/order plumbing.
-TableViewRequestDep = Annotated[TableViewRequest, Depends()]
+# query_dependency() binds every TableViewRequest field as a query param
+# (no hand-written offset/limit/order plumbing) and turns cross-field errors
+# (e.g. after_id + offset) into a 422 instead of a 500.
+TableViewRequestDep = Annotated[TableViewRequest, Depends(query_dependency(TableViewRequest))]
 
 async def get_current_user(session: SessionDep) -> "User":
     ...  # decode the bearer token, load the user — your auth, unchanged
@@ -1121,7 +1122,7 @@ mapping = Tool.get_identity_to_class_map()
 # {'websearchtool': WebSearchTool, 'calculatortool': CalculatorTool}
 
 # Check inheritance type
-Tool._is_joined_table_inheritance()  # True for JTI, False for STI
+Tool.is_joined_table_inheritance()  # True for JTI, False for STI
 ```
 
 ---

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/README_zh.md

@@ -343,7 +343,7 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlmodel import Field
 from sqlmodel_ext import (
     AsyncSession, SQLModelBase, UUIDTableBaseMixin, Str64, Text10K,
-    ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin,
+    ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin, query_dependency,
 )
 
 # ── 依赖注入层：声明一次（例如放在共享的 deps 模块），
@@ -359,9 +359,10 @@ async def get_session() -> AsyncGenerator[AsyncSession, None]:
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
 """请求级 AsyncSession。端点访问数据库的唯一途径。"""
 
-# TableViewRequest 是 Pydantic 模型 → FastAPI 自动把字段绑定为查询参数。
-# 无需手写 offset/limit/order 的管道代码。
-TableViewRequestDep = Annotated[TableViewRequest, Depends()]
+# query_dependency() 把 TableViewRequest 的每个字段绑定为查询参数（无需手写
+# offset/limit/order 的管道代码），并把跨字段错误（如 after_id + offset）变成
+# 422 而不是 500。
+TableViewRequestDep = Annotated[TableViewRequest, Depends(query_dependency(TableViewRequest))]
 
 async def get_current_user(session: SessionDep) -> "User":
     ...  # 解析 bearer token、加载用户——沿用你自己的认证逻辑
@@ -1121,7 +1122,7 @@ mapping = Tool.get_identity_to_class_map()
 # {'websearchtool': WebSearchTool, 'calculatortool': CalculatorTool}
 
 # 检查继承类型
-Tool._is_joined_table_inheritance()  # JTI 为 True，STI 为 False
+Tool.is_joined_table_inheritance()  # JTI 为 True，STI 为 False
 ```
 
 ---

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/ai-rules/AGENTS.md

@@ -199,6 +199,10 @@ data = patch.model_dump(exclude_unset=True)
 - List endpoints take a `TableViewRequest` (`offset` / `limit` / `order` /
   `desc` / `after_id` + time bounds). `after_id` cannot be combined with
   `offset`, custom `order_by` or `join`.
+- Inject query-parameter DTOs with
+  `Annotated[TableViewRequest, Depends(query_dependency(TableViewRequest))]`,
+  never a bare `Depends()` (a failed cross-field rule would be a 500 instead
+  of a 422).
 
 ## 7. Relationships: always preload
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/explanation/cached-table.md

@@ -118,7 +118,7 @@ With `commit=False` nothing is invalidated (the data is not committed yet); the
 | `delete(instances)` | per-instance `DEL id:...` + `INCR ver:{cls}` |
 | `delete(condition)` | model-level `SCAN+DEL id:{cls}:*` + `INCR ver:{cls}` |
 | `add()` | `INCR ver:{cls}`; instances with an explicitly specified id also have their ID cache invalidated (guards against id reuse) |
-| bare `session.add()` / attribute mutation / `session.delete()` + `commit()` | auto-registered before commit: new → query cache only; modified / deleted → row level + query cache |
+| bare `session.add()` / attribute mutation / `session.delete()` + `commit()` | registered by the flush that sends them (a savepoint flush, a manual `flush()`, an autoflush or the commit's own flush): row level (the flushed `id`) + query cache |
 
 ### Cascade deletes
 
@@ -140,8 +140,8 @@ The query cache `INCR`s the version keys of itself and all ancestors in one pipe
 
 ## The two invalidation paths
 
-1. **Synchronous path** (enhanced `AsyncSession.commit()`): snapshots the registered items before commit; after commit it `await`s invalidation of the snapshot items and cascade children.
-2. **Compensation path** (`after_commit` event): the event handler is synchronous and cannot `await`, so it schedules a fire-and-forget task that invalidates whatever the synchronous path did not cover (deduplicated by ID against the `synced` record). It catches commits that did not go through the enhanced `commit()`; there is a very short stale window, and TTL provides eventual consistency.
+1. **Synchronous path** (enhanced `AsyncSession.commit()`): it marks the session before the real commit; the `after_commit` event sees the mark and hands the complete set of registered items (including those registered during the commit's own flush, e.g. cascade children) over to `commit()`, which `await`s their invalidation before returning. Each item is invalidated once; no warning is logged.
+2. **Compensation path** (`after_commit` event without the mark): the event handler is synchronous and cannot `await`, so it schedules a fire-and-forget task that invalidates the items and logs a `WARNING` "fallback compensation triggered: ...". It catches commits that did not go through the enhanced `commit()` (a plain SQLAlchemy / SQLModel session, `run_sync(lambda s: s.commit())`), and an enhanced `commit()` that failed or was cancelled after the database committed; there is a very short stale window, and TTL provides eventual consistency.
 
 Sentinel objects:
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/explanation/metaclass.md

@@ -126,7 +126,7 @@ real_table_args, custom_table_args = [], []
 for arg in raw_table_args:
     (custom_table_args if isinstance(arg, CustomTableArg) else real_table_args).append(arg)
 attrs['__table_args__'] = tuple(real_table_args)
-# appended to the module-level queue _classes_with_custom_table_args after super().__new__
+# appended to the module-level queue classes_with_custom_table_args after super().__new__
 ```
 
 **Why**: SQLAlchemy's `Table.__init__` consumes every element of `__table_args__` immediately — an `Index` referencing a not-yet-existing column raises on the spot. `CustomTableArg` is a generic "defer this" marker: the metaclass only intercepts and enqueues, knowing nothing about the semantics; the current consumer is `mixins.polymorphic.DeferredIndex` (deferred indexes on STI subclass columns). `table_name=` / `abstract=` become `__tablename__` / `__abstract__`.
@@ -134,7 +134,7 @@ attrs['__table_args__'] = tuple(real_table_args)
 ### Step 4: Resolve annotations and record "which fields this class declares itself"
 
 ```python
-annotations, annotation_strings, eval_globals, eval_locals = _resolve_annotations(attrs)
+annotations, annotation_strings, eval_globals, eval_locals = resolve_annotations(attrs)
 _own_annotation_names = frozenset(annotations)
 ```
 
@@ -142,7 +142,7 @@ This snapshot must be taken **before** any annotation injection: later steps inj
 
 ### Step 4.5: Recover SQLModel attributes from `Annotated[T, Field(...)]`
 
-When Pydantic v2 processes `Annotated` metadata it replaces `sqlmodel.main.FieldInfo` with `pydantic.fields.FieldInfo`, which knows nothing about SQLModel attributes such as `foreign_key` or `sa_type`. For **table classes** (including `Annotated` fields inherited from parents), `_recover_annotated_sqlmodel_fields()` converts them back into the `= Field(...)` form; non-table classes are left as-is so child table classes can inherit them. When several `FieldInfo`s are merged, an explicit `default=None` is kept as a real value (not "unset") — otherwise the field would silently become required.
+When Pydantic v2 processes `Annotated` metadata it replaces `sqlmodel.main.FieldInfo` with `pydantic.fields.FieldInfo`, which knows nothing about SQLModel attributes such as `foreign_key` or `sa_type`. For **table classes** (including `Annotated` fields inherited from parents), `_recover_annotated_sqlmodel_fields()` converts them back into the `= Field(...)` form; non-table classes are left as-is so child table classes can inherit them. When several `FieldInfo`s are merged, an explicit `default=None` is kept as a real value (not "unset") — otherwise the field would silently become required. A field with a right-hand `Field` (`name: Alias = Field(...)`) is rebuilt from Pydantic's resolution of that declaration — `FieldInfo.from_annotated_attribute()` when the table class declares it, the base's resolved field `Base.model_fields[name]` when the table class **inherits** it (without re-declaring it). Both give the same field: its Pydantic attributes are taken as-is (an explicit `alias=None` stays `None`, as in plain SQLModel), and only the column attributes are completed — the `FieldInfoMetadata` carriers of the alias's and the right-hand `Field` are folded into one, since SQLModel reads only the first. Metadata that stays in the class annotation (an `AfterValidator` next to the alias's `Field`, for example) is not copied into the field, so it is applied once.
 
 ### Step 4.5.b: `oplock_version` is a reserved name
 
@@ -178,7 +178,7 @@ The generated annotations exist at runtime; static type checkers still see the b
 
 ```python
 for field_name, field_type in annotations.items():
-    sa_type = _extract_sa_type_from_annotation(field_type)
+    sa_type = extract_sa_type_from_annotation(field_type)
     if sa_type is not None:
         field_value = attrs.get(field_name, Undefined)
         if field_value is Undefined:
@@ -195,10 +195,10 @@ for field_name, field_type in annotations.items():
 
 `_durably_set_sa_type()` writes `sa_type` into a `FieldInfoMetadata` entry of `FieldInfo.metadata` — the channel SQLModel's own `Field(sa_type=...)` uses and that survives Pydantic's `model_fields` rebuild; a plain `setattr` would be lost before the column is built. An explicitly set `sa_type` is never overwritten.
 
-#### `_extract_sa_type_from_annotation()` — three extraction methods
+#### `extract_sa_type_from_annotation()` — three extraction methods
 
 ```python
-def _extract_sa_type_from_annotation(annotation):
+def extract_sa_type_from_annotation(annotation):
     # Method 1: the type itself has a __sqlmodel_sa_type__ attribute
     # Method 2: an Annotated metadata item has __sqlmodel_sa_type__, or the schema returned by
     #           its __get_pydantic_core_schema__ carries 'sa_type' in its metadata
@@ -206,7 +206,7 @@ def _extract_sa_type_from_annotation(annotation):
     ...
 ```
 
-Take `Array[str]`: `__class_getitem__` returns `Annotated[list[str], _ArrayTypeHandler(str)]`, and the `_ArrayTypeHandler` schema carries `metadata={'sa_type': ARRAY(String)}`; the `JSON100K` schema carries `metadata={'sa_type': JSONB}`. **The type declares its own column type**, and the metaclass delivers it to the column builder.
+Take `Array[str]`: `__class_getitem__` returns `Annotated[list[str], ArrayTypeHandler(str)]`, and the `ArrayTypeHandler` schema carries `metadata={'sa_type': ARRAY(String)}`; the `JSON100K` schema carries `metadata={'sa_type': JSONB}`. **The type declares its own column type**, and the metaclass delivers it to the column builder.
 
 ### Steps 5–7: Save SQLModel `FieldInfo`s, call the parent, restore
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/explanation/polymorphic-internals.md

@@ -45,7 +45,7 @@ def __init_subclass__(cls, polymorphic_on=None, polymorphic_abstract=None, **kwa
 
 ```python
 @classmethod
-def _is_joined_table_inheritance(cls) -> bool:
+def is_joined_table_inheritance(cls) -> bool:
     """Subclass table name differs from parent → JTI"""
 
 @classmethod

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/explanation/transactional-cache-transparency.md

@@ -94,15 +94,14 @@ Register first, then execute, and the warning won't fire (the table already has
 
 CRUD methods (`save` / `update` / `delete` / `add`) **don't invalidate** themselves; they only register pending invalidations into `session.info`. The enhanced `AsyncSession.commit()` orchestrates:
 
-1. Auto-register every change of cached models in the session (covering bare `add` / attribute mutation / `delete` that bypass the CRUD methods)
-2. Snapshot the pending invalidations (the `after_commit` event pops them during commit)
-3. Actually commit
-4. Synchronously invalidate the snapshot items + the children cascade-deleted in this flush
-5. Run post-commit callbacks
+1. Every flush registers the cached models it writes (the `after_flush` event), covering bare `add` / attribute mutation / `delete` that bypass the CRUD methods -- whether they were flushed earlier (inside a savepoint, by a manual `flush()`, by an autoflush) or by this commit
+2. Actually commit. The `after_commit` event pops the complete set of registered items — including those registered by this commit's own flush, such as cascade-deleted children — and hands it over to `commit()`
+3. Synchronously invalidate the handed-over items, each exactly once
+4. Run post-commit callbacks
 
 With `commit=False` nothing is invalidated (the data isn't committed yet); the registered items wait for your final `session.commit()` — "several `commit=False` operations + one commit" is naturally correct. Rollback discards the registered items.
 
-A fire-and-forget compensation task is also attached to the `after_commit` event, covering commit paths that don't go through the enhanced `commit()` (e.g. a plain sqlmodel session); it deduplicates by ID and only fills in what the synchronous path didn't cover.
+For a commit that doesn't go through the enhanced `commit()` (e.g. a plain sqlmodel session, or `run_sync(lambda s: s.commit())`), the `after_commit` event instead schedules a fire-and-forget compensation task that invalidates the popped items and logs a `WARNING` "fallback compensation triggered: ..." — there is a brief stale window, TTL provides eventual consistency. The same fallback takes over if the enhanced `commit()` fails or is cancelled after the database has committed. A commit through the enhanced session never logs that warning.
 
 ### Savepoints
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/how-to/cache-queries.md

@@ -79,7 +79,7 @@ char = await char.save(session)
 | `delete(instance)` | same |
 | `delete(condition=...)` | model-wide ID cleanup + version `+1` |
 | `add()` | version `+1` (instances with an explicitly specified id also clear their ID cache) |
-| Bare `session.add()` / attribute changes / `session.delete()` followed by `session.commit()` | Also invalidated automatically (the enhanced `commit()` registers them before committing) |
+| Bare `session.add()` / attribute changes / `session.delete()` followed by `session.commit()` | Also invalidated automatically (the flush that writes them registers them, including a savepoint flush, a manual `flush()` or an autoflush earlier in the transaction) |
 
 ## 4. Correct inside transactions too
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/how-to/extra-mixins.md

@@ -138,13 +138,14 @@ class Tag(SQLModelBase, UUIDTableBaseMixin, TrgmSearchableMixin, table=True):
 ```python
 from typing import Annotated
 from fastapi import Depends
+from sqlmodel_ext import query_dependency
 from sqlmodel_ext.mixins import TrgmSearchRequest
 
 @router.get("", response_model=ListResponse[TagResponse])
 async def list_tags(
     session: SessionDep,
-    table_view: Annotated[TableViewRequest, Depends()],
-    search: Annotated[TrgmSearchRequest, Depends()],
+    table_view: Annotated[TableViewRequest, Depends(query_dependency(TableViewRequest))],
+    search: Annotated[TrgmSearchRequest, Depends(query_dependency(TrgmSearchRequest))],
 ) -> ListResponse[Tag]:
     condition = search.apply_condition(Tag, col(Tag.name) != 'hidden')   # ANDed into your existing scope condition
     return await Tag.get_with_count(session, condition, table_view=table_view)

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/how-to/integrate-with-fastapi.md

@@ -64,10 +64,11 @@ if patch.subtitle is not Unset:
 from typing import Annotated
 from uuid import UUID
 from fastapi import APIRouter, Depends
-from sqlmodel_ext import ListResponse, TableViewRequest
+from sqlmodel_ext import ListResponse, TableViewRequest, query_dependency
 
 router = APIRouter(prefix="/articles", tags=["articles"])
-TableViewDep = Annotated[TableViewRequest, Depends()]
+# query_dependency(): a failed cross-field rule (after_id + offset, ...) is a 422, not a 500 -- see "Paginate a list endpoint"
+TableViewDep = Annotated[TableViewRequest, Depends(query_dependency(TableViewRequest))]
 
 @router.post("", response_model=ArticleResponse)
 async def create_article(
@@ -117,20 +118,12 @@ The `with_for_update=True` in the `delete` endpoint closes the TOCTOU window bet
 
 ```python
 from fastapi import FastAPI, Request
-from fastapi.encoders import jsonable_encoder
 from fastapi.responses import JSONResponse
-from pydantic import ValidationError
 from sqlmodel_ext import OptimisticLockError
 from sqlmodel_ext.mixins import KeysetCursorError, ResourceReferencedError
 
 app = FastAPI()
 
-@app.exception_handler(ValidationError)          # cross-field validation of query-parameter DTOs (after_id + offset, etc.)
-async def dto_validation_error_handler(request: Request, exc: ValidationError) -> JSONResponse:
-    return JSONResponse(status_code=422, content={
-        "detail": jsonable_encoder(exc.errors(include_url=False, include_context=False)),
-    })
-
 @app.exception_handler(KeysetCursorError)        # cursor invalid / unsupported, status_code = 422
 async def keyset_error_handler(request: Request, exc: KeysetCursorError) -> JSONResponse:
     return JSONResponse(status_code=exc.status_code, content={"detail": str(exc)})
@@ -144,7 +137,7 @@ async def oplock_handler(request: Request, exc: OptimisticLockError) -> JSONResp
     return JSONResponse(status_code=409, content={"detail": "Record was modified by someone else. Please refresh and retry."})
 ```
 
-Why the first handler is needed: FastAPI validates the query parameters of a `Depends()` class dependency one by one (single-field errors are 422), but a cross-field `model_validator` only fires when FastAPI calls `TableViewRequest(...)` to construct the object — left unhandled, that is a 500.
+Cross-field validation of query-parameter DTOs needs no handler: `query_dependency()` already turns it into FastAPI's `RequestValidationError` (422, locations starting with `query`). With a bare `Depends()` the same error would be a 500 — the `ValidationError` raised when FastAPI itself calls `TableViewRequest(...)` is outside its request-validation path.
 
 ## Key conventions
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/how-to/keyset-pagination.md

@@ -37,7 +37,7 @@ next_page = await Article.get(
 
 Repeat until the returned list is empty. `get_with_count()` accepts `after_id` as well; the `count` it returns is the size of the whole filtered set and is **not affected by the cursor**.
 
-In FastAPI the endpoint code doesn't change: with `TableViewRequest` as a dependency, the client simply passes `?after_id=<id of the last row of the previous page>&limit=20` (remember to register the handler that maps `ValidationError` to 422, see the constraints table below).
+In FastAPI the endpoint code doesn't change: with `TableViewRequest` as a dependency, the client simply passes `?after_id=<id of the last row of the previous page>&limit=20` (declare the dependency with `query_dependency(TableViewRequest)` so the rejected combinations below are a 422, see [Paginate a list endpoint](./paginate-a-list-endpoint#why-query-dependency)).
 
 ## How it guarantees no duplicates and no gaps
 
@@ -49,8 +49,8 @@ In FastAPI the endpoint code doesn't change: with `TableViewRequest` as a depend
 
 | Combination | When rejected | Error |
 |------|---------|------|
-| `after_id` + non-zero `offset` | When constructing `TableViewRequest` | `ValidationError` (in a FastAPI dependency it must be mapped to 422, see [Paginate a list endpoint](./paginate-a-list-endpoint#map-cross-field-validation-errors-to-422)) |
-| `after_id` + `order='updated_at'` (or any mutable domain sort column) | At construction | `ValidationError` |
+| `after_id` + non-zero `offset` | When constructing `TableViewRequest` | `ValidationError` at `after_id` (through `query_dependency()`: 422 at `["query", "after_id"]`) |
+| `after_id` + `order='updated_at'` (or any mutable domain sort column) | At construction | `ValidationError` at `after_id` (422 through `query_dependency()`) |
 | `after_id` + explicit `order_by=` | At `get()` | `KeysetCursorUnsupportedError` |
 | `after_id` + `join=` | At `get()` | `KeysetCursorUnsupportedError` |
 | Anchor does not exist, or is outside this query's visible scope (`condition` + `filter` + STI filter) | At `get()` | `KeysetCursorInvalidError` |

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/how-to/paginate-a-list-endpoint.md

@@ -13,33 +13,28 @@
 ```python
 from typing import Annotated
 from fastapi import Depends
-from sqlmodel_ext import TableViewRequest
+from sqlmodel_ext import TableViewRequest, query_dependency
 
-TableViewDep = Annotated[TableViewRequest, Depends()]
+TableViewDep = Annotated[TableViewRequest, Depends(query_dependency(TableViewRequest))]
 ```
 
-`TableViewRequest` carries pagination (`offset` / `limit` / `desc` / `order`), a keyset cursor (`after_id`) and time filtering (`created_after_datetime` / `created_before_datetime` / `updated_after_datetime` / `updated_before_datetime`). FastAPI's `Depends()` parses the query string into this object automatically.
+`TableViewRequest` carries pagination (`offset` / `limit` / `desc` / `order`), a keyset cursor (`after_id`) and time filtering (`created_after_datetime` / `created_before_datetime` / `updated_after_datetime` / `updated_before_datetime`). `query_dependency()` declares one query parameter per model field (same type, constraints, default, title, description, examples, deprecation and `json_schema_extra` as the model field, so each parameter's OpenAPI schema is the field's JSON schema) and constructs the `TableViewRequest` itself.
 
-### Map cross-field validation errors to 422
+### Why `query_dependency()`
 
-Single-field errors (`limit=0`, a time without a timezone) are validated per parameter by FastAPI and are a 422 directly. But **cross-field** rules — `after_id` and `offset` are mutually exclusive, `after_id` can't be combined with `order=updated_at`, time ranges must be in order — only fire when FastAPI calls `TableViewRequest(...)` to construct the dependency object. They raise a Pydantic `ValidationError`, which is a **500** if left unhandled. Register a handler that maps it to 422:
+Single-field errors (`limit=0`, a time without a timezone) are validated per parameter by FastAPI and are a 422 directly. But **cross-field** rules — `after_id` and `offset` are mutually exclusive, `after_id` can't be combined with `order=updated_at`, time ranges must be in order — only fire when the `TableViewRequest` is constructed. With a bare `Depends()`, FastAPI calls `TableViewRequest(...)` itself; the Pydantic `ValidationError` raised there is not a `RequestValidationError`, FastAPI does not catch it, and the request fails with a **500**.
 
-```python
-from fastapi import Request
-from fastapi.encoders import jsonable_encoder
-from fastapi.responses import JSONResponse
-from pydantic import ValidationError
-
-@app.exception_handler(ValidationError)
-async def dto_validation_error_handler(request: Request, exc: ValidationError) -> JSONResponse:
-    return JSONResponse(
-        status_code=422,
-        content={"detail": jsonable_encoder(exc.errors(include_url=False, include_context=False))},
-    )
+`query_dependency()` re-raises that `ValidationError` as a `RequestValidationError` whose error locations start with `query`, so FastAPI's default handler answers **422** in the same shape as any other query-parameter error — no exception handler to register:
+
+```json
+{"detail": [{"type": "value_error", "loc": ["query", "after_id"],
+             "msg": "Value error, after_id and offset cannot be combined: ...", "input": "..."}]}
 ```
 
-::: warning Don't switch to `Annotated[TableViewRequest, Query()]` to "fix" this
-A Pydantic query model does turn cross-field errors into 422, but only when it is the endpoint's **only** query parameter: add one more ordinary query parameter to the endpoint (e.g. `status: str | None = None`) and FastAPI no longer hands the whole query string to the model, so requests fail outright with 422 `Field required`. On top of that, `SQLModelBase`'s `extra='forbid'` turns any undeclared query parameter (such as a cache-busting `?_=123`) into a 422.
+A cross-field error is located at the field its rule constrains: both `after_id` rules report `after_id`, the time-range rules report the `*_before_datetime` field. The same form works for `PageWindowRequest`, `PaginationRequest`, `TimeFilterRequest`, `TrgmSearchRequest` and your own subclasses (`query_dependency(MyTableViewRequest)`). The endpoint can still declare further query parameters next to it; undeclared query parameters (such as a cache-busting `?_=123`) are ignored.
+
+::: warning Don't switch to `Annotated[TableViewRequest, Query()]`
+A Pydantic query model only works when it is the endpoint's **only** query parameter: add one more ordinary query parameter to the endpoint (e.g. `status: str | None = None`) and FastAPI no longer hands the whole query string to the model, so requests fail outright with 422 `Field required`. On top of that, `SQLModelBase`'s `extra='forbid'` turns any undeclared query parameter (such as `?_=123`) into a 422.
 :::
 
 ## 2. Call `get_with_count()` in the endpoint
@@ -98,7 +93,7 @@ Sorting always appends `id` in the same direction as a tiebreaker column, so row
 - **Time parameters must carry a timezone** (`...Z` or `+08:00`). All time bounds are `AwareDatetime`; a value without a timezone is a 422 outright — otherwise it would be silently interpreted in the database's timezone.
 - **Time intervals are half-open** `[after, before)`. `created_after_datetime=2026-01-01T00:00:00Z` + `created_before_datetime=2026-02-01T00:00:00Z` means "all of January (UTC)".
 - **`order` only accepts values in the `Literal`**; any other string makes FastAPI return `422`.
-- **`after_id` can't be used with a non-zero `offset`**, nor with `order=updated_at` — both are rejected when `TableViewRequest` is constructed (a 422 once you register the handler above).
+- **`after_id` can't be used with a non-zero `offset`**, nor with `order=updated_at` — both are rejected when `TableViewRequest` is constructed (a 422 at `["query", "after_id"]` through `query_dependency()`).
 
 ## Related reference
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/reference/crud-methods.md

@@ -154,14 +154,14 @@ async def get(
     offset: int | None = None,
     limit: int | None = None,
     fetch_mode: Literal["one", "first", "all"] = "first",
-    join: type[TableBaseMixin] | tuple[type[TableBaseMixin], _OnClauseArgument] | None = None,
+    join: type[TableBaseMixin] | tuple[type[TableBaseMixin], OnClauseArgument] | None = None,
     options: list[ExecutableOption] | None = None,
     load: QueryableAttribute[Any] | list[QueryableAttribute[Any]] | None = None,
     order_by: list[ColumnElement[Any]] | None = None,
     filter: ColumnElement[bool] | bool | None = None,
     with_for_update: bool = False,
     skip_locked: bool = False,
-    table_view: TableViewRequest | None = None,
+    table_view: TableViewArgument | None = None,  # TimeFilterRequest | PageWindowRequest
     jti_subclasses: list[type[PolymorphicBaseMixin]] | Literal['all'] | None = None,
     populate_existing: bool = False,
     authoritative: bool = False,
@@ -195,7 +195,7 @@ On `CachedTableBaseMixin` models, `get()` has one extra parameter, `no_cache: bo
 | `filter` | `ColumnElement[bool]` | Additional WHERE condition |
 | `with_for_update` | `bool` | `SELECT ... FOR UPDATE` row lock. Instance `id()`s are written to `session.info[SESSION_FOR_UPDATE_KEY]`; **forces** `populate_existing` (cannot be turned off), guaranteeing you get the latest database values rather than a stale object from the identity map |
 | `skip_locked` | `bool` | `FOR UPDATE SKIP LOCKED`: skip rows locked by other transactions instead of waiting. Only effective when `with_for_update=True`. "0 rows" may also mean "every candidate is locked by someone else", so **do not** use it for existence checks |
-| `table_view` | `TableViewRequest` | Bundle of pagination + ordering + time filtering + keyset cursor parameters. `order` always appends `id` in the same direction as a tiebreaker; `after_id` applies the keyset cursor |
+| `table_view` | `TableViewRequest` (or any `TimeFilterRequest` / `PageWindowRequest`; each part is applied when present) | Bundle of pagination + ordering + time filtering + keyset cursor parameters. `order` always appends `id` in the same direction as a tiebreaker; `after_id` applies the keyset cursor |
 | `jti_subclasses` | `list[type] \| 'all'` | Subclass loading for JTI polymorphic relationships (requires `load`) |
 | `populate_existing` | `bool` | Lock-free forced overwrite of identity-map objects with database data |
 | `authoritative` | `bool` | The single switch for **authorization reads** (the result decides whether something is allowed, so it must be authoritative): at this layer equivalent to `populate_existing=True`; cached models additionally bypass Redis. Monotonically merged with `populate_existing` (`or`) |
@@ -346,7 +346,7 @@ async def get_with_count(
     session: AsyncSession,
     condition: ColumnElement[bool] | bool | None = None,
     *,
-    join: type[TableBaseMixin] | tuple[type[TableBaseMixin], _OnClauseArgument] | None = None,
+    join: type[TableBaseMixin] | tuple[type[TableBaseMixin], OnClauseArgument] | None = None,
     options: list[ExecutableOption] | None = None,
     load: QueryableAttribute[Any] | list[QueryableAttribute[Any]] | None = None,
     order_by: list[ColumnElement[Any]] | None = None,

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/reference/decorators.md

@@ -190,7 +190,7 @@ from sqlmodel_ext.session import SessionFactory
 
 | Member | Description |
 |------|------|
-| `commit(*, fail_soft_when_observed=False)` | Before commit, automatically registers changes to all cached models (including bare `session.add()` / attribute changes / `session.delete()`); after commit, invalidates **synchronously**, then runs the post-commit callbacks in order. `fail_soft_when_observed=True`: a failure of the commit itself is raised as usual; every step **after** the commit (invalidation, each callback) is individually fault-tolerant (catches `BaseException` including cancellation, logs, continues). Default: errors raised by the invalidation step and cancellation propagate; a callback's `Exception` is logged and skipped. **Redis failures during invalidation are logged, not raised, in both modes** — the database has committed, so the affected cache entries serve pre-commit data until their TTL expires; use `no_cache=True` for reads that must not rely on the cache |
+| `commit(*, fail_soft_when_observed=False)` | Changes to cached models (including bare `session.add()` / attribute changes / `session.delete()`) are registered by the flush that writes them -- earlier in the transaction or during this commit; after commit, invalidates **synchronously**, then runs the post-commit callbacks in order. `fail_soft_when_observed=True`: a failure of the commit itself is raised as usual; every step **after** the commit (invalidation, each callback) is individually fault-tolerant (catches `BaseException` including cancellation, logs, continues). Default: errors raised by the invalidation step and cancellation propagate; a callback's `Exception` is logged and skipped. **Redis failures during invalidation are logged, not raised, in both modes** — the database has committed, so the affected cache entries serve pre-commit data until their TTL expires; use `no_cache=True` for reads that must not rely on the cache |
 | `commit_count` (property) | Number of successful commits on this session. The single source of truth for "was it committed": record a baseline before a critical write, and `commit_count > baseline` afterwards means the database has committed (a sufficient but not necessary signal) |
 | `add_post_commit_callback(callback)` | Registers an `async` zero-argument callback, run **only after the next real commit**; discarded by `rollback()` / `reset()` / `close()`; registering inside a savepoint → `RuntimeError`; a failing callback doesn't block later callbacks nor change the commit result |
 | `rollback(*, best_effort_budget_seconds=None)` | Rolls back + discards pending callbacks. Passing a budget enters **bounded abandon** mode: rolls back under `asyncio.timeout`, and on failure or timeout does a best-effort `invalidate()` of the connection, **without raising** (`CancelledError` still propagates). Not a hard cap (`invalidate` may still wait inside the driver) |

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/reference/field-types.md

@@ -358,7 +358,7 @@ from sqlmodel_ext.field_types.dialects.postgresql import JSON100K, JSONList100K,
 
 Contract: **object in, object out**.
 
-- **Inbound**: accepts a JSON object / array (preferred) or a JSON **string** (compatibility form). Both forms must be encodable (nesting within the limits of both serializers, orjson and Pydantic — Pydantic's is about 98 levels) with a canonical encoding of at most 100K **characters** (counted in characters, not UTF-8 bytes, so CJK text is not rejected 3x too early).
+- **Inbound**: accepts a JSON object / array (preferred) or a JSON **string** (compatibility form). Both forms must be encodable (nesting within the limits of both serializers, orjson and Pydantic — Pydantic's is platform-dependent, about 98 levels on Windows builds and higher on Linux) with a canonical encoding of at most 100K **characters** (counted in characters, not UTF-8 bytes, so CJK text is not rejected 3x too early).
 - **Outbound**: `model_dump()`, `model_dump(mode='json')` and `model_dump_json()` all output the object / array itself (since 0.5.0; it used to be a JSON string). The serialization schema declares a pure object / array; the validation schema honestly declares `anyOf[object, string]`.
 - **Table models are checked too**: `table=True` models skip Pydantic validation, so `SQLModelBase.model_post_init` calls `ensure_json_within_limits` on these fields (call `super()` when overriding `model_post_init`). Code paths that bypass models can call `ensure_json_within_limits(value)` directly.
 - The 100K limit does not appear in the JSON Schema (JSON Schema cannot express an encoded length for objects); document it in the field docstring.

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/reference/index.md

@@ -15,7 +15,7 @@ from sqlmodel_ext import (
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     create_subclass_id_mixin,
     RelationPreloadMixin, requires_relations, requires_for_update,
-    ListResponse, TableViewRequest, PaginationRequest, TimeFilterRequest,
+    ListResponse, TableViewRequest, PaginationRequest, TimeFilterRequest, query_dependency,
     Str64, Port, HttpUrl, SafeHttpUrl, IPAddress, ...
 )
 ```
@@ -29,7 +29,7 @@ from sqlmodel_ext import (
 | [Field types](./field-types) | `Str16`–`Text1M`, `Port`, `Percentage`, `PositiveInt`, `HttpUrl`, `SafeHttpUrl`, `IPAddress`, `Array[T]`, `JSON100K`, `NumpyVector` |
 | [Mixins](./mixins) | `CachedTableBaseMixin`, `OptimisticLockMixin`, `PolymorphicBaseMixin`, `AutoPolymorphicIdentityMixin`, `RelationPreloadMixin`, info response mixins |
 | [Decorators & helpers](./decorators) | `@requires_relations`, `@requires_for_update`, `rel()`, `cond()`, enhanced `session.reset()` |
-| [Pagination types](./pagination-types) | `ListResponse[T]`, `TableViewRequest`, `PaginationRequest`, `TimeFilterRequest` |
+| [Pagination types](./pagination-types) | `ListResponse[T]`, `TableViewRequest`, `PaginationRequest`, `TimeFilterRequest`, `query_dependency()` |
 
 ## Constants
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.1}/docs/en/reference/mixins.md

@@ -171,7 +171,7 @@ from sqlmodel_ext import PolymorphicBaseMixin
 
 ```python
 @classmethod
-def _is_joined_table_inheritance(cls) -> bool
+def is_joined_table_inheritance(cls) -> bool
 
 @classmethod
 def get_concrete_subclasses(cls) -> list[type[PolymorphicBaseMixin]]