sqlmodel-ext 0.3.5__tar.gz → 0.4.0__tar.gz

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.3.5
+Version: 0.4.0
 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
@@ -1402,18 +1402,42 @@ class UserUpdateRequest(UserBase, all_fields_optional=True):
 
 ---
 
-### safe_reset
+### Enhanced AsyncSession (cache-aware commit/reset/refresh)
 
-Safely reset an async session, clearing both the DB connection and FOR UPDATE lock tracking:
+`sqlmodel_ext.AsyncSession` subclasses sqlmodel's `AsyncSession` and makes cache
+correctness automatic. Point your session factory at it:
 
 ```python
-from sqlmodel_ext import safe_reset
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel_ext import AsyncSession
 
-# In long-lived tasks (e.g. background workers) between operations:
-await safe_reset(session)
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=True)
 ```
 
-This prevents stale `FOR UPDATE` lock tracking in `session.info` when Python reuses object IDs across `reset()` cycles.
+What it does:
+
+- **`commit()`** auto-registers every `CachedTableBaseMixin` mutation in the
+  session (including bare `session.add()` / attribute mutation /
+  `session.delete()` paths) and synchronously invalidates the Redis cache after
+  commit — no more "forgot the cache-aware commit" stale windows.
+- **`reset()`** releases the connection and clears FOR UPDATE lock tracking +
+  cache-invalidation tracking from `session.info` (replaces the removed
+  `safe_reset()` helper — just call `await session.reset()`).
+- **`refresh()`** routes whole-object refreshes of cached models through
+  `Model.get()` (Redis hit + STI polymorphic columns) instead of a raw DB query.
+- **`execute()`** warns when a bare `UPDATE`/`DELETE` hits a cached table
+  without registered invalidation.
+
+Models that don't use `CachedTableBaseMixin` are unaffected — every hook
+degrades to upstream behavior.
+
+> **Breaking change in 0.4.0**: `safe_reset()` and
+> `CachedTableBaseMixin.cache_aware_commit()` were removed. CRUD methods no
+> longer invalidate the cache themselves; invalidation now happens inside
+> `AsyncSession.commit()`. If you use `CachedTableBaseMixin`, you **must**
+> construct sessions with `class_=sqlmodel_ext.AsyncSession` (plain sessions
+> fall back to the fire-and-forget `after_commit` compensation hook, which
+> reintroduces a brief stale-cache window).
 
 ---
 
@@ -1430,7 +1454,7 @@ sqlmodel_ext/
     pagination.py            # ListResponse, TimeFilterRequest, PaginationRequest, TableViewRequest
     mixins/
         __init__.py          # Mixin re-exports
-        table.py             # TableBaseMixin, UUIDTableBaseMixin, safe_reset (async CRUD)
+        table.py             # TableBaseMixin, UUIDTableBaseMixin (async CRUD)
         cached_table.py      # CachedTableBaseMixin (two-tier Redis cache with version invalidation)
         polymorphic.py       # PolymorphicBaseMixin, AutoPolymorphicIdentityMixin, create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin, OptimisticLockError

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/README.md

@@ -1357,18 +1357,42 @@ class UserUpdateRequest(UserBase, all_fields_optional=True):
 
 ---
 
-### safe_reset
+### Enhanced AsyncSession (cache-aware commit/reset/refresh)
 
-Safely reset an async session, clearing both the DB connection and FOR UPDATE lock tracking:
+`sqlmodel_ext.AsyncSession` subclasses sqlmodel's `AsyncSession` and makes cache
+correctness automatic. Point your session factory at it:
 
 ```python
-from sqlmodel_ext import safe_reset
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel_ext import AsyncSession
 
-# In long-lived tasks (e.g. background workers) between operations:
-await safe_reset(session)
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=True)
 ```
 
-This prevents stale `FOR UPDATE` lock tracking in `session.info` when Python reuses object IDs across `reset()` cycles.
+What it does:
+
+- **`commit()`** auto-registers every `CachedTableBaseMixin` mutation in the
+  session (including bare `session.add()` / attribute mutation /
+  `session.delete()` paths) and synchronously invalidates the Redis cache after
+  commit — no more "forgot the cache-aware commit" stale windows.
+- **`reset()`** releases the connection and clears FOR UPDATE lock tracking +
+  cache-invalidation tracking from `session.info` (replaces the removed
+  `safe_reset()` helper — just call `await session.reset()`).
+- **`refresh()`** routes whole-object refreshes of cached models through
+  `Model.get()` (Redis hit + STI polymorphic columns) instead of a raw DB query.
+- **`execute()`** warns when a bare `UPDATE`/`DELETE` hits a cached table
+  without registered invalidation.
+
+Models that don't use `CachedTableBaseMixin` are unaffected — every hook
+degrades to upstream behavior.
+
+> **Breaking change in 0.4.0**: `safe_reset()` and
+> `CachedTableBaseMixin.cache_aware_commit()` were removed. CRUD methods no
+> longer invalidate the cache themselves; invalidation now happens inside
+> `AsyncSession.commit()`. If you use `CachedTableBaseMixin`, you **must**
+> construct sessions with `class_=sqlmodel_ext.AsyncSession` (plain sessions
+> fall back to the fire-and-forget `after_commit` compensation hook, which
+> reintroduces a brief stale-cache window).
 
 ---
 
