sqlmodel-ext 0.5.4__tar.gz → 0.5.5__tar.gz

sqlmodel_ext-0.5.5/.gitattributes

@@ -0,0 +1,5 @@
+# Store every text file with LF line endings, whatever the contributor's
+# core.autocrlf setting. Without this, files committed from Windows with CRLF
+# stayed CRLF in the repository (git only converts on add when it already
+# considers the file text-normalized).
+* text=auto eol=lf

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/CHANGELOG.md

@@ -7,6 +7,48 @@ 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.5]
+
+### Added
+
+- `TableViewRequest.id_prefix`: list only the rows whose UUID primary key, in canonical text
+  form, starts with the given prefix (case-insensitive, surrounding whitespace removed).
+  `get()` and `get_with_count()` apply it whenever the `table_view` carries it, and the count
+  of `get_with_count()` follows the same filter; a plain `count()` takes it as
+  `count(id_prefix=...)`. It is applied as a primary-key range (`id BETWEEN lower AND upper`),
+  which uses the primary-key index, rather than `CAST(id AS TEXT) LIKE 'prefix%'`, which scans
+  the table. With `query_dependency(TableViewRequest)` every list endpoint gets an `id_prefix`
+  query parameter. A model whose primary key is not a UUID raises `ValueError` when it is
+  given. Like the time filters, it is not part of the keyset cursor's anchor visibility. The
+  query cache key of `CachedTableBaseMixin` includes it.
+- `UUIDPrefix` field type: the beginning of a UUID in canonical text form, 4-36 characters
+  after stripping, hex digits in either case, `-` only right after a complete `8-4-4-4-12`
+  group. Input that cannot start a UUID (`"zzzz"`, `"0192-f4"`) is rejected instead of
+  silently matching nothing.
+
+### Fixed
+
+- Importing `sqlmodel_ext` with Pydantic 2.14 emitted `PydanticDeprecatedSince214`:
+  `Unset` was imported from `pydantic.experimental.missing_sentinel`, which 2.14 deprecates
+  in favor of `pydantic.MISSING`. It is now imported from `pydantic_core`, where every
+  supported Pydantic release (2.12 on) defines it; it is the same object, so `Unset is
+  pydantic.MISSING` still holds.
+- Type checking against SQLAlchemy 2.1.7+ reported two unnecessary suppressions inside the
+  library: 2.1.7 changed the overloads of `sqlalchemy.inspect()` so that a call without
+  `raiseerr` returns `Any` instead of `Optional[Any]`. Both call sites now pass
+  `raiseerr=True`, which is typed the same way before and after 2.1.7. No runtime change.
+
+### Changed
+
+- With Pydantic 2.14, an explicit `null` for an `Unset | T` field that does not accept `None`
+  is reported as a single error for the `T` branch (e.g. `string_type`, `loc` ending at the
+  field name); 2.12 and 2.13 also report a `missing_sentinel_error` with branch tags in
+  `loc`. This is Pydantic's change; the input is rejected either way. The documentation and
+  the tests now describe both shapes.
+- Pydantic 2.14.1 checks the integer digits of a `Decimal` regardless of where a
+  `BeforeValidator` sits in the `Annotated` metadata. The decimal aliases keep their
+  metadata order, which earlier Pydantic releases still need.
+
 ## [0.5.4]
 
 ### Changed

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlmodel-ext
-Version: 0.5.4
+Version: 0.5.5
 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

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/en/explanation/prerequisites.md

@@ -150,7 +150,7 @@ That is the basic building block of sqlmodel-ext's "declare once" approach: the
 
 ## Sentinel values: when `None` is a real value
 
