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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.4.0
+Version: 0.4.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
@@ -24,14 +24,20 @@ 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'
 Provides-Extra: dev
 Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: fakeredis>=2.20; extra == 'dev'
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: orjson>=3.0; extra == 'dev'
+Requires-Dist: pgvector>=0.3; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: redis>=5.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: fastapi
 Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
@@ -70,7 +76,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 +114,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 +445,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 +466,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 +502,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 +538,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 +573,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 +655,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 +779,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 +796,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 +836,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 +872,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 +899,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 +966,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 +1412,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.2}/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
 ```