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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.4.0
+Version: 0.4.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
@@ -24,7 +24,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: pydantic>=2.0
 Requires-Dist: sqlalchemy>=2.0
-Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: sqlmodel>=0.0.32
 Provides-Extra: cache
 Requires-Dist: orjson>=3.0; extra == 'cache'
 Requires-Dist: redis>=5.0; extra == 'cache'
@@ -70,7 +70,7 @@ Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphi
 | **RelationPreloadMixin** | Decorator-based automatic relationship preloading (prevents `MissingGreenlet` errors) |
 | **ListResponse[T]** | Generic paginated response model for list endpoints |
 | **Field Types** | Reusable constrained types: `Str64`, `Port`, `IPAddress`, `HttpUrl`, `SafeHttpUrl`, and more |
-| **PostgreSQL Types** | `Array[T]` for native ARRAY, `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
+| **PostgreSQL Types** | `Array[T]` for native ARRAY (read-tolerant for enum arrays during rolling-deploy version skew), `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
 | **Info Response DTOs** | Pre-built mixins for API response models with id/timestamp fields |
 
 ## Installation
@@ -108,12 +108,13 @@ pip install sqlmodel-ext[pgvector]
 ### Define Models
 
 ```python
-from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, Str64
+from pydantic import EmailStr  # requires: pip install 'pydantic[email]'
+from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, NonEmptyStrippedStr64
 
 # Base class -- fields only, no database table
 class UserBase(SQLModelBase):
-    name: Str64
-    email: str
+    name: NonEmptyStrippedStr64   # user-visible name: rejects "" and whitespace-only
+    email: EmailStr
 
 # Table class -- inherits fields + gains async CRUD + UUID primary key
 class User(UserBase, UUIDTableBaseMixin, table=True):
@@ -438,17 +439,19 @@ async def delete_article(session: SessionDep, article_id: UUID) -> None:
 
 ```python
 from abc import ABC, abstractmethod
+from pydantic import EmailStr
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin,
     AutoPolymorphicIdentityMixin, create_subclass_id_mixin,
     ListResponse, TableViewRequest,
+    Str512, Text1K,
 )
 
 # ── Polymorphic models ────────────────────────────────────────────
 
 class NotificationBase(SQLModelBase):
     user_id: UUID = Field(foreign_key='user.id')
-    message: str
+    message: Text1K
 
 class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
     @abstractmethod
@@ -457,13 +460,13 @@ class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, A
 NotifSubclassId = create_subclass_id_mixin('notification')
 
 class EmailNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    email_to: str
+    email_to: EmailStr
 
     def summary(self) -> str:
         return f"Email to {self.email_to}: {self.message}"
 
 class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    device_token: str
+    device_token: Str512
 
     def summary(self) -> str:
         return f"Push to {self.device_token}: {self.message}"
@@ -493,15 +496,15 @@ These mixins provide the async CRUD interface. `TableBaseMixin` uses an auto-inc
 Both mixins automatically add `id`, `created_at`, and `updated_at` fields.
 
 ```python
-from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin
+from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin, NonEmptyStrippedStr64, Text1K
 
 # Integer primary key
 class LogEntry(SQLModelBase, TableBaseMixin, table=True):
-    message: str
+    message: Text1K
 
 # UUID primary key (recommended for most use cases)
 class Project(SQLModelBase, UUIDTableBaseMixin, table=True):
-    name: str
+    name: NonEmptyStrippedStr64
 ```
 
 #### `add()` -- Batch Insert
@@ -529,7 +532,9 @@ user = await User.add(session, User(name="Alice", email="a@x.com"))
 user = await user.save(session)
 
 # Save with relationship preloading
-user = await user.save(session, load=User.profile)
+# (rel() casts the Relationship field for type checkers, which would
+#  otherwise infer User.profile as Profile instead of a loadable attribute)
+user = await user.save(session, load=rel(User.profile))
 
 # Save with optimistic lock retry
 user = await user.save(session, optimistic_retry_count=3)