@@ -1385,7 +1409,7 @@ sqlmodel_ext/
     pagination.py            # ListResponse, TimeFilterRequest, PaginationRequest, TableViewRequest
     mixins/
         __init__.py          # Mixin re-exports
-        table.py             # TableBaseMixin, UUIDTableBaseMixin, safe_reset (async CRUD)
+        table.py             # TableBaseMixin, UUIDTableBaseMixin (async CRUD)
         cached_table.py      # CachedTableBaseMixin (two-tier Redis cache with version invalidation)
         polymorphic.py       # PolymorphicBaseMixin, AutoPolymorphicIdentityMixin, create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin, OptimisticLockError

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/README_zh.md

@@ -1288,15 +1288,28 @@ class ArticleUpdateRequest(ArticleBase, all_fields_optional=True):
 
 ---
 
-### safe_reset
+### 增强 AsyncSession（缓存感知 commit/reset/refresh）
 
-安全重置异步会话，同时清理 FOR UPDATE 锁跟踪：
+`sqlmodel_ext.AsyncSession` 是 sqlmodel `AsyncSession` 的增强子类，把缓存正确性变为自动行为。把 session 工厂指向它：
 
 ```python
-from sqlmodel_ext import safe_reset
-await safe_reset(session)
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel_ext import AsyncSession
+
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=True)
 ```
 
+能力：
+
+- **`commit()`** 自动登记 session 中所有 `CachedTableBaseMixin` 变更（含裸 `session.add()` / 改属性 / `session.delete()` 路径），commit 后同步失效 Redis 缓存——消除"忘记 cache-aware commit"的 stale 窗口。
+- **`reset()`** 释放连接并清理 `session.info` 中的 FOR UPDATE 锁跟踪 + 缓存失效跟踪（替代已删除的 `safe_reset()`——直接 `await session.reset()` 即可）。
+- **`refresh()`** 对缓存模型的整体刷新走 `Model.get()`（Redis 命中 + STI 多态列），而非裸查 DB。
+- **`execute()`** 对绕过缓存失效的裸 `UPDATE`/`DELETE` 打 WARNING。
+
+不使用 `CachedTableBaseMixin` 的模型完全不受影响——所有钩子退化为上游行为。
+
+> **0.4.0 Breaking change**：`safe_reset()` 与 `CachedTableBaseMixin.cache_aware_commit()` 已删除。CRUD 方法不再自行失效缓存，失效统一发生在 `AsyncSession.commit()` 内。使用 `CachedTableBaseMixin` 时**必须**以 `class_=sqlmodel_ext.AsyncSession` 构造 session（普通 session 会退化为 fire-and-forget 的 `after_commit` 补偿钩子，重新引入短暂的 stale 窗口）。
+
 ---
 
 ## 架构
@@ -1312,7 +1325,7 @@ sqlmodel_ext/
     pagination.py            # ListResponse、TimeFilterRequest、PaginationRequest、TableViewRequest
     mixins/
         __init__.py          # Mixin 重导出
-        table.py             # TableBaseMixin、UUIDTableBaseMixin、safe_reset（异步 CRUD）
+        table.py             # TableBaseMixin、UUIDTableBaseMixin（异步 CRUD）
         cached_table.py      # CachedTableBaseMixin（双层 Redis 缓存 + 版本号失效）
         polymorphic.py       # PolymorphicBaseMixin、AutoPolymorphicIdentityMixin、create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin、OptimisticLockError

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/en/how-to/index.md

@@ -20,7 +20,7 @@
 
 - [Handle concurrent updates](./handle-concurrent-updates) — Use `OptimisticLockMixin` to prevent lost updates
 - [Prevent MissingGreenlet errors](./prevent-missing-greenlet) — `@requires_relations` + `lazy='raise_on_sql'` + static analysis: three layers of defense
