sqlmodel-ext 0.2.1__tar.gz → 0.3.0__tar.gz

{sqlmodel_ext-0.2.1 → sqlmodel_ext-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.2.1
+Version: 0.3.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
@@ -25,6 +25,9 @@ Requires-Python: >=3.12
 Requires-Dist: pydantic>=2.0
 Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: sqlmodel>=0.0.22
+Provides-Extra: cache
+Requires-Dist: orjson>=3.0; extra == 'cache'
+Requires-Dist: redis>=5.0; extra == 'cache'
 Provides-Extra: dev
 Requires-Dist: aiosqlite>=0.20; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
@@ -58,8 +61,9 @@ Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphi
 
 | Feature | Description |
 |---------|-------------|
-| **SQLModelBase** | Smart metaclass with automatic `table=True`, `mapper_args` merging, and Python 3.14 (PEP 649) compatibility |
+| **SQLModelBase** | Smart metaclass with automatic `table=True`, `mapper_args` merging, `all_fields_optional` for UpdateRequest DTOs, attribute docstring inheritance, and Python 3.14 (PEP 649) compatibility |
 | **TableBaseMixin / UUIDTableBaseMixin** | Full async CRUD: `add()`, `save()`, `update()`, `delete()`, `get()`, `count()`, `get_with_count()`, `get_exist_one()` |
+| **CachedTableBaseMixin** | Two-tier Redis cache (ID + query) with version-based invalidation, STI-aware cascade, and optional metrics callbacks |
 | **PolymorphicBaseMixin** | Simplified Joined Table Inheritance (JTI) and Single Table Inheritance (STI) |
 | **AutoPolymorphicIdentityMixin** | Auto-generated `polymorphic_identity` from class names |
 | **OptimisticLockMixin** | Version-based optimistic locking with automatic retry |
@@ -87,6 +91,12 @@ With PostgreSQL ARRAY and JSONB types (requires `orjson`):
 pip install sqlmodel-ext[postgresql]
 ```
 
+With Redis caching support (enables `CachedTableBaseMixin`):
+
+```bash
+pip install sqlmodel-ext[cache]
+```
+
 With pgvector + NumPy vector support (includes `[postgresql]`):
 
 ```bash
@@ -1251,6 +1261,130 @@ These mixins define the fields as **required** (non-optional), because in API re
 
 ---
 
+### Redis Caching (CachedTableBaseMixin)
+
+Add a two-tier Redis cache to any table model. Queries go through Redis first; cache misses fall through to the database.
+
+```bash
+pip install sqlmodel-ext[cache]  # installs redis + orjson
+```
+
+**Setup (once at application startup):**
+
+```python
+from redis.asyncio import Redis
+from sqlmodel_ext import CachedTableBaseMixin
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=False)
+CachedTableBaseMixin.configure_redis(redis)
+```
+
+**Define a cached model:**
+
+```python
+class Character(CachedTableBaseMixin, CharacterBase, UUIDTableBaseMixin, table=True, cache_ttl=1800):
+    pass  # 30-minute cache TTL
+```
+
+That's it. All `get()` calls now check Redis first. Cache invalidation is automatic on `save()`, `update()`, and `delete()`.
+
+**Cache architecture:**
+
+| Layer | Key format | Invalidation |
+|-------|-----------|--------------|
+| ID cache | `id:{Model}:{id}` | Row-level DEL on save/update/delete |
+| Query cache | `query:{Model}:v{version}:{hash}` | Version bump (O(1) INCR) makes old keys unreachable |
+| Version | `ver:{Model}` | INCR on any write; STI subclass changes bump all ancestor versions |
+
+**Optional metrics callbacks:**
+
+```python
+CachedTableBaseMixin.on_cache_hit = lambda name: print(f"HIT: {name}")
+CachedTableBaseMixin.on_cache_miss = lambda name: print(f"MISS: {name}")
+```
+
+**Cache skip conditions** (automatically detected):
+- `no_cache=True` (explicit bypass)
+- `with_for_update=True` (pessimistic lock needs latest)
+- `join` is set (join target changes don't trigger invalidation)
+- `options` is set (custom loading options)
+
+**No Redis? No problem.** If you don't call `configure_redis()` and don't inherit `CachedTableBaseMixin`, there is zero Redis dependency. The caching layer is entirely opt-in.
+
+---
+
+### all_fields_optional
+
+Automatically convert all inherited fields to optional for PATCH/UpdateRequest DTOs:
+
+```python
+class ArticleBase(SQLModelBase):
+    title: Str64
+    """Article title"""
+    body: Text10K
+    """Article body"""
+    is_published: bool = False
+    """Publication status"""
+
+class ArticleUpdateRequest(ArticleBase, all_fields_optional=True):
+    pass
+    # All fields become: title: Str64 | None = None, body: Text10K | None = None, etc.
+    # Annotated constraints (max_length, ge, le) are preserved
+    # Attribute docstrings are inherited from ArticleBase
+```
+
+**What it does:**
+- Converts `T` to `T | None = None` for all inherited fields
+- Preserves `Annotated` metadata (e.g. `Field(ge=0)` constraints stay intact)
+- Skips `Literal` fields (discriminator fields must remain required)
+- Replaces `default_factory` with `default=None`
+
+**No more manual overrides** like this:
+
+```python
+# Before: tedious and error-prone
+class ArticleUpdateRequest(ArticleBase):
+    title: Str64 | None = None    # Must manually repeat type + optional
+    body: Text10K | None = None   # Easy to forget constraints
+    is_published: bool | None = None
+```
+
+---
+
+### Attribute Docstring Inheritance
+
+When using Pydantic's `use_attribute_docstrings=True` (enabled by default in `SQLModelBase`), field descriptions appear in OpenAPI schemas. However, Pydantic's AST-based docstring parser doesn't inherit descriptions when subclasses override fields.
+
+**sqlmodel-ext fixes this automatically.** The metaclass inherits missing descriptions from parent classes via MRO traversal, and `__get_pydantic_json_schema__` patches bare `$ref` properties to include descriptions.
+
+```python
+class UserBase(SQLModelBase):
+    name: str
+    """User display name"""     # ← parsed by Pydantic
+
+class UserUpdateRequest(UserBase, all_fields_optional=True):
+    pass
+    # name: str | None = None   — description "User display name" is automatically inherited
+    # Shows up correctly in OpenAPI/Swagger docs
+```
+
+---
+
+### safe_reset
+
+Safely reset an async session, clearing both the DB connection and FOR UPDATE lock tracking:
+
+```python
+from sqlmodel_ext import safe_reset
+
+# In long-lived tasks (e.g. background workers) between operations:
+await safe_reset(session)
+```
+
+This prevents stale `FOR UPDATE` lock tracking in `session.info` when Python reuses object IDs across `reset()` cycles.
+
+---
+
 ## Architecture
 
 ```
@@ -1264,7 +1398,8 @@ sqlmodel_ext/
     pagination.py            # ListResponse, TimeFilterRequest, PaginationRequest, TableViewRequest
     mixins/
         __init__.py          # Mixin re-exports
-        table.py             # TableBaseMixin, UUIDTableBaseMixin (async CRUD)
+        table.py             # TableBaseMixin, UUIDTableBaseMixin, safe_reset (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
         relation_preload.py  # RelationPreloadMixin, @requires_relations
@@ -1292,7 +1427,8 @@ sqlmodel_ext/
 - **pydantic** >= 2.0
 - **sqlalchemy** >= 2.0
 - (optional) **fastapi** >= 0.100.0
-- (optional) **orjson** >= 3.0 -- for `JSON100K` / `JSONList100K`
+- (optional) **redis** >= 5.0 -- for `CachedTableBaseMixin`
+- (optional) **orjson** >= 3.0 -- for `CachedTableBaseMixin` and `JSON100K` / `JSONList100K`
 - (optional) **numpy** >= 1.24 -- for `NumpyVector`
 - (optional) **pgvector** >= 0.3 -- for `NumpyVector`
 

{sqlmodel_ext-0.2.1 → sqlmodel_ext-0.3.0}/README.md

@@ -16,8 +16,9 @@ Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphi
 
 | Feature | Description |
 |---------|-------------|
-| **SQLModelBase** | Smart metaclass with automatic `table=True`, `mapper_args` merging, and Python 3.14 (PEP 649) compatibility |
+| **SQLModelBase** | Smart metaclass with automatic `table=True`, `mapper_args` merging, `all_fields_optional` for UpdateRequest DTOs, attribute docstring inheritance, and Python 3.14 (PEP 649) compatibility |
 | **TableBaseMixin / UUIDTableBaseMixin** | Full async CRUD: `add()`, `save()`, `update()`, `delete()`, `get()`, `count()`, `get_with_count()`, `get_exist_one()` |
+| **CachedTableBaseMixin** | Two-tier Redis cache (ID + query) with version-based invalidation, STI-aware cascade, and optional metrics callbacks |
 | **PolymorphicBaseMixin** | Simplified Joined Table Inheritance (JTI) and Single Table Inheritance (STI) |
 | **AutoPolymorphicIdentityMixin** | Auto-generated `polymorphic_identity` from class names |
 | **OptimisticLockMixin** | Version-based optimistic locking with automatic retry |
@@ -45,6 +46,12 @@ With PostgreSQL ARRAY and JSONB types (requires `orjson`):
 pip install sqlmodel-ext[postgresql]
 ```
 
+With Redis caching support (enables `CachedTableBaseMixin`):
+
+```bash
+pip install sqlmodel-ext[cache]
+```
+
 With pgvector + NumPy vector support (includes `[postgresql]`):
 
 ```bash
@@ -1209,6 +1216,130 @@ These mixins define the fields as **required** (non-optional), because in API re
 
 ---
 
+### Redis Caching (CachedTableBaseMixin)
+
+Add a two-tier Redis cache to any table model. Queries go through Redis first; cache misses fall through to the database.
+
+```bash
+pip install sqlmodel-ext[cache]  # installs redis + orjson
+```
+
+**Setup (once at application startup):**
+
+```python
+from redis.asyncio import Redis
+from sqlmodel_ext import CachedTableBaseMixin
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=False)
+CachedTableBaseMixin.configure_redis(redis)
+```
+
+**Define a cached model:**
+
+```python
+class Character(CachedTableBaseMixin, CharacterBase, UUIDTableBaseMixin, table=True, cache_ttl=1800):
+    pass  # 30-minute cache TTL
+```
+
+That's it. All `get()` calls now check Redis first. Cache invalidation is automatic on `save()`, `update()`, and `delete()`.
+
+**Cache architecture:**
+
+| Layer | Key format | Invalidation |
+|-------|-----------|--------------|
+| ID cache | `id:{Model}:{id}` | Row-level DEL on save/update/delete |
+| Query cache | `query:{Model}:v{version}:{hash}` | Version bump (O(1) INCR) makes old keys unreachable |
+| Version | `ver:{Model}` | INCR on any write; STI subclass changes bump all ancestor versions |
+
+**Optional metrics callbacks:**
+
+```python
+CachedTableBaseMixin.on_cache_hit = lambda name: print(f"HIT: {name}")
+CachedTableBaseMixin.on_cache_miss = lambda name: print(f"MISS: {name}")
+```
+
+**Cache skip conditions** (automatically detected):
+- `no_cache=True` (explicit bypass)
+- `with_for_update=True` (pessimistic lock needs latest)
+- `join` is set (join target changes don't trigger invalidation)
+- `options` is set (custom loading options)
+
+**No Redis? No problem.** If you don't call `configure_redis()` and don't inherit `CachedTableBaseMixin`, there is zero Redis dependency. The caching layer is entirely opt-in.
+
+---
+
+### all_fields_optional
+
+Automatically convert all inherited fields to optional for PATCH/UpdateRequest DTOs:
+
+```python
+class ArticleBase(SQLModelBase):
+    title: Str64
+    """Article title"""
+    body: Text10K
+    """Article body"""
+    is_published: bool = False
+    """Publication status"""
+
+class ArticleUpdateRequest(ArticleBase, all_fields_optional=True):
+    pass
+    # All fields become: title: Str64 | None = None, body: Text10K | None = None, etc.
+    # Annotated constraints (max_length, ge, le) are preserved
+    # Attribute docstrings are inherited from ArticleBase
+```
+
+**What it does:**
+- Converts `T` to `T | None = None` for all inherited fields
+- Preserves `Annotated` metadata (e.g. `Field(ge=0)` constraints stay intact)
+- Skips `Literal` fields (discriminator fields must remain required)
+- Replaces `default_factory` with `default=None`
+
+**No more manual overrides** like this:
+
+```python
+# Before: tedious and error-prone
+class ArticleUpdateRequest(ArticleBase):
+    title: Str64 | None = None    # Must manually repeat type + optional
+    body: Text10K | None = None   # Easy to forget constraints
+    is_published: bool | None = None
+```
+
+---
+
+### Attribute Docstring Inheritance
+
+When using Pydantic's `use_attribute_docstrings=True` (enabled by default in `SQLModelBase`), field descriptions appear in OpenAPI schemas. However, Pydantic's AST-based docstring parser doesn't inherit descriptions when subclasses override fields.
+
+**sqlmodel-ext fixes this automatically.** The metaclass inherits missing descriptions from parent classes via MRO traversal, and `__get_pydantic_json_schema__` patches bare `$ref` properties to include descriptions.
+
+```python
+class UserBase(SQLModelBase):
+    name: str
+    """User display name"""     # ← parsed by Pydantic
+
+class UserUpdateRequest(UserBase, all_fields_optional=True):
+    pass
+    # name: str | None = None   — description "User display name" is automatically inherited
+    # Shows up correctly in OpenAPI/Swagger docs
+```
+
+---
+
+### safe_reset
+
+Safely reset an async session, clearing both the DB connection and FOR UPDATE lock tracking:
+
+```python
+from sqlmodel_ext import safe_reset
+
+# In long-lived tasks (e.g. background workers) between operations:
+await safe_reset(session)
+```
+
+This prevents stale `FOR UPDATE` lock tracking in `session.info` when Python reuses object IDs across `reset()` cycles.
+
+---
+
 ## Architecture
 
 ```
@@ -1222,7 +1353,8 @@ sqlmodel_ext/
     pagination.py            # ListResponse, TimeFilterRequest, PaginationRequest, TableViewRequest
     mixins/
         __init__.py          # Mixin re-exports
-        table.py             # TableBaseMixin, UUIDTableBaseMixin (async CRUD)
+        table.py             # TableBaseMixin, UUIDTableBaseMixin, safe_reset (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
         relation_preload.py  # RelationPreloadMixin, @requires_relations
@@ -1250,7 +1382,8 @@ sqlmodel_ext/
 - **pydantic** >= 2.0
 - **sqlalchemy** >= 2.0
 - (optional) **fastapi** >= 0.100.0
-- (optional) **orjson** >= 3.0 -- for `JSON100K` / `JSONList100K`
+- (optional) **redis** >= 5.0 -- for `CachedTableBaseMixin`
+- (optional) **orjson** >= 3.0 -- for `CachedTableBaseMixin` and `JSON100K` / `JSONList100K`
 - (optional) **numpy** >= 1.24 -- for `NumpyVector`
 - (optional) **pgvector** >= 0.3 -- for `NumpyVector`
 

{sqlmodel_ext-0.2.1 → sqlmodel_ext-0.3.0}/README_zh.md

@@ -16,8 +16,9 @@ SQLModel 增强基础设施：智能元类、异步 CRUD Mixin、多态继承、
 
 | 特性 | 说明 |
 |------|------|
-| **SQLModelBase** | 智能元类，自动设置 `table=True`、合并 `mapper_args`，兼容 Python 3.14 (PEP 649) |
+| **SQLModelBase** | 智能元类，自动 `table=True`、合并 `mapper_args`、`all_fields_optional` UpdateRequest DTO、属性 docstring 继承、兼容 Python 3.14 (PEP 649) |
 | **TableBaseMixin / UUIDTableBaseMixin** | 完整异步 CRUD：`add()`、`save()`、`update()`、`delete()`、`get()`、`count()`、`get_with_count()`、`get_exist_one()` |
+| **CachedTableBaseMixin** | 双层 Redis 缓存（ID + 查询），版本号失效、STI 级联感知、可选 metrics 回调 |
 | **PolymorphicBaseMixin** | 简化联表继承 (JTI) 和单表继承 (STI) 配置 |
 | **AutoPolymorphicIdentityMixin** | 根据类名自动生成 `polymorphic_identity` |
 | **OptimisticLockMixin** | 基于版本号的乐观锁，支持自动重试 |
@@ -45,6 +46,12 @@ pip install sqlmodel-ext[fastapi]
 pip install sqlmodel-ext[postgresql]
 ```
 
+使用 Redis 缓存（启用 `CachedTableBaseMixin`）：
+
+```bash
+pip install sqlmodel-ext[cache]
+```
+
 使用 pgvector + NumPy 向量支持（包含 `[postgresql]`）：
 
 ```bash
@@ -1209,6 +1216,89 @@ class UserResponse(UserBase, UUIDIdDatetimeInfoMixin):
 
 ---
 
+### Redis 缓存 (CachedTableBaseMixin)
+
+为任何表模型添加双层 Redis 缓存。查询先走 Redis，未命中再查数据库。
+
+```bash
+pip install sqlmodel-ext[cache]  # 安装 redis + orjson
+```
+
+**启动配置（一次性）：**
+
+```python
+from redis.asyncio import Redis
+from sqlmodel_ext import CachedTableBaseMixin
+
+redis = Redis.from_url("redis://localhost:6379/0", decode_responses=False)
+CachedTableBaseMixin.configure_redis(redis)
+```
+
+**定义缓存模型：**
+
+```python
+class Character(CachedTableBaseMixin, CharacterBase, UUIDTableBaseMixin, table=True, cache_ttl=1800):
+    pass  # 30 分钟缓存 TTL
+```
+
+所有 `get()` 调用自动先查 Redis。`save()`、`update()`、`delete()` 时自动失效缓存。
+
+**缓存架构：**
+
+| 层 | Key 格式 | 失效方式 |
+|----|---------|---------|
+| ID 缓存 | `id:{Model}:{id}` | 行级 DEL |
+| 查询缓存 | `query:{Model}:v{version}:{hash}` | 版本号 INCR（O(1)）使旧 key 不可达 |
+| 版本号 | `ver:{Model}` | 写入时 INCR；STI 子类变更级联 bump 所有祖先 |
+
+**可选 metrics 回调：**
+
+```python
+CachedTableBaseMixin.on_cache_hit = lambda name: print(f"命中: {name}")
+CachedTableBaseMixin.on_cache_miss = lambda name: print(f"未命中: {name}")
+```
+
+**不用 Redis？** 不调用 `configure_redis()`、不继承 `CachedTableBaseMixin`，则零 Redis 依赖。缓存层完全可选。
+
+---
+
+### all_fields_optional
+
+自动将所有继承字段转为可选，用于 PATCH/UpdateRequest DTO：
+
+```python
+class ArticleBase(SQLModelBase):
+    title: Str64
+    """文章标题"""
+    body: Text10K
+    """文章内容"""
+
+class ArticleUpdateRequest(ArticleBase, all_fields_optional=True):
+    pass
+    # 所有字段变为: title: Str64 | None = None, body: Text10K | None = None, ...
+    # Annotated 约束（max_length, ge, le）保留
+    # 属性 docstring 从 ArticleBase 继承
+```
+
+---
+
+### 属性 Docstring 继承
+
+`SQLModelBase` 默认启用 Pydantic 的 `use_attribute_docstrings=True`，字段后的 docstring 自动出现在 OpenAPI Schema 中。当子类覆盖字段时，Pydantic 不会继承父类的 description——**sqlmodel-ext 在元类中自动修复此问题**。
+
+---
+
+### safe_reset
+
+安全重置异步会话，同时清理 FOR UPDATE 锁跟踪：
+
+```python
+from sqlmodel_ext import safe_reset
+await safe_reset(session)
+```
+
+---
+
 ## 架构
 
 ```
@@ -1222,7 +1312,8 @@ sqlmodel_ext/
     pagination.py            # ListResponse、TimeFilterRequest、PaginationRequest、TableViewRequest
     mixins/
         __init__.py          # Mixin 重导出
-        table.py             # TableBaseMixin、UUIDTableBaseMixin（异步 CRUD）
+        table.py             # TableBaseMixin、UUIDTableBaseMixin、safe_reset（异步 CRUD）
+        cached_table.py      # CachedTableBaseMixin（双层 Redis 缓存 + 版本号失效）
         polymorphic.py       # PolymorphicBaseMixin、AutoPolymorphicIdentityMixin、create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin、OptimisticLockError
         relation_preload.py  # RelationPreloadMixin、@requires_relations
@@ -1250,7 +1341,8 @@ sqlmodel_ext/
 - **pydantic** >= 2.0
 - **sqlalchemy** >= 2.0
 - （可选）**fastapi** >= 0.100.0
-- （可选）**orjson** >= 3.0 -- 用于 `JSON100K` / `JSONList100K`
+- （可选）**redis** >= 5.0 -- 用于 `CachedTableBaseMixin`
+- （可选）**orjson** >= 3.0 -- 用于 `CachedTableBaseMixin` 和 `JSON100K` / `JSONList100K`
 - （可选）**numpy** >= 1.24 -- 用于 `NumpyVector`
 - （可选）**pgvector** >= 0.3 -- 用于 `NumpyVector`
 

{sqlmodel_ext-0.2.1 → sqlmodel_ext-0.3.0}/docs/en/guide/cached-table.md

@@ -103,6 +103,36 @@ await Character.invalidate_by_id(id1, id2, id3)  # Multiple
 await Character.invalidate_all()
 ```
 
+## Cache invalidation on cascade deletes
+
+When a parent row is deleted, ``CachedTableBaseMixin`` follows one of two
+paths depending on the relationship's ``passive_deletes`` flag, and both paths
+correctly clean up the child model's cache.
+
+| `passive_deletes` | Who removes the children | How the cache is invalidated |
+|-------------------|--------------------------|------------------------------|
+| `False` (default) | SA issues one `DELETE` per child during flush | `persistent_to_deleted` event fires automatically |
+| `True` | The database `ON DELETE CASCADE` removes them silently | `delete()` pre-queries child IDs, then explicitly invalidates after `DELETE` |
+
+```python
+class User(CachedTableBaseMixin, UserBase, UUIDTableBaseMixin, table=True):
+    # passive_deletes=True: rely on the DB CASCADE; SA will not load children
+    files: list['UserFile'] = Relationship(
+        back_populates='user',
+        cascade_delete=True,
+        passive_deletes=True,
+    )
+```
+
+``passive_deletes=True`` is especially useful under high write pressure
+because it keeps SA from pulling thousands of child rows into memory. Older
+releases rejected this combination outright. Starting with 0.3.0, ``delete()``
+pre-queries the child IDs before the DB CASCADE runs, then explicitly calls
+``_invalidate_id_cache`` + ``_invalidate_query_caches`` on the target class,
+so the child model's Redis cache can never serve stale data. Condition-based
+deletes (``delete(condition=...)``) cannot enumerate parent IDs and therefore
+perform a model-level full invalidation on the target.
+
 ## Polymorphic Inheritance Support
 
 STI subclass caches automatically cascade to ancestor classes: when subclass data changes, ancestor class query caches are also cleaned.

{sqlmodel_ext-0.2.1 → sqlmodel_ext-0.3.0}/docs/en/guide/field-types.md

@@ -8,6 +8,7 @@ Writing `name: Str64` simultaneously tells Pydantic to validate `max_length=64`
 
 | Type | Max Length | Typical Use |
 |------|-----------|-------------|
+| `Str16` | 16 | Trigger words, short tokens |
 | `Str24` | 24 | Short codes |
 | `Str32` | 32 | Tokens, hashes |
 | `Str36` | 36 | UUID string format |
@@ -34,11 +35,19 @@ class Article(SQLModelBase):
 |------|-------|-------------|
 | `Port` | 1 ~ 65535 | Network ports |
 | `Percentage` | 0 ~ 100 | Percentages |
-| `PositiveInt` | >= 1 | Counts, quantities |
-| `NonNegativeInt` | >= 0 | Indices, counters |
+| `PositiveInt` | 1 ~ `INT32_MAX` (2³¹−1) | Counts, quantities (fits PostgreSQL INTEGER) |
+| `NonNegativeInt` | 0 ~ `INT32_MAX` | Indices, counters |
 | `PositiveFloat` | > 0.0 | Prices, weights |
-| `PositiveBigInt` | >= 1 (BigInteger) | Large integer IDs, timestamps |
-| `NonNegativeBigInt` | >= 0 (BigInteger) | Large integer counters |
+| `PositiveBigInt` | 1 ~ `JS_MAX_SAFE_INTEGER` (2⁵³−1) | Large integer IDs, timestamps (BigInteger storage) |
+| `NonNegativeBigInt` | 0 ~ `JS_MAX_SAFE_INTEGER` | Large integer counters (BigInteger storage) |
+
+::: tip BigInt is capped at `JS_MAX_SAFE_INTEGER`
+`PositiveBigInt` / `NonNegativeBigInt` use `JS_MAX_SAFE_INTEGER = 2⁵³ − 1`
+as their upper bound instead of `INT64_MAX = 2⁶³ − 1`. Integers larger
+than `JS_MAX_SAFE_INTEGER` lose precision when parsed by JavaScript
+clients. Define a custom alias with `le=INT64_MAX` if the field is never
+consumed by a browser. Both constants are exported from `sqlmodel_ext`.
+:::
 
 ```python
 from sqlmodel_ext import Port, Percentage

{sqlmodel_ext-0.2.1 → sqlmodel_ext-0.3.0}/docs/en/guide/relation-load-checker.md

@@ -1,5 +1,26 @@
 # Static Analyzer
 
+::: warning Experimental (off by default)
+Starting with 0.3.0 the relation-load static analyzer is **experimental** and
+ships with `check_on_startup = False`. Every auto-check entry point
+(`run_model_checks`, `RelationLoadCheckMiddleware`, the `atexit` warning)
+short-circuits immediately and the analyzer has no effect on your app.
+
+The analyzer's AST rules are tuned for a specific project layout (FastAPI
+endpoints, STI inheritance conventions, `save`/`update`/`delete` naming, and
+more). On projects that deviate from those assumptions it may emit false
+positives or fail to parse source files. Only enable it after verifying that
+your project matches the assumptions described below:
+
+```python
+import sqlmodel_ext.relation_load_checker as rlc
+rlc.check_on_startup = True  # explicit opt-in, experimental
+```
+
+The module API is not covered by semver stability guarantees; rules and
+signatures may change in subsequent releases.
+:::
+
 The static analyzer uses AST analysis to scan source code **at application startup**, detecting code that could cause `MissingGreenlet` errors before any request is served.
 
 ## Purpose
@@ -20,25 +41,33 @@ flowchart LR
 | **RLC002** | Accessing relations after `save()`/`update()` without `load=` |
 | **RLC003** | Accessing relations without prior `load=` loading (local variables only) |
 | **RLC005** | Dependency function doesn't preload relations needed by `response_model` |
-| **RLC007** | Accessing column attributes on expired objects after commit |
-| **RLC008** | Calling methods on expired objects after commit |
-| **RLC009** | Type annotation resolution errors (mixing resolved types with string forward references) |
+| **RLC007** | Accessing column attributes on expired objects after commit (triggers sync lazy load → MissingGreenlet) |
+| **RLC008** | Calling business methods on expired objects after commit (method body may touch expired columns) |
+| **RLC010** | Passing expired ORM objects after commit as arguments into other functions/methods |
+| **RLC011** | Implicit dunder access (`if not obj:` → `__len__`, `for x in obj:` → `__iter__`) triggers relation load |
+| **RLC012** | `response_model` declares STI-subclass-specific columns but the endpoint returns STI base-class results (heterogeneous serialization touches missing columns) |
 
 ## Usage
 
-### Automatic Checking (Recommended)
+### Automatic Checking (requires explicit opt-in)
 
 ```python
-# In models/__init__.py, after configure_mappers():
+# 1. Enable the experimental checker at your earliest bootstrap entrypoint
+import sqlmodel_ext.relation_load_checker as rlc
+rlc.check_on_startup = True  # experimental, off by default
+
+# 2. In models/__init__.py, after configure_mappers():
 from sqlmodel_ext import run_model_checks, SQLModelBase
 run_model_checks(SQLModelBase)
 
-# In main.py:
+# 3. In main.py:
 from sqlmodel_ext import RelationLoadCheckMiddleware
 app.add_middleware(RelationLoadCheckMiddleware)
 ```
 
-`run_model_checks` scans all model class methods. `RelationLoadCheckMiddleware` scans all FastAPI route functions when the first request arrives.
+`run_model_checks` scans every model class method; `RelationLoadCheckMiddleware`
+scans FastAPI routes when the lifespan startup completes. Without
+`check_on_startup = True`, both entry points return immediately and do nothing.
 
 ### Manual Checking
 

{sqlmodel_ext-0.2.1 → sqlmodel_ext-0.3.0}/docs/guide/cached-table.md

@@ -102,6 +102,27 @@ await Character.invalidate_by_id(id1, id2, id3)  # 多个
 await Character.invalidate_all()
 ```
 
+## 级联删除的缓存失效
+
+当父模型被删除时，``CachedTableBaseMixin`` 会按 SQLAlchemy 关系的 ``passive_deletes`` 设置走两条不同的路径，两种都能正确清理子模型的缓存。
+
+| `passive_deletes` | 子行谁删除 | 缓存怎么失效 |
+|-------------------|-----------|-------------|
+| `False`（默认） | SA 在 flush 时逐行 `DELETE` | `persistent_to_deleted` 事件自动触发 |
+| `True` | 数据库 `ON DELETE CASCADE` 静默删除 | `delete()` 在 DELETE 前预查 child ID，DELETE 后显式失效 |
+
+```python
+class User(CachedTableBaseMixin, UserBase, UUIDTableBaseMixin, table=True):
+    # passive_deletes=True：依赖 DB CASCADE，SA 不会加载子行
+    files: list['UserFile'] = Relationship(
+        back_populates='user',
+        cascade_delete=True,
+        passive_deletes=True,
+    )
+```
+
+``passive_deletes=True`` 在高并发环境下尤其有用，可以避免 SA 把几千行子记录拉进内存。旧版本会拒绝这个组合（要求 ``passive_deletes=False``）；新版本在 ``delete()`` 中预查 child ID 后再交给 DB CASCADE，之后显式 ``_invalidate_id_cache`` + ``_invalidate_query_caches``，保证子模型的 Redis 缓存不会出现陈旧数据。条件删除（``delete(condition=...)``）下无法枚举父 ID，会对子模型执行模型级全量失效。
+
 ## 多态继承支持
 
 STI 子类的缓存会自动联动祖先类：子类数据变更时，祖先类的查询缓存也会被清理。