@@ -562,9 +567,10 @@ user3 = await user3.save(session)        # commits all three
 #### `update()` -- Partial Update from a Model
 
 ```python
-class UserUpdate(SQLModelBase):
-    name: str | None = None
-    email: str | None = None
+# all_fields_optional auto-converts every inherited field to ``T | None = None``
+# while preserving constraints -- no hand-written Optional boilerplate
+class UserUpdate(UserBase, all_fields_optional=True):
+    pass
 
 # Only updates fields that were explicitly set
 user = await user.update(session, UserUpdate(name="Charlie"))
@@ -643,7 +649,7 @@ users = await User.get(session, fetch_mode="all")
 user = await User.get(
     session,
     User.id == user_id,
-    load=[User.profile, User.orders],
+    load=[rel(User.profile), rel(User.orders)],
 )
 
 # With JOIN
@@ -767,11 +773,12 @@ from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     create_subclass_id_mixin,
+    HttpUrl, NonEmptyStrippedStr64, NonNegativeInt,
 )
 
 # 1. Base class (fields only, no table)
 class ToolBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
 
 # 2. Abstract parent (creates the parent table)
 class Tool(ToolBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
@@ -783,13 +790,13 @@ ToolSubclassIdMixin = create_subclass_id_mixin('tool')
 
 # 4. Concrete subclasses (each gets its own table)
 class WebSearchTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    search_url: str
+    search_url: HttpUrl
 
     async def execute(self) -> str:
         return f"Searching {self.search_url}"
 
 class CalculatorTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    precision: int = 2
+    precision: NonNegativeInt = 2
 
     async def execute(self) -> str:
         return "Calculating..."
@@ -823,16 +830,17 @@ from sqlmodel_ext import (
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     register_sti_columns_for_all_subclasses,
     register_sti_column_properties_for_all_subclasses,
+    NonNegativeBigInt, Str256,
 )
 
 class UserFile(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
-    filename: str
+    filename: Str256
 
 class PendingFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
     upload_deadline: datetime | None = None  # Added to userfile table as nullable
 
 class CompletedFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
-    file_size: int | None = None  # Added to userfile table as nullable
+    file_size: NonNegativeBigInt | None = None  # Added to userfile table as nullable
 
 # After all models are defined, before configure_mappers():
 register_sti_columns_for_all_subclasses()
@@ -858,7 +866,7 @@ class ToolSet(SQLModelBase, UUIDTableBaseMixin, table=True):
 tool_set = await ToolSet.get(
     session,
     ToolSet.id == ts_id,
-    load=ToolSet.tools,
+    load=rel(ToolSet.tools),
     jti_subclasses='all',  # Loads all subclass-specific columns
 )
 ```
@@ -885,15 +893,22 @@ Tool._is_joined_table_inheritance()  # True for JTI, False for STI
 Prevents lost updates in concurrent environments using SQLAlchemy's `version_id_col` mechanism.
 
 ```python
+from enum import StrEnum
+
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     OptimisticLockMixin, OptimisticLockError,
+    NonNegativeDecimal38_18,
 )
 
+class OrderStatusEnum(StrEnum):
+    pending = 'pending'
+    paid = 'paid'
+
 # OptimisticLockMixin MUST come before TableBaseMixin in MRO
 class Order(OptimisticLockMixin, UUIDTableBaseMixin, table=True):
-    status: str
-    amount: int
+    status: OrderStatusEnum = OrderStatusEnum.pending
+    amount: NonNegativeDecimal38_18
 ```
 
 The mixin adds a `version` integer field (starting at 0). Every `UPDATE` generates SQL like:
@@ -945,11 +960,11 @@ The `RelationPreloadMixin` and `@requires_relations` decorator automatically loa
 
 ```python
 from sqlmodel import Relationship
-from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase
+from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase, NonNegativeDecimal38_18
 from sqlmodel_ext.mixins import RelationPreloadMixin, requires_relations
 
 class GeneratorConfig(SQLModelBase, UUIDTableBaseMixin, table=True):
-    price: int
+    price: NonNegativeDecimal38_18
 
 class Generator(SQLModelBase, UUIDTableBaseMixin, table=True):
     config: GeneratorConfig = Relationship()
@@ -1391,12 +1406,12 @@ When using Pydantic's `use_attribute_docstrings=True` (enabled by default in `SQ
 
 ```python
 class UserBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
     """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
+    # name: NonEmptyStrippedStr64 | None = None — description "User display name" is inherited
     # Shows up correctly in OpenAPI/Swagger docs
 ```
 

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