-- [Release the DB connection during long I/O](./release-connection-during-long-io) — Use `safe_reset()` to keep external I/O from exhausting the pool
+- [Release the DB connection during long I/O](./release-connection-during-long-io) — Use `session.reset()` to keep external I/O from exhausting the pool
 
 ### Performance
 

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/en/how-to/release-connection-during-long-io.md

@@ -28,11 +28,11 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
     return file
 ```
 
-## 2. Use `safe_reset()` around the I/O block
+## 2. Use `session.reset()` around the I/O block
 
-```python
-from sqlmodel_ext import safe_reset
+> Since 0.4.0 `safe_reset()` has been removed -- its responsibility moved into the enhanced `sqlmodel_ext.AsyncSession.reset()` (construct sessions with `async_sessionmaker(class_=AsyncSession)`). `reset()` releases the connection and also clears FOR UPDATE lock tracking and cache-invalidation tracking.
 
+```python
 @router.get("/files/{file_id}")
 async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
     file = await UserFile.get(session, UserFile.id == file_id)
@@ -42,7 +42,7 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
         key = file.key
         file_id = file.id
 
-        await safe_reset(session)  # ← release the DB connection // [!code ++]
+        await session.reset()  # ← release the DB connection // [!code ++]
 
         # ↓ This block holds NO DB connection — concurrent requests can use the pool
         data = await s3.download_file(bucket_id, key)
@@ -56,26 +56,26 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
 ```
 
 **Key points**:
