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

{sqlmodel_ext-0.1.1 → sqlmodel_ext-0.2.1}/.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.1.1 → sqlmodel_ext-0.2.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.1.1
+Version: 0.2.1
 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
@@ -48,6 +48,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.

{sqlmodel_ext-0.1.1 → sqlmodel_ext-0.2.1}/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.

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

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

sqlmodel_ext-0.2.1/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.2.1/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.2.1/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.2.1/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;
+  }

sqlmodel_ext-0.2.1/docs/.vitepress/zh.mts

@@ -0,0 +1,59 @@
+import type { DefaultTheme } from 'vitepress'
+
+export const zh = {
+  lang: 'zh-CN',
+  description: 'SQLModel 增强库：使用指南与实现原理',
+
+  themeConfig: {
+    nav: [
+      { text: '首页', link: '/' },
+      { text: '指南', link: '/guide/' },
+      { text: '原理', link: '/internals/' },
+    ],
+
+    sidebar: {
+      '/guide/': [
+        {
+          text: '指南',
+          items: [
+            { text: '快速开始', link: '/guide/' },
+            { text: '字段类型', link: '/guide/field-types' },
+            { text: 'CRUD 操作', link: '/guide/crud' },
+            { text: '分页与列表', link: '/guide/pagination' },
+            { text: '多态继承', link: '/guide/polymorphic' },
+            { text: '乐观锁', link: '/guide/optimistic-lock' },
+            { text: '关系预加载', link: '/guide/relation-preload' },
+            { text: 'Redis 缓存', link: '/guide/cached-table' },
+            { text: '静态分析器', link: '/guide/relation-load-checker' },
+          ],
+        },
+      ],
+      '/internals/': [
+        {
+          text: '实现原理',
+          items: [
+            { text: '架构总览', link: '/internals/' },
+            { text: '前置知识', link: '/internals/prerequisites' },
+            { text: '元类与 SQLModelBase', link: '/internals/metaclass' },
+            { text: 'CRUD 实现', link: '/internals/crud' },
+            { text: '多态继承机制', link: '/internals/polymorphic' },
+            { text: '乐观锁机制', link: '/internals/optimistic-lock' },
+            { text: '关系预加载机制', link: '/internals/relation-preload' },
+            { text: 'Redis 缓存机制', link: '/internals/cached-table' },
+            { text: '静态分析器原理', link: '/internals/relation-load-checker' },
+          ],
+        },
+      ],
+    },
+
+    outline: {
+      level: [2, 3],
+      label: '目录',
+    },
+
+    docFooter: {
+      prev: '上一页',
+      next: '下一页',
+    },
+  } satisfies DefaultTheme.Config,
+}

sqlmodel_ext-0.2.1/docs/en/guide/cached-table.md