@@ -25,7 +25,7 @@ Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphi
 | **RelationPreloadMixin** | Decorator-based automatic relationship preloading (prevents `MissingGreenlet` errors) |
 | **ListResponse[T]** | Generic paginated response model for list endpoints |
 | **Field Types** | Reusable constrained types: `Str64`, `Port`, `IPAddress`, `HttpUrl`, `SafeHttpUrl`, and more |
-| **PostgreSQL Types** | `Array[T]` for native ARRAY, `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
+| **PostgreSQL Types** | `Array[T]` for native ARRAY (read-tolerant for enum arrays during rolling-deploy version skew), `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
 | **Info Response DTOs** | Pre-built mixins for API response models with id/timestamp fields |
 
 ## Installation
@@ -63,12 +63,13 @@ pip install sqlmodel-ext[pgvector]
 ### Define Models
 
 ```python
-from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, Str64
+from pydantic import EmailStr  # requires: pip install 'pydantic[email]'
+from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, NonEmptyStrippedStr64
 
 # Base class -- fields only, no database table
 class UserBase(SQLModelBase):
-    name: Str64
-    email: str
+    name: NonEmptyStrippedStr64   # user-visible name: rejects "" and whitespace-only
+    email: EmailStr
 
 # Table class -- inherits fields + gains async CRUD + UUID primary key
 class User(UserBase, UUIDTableBaseMixin, table=True):
@@ -393,17 +394,19 @@ async def delete_article(session: SessionDep, article_id: UUID) -> None:
 
 ```python
 from abc import ABC, abstractmethod
+from pydantic import EmailStr
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin,
     AutoPolymorphicIdentityMixin, create_subclass_id_mixin,
     ListResponse, TableViewRequest,
+    Str512, Text1K,
 )
 
 # ── Polymorphic models ────────────────────────────────────────────
 
 class NotificationBase(SQLModelBase):
     user_id: UUID = Field(foreign_key='user.id')
-    message: str
+    message: Text1K
 
 class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
     @abstractmethod
@@ -412,13 +415,13 @@ class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, A
 NotifSubclassId = create_subclass_id_mixin('notification')
 
 class EmailNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    email_to: str
+    email_to: EmailStr
 
     def summary(self) -> str:
         return f"Email to {self.email_to}: {self.message}"
 
 class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    device_token: str
+    device_token: Str512
 
     def summary(self) -> str:
         return f"Push to {self.device_token}: {self.message}"
@@ -448,15 +451,15 @@ These mixins provide the async CRUD interface. `TableBaseMixin` uses an auto-inc
 Both mixins automatically add `id`, `created_at`, and `updated_at` fields.
 
 ```python
-from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin
+from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin, NonEmptyStrippedStr64, Text1K
 
 # Integer primary key
 class LogEntry(SQLModelBase, TableBaseMixin, table=True):
-    message: str
+    message: Text1K
 
 # UUID primary key (recommended for most use cases)
 class Project(SQLModelBase, UUIDTableBaseMixin, table=True):
-    name: str
+    name: NonEmptyStrippedStr64
 ```
 
 #### `add()` -- Batch Insert
@@ -484,7 +487,9 @@ user = await User.add(session, User(name="Alice", email="a@x.com"))
 user = await user.save(session)
 
 # Save with relationship preloading
-user = await user.save(session, load=User.profile)
+# (rel() casts the Relationship field for type checkers, which would
+#  otherwise infer User.profile as Profile instead of a loadable attribute)
+user = await user.save(session, load=rel(User.profile))
 
 # Save with optimistic lock retry
 user = await user.save(session, optimistic_retry_count=3)