-A **sentinel** is a unique object whose only job is to mean "a special situation", compared with `is`. Python has used them for a long time (`dataclasses.MISSING`, private `_NOTSET = object()` constants), and [PEP 661](https://peps.python.org/pep-0661/) standardizes the pattern. Pydantic 2.12 ships one as `pydantic.experimental.missing_sentinel.MISSING`, which sqlmodel-ext exports as `Unset`.
+A **sentinel** is a unique object whose only job is to mean "a special situation", compared with `is`. Python has used them for a long time (`dataclasses.MISSING`, private `_NOTSET = object()` constants), and [PEP 661](https://peps.python.org/pep-0661/) standardizes the pattern. Pydantic ships one as `MISSING` (`pydantic.experimental.missing_sentinel.MISSING` since 2.12, `pydantic.MISSING` since 2.14), which sqlmodel-ext exports as `Unset`.
 
 Why it matters: in a PATCH body, `None` has to be able to mean "clear this column", so "the field was not sent" needs a different carrier. With `Unset`, the three states — not sent / `null` / a value — become distinguishable:
 

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/en/explanation/unset-three-state.md

@@ -38,7 +38,7 @@ Conventions live in people's heads. The one time someone forgets, nothing raises
 from sqlmodel_ext import Unset
 ```
 
-`Unset` **is** Pydantic's official `pydantic.experimental.missing_sentinel.MISSING` (a PEP 661-style sentinel); sqlmodel-ext only exports it under another name. Once "not provided" is carried by `Unset`, `None` goes back to being an **ordinary value**.
+`Unset` **is** Pydantic's official `MISSING` sentinel (a PEP 661-style sentinel; `pydantic.MISSING` since Pydantic 2.14, `pydantic.experimental.missing_sentinel.MISSING` in 2.12–2.13); sqlmodel-ext only exports it under another name. Once "not provided" is carried by `Unset`, `None` goes back to being an **ordinary value**.
 
 | Annotation | Meaning |
 |---|---|
@@ -94,7 +94,7 @@ else:
 - **A value** → validated as usual (length, range and every other constraint is kept).
 
 ::: warning Do not rely on the order of errors
-`Unset | T` is a union, so a failed validation lists one error per branch in `ValidationError.errors()` (for `title=null` above you get both `missing_sentinel_error` and `string_type`, with branch tags such as `'missing-sentinel'` / `'constrained-str'` in `loc`). The order of union members does not change **which** inputs are accepted or rejected, but it does change the **order** of error entries; do not depend on that order downstream.
+`Unset | T` is a union. With Pydantic 2.12–2.13 a failed validation lists one error per branch in `ValidationError.errors()` (for `title=null` above you get both `missing_sentinel_error` and `string_type`, with branch tags such as `'missing-sentinel'` / `'constrained-str'` in `loc`); from Pydantic 2.14 on the `MISSING` branch is no longer reported, so you get only the `T` branch's error (`string_type`, with `loc` ending at the field name). The order of union members does not change **which** inputs are accepted or rejected, but it does change the **order** of error entries; do not depend on that order downstream.
 :::
 
 ## `partial=True`: derive a PATCH DTO from the base
@@ -312,6 +312,6 @@ In one sentence: **`EXCLUDE_IF_NONE` is an output-format convention; `Unset` is
 
 ## Known limitations
 
-- Pydantic still marks the feature experimental (module `pydantic.experimental.missing_sentinel`, available since Pydantic 2.12), hence sqlmodel-ext 0.5 requires `pydantic>=2.12`.
+- The sentinel first shipped in Pydantic 2.12 as experimental (`pydantic.experimental.missing_sentinel.MISSING`), hence sqlmodel-ext 0.5 requires `pydantic>=2.12`. Pydantic 2.14 made it stable as `pydantic.MISSING` and deprecated the experimental path; sqlmodel-ext imports it from `pydantic_core`, which works without a deprecation warning on every supported release.
 - Static narrowing requires PEP 661 support (versions above); with basedpyright alone, partial-derived fields do not take part in static narrowing — declare them explicitly or use [`check_derived`](/en/how-to/check-partial-dtos) (see above).
 - In models with `omitted_sentinel` enabled, string fields cannot hold the literal `'__omitted__'`.

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/en/reference/base-classes.md

@@ -121,7 +121,7 @@ class ToolArguments(SQLModelBase):
 from sqlmodel_ext import Unset, OMITTED_SENTINEL
 ```
 
-- `Unset`: Pydantic's official `pydantic.experimental.missing_sentinel.MISSING`, meaning "this field was not provided". Check with `x is Unset`. Fields whose value is `Unset` never appear in `model_dump()` / `model_dump_json()` output. `copy.deepcopy(Unset) is Unset`.
+- `Unset`: Pydantic's official `MISSING` sentinel (`pydantic.MISSING` since Pydantic 2.14, `pydantic.experimental.missing_sentinel.MISSING` before), meaning "this field was not provided". Check with `x is Unset`. Fields whose value is `Unset` never appear in `model_dump()` / `model_dump_json()` output. `copy.deepcopy(Unset) is Unset`.
 - `OMITTED_SENTINEL`: `'__omitted__'`, the wire sentinel value; it only exists in the JSON Schema and inbound payloads of models with `omitted_sentinel` enabled and is normalized to `Unset` on entry. Application code should never compare against it.
 
 Full semantics in [Unset](/en/explanation/unset-three-state).

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/en/reference/crud-methods.md

@@ -280,10 +280,11 @@ async def count(
     created_after_datetime: datetime | None = None,
     updated_before_datetime: datetime | None = None,
     updated_after_datetime: datetime | None = None,
+    id_prefix: UUIDPrefix | None = None,
 ) -> int
 ```
 
-Returns the number of matching records via `SELECT COUNT(*)`. Passing `distinct_column` switches to `COUNT(DISTINCT col)` (e.g. "distinct active users"). Non-null fields in `time_filter` take precedence over the individually passed time parameters.
+Returns the number of matching records via `SELECT COUNT(*)`. Passing `distinct_column` switches to `COUNT(DISTINCT col)` (e.g. "distinct active users"). Non-null fields in `time_filter` take precedence over the individually passed time parameters. `id_prefix` counts only rows whose UUID primary key starts with the prefix (the same filter as [`TableViewRequest.id_prefix`](/en/reference/pagination-types)); `time_filter` does not carry it, even when a `TableViewRequest` is passed there.
 
 ## `distinct_column()`
 

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/en/reference/field-types.md

@@ -37,7 +37,7 @@ from sqlmodel_ext import Str1, Str16, Str24, Str32, Str36, Str48, Str64, Str100,
 from sqlmodel_ext import (
     NonEmptyStr64, NonEmptyStr128, NonEmptyStr256,
     NonEmptyStrippedStr32, NonEmptyStrippedStr64, NonEmptyStrippedStr128, NonEmptyStrippedStr256,
-    SingleLineStr64, SearchQueryStr64, HttpHeaderName,
+    SingleLineStr64, SearchQueryStr64, UUIDPrefix, HttpHeaderName,
     Sha256Hex, BCP47LanguageCode,
 )
 ```
@@ -48,6 +48,7 @@ from sqlmodel_ext import (
 | `NonEmptyStrippedStr32/64/128/256` | Same as above + `strip_whitespace`, rejects whitespace-only input (`"   "` / `"\t"`) |
 | `SingleLineStr64` | `NonEmptyStrippedStr64` + **single line**: rejects NUL and every line-break character (`\n \v \f \r \x1c \x1d \x1e \x85 
 
`, derived from `str.splitlines()`); tabs are allowed. For names rendered line by line, so a line break cannot forge an extra listing entry |
 | `SearchQueryStr64` | `2 <= len <= 64` after stripping: a one-character trigram query has no selective trigrams and degrades into a near-full table scan |
+| `UUIDPrefix` | The beginning of a UUID in canonical text form, `4 <= len <= 36` after stripping: hex digits in either case, `-` only right after a complete `8-4-4-4-12` group (`"0192f4"`, `"0192f4a1-7c"`; `"zzzz"` and `"0192-f4"` are rejected). Used by [`TableViewRequest.id_prefix`](/en/reference/pagination-types) |
 | `HttpHeaderName` | RFC 9110 `token` (letters, digits and ``!#$%&'*+-.^_`|~``), `1 <= len <= 64` |
 | `Sha256Hex` | Exactly 64 lowercase hex characters (a SHA-256 digest) |
 | `BCP47LanguageCode` | BCP-47 language tag syntax (e.g. `zh-Hans-CN`), `max_length=16` |

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/en/reference/pagination-types.md

@@ -10,7 +10,7 @@ Class hierarchy:
 PageWindowRequest            offset / limit / desc
   └── PaginationRequest      + order / after_id (keyset cursor)
 TimeFilterRequest            created_* / updated_* time bounds
-TableViewRequest             TimeFilterRequest + PaginationRequest
+TableViewRequest             TimeFilterRequest + PaginationRequest + id_prefix
 ```
 
 They are all pure data classes that only carry parameters; the SQL clauses are built by `TableBaseMixin.get()`.
@@ -84,10 +84,16 @@ from sqlmodel_ext import TableViewRequest
 
 ```python
 class TableViewRequest(TimeFilterRequest, PaginationRequest):
-    pass
+    id_prefix: UUIDPrefix | None = None
 ```
 
-Carries pagination + ordering + keyset cursor + time filter parameters together. `get()` / `get_with_count()` accept a `table_view` parameter; explicitly passed `offset` / `limit` / `order_by` / time parameters take precedence, falling back to `table_view` when not provided.
+Carries pagination + ordering + keyset cursor + time filter + ID prefix parameters together. `get()` / `get_with_count()` accept a `table_view` parameter; explicitly passed `offset` / `limit` / `order_by` / time parameters take precedence, falling back to `table_view` when not provided.
+
+| Field | Type | Default | Semantics |
+|------|------|--------|------|
+| `id_prefix` | [`UUIDPrefix`](/en/reference/field-types) `\| None` | `None` | Only rows whose UUID primary key, in canonical text form, starts with this prefix; case-insensitive, surrounding whitespace removed |
+
+`get()` / `get_with_count()` apply it as a primary-key range (`id BETWEEN lower AND upper`), so it can use the primary-key index instead of scanning the table; the count of `get_with_count()` follows the same filter. To filter a plain `count()`, pass `count(id_prefix=...)` — `time_filter` does not carry it. Like the time filters, it narrows the page but is not part of the keyset cursor's anchor visibility. A model whose primary key is not a UUID raises `ValueError` when it is given.
 
 ## `query_dependency()`
 

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/explanation/prerequisites.md

@@ -150,7 +150,7 @@ class User(SQLModel, table=True):
 
 ## 哨兵值：当 `None` 本身是一个有意义的值
 
-**哨兵值（sentinel）**是一个独一无二的对象，唯一的作用是表示"某种特殊情况"，用 `is` 比较。Python 里早就有这种用法（`dataclasses.MISSING`、私有的 `_NOTSET = object()` 常量），[PEP 661](https://peps.python.org/pep-0661/) 把它标准化了。Pydantic 2.12 提供了一个：`pydantic.experimental.missing_sentinel.MISSING`，sqlmodel-ext 以 `Unset` 的名字导出它。
+**哨兵值（sentinel）**是一个独一无二的对象，唯一的作用是表示"某种特殊情况"，用 `is` 比较。Python 里早就有这种用法（`dataclasses.MISSING`、私有的 `_NOTSET = object()` 常量），[PEP 661](https://peps.python.org/pep-0661/) 把它标准化了。Pydantic 提供了一个：`MISSING`（2.12 起为 `pydantic.experimental.missing_sentinel.MISSING`，2.14 起为 `pydantic.MISSING`），sqlmodel-ext 以 `Unset` 的名字导出它。
 
 为什么需要它：在 PATCH 请求体里，`None` 必须能表示"清空这一列"，于是"这个字段没传"就需要另一个载体。有了 `Unset`，三种状态——没传 / `null` / 有值——就能区分开：
 

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/explanation/unset-three-state.md

@@ -38,7 +38,7 @@ class ArticleUpdate(SQLModelBase):
 from sqlmodel_ext import Unset
 ```
 
-`Unset` 就是 Pydantic 官方的 `pydantic.experimental.missing_sentinel.MISSING`（PEP 661 风格的哨兵），sqlmodel-ext 只是给它换了个名字导出。「没传」由 `Unset` 承载之后，`None` 重新变回一个**普通的值**。
+`Unset` 就是 Pydantic 官方的 `MISSING` 哨兵（PEP 661 风格；Pydantic 2.14 起为 `pydantic.MISSING`，2.12–2.13 为 `pydantic.experimental.missing_sentinel.MISSING`），sqlmodel-ext 只是给它换了个名字导出。「没传」由 `Unset` 承载之后，`None` 重新变回一个**普通的值**。
 
 | 注解 | 含义 |
 |---|---|
@@ -94,7 +94,7 @@ else:
 - **传了值** → 照常校验（长度、范围等约束全部保留）。
 
 ::: warning 错误列表的顺序不要依赖
-`Unset | T` 是一个联合类型，校验失败时 `ValidationError.errors()` 里会有每个分支各自的错误（例如上面 `title=null` 会同时出现 `missing_sentinel_error` 与 `string_type`，`loc` 里带有分支标签如 `'missing-sentinel'` / `'constrained-str'`）。成员的顺序不影响**接受/拒绝哪些输入**，但会影响错误条目的**顺序**；下游不要依赖这个顺序。
+`Unset | T` 是一个联合类型。Pydantic 2.12–2.13 下校验失败时，`ValidationError.errors()` 里会有每个分支各自的错误（例如上面 `title=null` 会同时出现 `missing_sentinel_error` 与 `string_type`，`loc` 里带有分支标签如 `'missing-sentinel'` / `'constrained-str'`）；Pydantic 2.14 起不再报告 `MISSING` 分支，只剩 `T` 分支的那条错误（`string_type`，`loc` 到字段名为止）。成员的顺序不影响**接受/拒绝哪些输入**，但会影响错误条目的**顺序**；下游不要依赖这个顺序。
 :::
 
 ## `partial=True`：从基类派生 PATCH DTO
@@ -312,6 +312,6 @@ assert Event(marker=True).model_dump() == {'marker': True}
 
 ## 已知限制
 
-- Pydantic 仍把该特性标为 experimental（模块路径 `pydantic.experimental.missing_sentinel`，自 Pydantic 2.12 起提供），因此 sqlmodel-ext 0.5 要求 `pydantic>=2.12`。
+- 该哨兵自 Pydantic 2.12 起以 experimental 形式提供（`pydantic.experimental.missing_sentinel.MISSING`），因此 sqlmodel-ext 0.5 要求 `pydantic>=2.12`。Pydantic 2.14 将其转正为 `pydantic.MISSING`，并弃用 experimental 路径；sqlmodel-ext 从 `pydantic_core` 导入它，在所有支持的版本上都不会触发弃用警告。
 - 静态收窄需要 PEP 661 支持（见上文版本要求）；partial 派生字段在单独运行 basedpyright 时不参与静态收窄，需显式声明或用 [`check_derived`](/how-to/check-partial-dtos)（见上文）。
 - 开启 `omitted_sentinel` 的模型，字符串字段不能持有字面量 `'__omitted__'`。

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/reference/base-classes.md

@@ -120,7 +120,7 @@ class ToolArguments(SQLModelBase):
 from sqlmodel_ext import Unset, OMITTED_SENTINEL
 ```
 
-- `Unset`：Pydantic 官方的 `pydantic.experimental.missing_sentinel.MISSING`，表示"这个字段没有提供"。用 `x is Unset` 判断。值为 `Unset` 的字段不出现在 `model_dump()` / `model_dump_json()` 输出中。`copy.deepcopy(Unset) is Unset`。
+- `Unset`：Pydantic 官方的 `MISSING` 哨兵（Pydantic 2.14 起为 `pydantic.MISSING`，此前为 `pydantic.experimental.missing_sentinel.MISSING`），表示"这个字段没有提供"。用 `x is Unset` 判断。值为 `Unset` 的字段不出现在 `model_dump()` / `model_dump_json()` 输出中。`copy.deepcopy(Unset) is Unset`。
 - `OMITTED_SENTINEL`：`'__omitted__'`，线上哨兵值，只存在于开启 `omitted_sentinel` 的模型的 JSON Schema 与入站负载中，进门即被归一为 `Unset`。业务代码不应与它比较。
 
 完整语义见 [Unset 三态](/explanation/unset-three-state)。

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/reference/crud-methods.md

@@ -280,10 +280,11 @@ async def count(
     created_after_datetime: datetime | None = None,
     updated_before_datetime: datetime | None = None,
     updated_after_datetime: datetime | None = None,
+    id_prefix: UUIDPrefix | None = None,
 ) -> int
 ```
 
-返回符合条件的记录数，底层 `SELECT COUNT(*)`。传 `distinct_column` 时改为 `COUNT(DISTINCT col)`（如"活跃用户去重数"）。`time_filter` 中的非空字段优先于单独传入的时间参数。
+返回符合条件的记录数，底层 `SELECT COUNT(*)`。传 `distinct_column` 时改为 `COUNT(DISTINCT col)`（如"活跃用户去重数"）。`time_filter` 中的非空字段优先于单独传入的时间参数。`id_prefix` 只统计 UUID 主键以该前缀开头的行（与 [`TableViewRequest.id_prefix`](/reference/pagination-types) 同一个过滤）；`time_filter` 不携带它，即使传进去的是 `TableViewRequest`。
 
 ## `distinct_column()`
 

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/reference/field-types.md

@@ -37,7 +37,7 @@ from sqlmodel_ext import Str1, Str16, Str24, Str32, Str36, Str48, Str64, Str100,
 from sqlmodel_ext import (
     NonEmptyStr64, NonEmptyStr128, NonEmptyStr256,
     NonEmptyStrippedStr32, NonEmptyStrippedStr64, NonEmptyStrippedStr128, NonEmptyStrippedStr256,
-    SingleLineStr64, SearchQueryStr64, HttpHeaderName,
+    SingleLineStr64, SearchQueryStr64, UUIDPrefix, HttpHeaderName,
     Sha256Hex, BCP47LanguageCode,
 )
 ```
@@ -48,6 +48,7 @@ from sqlmodel_ext import (
 | `NonEmptyStrippedStr32/64/128/256` | 同上 + `strip_whitespace`，拒绝纯空白（`"   "` / `"\t"`） |
 | `SingleLineStr64` | 等于 `NonEmptyStrippedStr64` + **单行**：拒绝 NUL 与所有换行字符（`\n \v \f \r \x1c \x1d \x1e \x85 
 
`，由 `str.splitlines()` 推导）；制表符允许。用于逐行渲染的名称，防止用换行伪造列表条目 |
 | `SearchQueryStr64` | 去空白后 `2 <= len <= 64`：单字符 trigram 查询没有选择性，会退化成近乎全表扫描 |
+| `UUIDPrefix` | UUID 标准文本形式的开头部分，去空白后 `4 <= len <= 36`：十六进制字符不区分大小写，`-` 只能紧跟在完整的 `8-4-4-4-12` 分组之后（`"0192f4"`、`"0192f4a1-7c"`；`"zzzz"`、`"0192-f4"` 会被拒绝）。供 [`TableViewRequest.id_prefix`](/reference/pagination-types) 使用 |
 | `HttpHeaderName` | RFC 9110 `token`（字母、数字与 ``!#$%&'*+-.^_`|~``），`1 <= len <= 64` |
 | `Sha256Hex` | 精确 64 位小写 hex（SHA-256 摘要） |
 | `BCP47LanguageCode` | BCP-47 语言代码语法（如 `zh-Hans-CN`），`max_length=16` |

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/docs/reference/pagination-types.md

@@ -10,7 +10,7 @@
 PageWindowRequest            offset / limit / desc
   └── PaginationRequest      + order / after_id（keyset 游标）
 TimeFilterRequest            created_* / updated_* 时间边界
-TableViewRequest             TimeFilterRequest + PaginationRequest
+TableViewRequest             TimeFilterRequest + PaginationRequest + id_prefix
 ```
 
 它们都是纯数据类，只承载参数；SQL 子句由 `TableBaseMixin.get()` 构造。
@@ -84,10 +84,16 @@ from sqlmodel_ext import TableViewRequest
 
 ```python
 class TableViewRequest(TimeFilterRequest, PaginationRequest):
-    pass
+    id_prefix: UUIDPrefix | None = None
 ```
 
-同时承载分页 + 排序 + keyset 游标 + 时间过滤参数。`get()` / `get_with_count()` 接受 `table_view` 参数；显式传入的 `offset` / `limit` / `order_by` / 时间参数优先，未提供时回退到 `table_view`。
+同时承载分页 + 排序 + keyset 游标 + 时间过滤 + ID 前缀参数。`get()` / `get_with_count()` 接受 `table_view` 参数；显式传入的 `offset` / `limit` / `order_by` / 时间参数优先，未提供时回退到 `table_view`。
+
+| 字段 | 类型 | 默认值 | 语义 |
+|------|------|--------|------|
+| `id_prefix` | [`UUIDPrefix`](/reference/field-types) `\| None` | `None` | 只返回 UUID 主键（标准文本形式）以该前缀开头的行；不区分大小写，首尾空白会去除 |
+
+`get()` / `get_with_count()` 把它转成主键范围（`id BETWEEN 下界 AND 上界`），可以走主键索引而不是全表扫描；`get_with_count()` 的总数按同一条件统计。单独调用 `count()` 时传 `count(id_prefix=...)`——`time_filter` 不携带它。和时间过滤一样，它只收窄结果，不参与 keyset 游标的锚点可见性判断。主键不是 UUID 的模型传了它会抛 `ValueError`。
 
 ## `query_dependency()`
 

{sqlmodel_ext-0.5.4 → sqlmodel_ext-0.5.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlmodel-ext"
-version = "0.5.4"
+version = "0.5.5"
 description = "Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types."
 readme = "README.md"
 license = "MIT"
@@ -31,8 +31,9 @@ dependencies = [
     # 0.0.48 made ``Select`` variadic (``Select[A, B]``); ``sqlmodel_ext.select``'s
     # overloads mirror that spelling, which earlier releases reject.
     "sqlmodel>=0.0.48",
-    # 2.12 is the first release shipping ``pydantic.experimental.missing_sentinel.MISSING``
-    # (the object ``Unset`` is) and ``Field(exclude_if=...)`` (behind ``EXCLUDE_IF_NONE``).
+    # 2.12 is the first release shipping the ``MISSING`` sentinel (the object ``Unset`` is;
+    # ``pydantic.MISSING`` since 2.14, ``pydantic.experimental.missing_sentinel`` before) and
+    # ``Field(exclude_if=...)`` (behind ``EXCLUDE_IF_NONE``).
     "pydantic>=2.12",
     # The ``asyncio`` extra pulls in ``greenlet``: ``sqlmodel_ext.session`` imports
     # ``sqlalchemy.ext.asyncio`` at module level, and SQLAlchemy 2.1 made greenlet optional.