@@ -0,0 +1,156 @@
+# Redis Caching
+
+`CachedTableBaseMixin` adds a Redis cache layer to the model's `get()` queries, with automatic invalidation on CRUD operations.
+
+## Basic Usage
+
+```python
+from sqlmodel_ext import CachedTableBaseMixin, SQLModelBase, UUIDTableBaseMixin
+
+class CharacterBase(SQLModelBase):
+    name: str
+
+class Character(CachedTableBaseMixin, CharacterBase, UUIDTableBaseMixin, table=True, cache_ttl=1800):
+    pass  # Cache for 30 minutes
+```
+
+::: warning Warning
+`CachedTableBaseMixin` must be placed **before** `UUIDTableBaseMixin` in the inheritance list.
+:::
+
+### Configure Redis
+
+Configure once at startup:
+
+```python
+import redis.asyncio as redis
+
+redis_client = redis.from_url("redis://localhost:6379")
+CachedTableBaseMixin.configure_redis(redis_client)
+```
+
+### Startup Check (Recommended)
+
+```python
+CachedTableBaseMixin.check_cache_config()
+```
+
+Verifies configuration correctness for all cached models: Redis client is set, `__cache_ttl__` is a positive integer, no forbidden direct calls.
+
+## Cache Behavior
+
+### Automatic Caching
+
+`get()` query results are automatically cached to Redis; subsequent identical queries read directly from cache:
+
+```python
+# First time: queries database + writes cache
+char = await Character.get(session, Character.id == char_id) # [!code highlight]
+
+# Second time: reads from cache directly, zero SQL
+char = await Character.get(session, Character.id == char_id) # [!code highlight]
+```
+
+### Automatic Invalidation
+
+CRUD operations automatically clean related caches:
+
+| Operation | Invalidation Strategy |
+|-----------|----------------------|
+| `save()` / `update()` | Delete the record's ID cache + all query caches for the model |
+| `delete(instances)` | Delete each instance's ID cache + all query caches |
+| `delete(condition)` | Delete all caches for the model (ID + query) |
+| `add()` | Delete all query caches (new objects have no old cache) |
+
+### Skipping Cache
+
+```python
+# Explicitly skip cache
+char = await Character.get(session, Character.id == char_id, no_cache=True) # [!code highlight]
+```
+
+::: details Details
+Cache is automatically skipped in these scenarios:
+- `with_for_update=True` (needs latest data)
+- `populate_existing=True`
+- `options` parameter is non-empty
+- `join` parameter is non-empty
+- Transaction has uncommitted pending invalidation data
+:::
+
+## Dual-Layer Cache Architecture
+
+```
+1. ID Cache (id:{ModelName}:{id_value})
+   → Single-row ID equality queries
+   → Row-level invalidation O(1)
+
+2. Query Cache (query:{ModelName}:{hash})
+   → Conditional/list queries
+   → Model-level invalidation SCAN+DEL
+```
+
+ID queries (`Character.id == some_id`) use precise ID cache keys, requiring only one key deletion for invalidation. Other queries use parameter hashes as cache keys.
+
+## Manual Invalidation
+
+```python
+# Invalidate specific ID
+await Character.invalidate_by_id(char_id)
+await Character.invalidate_by_id(id1, id2, id3)  # Multiple
+
+# Invalidate all caches for the model
+await Character.invalidate_all()
+```
+
+## Polymorphic Inheritance Support
+
+STI subclass caches automatically cascade to ancestor classes: when subclass data changes, ancestor class query caches are also cleaned.
+
+## TTL Configuration
+
+::: code-group
+
+```python [Keyword argument (recommended)]
+class Character(CachedTableBaseMixin, CharacterBase, UUIDTableBaseMixin,
+                table=True, cache_ttl=1800):  # [!code highlight]
+    pass  # 30 minutes
+
+class Config(CachedTableBaseMixin, ConfigBase, UUIDTableBaseMixin,
+             table=True, cache_ttl=86400):  # [!code highlight]
+    pass  # 24 hours
+```
+
+```python [Class variable]
+class Character(CachedTableBaseMixin, CharacterBase, UUIDTableBaseMixin, table=True):
+    __cache_ttl__: ClassVar[int] = 1800  # [!code highlight]
+```
+
+:::
+
+Default TTL is 3600 seconds (1 hour).
+
+## Graceful Degradation
+
+::: tip Tip
+When Redis is unavailable, the system automatically degrades to database queries without affecting business logic:
+- Read failure → log + query database
+- Write failure → log + continue (non-critical path)
+- Delete failure → log + TTL provides eventual consistency
+:::
+
+## Raw SQL Scenarios
+
+::: warning Warning
+When bypassing the ORM, you need to manage cache manually:
+:::
+
+```python
+from sqlmodel_ext.mixins.cached_table import CachedTableBaseMixin
+
+# Register before raw SQL operations
+CachedTableBaseMixin._register_pending_invalidation(session, Character, char_id) # [!code warning]
+
+# Commit and invalidate
+await instance._commit_and_invalidate(session)
+```

sqlmodel_ext-0.2.1/docs/en/guide/crud.md