@@ -517,9 +522,10 @@ user3 = await user3.save(session)        # commits all three
 #### `update()` -- Partial Update from a Model
 
 ```python
-class UserUpdate(SQLModelBase):
-    name: str | None = None
-    email: str | None = None
+# all_fields_optional auto-converts every inherited field to ``T | None = None``
+# while preserving constraints -- no hand-written Optional boilerplate
+class UserUpdate(UserBase, all_fields_optional=True):
+    pass
 
 # Only updates fields that were explicitly set
 user = await user.update(session, UserUpdate(name="Charlie"))
@@ -598,7 +604,7 @@ users = await User.get(session, fetch_mode="all")
 user = await User.get(
     session,
     User.id == user_id,
-    load=[User.profile, User.orders],
+    load=[rel(User.profile), rel(User.orders)],
 )
 
 # With JOIN
@@ -722,11 +728,12 @@ from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     create_subclass_id_mixin,
+    HttpUrl, NonEmptyStrippedStr64, NonNegativeInt,
 )
 
 # 1. Base class (fields only, no table)
 class ToolBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
 
 # 2. Abstract parent (creates the parent table)
 class Tool(ToolBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
@@ -738,13 +745,13 @@ ToolSubclassIdMixin = create_subclass_id_mixin('tool')
 
 # 4. Concrete subclasses (each gets its own table)
 class WebSearchTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    search_url: str
+    search_url: HttpUrl
 
     async def execute(self) -> str:
         return f"Searching {self.search_url}"
 
 class CalculatorTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    precision: int = 2
+    precision: NonNegativeInt = 2
 
     async def execute(self) -> str:
         return "Calculating..."
@@ -778,16 +785,17 @@ from sqlmodel_ext import (
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     register_sti_columns_for_all_subclasses,
     register_sti_column_properties_for_all_subclasses,
+    NonNegativeBigInt, Str256,
 )
 
 class UserFile(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
-    filename: str
+    filename: Str256
 
 class PendingFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
     upload_deadline: datetime | None = None  # Added to userfile table as nullable
 
 class CompletedFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
-    file_size: int | None = None  # Added to userfile table as nullable
+    file_size: NonNegativeBigInt | None = None  # Added to userfile table as nullable
 
 # After all models are defined, before configure_mappers():
 register_sti_columns_for_all_subclasses()
@@ -813,7 +821,7 @@ class ToolSet(SQLModelBase, UUIDTableBaseMixin, table=True):
 tool_set = await ToolSet.get(
     session,
     ToolSet.id == ts_id,
-    load=ToolSet.tools,
+    load=rel(ToolSet.tools),
     jti_subclasses='all',  # Loads all subclass-specific columns
 )
 ```
@@ -840,15 +848,22 @@ Tool._is_joined_table_inheritance()  # True for JTI, False for STI
 Prevents lost updates in concurrent environments using SQLAlchemy's `version_id_col` mechanism.
 
 ```python
+from enum import StrEnum
+
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     OptimisticLockMixin, OptimisticLockError,
+    NonNegativeDecimal38_18,
 )
 
+class OrderStatusEnum(StrEnum):
+    pending = 'pending'
+    paid = 'paid'
+
 # OptimisticLockMixin MUST come before TableBaseMixin in MRO
 class Order(OptimisticLockMixin, UUIDTableBaseMixin, table=True):
-    status: str
-    amount: int
+    status: OrderStatusEnum = OrderStatusEnum.pending
+    amount: NonNegativeDecimal38_18
 ```
 
 The mixin adds a `version` integer field (starting at 0). Every `UPDATE` generates SQL like:
@@ -900,11 +915,11 @@ The `RelationPreloadMixin` and `@requires_relations` decorator automatically loa
 
 ```python
 from sqlmodel import Relationship
-from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase
+from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase, NonNegativeDecimal38_18
 from sqlmodel_ext.mixins import RelationPreloadMixin, requires_relations
 
 class GeneratorConfig(SQLModelBase, UUIDTableBaseMixin, table=True):
-    price: int
+    price: NonNegativeDecimal38_18
 
 class Generator(SQLModelBase, UUIDTableBaseMixin, table=True):
     config: GeneratorConfig = Relationship()
@@ -1346,12 +1361,12 @@ When using Pydantic's `use_attribute_docstrings=True` (enabled by default in `SQ
 
 ```python
 class UserBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
     """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
+    # name: NonEmptyStrippedStr64 | None = None — description "User display name" is inherited
     # Shows up correctly in OpenAPI/Swagger docs
 ```
 

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

