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

{sqlmodel_ext-0.2.0 → sqlmodel_ext-0.3.0}/.gitignore

@@ -14,6 +14,7 @@ build/
 .venv/
 venv/
 ENV/
+node_modules/
 
 # IDE
 .idea/
@@ -26,6 +27,10 @@ ENV/
 .coverage
 htmlcov/
 
+# VitePress
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
 # OS
 .DS_Store
 Thumbs.db

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.2.0
+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
 Project-URL: Issues, https://github.com/Foxerine/sqlmodel-ext/issues
-Author: Foxline AI
+Author: Foxerine
 License-Expression: MIT
 License-File: LICENSE
 Keywords: async,crud,orm,polymorphic,pydantic,sqlalchemy,sqlmodel
@@ -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'
@@ -48,6 +51,8 @@ Description-Content-Type: text/markdown
 
 **English** | [中文](README_zh.md)
 
+> **Warning**: This project is under active development. APIs may change without notice between releases. No stability or backward-compatibility guarantees are provided at this stage. Use at your own risk.
+
 Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types.
 
 **sqlmodel-ext** eliminates the boilerplate of building async database applications with [SQLModel](https://sqlmodel.tiangolo.com/). Define your models, inherit a mixin, and get a full async CRUD API -- pagination, relationship loading, polymorphic queries, and optimistic locking included.
@@ -56,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 |
@@ -85,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
@@ -1249,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
 
 ```
@@ -1262,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
@@ -1290,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.0 → sqlmodel_ext-0.3.0}/README.md

@@ -6,6 +6,8 @@
 
 **English** | [中文](README_zh.md)
 
+> **Warning**: This project is under active development. APIs may change without notice between releases. No stability or backward-compatibility guarantees are provided at this stage. Use at your own risk.
+
 Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types.
 
 **sqlmodel-ext** eliminates the boilerplate of building async database applications with [SQLModel](https://sqlmodel.tiangolo.com/). Define your models, inherit a mixin, and get a full async CRUD API -- pagination, relationship loading, polymorphic queries, and optimistic locking included.
@@ -14,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 |
@@ -43,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
@@ -1207,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
 
 ```
@@ -1220,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
@@ -1248,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.0 → sqlmodel_ext-0.3.0}/README_zh.md

@@ -6,6 +6,8 @@
 
 [English](README.md) | **中文**
 
+> **警告**：本项目正在积极开发中。API 可能在版本之间发生不兼容变更，且不提供任何稳定性或向后兼容性保证。请自行承担使用风险。
+
 SQLModel 增强基础设施：智能元类、异步 CRUD Mixin、多态继承、乐观锁、关系预加载、可复用字段类型。
 
 **sqlmodel-ext** 消除了使用 [SQLModel](https://sqlmodel.tiangolo.com/) 构建异步数据库应用时的样板代码。定义模型、继承一个 Mixin，即可获得完整的异步 CRUD API -- 分页、关系加载、多态查询、乐观锁一应俱全。
@@ -14,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** | 基于版本号的乐观锁，支持自动重试 |
@@ -43,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
@@ -1207,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)
+```
+
+---
+
 ## 架构
 
 ```
@@ -1220,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
@@ -1248,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.3.0/docs/.vitepress/config.mts

@@ -0,0 +1,27 @@
+import { withMermaid } from 'vitepress-plugin-mermaid'
+import { zh } from './zh.mts'
+import { en } from './en.mts'
+
+export default withMermaid({
+  title: 'sqlmodel-ext',
+
+  locales: {
+    root: {
+      label: '简体中文',
+      ...zh,
+    },
+    en: {
+      label: 'English',
+      ...en,
+    },
+  },
+
+  themeConfig: {
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Foxerine/sqlmodel-ext' },
+    ],
+    search: {
+      provider: 'local',
+    },
+  },
+})

sqlmodel_ext-0.3.0/docs/.vitepress/en.mts

@@ -0,0 +1,59 @@
+import type { DefaultTheme } from 'vitepress'
+
+export const en = {
+  lang: 'en',
+  description: 'SQLModel Enhancement Library: Usage Guide & Implementation Internals',
+
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/en/' },
+      { text: 'Guide', link: '/en/guide/' },
+      { text: 'Internals', link: '/en/internals/' },
+    ],
+
+    sidebar: {
+      '/en/guide/': [
+        {
+          text: 'Guide',
+          items: [
+            { text: 'Quick Start', link: '/en/guide/' },
+            { text: 'Field Types', link: '/en/guide/field-types' },
+            { text: 'CRUD Operations', link: '/en/guide/crud' },
+            { text: 'Pagination & Lists', link: '/en/guide/pagination' },
+            { text: 'Polymorphic Inheritance', link: '/en/guide/polymorphic' },
+            { text: 'Optimistic Locking', link: '/en/guide/optimistic-lock' },
+            { text: 'Relation Preloading', link: '/en/guide/relation-preload' },
+            { text: 'Redis Caching', link: '/en/guide/cached-table' },
+            { text: 'Static Analyzer', link: '/en/guide/relation-load-checker' },
+          ],
+        },
+      ],
+      '/en/internals/': [
+        {
+          text: 'Implementation Internals',
+          items: [
+            { text: 'Architecture Overview', link: '/en/internals/' },
+            { text: 'Prerequisites', link: '/en/internals/prerequisites' },
+            { text: 'Metaclass & SQLModelBase', link: '/en/internals/metaclass' },
+            { text: 'CRUD Implementation', link: '/en/internals/crud' },
+            { text: 'Polymorphic Inheritance', link: '/en/internals/polymorphic' },
+            { text: 'Optimistic Locking', link: '/en/internals/optimistic-lock' },
+            { text: 'Relation Preloading', link: '/en/internals/relation-preload' },
+            { text: 'Redis Caching', link: '/en/internals/cached-table' },
+            { text: 'Static Analyzer', link: '/en/internals/relation-load-checker' },
+          ],
+        },
+      ],
+    },
+
+    outline: {
+      level: [2, 3],
+      label: 'On this page',
+    },
+
+    docFooter: {
+      prev: 'Previous',
+      next: 'Next',
+    },
+  } satisfies DefaultTheme.Config,
+}

sqlmodel_ext-0.3.0/docs/.vitepress/theme/index.ts

@@ -0,0 +1,6 @@
+// .vitepress/theme/index.ts
+import DefaultTheme from 'vitepress/theme'
+import '@fontsource/maple-mono';
+import './style/custom.css'
+
+export default DefaultTheme

sqlmodel_ext-0.3.0/docs/.vitepress/theme/style/custom.css

@@ -0,0 +1,4 @@
+/* .vitepress/theme/custom.css */
+:root {
+    --vp-font-family-mono: Maple Mono, JetBrains Mono, Menlo, Monaco, Consolas, "Courier New", monospace !important;
+  }