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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.2.1
+Version: 0.3.2
 Summary: Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types.
 Project-URL: Homepage, https://github.com/Foxerine/sqlmodel-ext
 Project-URL: Repository, https://github.com/Foxerine/sqlmodel-ext
@@ -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.2}/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.2}/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.3.2/docs/.vitepress/config.mts

@@ -0,0 +1,57 @@
+import { withMermaid } from 'vitepress-plugin-mermaid'
+import llmstxt from 'vitepress-plugin-llms'
+import { copyOrDownloadAsMarkdownButtons } from 'vitepress-plugin-llms'
+import { zh } from './zh.mts'
+import { en } from './en.mts'
+
+export default withMermaid({
+  title: 'sqlmodel-ext',
+
+  vite: {
+    plugins: [
+      llmstxt({
+        // Exclude legacy redirect placeholders. The old guide/internals trees were
+        // migrated to tutorials/how-to/reference/explanation under Diátaxis;
+        // the placeholders only carry meta-refresh stubs and would pollute llms-full.txt.
+        ignoreFiles: [
+          'guide/*',
+          'internals/*',
+          'en/guide/*',
+          'en/internals/*',
+        ],
+      }),
+    ],
+    optimizeDeps: {
+      include: ['mermaid', 'dayjs'],
+    },
+    ssr: {
+      noExternal: ['vitepress-plugin-mermaid', 'mermaid'],
+    },
+  },
+
+  markdown: {
+    config(md) {
+      md.use(copyOrDownloadAsMarkdownButtons)
+    },
+  },
+
+  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.2/docs/.vitepress/en.mts

@@ -0,0 +1,88 @@
+import type { DefaultTheme } from 'vitepress'
+
+export const en = {
+  lang: 'en',
+  description: 'SQLModel Enhancement Library — Tutorials, How-to, Reference, Explanation',
+
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/en/' },
+      { text: 'Tutorials', link: '/en/tutorials/' },
+      { text: 'How-to', link: '/en/how-to/' },
+      { text: 'Reference', link: '/en/reference/' },
+      { text: 'Explanation', link: '/en/explanation/' },
+    ],
+
+    sidebar: {
+      '/en/tutorials/': [
+        {
+          text: 'Tutorials',
+          items: [
+            { text: 'Overview', link: '/en/tutorials/' },
+            { text: '01 · Getting started', link: '/en/tutorials/01-getting-started' },
+            { text: '02 · Building a blog API', link: '/en/tutorials/02-building-a-blog-api' },
+            { text: '03 · Adding Redis caching', link: '/en/tutorials/03-adding-redis-cache' },
+          ],
+        },
+      ],
+      '/en/how-to/': [
+        {
+          text: 'How-to guides',
+          items: [
+            { text: 'Overview', link: '/en/how-to/' },
+            { text: 'Integrate with FastAPI', link: '/en/how-to/integrate-with-fastapi' },
+            { text: 'Paginate a list endpoint', link: '/en/how-to/paginate-a-list-endpoint' },
+            { text: 'Define JTI models', link: '/en/how-to/define-jti-models' },
+            { text: 'Define STI models', link: '/en/how-to/define-sti-models' },
+            { text: 'Handle concurrent updates', link: '/en/how-to/handle-concurrent-updates' },
+            { text: 'Prevent MissingGreenlet errors', link: '/en/how-to/prevent-missing-greenlet' },
+            { text: 'Release the DB connection during long I/O', link: '/en/how-to/release-connection-during-long-io' },
+            { text: 'Configure cascade delete', link: '/en/how-to/configure-cascade-delete' },
+            { text: 'Cache queries with Redis', link: '/en/how-to/cache-queries' },
+          ],
+        },
+      ],
+      '/en/reference/': [
+        {
+          text: 'Reference',
+          items: [
+            { text: 'Overview', link: '/en/reference/' },
+            { text: 'Base classes', link: '/en/reference/base-classes' },
+            { text: 'CRUD methods', link: '/en/reference/crud-methods' },
+            { text: 'Field types', link: '/en/reference/field-types' },
+            { text: 'Mixins', link: '/en/reference/mixins' },
+            { text: 'Decorators & helpers', link: '/en/reference/decorators' },
+            { text: 'Pagination types', link: '/en/reference/pagination-types' },
+          ],
+        },
+      ],
+      '/en/explanation/': [
+        {
+          text: 'Explanation',
+          items: [
+            { text: 'Overview', link: '/en/explanation/' },
+            { text: 'Prerequisites', link: '/en/explanation/prerequisites' },
+            { text: 'Metaclass & SQLModelBase', link: '/en/explanation/metaclass' },
+            { text: 'CRUD pipeline', link: '/en/explanation/crud-pipeline' },
+            { text: 'Polymorphic internals', link: '/en/explanation/polymorphic-internals' },
+            { text: 'Optimistic locking', link: '/en/explanation/optimistic-lock' },
+            { text: 'Relation preloading', link: '/en/explanation/relation-preload' },
+            { text: 'Cascade delete semantics', link: '/en/explanation/cascade-delete-semantics' },
+            { text: 'Redis caching', link: '/en/explanation/cached-table' },
+            { text: 'Static analyzer', link: '/en/explanation/relation-load-checker' },
+          ],
+        },
+      ],
+    },
+
+    outline: {
+      level: [2, 3],
+      label: 'On this page',
+    },
+
+    docFooter: {
+      prev: 'Previous',
+      next: 'Next',
+    },
+  } satisfies DefaultTheme.Config,
+}

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

@@ -0,0 +1,13 @@
+// .vitepress/theme/index.ts
+import DefaultTheme from 'vitepress/theme'
+import type { Theme } from 'vitepress'
+import CopyOrDownloadAsMarkdownButtons from 'vitepress-plugin-llms/vitepress-components/CopyOrDownloadAsMarkdownButtons.vue'
+import '@fontsource/maple-mono';
+import './style/custom.css'
+
+export default {
+    extends: DefaultTheme,
+    enhanceApp({ app }) {
+      app.component('CopyOrDownloadAsMarkdownButtons', CopyOrDownloadAsMarkdownButtons)
+    },
+  } satisfies Theme