@@ -25,7 +25,7 @@ SQLModel 增强基础设施：智能元类、异步 CRUD Mixin、多态继承、
 | **RelationPreloadMixin** | 基于装饰器的关系自动预加载（防止 `MissingGreenlet` 错误） |
 | **ListResponse[T]** | 泛型分页响应模型，适用于列表接口 |
 | **字段类型** | 可复用的约束类型：`Str64`、`Port`、`IPAddress`、`HttpUrl`、`SafeHttpUrl` 等 |
-| **PostgreSQL 类型** | `Array[T]` 原生 ARRAY、`JSON100K`/`JSONList100K` 限长 JSONB、`NumpyVector` pgvector+NumPy 集成 |
+| **PostgreSQL 类型** | `Array[T]` 原生 ARRAY（枚举数组在滚动部署版本偏差窗口读容忍）、`JSON100K`/`JSONList100K` 限长 JSONB、`NumpyVector` pgvector+NumPy 集成 |
 | **响应 DTO Mixin** | 预构建的 API 响应模型 Mixin，包含 id/时间戳字段 |
 
 ## 安装
@@ -63,12 +63,13 @@ pip install sqlmodel-ext[pgvector]
 ### 定义模型
 
 ```python
-from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, Str64
+from pydantic import EmailStr  # 需要：pip install 'pydantic[email]'
+from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, NonEmptyStrippedStr64
 
 # Base 类 -- 仅定义字段，不创建数据库表
 class UserBase(SQLModelBase):
-    name: Str64
-    email: str
+    name: NonEmptyStrippedStr64   # 用户可见命名：拒绝空串与纯空白
+    email: EmailStr
 
 # Table 类 -- 继承字段 + 获得异步 CRUD + UUID 主键
 class User(UserBase, UUIDTableBaseMixin, table=True):
@@ -361,17 +362,19 @@ async def delete_article(session: SessionDep, article_id: UUID) -> None:
 
 ```python
 from abc import ABC, abstractmethod
+from pydantic import EmailStr
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin,
     AutoPolymorphicIdentityMixin, create_subclass_id_mixin,
     ListResponse, TableViewRequest,
+    Str512, Text1K,
 )
 
 # ── 多态模型 ─────────────────────────────────────────────────────
 
 class NotificationBase(SQLModelBase):
     user_id: UUID = Field(foreign_key='user.id')
-    message: str
+    message: Text1K
 
 class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
     @abstractmethod
@@ -380,13 +383,13 @@ class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, A
 NotifSubclassId = create_subclass_id_mixin('notification')
 
 class EmailNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    email_to: str
+    email_to: EmailStr
 
     def summary(self) -> str:
         return f"Email to {self.email_to}: {self.message}"
 
 class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    device_token: str
+    device_token: Str512
 
     def summary(self) -> str:
         return f"Push to {self.device_token}: {self.message}"
