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

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.2}/.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.2}/CHANGELOG.md

@@ -7,6 +7,147 @@ 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.2]
+
+### Fixed
+
+- A table class field declared with a type alias and a plain right-hand value
+  (`x: NonNegativeDecimal38_18 = Decimal(0)`, `s: Str64 = 'a'`) had its default only in
+  `model_fields`: the JSON schema listed the field as `required` with no `default`, and
+  `model_validate({})` rejected the payload with "Field required". With an alias that
+  carries its own default (`opt: OptionalNonNegativeDecimal38_18 = Decimal(1)`),
+  `model_fields` even showed the alias's default (`None`) instead of the declared one.
+  The metaclass set the value on the field after constructing it, so Pydantic did not
+  count it as set when it built the core schema. A metaclass rebuild (an inherited field
+  description, a relationship) hid the defect in some classes. The same applied to a
+  field re-declared in the table class body without a right-hand side, which takes the
+  base's default. The table class now matches a non-table class with the same
+  declaration (schema, validation and `model_fields`). Non-table classes and fields the
+  table class inherits without re-declaring were not affected. Also present in 0.5.0
+  and 0.5.1.
+- **Behavior change.** A table class field declared with **several** `Field(...)` in one
+  `Annotated` and no right-hand side (`value: Legacy` with
+  `Legacy = Annotated[str, Field(alias='legacy', title='T'), Field(unique=True)]`, or a
+  nested alias such as `Annotated[Str64, Field(unique=True)]`) now gets its Pydantic
+  attributes as Pydantic merges them -- the same field a non-table class, plain
+  SQLModel and a table class inheriting the declaration already got. A later `Field`
+  overrides an earlier one, `None` included, and sqlmodel's `Field()` passes
+  `alias` / `validation_alias` / `serialization_alias` / `title` / `description` /
+  `default_factory` / `discriminator` / `exclude` explicitly as `None` and `repr` as
+  `True`. So when an earlier `Field` of the annotation sets any of these and a later
+  one does not, the table class no longer keeps the earlier value: the alias / title /
+  description are gone, and a `default_factory` is dropped, which makes the field
+  **required**. A `default` is not affected (sqlmodel's `Field()` does not pass it).
+  None of the bundled aliases combines several `Field`s or sets such an attribute. To keep the value, set it in the last `Field` or on a right-hand
+  `= Field(...)`. The same holds for a non-table class whose field needs an injected
+  `sa_type` (`Annotated[FilePathType, Field(alias='p'), Field(index=True)]`), which kept
+  the earlier `alias` too. The same path also applied the `Field` of an alias nested in a
+  union with no right-hand side, which Pydantic does not merge at field level:
+  `x: OptionalNonNegativeDecimal38_18 | None` declared in a table class had
+  `default=None`; it is now **required**, as it already was in a non-table class, when
+  inherited, and with a right-hand `Field` that sets no default (0.5.1). Drop the
+  redundant `| None` or write `= None`. The column attributes of all the declaration's `Field`s are
+  still folded into the column, now with the precedence Pydantic uses for the Pydantic
+  attributes: the right-hand `Field` first, then the annotation's `Field`s from the last
+  to the first; `False` still never switches off `True`. So a table class **inheriting**
+  such a declaration agrees with one declaring it directly:
+  `Annotated[NonNegativeDecimal38_18, Field(sa_type=Numeric(20, 2))]` gives
+  `NUMERIC(20, 2)` in both (inheriting it gave `NUMERIC(38, 18)`, the alias's
+  `sa_type`). Plain SQLModel, which reads only the first carrier, still gives
+  `NUMERIC(38, 18)`. Also present in 0.5.0 and 0.5.1. This only changes the metadata
+  the models build: existing databases are not altered. Tables created from now on
+  (`create_all`) get the new column type; to align an existing table, write a migration.
+
+## [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 +305,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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlmodel-ext
-Version: 0.5.0
+Version: 0.5.2
 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.2}/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.2}/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.2}/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.2}/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.2}/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. Every such field is rebuilt from **Pydantic's own resolution of its declaration** — the field a non-table class (or plain SQLModel) gets for the same declaration: `FieldInfo.from_annotated_attribute()` when the table class declares it with a right-hand side (`= Field(...)` or a plain value such as `= 'a'`), `FieldInfo.from_annotation()` when it declares it without one, and the base's resolved field `Base.model_fields[name]` when the table class **inherits** it (without re-declaring it). Its Pydantic attributes are taken as-is. Several `Field`s in one `Annotated` merge as Pydantic merges them: a later `Field` overrides an earlier one, `None` included — sqlmodel's `Field()` passes `alias` / `validation_alias` / `serialization_alias` / `title` / `description` / `default_factory` / `discriminator` / `exclude` explicitly as `None` (and `repr` as `True`), so `Annotated[str, Field(alias='a', title='T'), Field(unique=True)]` has neither alias nor title; a right-hand `Field` overrides them all. The `Field` of an alias nested in a union (`OptionalNonNegativeDecimal38_18 | None`) is not merged at field level, so its `default=None` does not apply — only its constraints and column attributes are carried over. The attributes are passed to the constructor, so Pydantic records them as set and they reach the core schema: a default of `x: Str64 = 'a'` is in the JSON schema and in validation, not only in `model_fields`. Only the column attributes are completed — the `FieldInfoMetadata` carriers of all the declaration's `Field`s are folded into one, since SQLModel reads only the first: the right-hand `Field`'s first, then the annotation's from the last to the first (`Annotated[NonNegativeDecimal38_18, Field(sa_type=Numeric(20, 2))]` gets `NUMERIC(20, 2)`), and `False` never switches off `True`. One library rule departs from Pydantic: a field re-declared in the table class body without a right-hand side keeps the base's default (Pydantic would make it required). 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,12 +178,12 @@ 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:
-            # no "= Field(...)": prefer recovering the user's FieldInfo from inside Annotated,
-            # keeping default_factory / max_length etc., and only add sa_type
+            # no "= Field(...)": a right-hand Field carrying Pydantic's own resolution of the
+            # Annotated (default_factory etc. kept, nothing changed) plus sa_type
             annotated_fi = _find_field_info_in_annotated(field_type)
             attrs[field_name] = annotated_fi if annotated_fi is not None else Field(sa_type=sa_type)
         elif isinstance(field_value, FieldInfo):
@@ -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
 
@@ -218,7 +218,7 @@ result = super().__new__(cls, name, bases, attrs, **kwargs)
 #         merge the saved SQLModelFieldInfo back and rebuild the Column
 ```
 
-While merging, boolean flags are never overwritten with `False` (`unique=False` never switches off an inherited `unique=True`), and `FieldInfoMetadata` carriers are folded into one (SQLModel reads only the first; otherwise an all-unset carrier inside a type alias shadows `= Field(primary_key=True)` — which is exactly why `id: NonNegativeInt = Field(primary_key=True)` lost its primary key on sqlmodel ≥ 0.0.32).
+Step 7 only copies back what Pydantic filled in; there `None` and `False` never overwrite a saved value. The `FieldInfoMetadata` carriers of one declaration were already folded into one in step 4.5 (SQLModel reads only the first; otherwise an all-unset carrier inside a type alias shadows `= Field(primary_key=True)` — which is exactly why `id: NonNegativeInt = Field(primary_key=True)` lost its primary key on sqlmodel ≥ 0.0.32).
 
 ### Steps 8–9: Relationship fields under inheritance
 

{sqlmodel_ext-0.5.0 → sqlmodel_ext-0.5.2}/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.2}/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.2}/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.2}/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.2}/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.2}/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.2}/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