-- `safe_reset` releases the current transaction and connection, but the session object itself stays alive (it's not closed)
+- `session.reset()` releases the current transaction and connection, but the session object itself stays alive (it's not closed)
 - Any subsequent `await Model.get/save` that issues SQL transparently checks out a new connection from the pool
 - During the released window all 30 connections are idle (unless other requests use them) — concurrent requests **are not stalled**
 
-## 3. Object state after `safe_reset`: detached but not expired
+## 3. Object state after `session.reset()`: detached but not expired
 
-After `safe_reset`, every ORM object in the session enters the **detached** state (no longer in `session.identity_map`), but **already-loaded scalar fields remain in `obj.__dict__`** — accessing them does not trigger a SQL query, so it does **not** raise `MissingGreenlet`.
+After `session.reset()`, every ORM object in the session enters the **detached** state (no longer in `session.identity_map`), but **already-loaded scalar fields remain in `obj.__dict__`** — accessing them does not trigger a SQL query, so it does **not** raise `MissingGreenlet`.
 
 ```python
 from sqlalchemy import inspect as sa_inspect
 
-# Before safe_reset:
+# Before reset:
 file = await UserFile.get(session, UserFile.id == fid)
 print(sa_inspect(file).detached)  # False
 print(sa_inspect(file).expired)   # False
 print(file.bucket_id)             # OK, loaded
 
-await safe_reset(session)
+await session.reset()
 
-# After safe_reset:
+# After reset:
 print(sa_inspect(file).detached)  # True  ← note // [!code highlight]
 print(sa_inspect(file).expired)   # False ← loaded fields are NOT expired // [!code highlight]
 print(file.bucket_id)             # OK! scalar field access is safe // [!code ++]
@@ -84,7 +84,7 @@ print(file.parent)                # InvalidRequestError or MissingGreenlet // [!
 
 ### Safe-access rules
 
-| Access | After safe_reset | Why |
+| Access | After session.reset() | Why |
 |--------|-----------------|-----|
 | Already-loaded scalar field | ✓ Safe | In `__dict__`, no DB query |
 | Already-loaded relation (preloaded via `load=`) | ✓ Safe | Same |
@@ -93,7 +93,7 @@ print(file.parent)                # InvalidRequestError or MissingGreenlet // [!
 
 ### Recommended style
 
-When writing the code that runs **before** `safe_reset`, extract any field you'll need later into local variables:
+When writing the code that runs **before** `session.reset()`, extract any field you'll need later into local variables:
 
 ```python
 # Recommended:
@@ -102,7 +102,7 @@ bucket_id = file.bucket_id
 key = file.key
 user_id = file.user_id
 
-await safe_reset(session)
+await session.reset()
 
 # The code below uses local variables (file_id / bucket_id / ...),
 # never touches file.X again.
@@ -112,10 +112,10 @@ This way, even if some field on the model becomes lazy-loaded in the future, the
 
 ## 4. You must re-query before writing
 
-After `safe_reset` the object is detached and **cannot be saved directly**. To write, re-query a fresh attached instance:
+After `session.reset()` the object is detached and **cannot be saved directly**. To write, re-query a fresh attached instance:
 
 ```python
-await safe_reset(session)
+await session.reset()
 
 # Long I/O...
 metadata = await fetch_external_metadata(...)
@@ -130,15 +130,15 @@ file.metadata = metadata
 await file.save(session)
 ```
 
-## 5. When to use safe_reset vs Taskiq dispatch
+## 5. When to use session.reset() vs Taskiq dispatch
 
-`safe_reset` fits when you **must** synchronously return a result to the client. If your business can tolerate async — dispatch a job, return immediately, let the client poll — use Taskiq instead and **don't do long I/O in the HTTP endpoint at all**.
+`session.reset()` fits when you **must** synchronously return a result to the client. If your business can tolerate async — dispatch a job, return immediately, let the client poll — use Taskiq instead and **don't do long I/O in the HTTP endpoint at all**.
 
 ```mermaid
 flowchart TD
     A["Need long I/O in the endpoint?"] --> B{Can the response wait until the next poll?}
     B -- Yes --> C["Dispatch a Taskiq task<br/>return status=pending immediately"]
-    B -- No --> D["safe_reset to release connection<br/>execute the long I/O synchronously"]
+    B -- No --> D["session.reset() to release connection<br/>execute the long I/O synchronously"]
     C --> E["Cleanest, holds zero connection time"]
     D --> F["Pool is usable during the released window<br/>but still occupies a worker coroutine"]
 ```
@@ -147,7 +147,7 @@ flowchart TD
 |----------|-------------|
 | Polling for upload status | Taskiq (the polling client picks up the state change) |
 | AI generation tasks (image/video) | Taskiq (the project's mainstream pattern) |
-| Synchronous response that must contain the full result (e.g. PDF export) | safe_reset |
+| Synchronous response that must contain the full result (e.g. PDF export) | session.reset() |
 | WebSocket long connections | `session.close()` + per-message short-lived sessions |
 
 ## 6. Verification: did your endpoint actually release the connection?
@@ -169,13 +169,13 @@ def _on_checkin(conn, rec):
 
 Trigger a request that hits the long-I/O path. You should see:
 1. `checkout 1/N` — endpoint starts
-2. `checkin 0/N` — safe_reset fires
+2. `checkin 0/N` — session.reset() fires
 3. 30 seconds of external I/O with no checkout log in between
 4. `checkout 1/N` — subsequent DB op
 5. `checkin 0/N` — endpoint cleanup
 
 ## 7. Related
 
-- [`safe_reset()` API reference](/en/reference/decorators#safe-reset)
+- [`session.reset()` API reference](/en/reference/decorators#session-reset)
 - [Integrate with FastAPI](./integrate-with-fastapi)
 - [Prevent MissingGreenlet](./prevent-missing-greenlet)

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/en/index.md

@@ -34,3 +34,12 @@ features:
   - title: Safe & Reliable
     details: Optimistic locking for concurrency control, @requires_relations to prevent MissingGreenlet, and AST static analysis at startup
 ---
+
+## Design orientation
+
+sqlmodel-ext is not a new ORM. It is a set of **opt-in Mixins** layered on top of SQLModel / Pydantic v2 / SQLAlchemy 2.0. The library only introduces two kinds of machinery:
+
+- **Metaclass enhancements** — automatic SQLAlchemy column setup driven by `Annotated` type hints, `mapper_args` merging, on-demand `*UpdateRequest` DTO generation, attribute-docstring inheritance, and a Python 3.14 (PEP 649) compatibility patch.
+- **Composable Mixins** — `TableBaseMixin` (async CRUD), `PolymorphicBaseMixin` (JTI/STI), `OptimisticLockMixin` (version-column concurrency), `RelationPreloadMixin` (eager loading), `CachedTableBaseMixin` (Redis two-tier cache). Each Mixin stands alone and has no hard dependency on the others.
+
+The underlying `Session`, `select()`, query construction, and migration tooling remain native SQLAlchemy — there is no custom DSL, and the library does not take over `engine` / `session` lifecycle. In practice that means you can drop a single Mixin into an existing SQLModel/SQLAlchemy project without rewriting your data-access layer.

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/en/reference/decorators.md

@@ -113,21 +113,23 @@ scope = cond(UserFile.user_id == current_user.id)
 condition = scope & cond(UserFile.status == FileStatusEnum.uploaded)
 ```
 
-## `safe_reset()`
+## `session.reset()` (enhanced AsyncSession) {#session-reset}
 
 ```python
-from sqlmodel_ext import safe_reset
+from sqlmodel_ext import AsyncSession
 ```
 
-**Signature**:
+**Signature** (enhanced method on `sqlmodel_ext.session.AsyncSession`):
 
 ```python
-async def safe_reset(session: AsyncSession) -> None
+async def reset(self) -> None
 ```
 
-**Purpose**: clears the FOR UPDATE lock tracking set in `session.info[SESSION_FOR_UPDATE_KEY]` before calling `session.reset()`. Safer than calling `session.reset()` directly — prevents the lock-tracking set from leaking into the next session reuse cycle.
+> Replaces the removed `safe_reset()` helper since 0.4.0. Construct sessions with `async_sessionmaker(class_=AsyncSession)` and simply `await session.reset()`.
+
+**Purpose**: after the upstream `reset()` (releasing the transaction and connection), automatically clears the FOR UPDATE lock-tracking set in `session.info[SESSION_FOR_UPDATE_KEY]` and the cache-invalidation tracking state — preventing tracking state from leaking into the next session reuse cycle.
 
-**Typical use case**: an HTTP endpoint / Taskiq task needs to do long external I/O mid-flight (S3, ffprobe, third-party HTTP polling, etc.). Call `safe_reset` first to release the DB connection, so the connection isn't blocked on network I/O and the pool isn't exhausted. See [Release the DB connection during long I/O](/en/how-to/release-connection-during-long-io).
+**Typical use case**: an HTTP endpoint / Taskiq task needs to do long external I/O mid-flight (S3, ffprobe, third-party HTTP polling, etc.). Call `session.reset()` first to release the DB connection, so the connection isn't blocked on network I/O and the pool isn't exhausted. See [Release the DB connection during long I/O](/en/how-to/release-connection-during-long-io).
 
 **Object state after the call**:
 

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/en/reference/field-types.md

@@ -30,10 +30,27 @@ from sqlmodel_ext import Str16, Str24, Str32, Str36, Str48, Str64, Str100, Str12
 | `Str512` | 512 | same form |
 | `Str2048` | 2048 | same form |
 
+### Non-empty & special-purpose strings
+
+```python
+from sqlmodel_ext import (
+    NonEmptyStr64, NonEmptyStr128, NonEmptyStr256,
+    NonEmptyStrippedStr64, NonEmptyStrippedStr128, NonEmptyStrippedStr256,
+    Sha256Hex, BCP47LanguageCode,
+)
+```
+
+| Type | Constraint |
+|------|-----------|
+| `NonEmptyStr64/128/256` | `1 <= len <= N`, rejects empty `""` |
+| `NonEmptyStrippedStr64/128/256` | same + `strip_whitespace`, rejects whitespace-only (`"   "` / `"\t"`) |
+| `Sha256Hex` | exactly 64 lowercase hex chars (SHA-256 digest) |
+| `BCP47LanguageCode` | BCP-47 language tag syntax (e.g. `zh-Hans-CN`), `max_length=16` |
+
 ## Text constraints
 
 ```python
-from sqlmodel_ext import Text1K, Text1024, Text2K, Text2500, Text3K, Text5K, Text10K, Text32K, Text60K, Text64K, Text100K, Text1M
+from sqlmodel_ext import Text1K, Text1024, Text2K, Text2500, Text3K, Text5K, Text8K, Text10K, Text16K, Text32K, Text48K, Text60K, Text64K, Text100K, Text128K, Text1M
 ```
 
 | Type | `max_length` |
@@ -44,11 +61,15 @@ from sqlmodel_ext import Text1K, Text1024, Text2K, Text2500, Text3K, Text5K, Tex
 | `Text2500` | 2500 |
 | `Text3K` | 3000 |
 | `Text5K` | 5000 |
+| `Text8K` | 8000 |
 | `Text10K` | 10000 |
+| `Text16K` | 16000 |
 | `Text32K` | 32000 |
+| `Text48K` | 48000 |
 | `Text60K` | 60000 |
 | `Text64K` | 65536 |
 | `Text100K` | 100000 |
+| `Text128K` | 131072 (= 128 × 1024) |
 | `Text1M` | 1000000 |
 
 ## Numeric constraints
@@ -89,6 +110,42 @@ from sqlmodel_ext import INT32_MAX, INT64_MAX, JS_MAX_SAFE_INTEGER
 | `INT64_MAX` | `9_223_372_036_854_775_807` (2⁶³−1) |
 | `JS_MAX_SAFE_INTEGER` | `9_007_199_254_740_991` (2⁵³−1) |
 
+## Decimal constraints (new in 0.4.0)
+
+```python
+from sqlmodel_ext import (
+    SignedDecimal38_18, NonNegativeDecimal38_18, PositiveDecimal38_18, OptionalNonNegativeDecimal38_18,
+    SignedDecimal20_10, NonNegativeDecimal20_10, OptionalNonNegativeDecimal20_10,
+)
+```
+
+Naming convention: `[Optional][Signed|NonNegative|Positive]Decimal{precision}_{scale}`, mapping to a `NUMERIC(precision, scale)` database column.
+
+| Type | Sign | Database column |
+|------|------|------------------|
+| `SignedDecimal38_18` | any | `NUMERIC(38, 18)` |
+| `NonNegativeDecimal38_18` | `>= 0` | `NUMERIC(38, 18)` |
+| `PositiveDecimal38_18` | `> 0` | `NUMERIC(38, 18)` |
+| `OptionalNonNegativeDecimal38_18` | `>= 0` or `None` | `NUMERIC(38, 18)` |
+| `SignedDecimal20_10` | any | `NUMERIC(20, 10)` |
+| `NonNegativeDecimal20_10` | `>= 0` | `NUMERIC(20, 10)` |
+| `OptionalNonNegativeDecimal20_10` | `>= 0` or `None` | `NUMERIC(20, 10)` |
+
+Behavioral contract:
+
+- **Rejects float / bool input** (precision already lost via IEEE 754) — accepts `Decimal` / `int` / `str`
+- **Serializes to a fixed-point JSON string** (`model_dump_json()`): never scientific notation (`0E-18` → `'0'`), trailing zeros stripped (`1200.000...0` → `'1200'`) — protects JS clients from Number precision loss
+- **dict mode keeps the `Decimal` object** (`model_dump()`)
+- The `Optional*` variants nest their constraints in the inner `Annotated`, so JSON `null` parses safely
+
+## Bounded-length list aliases (new in 0.4.0)
+
+```python
+from sqlmodel_ext import List, List1, List2, List3, List7, List10, List16, List20, List32, List40, List50, List64, List100, List128, List200, List256, List1024
+```
+
+`List<N>[T]` is equivalent to `Annotated[list[T], Field(max_length=N)]` — the max length is encoded in the type name (consistent with `Str64` / `Text1K`). `List[T]` (no number) is equivalent to `list[T]`. Intended for request DTOs / protocol layers, unrelated to the PG `Array[T]` column type.
+
 ## URL types
 
 ```python

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/en/reference/index.md

@@ -28,7 +28,7 @@ from sqlmodel_ext import (
 | [CRUD methods](./crud-methods) | Full signatures for `add` / `save` / `update` / `delete` / `get` / `get_one` / `get_exist_one` / `count` / `get_with_count` |
 | [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()`, `safe_reset()` |
+| [Decorators & helpers](./decorators) | `@requires_relations`, `@requires_for_update`, `rel()`, `cond()`, enhanced `session.reset()` |
 | [Pagination types](./pagination-types) | `ListResponse[T]`, `TableViewRequest`, `PaginationRequest`, `TimeFilterRequest` |
 
 ## Constants

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/en/tutorials/01-getting-started.md

@@ -8,7 +8,7 @@ This is your first conversation with sqlmodel-ext. In 15 minutes you'll have:
 - A clear mental model for "model + Mixin = table"
 
 ::: tip You don't need prior SQLAlchemy or SQLModel experience
-This tutorial introduces those concepts on demand. You only need Python 3.10+ and basic `async` / `await` knowledge. If you've never touched an ORM, skim [Prerequisites](/en/explanation/prerequisites) first.
+This tutorial introduces those concepts on demand. You only need Python 3.12+ and basic `async` / `await` knowledge. If you've never touched an ORM, skim [Prerequisites](/en/explanation/prerequisites) first.
 :::
 
 ## 0. Set up the environment

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/en/tutorials/index.md

@@ -25,7 +25,7 @@ Tutorials don't **exhaustively cover the API**. If a feature you need is missing
 
 All tutorials assume you know:
 
-- Python 3.10+
+- Python 3.12+ (3.12 / 3.13 / 3.14 are all exercised in CI)
 - Basic `async` / `await` syntax
 - What SELECT / INSERT / UPDATE / DELETE do in SQL
 

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/how-to/index.md

@@ -20,7 +20,7 @@
 
 - [处理并发更新](./handle-concurrent-updates) — 用 `OptimisticLockMixin` 防止丢失更新
 - [防止 MissingGreenlet 错误](./prevent-missing-greenlet) — `@requires_relations` + `lazy='raise_on_sql'` + 静态分析三道防线
-- [长 I/O 期间释放数据库连接](./release-connection-during-long-io) — 用 `safe_reset()` 防连接池被外部 I/O 拖死
+- [长 I/O 期间释放数据库连接](./release-connection-during-long-io) — 用 `session.reset()` 防连接池被外部 I/O 拖死
 
 ### 性能优化
 

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/how-to/release-connection-during-long-io.md

@@ -28,11 +28,11 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
     return file
 ```
 
-## 2. 用 `safe_reset()` 在 I/O 前后释放连接
+## 2. 用 `session.reset()` 在 I/O 前后释放连接
 
-```python
-from sqlmodel_ext import safe_reset
+> 0.4.0 起 `safe_reset()` 已删除——其职责并入增强版 `sqlmodel_ext.AsyncSession.reset()`（用 `async_sessionmaker(class_=AsyncSession)` 构造 session），`reset()` 在释放连接的同时自动清理 FOR UPDATE 锁跟踪和缓存失效跟踪。
 
+```python
 @router.get("/files/{file_id}")
 async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
     file = await UserFile.get(session, UserFile.id == file_id)
@@ -42,7 +42,7 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
         key = file.key
         file_id = file.id
 
-        await safe_reset(session)  # ← 释放 DB 连接 // [!code ++]
+        await session.reset()  # ← 释放 DB 连接 // [!code ++]
 
         # ↓ 下面这段不持有 DB 连接，并发请求可以拿到连接
         data = await s3.download_file(bucket_id, key)
@@ -56,26 +56,26 @@ async def get_file(session: SessionDep, s3: S3APIClientDep, file_id: UUID):
 ```
 
 **关键点**：
-- `safe_reset` 释放当前事务和 connection，但 session 对象本身仍存活（不是 close）
+- `session.reset()` 释放当前事务和 connection，但 session 对象本身仍存活（不是 close）
 - 后续任何 `await Model.get/save` 触发 SQL 时会自动从池 checkout 新连接
 - 释放期间池有 30 个连接全部空闲（除非别的请求占用），**并发请求不会被拖死**
 
-## 3. `safe_reset` 后对象的状态：detached 但不 expired
+## 3. `session.reset()` 后对象的状态：detached 但不 expired
 
-调用 `safe_reset` 后，session 中所有 ORM 对象进入 **detached** 状态（不在 `session.identity_map` 中），但**已加载的 scalar 字段仍在 `obj.__dict__`** —— 访问它们不会触发 SQL 查询，因此**不会抛 `MissingGreenlet`**。
+调用 `session.reset()` 后，session 中所有 ORM 对象进入 **detached** 状态（不在 `session.identity_map` 中），但**已加载的 scalar 字段仍在 `obj.__dict__`** —— 访问它们不会触发 SQL 查询，因此**不会抛 `MissingGreenlet`**。
 
 ```python
 from sqlalchemy import inspect as sa_inspect
 
-# Before safe_reset:
+# Before reset:
 file = await UserFile.get(session, UserFile.id == fid)
 print(sa_inspect(file).detached)  # False
 print(sa_inspect(file).expired)   # False
 print(file.bucket_id)             # OK，已加载
 
-await safe_reset(session)
+await session.reset()
 
-# After safe_reset:
+# After reset:
 print(sa_inspect(file).detached)  # True  ← 注意 // [!code highlight]
 print(sa_inspect(file).expired)   # False ← 已加载字段没被 expire // [!code highlight]
 print(file.bucket_id)             # OK！scalar 字段访问安全 // [!code ++]
@@ -84,7 +84,7 @@ print(file.parent)                # InvalidRequestError 或 MissingGreenlet // [
 
 ### 安全访问规则
 
-| 访问类型 | safe_reset 后 | 说明 |
+| 访问类型 | session.reset() 后 | 说明 |
 |----------|--------------|------|
 | 已加载的 scalar 字段 | ✓ 安全 | 在 `__dict__` 中，无需 DB 查询 |
 | 已加载的关系（`load=` 预加载过） | ✓ 安全 | 同上 |
@@ -93,7 +93,7 @@ print(file.parent)                # InvalidRequestError 或 MissingGreenlet // [
 
 ### 实操建议
 
-写到 safe_reset 前的代码时，把后面要用到的字段**提前提取到局部变量**：
+写到 session.reset() 前的代码时，把后面要用到的字段**提前提取到局部变量**：
 
 ```python
 # 推荐风格：
@@ -102,7 +102,7 @@ bucket_id = file.bucket_id
 key = file.key
 user_id = file.user_id
 
-await safe_reset(session)
+await session.reset()
 
 # 后面的代码用 file_id / bucket_id 等局部变量，
 # 永远不要碰 file.X
@@ -112,10 +112,10 @@ await safe_reset(session)
 
 ## 4. 写操作前必须重新查询
 
-`safe_reset` 后对象处于 detached 状态，**不能直接 save**。需要写操作的话，重新查询拿到 attached 实例：
+`session.reset()` 后对象处于 detached 状态，**不能直接 save**。需要写操作的话，重新查询拿到 attached 实例：
 
 ```python
-await safe_reset(session)
+await session.reset()
 
 # 长 I/O ...
 metadata = await fetch_external_metadata(...)
@@ -130,15 +130,15 @@ file.metadata = metadata
 await file.save(session)
 ```
 
-## 5. 什么时候用 safe_reset，什么时候用 Taskiq
+## 5. 什么时候用 session.reset()，什么时候用 Taskiq
 
-`safe_reset` 适合"必须同步返回结果给客户端"的场景。如果业务可以接受异步——派发任务 + 立即返回 + 客户端轮询——那应该用 Taskiq，**根本不在 HTTP 端点里做长 I/O**。
+`session.reset()` 适合"必须同步返回结果给客户端"的场景。如果业务可以接受异步——派发任务 + 立即返回 + 客户端轮询——那应该用 Taskiq，**根本不在 HTTP 端点里做长 I/O**。
 
 ```mermaid
 flowchart TD
     A["端点中需要长 I/O？"] --> B{响应能延后到下次轮询吗？}
     B -- 可以 --> C["派发 Taskiq 任务<br/>立即返回 status=pending"]
-    B -- 不能 --> D["safe_reset 释放连接<br/>同步执行长 I/O"]
+    B -- 不能 --> D["session.reset() 释放连接<br/>同步执行长 I/O"]
     C --> E["最干净，连接零持有"]
     D --> F["连接释放期间池可用<br/>仍占 1 个 worker 协程"]
 ```
@@ -147,7 +147,7 @@ flowchart TD
 |------|---------|
 | 文件上传后状态轮询 | Taskiq（前端轮询能感知状态变更）|
 | AI 生成任务（图片/视频） | Taskiq（项目主流模式）|
-| 同步必须返回完整结果（如导出 PDF）| safe_reset |
+| 同步必须返回完整结果（如导出 PDF）| session.reset() |
 | WebSocket 长连接 | 用 `session.close()` + 短生命周期 session（每次消息处理一个 session） |
 
 ## 6. 验证：你的端点真的释放了连接吗？
@@ -169,13 +169,13 @@ def _on_checkin(conn, rec):
 
 跑一个能触发长 I/O 的请求，应该看到：
 1. `checkout 1/N` 端点开始
-2. `checkin 0/N` safe_reset 触发
+2. `checkin 0/N` session.reset() 触发
 3. 30 秒外部 I/O，期间没有 checkout 日志
 4. `checkout 1/N` 后续 DB 操作触发
 5. `checkin 0/N` 端点 cleanup
 
 ## 7. 相关参考
 
-- [`safe_reset()` API 参考](/reference/decorators#safe-reset)
+- [`session.reset()` API 参考](/reference/decorators#session-reset)
 - [集成 FastAPI](./integrate-with-fastapi)
 - [防止 MissingGreenlet 错误](./prevent-missing-greenlet)

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.0}/docs/index.md

@@ -34,3 +34,12 @@ features:
   - title: 安全与可靠
     details: 乐观锁并发控制、@requires_relations 防止 MissingGreenlet、启动时 AST 静态分析
 ---
+
+## 设计取向
+
+sqlmodel-ext 不是新的 ORM，而是构建在 SQLModel / Pydantic v2 / SQLAlchemy 2.0 之上的一组**可单独取用的 Mixin**。库本身只引入两类东西：
+
+- **元类增强**——根据 `Annotated` 类型注解自动设置 SQLAlchemy 列、合并 `mapper_args`、按需生成 `*UpdateRequest` DTO、保留属性 docstring，并打上 Python 3.14 (PEP 649) 兼容补丁。
+- **可插拔 Mixin**——`TableBaseMixin`（异步 CRUD）、`PolymorphicBaseMixin`（JTI/STI）、`OptimisticLockMixin`（版本号并发）、`RelationPreloadMixin`（关系预加载）、`CachedTableBaseMixin`（Redis 双层缓存）。每个 Mixin 都可以独立使用，不互相依赖。
+
+底层 `Session`、`select()`、查询构造、迁移工具仍是原生 SQLAlchemy，没有自创 DSL，也不接管 `engine`/`session` 的生命周期。换句话说：在已有 SQLModel/SQLAlchemy 项目里，可以单独引入需要的 Mixin，而不必重写既有数据访问层。