@@ -416,15 +419,15 @@ async def list_notifications(
 两者均自动添加 `id`、`created_at` 和 `updated_at` 字段。
 
 ```python
-from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin
+from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin, NonEmptyStrippedStr64, Text1K
 
 # 整数主键
 class LogEntry(SQLModelBase, TableBaseMixin, table=True):
-    message: str
+    message: Text1K
 
 # UUID 主键（大多数场景推荐）
 class Project(SQLModelBase, UUIDTableBaseMixin, table=True):
-    name: str
+    name: NonEmptyStrippedStr64
 ```
 
 #### `add()` -- 批量插入
@@ -452,7 +455,9 @@ user = await User.add(session, User(name="Alice", email="a@x.com"))
 user = await user.save(session)
 
 # 保存后预加载关系
-user = await user.save(session, load=User.profile)
+# rel() 把 Relationship 字段 cast 为 QueryableAttribute——
+# 否则类型检查器把 User.profile 推断为 Profile 而非可加载属性
+user = await user.save(session, load=rel(User.profile))
 
 # 乐观锁自动重试
 user = await user.save(session, optimistic_retry_count=3)
@@ -485,9 +490,10 @@ user3 = await user3.save(session)        # 一次性 commit 全部三条
 #### `update()` -- 从模型实例局部更新
 
 ```python
-class UserUpdate(SQLModelBase):
-    name: str | None = None
-    email: str | None = None
+# all_fields_optional 自动把所有继承字段转为 ``T | None = None``
+# 并保留约束——无需手写 Optional 样板
+class UserUpdate(UserBase, all_fields_optional=True):
+    pass
 
 # 仅更新显式设置的字段
 user = await user.update(session, UserUpdate(name="Charlie"))
@@ -566,7 +572,7 @@ users = await User.get(session, fetch_mode="all")
 user = await User.get(
     session,
     User.id == user_id,
-    load=[User.profile, User.orders],
+    load=[rel(User.profile), rel(User.orders)],
 )
 
 # JOIN 查询
@@ -690,11 +696,12 @@ from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     create_subclass_id_mixin,
+    HttpUrl, NonEmptyStrippedStr64, NonNegativeInt,
 )
 
 # 1. Base 类（仅定义字段，无表）
 class ToolBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
 
 # 2. 抽象父类（创建父表）
 class Tool(ToolBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
@@ -706,13 +713,13 @@ ToolSubclassIdMixin = create_subclass_id_mixin('tool')
 
 # 4. 具体子类（各自拥有独立表）
 class WebSearchTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    search_url: str
+    search_url: HttpUrl
 
     async def execute(self) -> str:
         return f"Searching {self.search_url}"
 
 class CalculatorTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    precision: int = 2
+    precision: NonNegativeInt = 2
 
     async def execute(self) -> str:
         return "Calculating..."
@@ -746,16 +753,17 @@ from sqlmodel_ext import (
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     register_sti_columns_for_all_subclasses,
     register_sti_column_properties_for_all_subclasses,
+    NonNegativeBigInt, Str256,
 )
 
 class UserFile(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
-    filename: str
+    filename: Str256
 
 class PendingFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
     upload_deadline: datetime | None = None  # 作为 nullable 列添加到 userfile 表
 
 class CompletedFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
-    file_size: int | None = None  # 作为 nullable 列添加到 userfile 表
+    file_size: NonNegativeBigInt | None = None  # 作为 nullable 列添加到 userfile 表
 
 # 所有模型定义完成后，在 configure_mappers() 之前调用：
 register_sti_columns_for_all_subclasses()
@@ -781,7 +789,7 @@ class ToolSet(SQLModelBase, UUIDTableBaseMixin, table=True):
 tool_set = await ToolSet.get(
     session,
     ToolSet.id == ts_id,
-    load=ToolSet.tools,
+    load=rel(ToolSet.tools),
     jti_subclasses='all',  # 加载所有子类特有的列
 )
 ```
@@ -808,15 +816,22 @@ Tool._is_joined_table_inheritance()  # JTI 返回 True，STI 返回 False
 利用 SQLAlchemy 的 `version_id_col` 机制防止并发环境下的更新丢失。
 
 ```python
+from enum import StrEnum
+
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     OptimisticLockMixin, OptimisticLockError,
+    NonNegativeDecimal38_18,
 )
 
+class OrderStatusEnum(StrEnum):
+    pending = 'pending'
+    paid = 'paid'
+
 # OptimisticLockMixin 在 MRO 中必须位于 TableBaseMixin 之前
 class Order(OptimisticLockMixin, UUIDTableBaseMixin, table=True):
-    status: str
-    amount: int
+    status: OrderStatusEnum = OrderStatusEnum.pending
+    amount: NonNegativeDecimal38_18
 ```
 
 该 Mixin 添加一个 `version` 整数字段（初始值为 0）。每次 `UPDATE` 生成如下 SQL：
@@ -868,11 +883,11 @@ order = await order.update(session, update_data, optimistic_retry_count=3)
 
 ```python
 from sqlmodel import Relationship
-from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase
+from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase, NonNegativeDecimal38_18
 from sqlmodel_ext.mixins import RelationPreloadMixin, requires_relations
 
 class GeneratorConfig(SQLModelBase, UUIDTableBaseMixin, table=True):
-    price: int
+    price: NonNegativeDecimal38_18
 
 class Generator(SQLModelBase, UUIDTableBaseMixin, table=True):
     config: GeneratorConfig = Relationship()