@@ -0,0 +1,264 @@
+# CRUD Operations
+
+Inherit `TableBaseMixin` (auto-increment ID) or `UUIDTableBaseMixin` (UUID ID) to get a full set of async CRUD methods.
+
+## Utility Functions
+
+### `rel()` — Type-safe Relationship Reference
+
+basedpyright infers SQLModel's Relationship fields as the annotated type (e.g., `LLM`) rather than `QueryableAttribute`. `rel()` fixes this type issue:
+
+```python
+from sqlmodel_ext import rel
+
+# Without rel: basedpyright reports type error
+user = await User.get(session, load=User.profile) # [!code --]
+
+# With rel: correct type
+user = await User.get(session, load=rel(User.profile)) # [!code ++]
+```
+
+### `cond()` — Type-safe Condition Composition
+
+Similar issue: basedpyright infers `Model.field == value` as `bool`, causing `&` / `|` operator errors.
+
+```python
+from sqlmodel_ext import cond
+
+scope = cond(UserFile.user_id == current_user.id) # [!code highlight]
+condition = scope & cond(UserFile.status == FileStatusEnum.uploaded) # [!code highlight]
+users = await UserFile.get(session, condition, fetch_mode="all")
+```
+
+### `sanitize_integrity_error()` — User-friendly Error Messages
+
+Extracts user-safe error messages from `IntegrityError`. Specifically supports PostgreSQL trigger SQLSTATE 23514 errors:
+
+```python
+from sqlalchemy.exc import IntegrityError
+
+try:
+    await order.save(session)
+except IntegrityError as e:
+    msg = Order.sanitize_integrity_error(e, "Operation failed")
+    # PostgreSQL trigger messages are extracted; other constraint errors return the default message
+```
+
+## Built-in Fields
+
+Three fields are automatically included upon inheritance:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `int` or `UUID` | Primary key, auto-generated |
+| `created_at` | `datetime` | Creation time, auto-set |
+| `updated_at` | `datetime` | Update time, auto-refreshed on every UPDATE |
+
+## `save()` — Create or Update
+
+```python{3}
+user = User(name="Alice", email="alice@example.com")
+await user.save(session)            # Don't do this — causes expiration // [!code --]
+user = await user.save(session)     # Correct usage // [!code ++]
+print(user.id)  # Has a value now
+
+# Modify then save again = UPDATE
+user.name = "Bob"
+user = await user.save(session)
+```
+
+### Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `commit` | `True` | When `False`, only flushes without committing — useful for batch operations |
+| `load` | `None` | Preload specified relations after saving |
+| `optimistic_retry_count` | `0` | Number of retries on optimistic lock conflicts |
+
+```python
+# Batch operations: only flush earlier ones, commit with the last
+await user1.save(session, commit=False)
+await user2.save(session, commit=False)
+user3 = await user3.save(session)  # Commits all at once // [!code highlight]
+
+# Preload relations after save
+user = await user.save(session, load=User.profile)
+```
+
+## `add()` — Bulk Insert
+
+```python
+users = [User(name="Alice"), User(name="Bob")]
+users = await User.add(session, users)
+
+# Single item works too
+user = await User.add(session, User(name="Eve"))
+```
+
+## `update()` — Partial Update (PATCH Semantics)
+
+```python
+class UserUpdate(SQLModelBase):
+    name: str | None = None
+    email: str | None = None
+
+data = UserUpdate(name="Bob")  # Only name is set // [!code highlight]
+user = await user.update(session, data)
+# Only name is updated, email remains unchanged (exclude_unset=True)
+```
+
+### Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `exclude_unset` | `True` | Only update explicitly set fields (PATCH semantics) |
+| `exclude` | `None` | Exclude certain fields from being updated |
+| `extra_data` | `None` | Append additional fields beyond the update model |
+
+```python
+# Append extra fields
+user = await user.update(session, data, extra_data={"updated_by": admin.id})
+
+# Exclude sensitive fields
+user = await user.update(session, data, exclude={"role", "is_admin"})
+```
+
+## `delete()` — Delete
+
+Two modes, mutually exclusive:
+
+```python
+# Delete by instance
+await User.delete(session, user)
+await User.delete(session, [user1, user2])
+
+# Bulk delete by condition (⚠️ deletes ALL matching records)
+count = await User.delete(session, condition=User.is_active == False) # [!code warning]
+```
+
+Returns the number of deleted records.
+
+## `get()` — Query
+
+A versatile query method that covers all query scenarios through different parameter combinations.
+
+### Basic Queries
+
+```python
+# Get first match by condition (default fetch_mode="first")
+user = await User.get(session, User.email == "alice@example.com")
+
+# Get all
+users = await User.get(session, fetch_mode="all") # [!code highlight]
+
+# Get exactly one (errors on 0 or multiple results)
+user = await User.get(session, User.id == some_id, fetch_mode="one") # [!code highlight]
+```
+
+### `fetch_mode` Return Values
+
+| `fetch_mode` | Return Type | On 0 results | On multiple results |
+|---|---|---|---|
+| `"first"` (default) | `T \| None` | `None` | Returns first |
+| `"one"` | `T` | Raises exception | Raises exception |
+| `"all"` | `list[T]` | Empty list | Returns all |
+
+### Pagination & Sorting
+
+```python
+from sqlmodel_ext import TableViewRequest
+
+tv = TableViewRequest(offset=0, limit=20, desc=True, order="created_at")
+users = await User.get(session, fetch_mode="all", table_view=tv)
+# → SELECT ... ORDER BY created_at DESC LIMIT 20 OFFSET 0
+```
+
+### Time Filtering
+
+```python
+users = await User.get(
+    session,
+    fetch_mode="all",
+    created_after=datetime(2024, 1, 1),
+    created_before=datetime(2024, 12, 31),
+)
+```
+
+### Relation Preloading
+
+```python
+user = await User.get(
+    session,
+    User.id == user_id,
+    load=[User.profile, Profile.avatar], # [!code highlight]
+)
+# Automatically builds: selectinload(User.profile).selectinload(Profile.avatar)
+```
+
+### Other Parameters
+
+| Parameter | Purpose |
+|-----------|---------|
+| `join` | JOIN another table |
+| `options` | Custom SQLAlchemy query options |
+| `filter` | Additional WHERE conditions |
+| `with_for_update` | SELECT ... FOR UPDATE (row lock) |
+
+## `count()` — Count
+
+```python
+total = await User.count(session)
+active = await User.count(session, User.is_active == True)
+```
+
+## `get_with_count()` — Paginated List
+
+Combination of `count()` + `get(fetch_mode="all")`, returns `ListResponse`:
+
+```python
+result = await User.get_with_count(session, table_view=table_view)
+# result.count = 42
+# result.items = [User(...), User(...), ...]
+```
+
+## `get_one()` — Guaranteed Existence Query
+
+Similar to `get(fetch_mode="one")` but with a simpler interface — pass the ID directly:
+
+```python
+user = await User.get_one(session, user_id)
+# Record not found → NoResultFound // [!code error]
+# Multiple records → MultipleResultsFound // [!code error]
+
+# Query with lock
+user = await User.get_one(session, user_id, with_for_update=True)
+```
+
+::: tip Tip
+`get_one()` raises SQLAlchemy exceptions (`NoResultFound`), while `get_exist_one()` raises HTTP 404 (with FastAPI) or `RecordNotFoundError`.
+:::
+
+## `get_exist_one()` — Find or 404
+
+```python
+user = await User.get_exist_one(session, user_id) # [!code highlight]
+# Not found → HTTPException(404) (with FastAPI)
+# Or RecordNotFoundError (without FastAPI)
+
+# With relation preloading
+user = await User.get_exist_one(session, user_id, load=User.profile)
+```
+
+## Method Quick Reference
+
+| Method | Type | SQL Equivalent | Return Value |
+|--------|------|---------------|--------------|
+| `add()` | Class method | INSERT | Instance or list |
+| `save()` | Instance method | INSERT or UPDATE | Refreshed instance |
+| `update()` | Instance method | UPDATE (partial) | Refreshed instance |
+| `delete()` | Class method | DELETE | Delete count |
+| `get()` | Class method | SELECT + WHERE + ... | Instance / list / None |
+| `get_one()` | Class method | SELECT + guaranteed existence | Instance |
+| `count()` | Class method | SELECT COUNT(*) | int |
+| `get_with_count()` | Class method | COUNT + SELECT | ListResponse |
+| `get_exist_one()` | Class method | SELECT + 404 | Instance |