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

sqlmodel_ext-0.3.3/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # -------------------------------------------------------------------
+  # Job 1: source-tree tests across supported Python versions.
+  # Uses uv sync so the lockfile is honoured and runs are reproducible.
+  # -------------------------------------------------------------------
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create venv and install project with dev extras
+        # Dev extras: pytest, pytest-asyncio, aiosqlite, ruff. Editable install
+        # keeps the wheel build separate for the consumer-integration job.
+        run: |
+          uv venv --python ${{ matrix.python-version }} .venv
+          uv pip install --python .venv/bin/python -e ".[dev]"
+
+      - name: Run pytest
+        run: .venv/bin/python -m pytest tests/ -v
+
+  # -------------------------------------------------------------------
+  # Job 2: build wheel + sdist, then install the wheel into a clean
+  # virtualenv with zero dev deps and run the consumer integration
+  # script. This simulates an external PyPI consumer.
+  # -------------------------------------------------------------------
+  consumer-integration:
+    name: consumer integration (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: test
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Build wheel and sdist
+        run: uv tool run --from build python -m build
+
+      - name: Create isolated consumer venv
+        run: uv venv --python ${{ matrix.python-version }} /tmp/consumer-env
+
+      - name: Install built wheel (no dev deps, only the wheel + aiosqlite driver)
+        run: uv pip install --python /tmp/consumer-env/bin/python dist/*.whl aiosqlite
+
+      - name: Confirm installed version matches wheel
+        run: |
+          /tmp/consumer-env/bin/python -c "import sqlmodel_ext; print('installed:', sqlmodel_ext.__version__ if hasattr(sqlmodel_ext, '__version__') else '(no __version__)')"
+
+      - name: Run consumer integration scenario
+        run: /tmp/consumer-env/bin/python examples/consumer_integration/run.py
+
+      - name: Upload distribution artifacts
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 14

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.3.2
+Version: 0.3.3
 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

sqlmodel_ext-0.3.3/examples/consumer_integration/run.py

@@ -0,0 +1,148 @@
+"""
+Consumer-side integration test.
+
+Runs from a clean virtualenv that has ONLY the built sqlmodel-ext wheel
+installed (plus aiosqlite for the async SQLite driver). Simulates what an
+external PyPI consumer experiences: if this script passes, the wheel is
+well-formed and the STI default-isolation fix behaves end-to-end.
+
+Exits with status 0 on success, non-zero on any failed assertion. Intended
+to be invoked directly by CI:
+
+    python -m pip install dist/*.whl aiosqlite
+    python examples/consumer_integration/run.py
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.orm import configure_mappers
+from sqlmodel import SQLModel
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from sqlmodel_ext import (
+    AutoPolymorphicIdentityMixin,
+    PolymorphicBaseMixin,
+    SQLModelBase,
+    UUIDTableBaseMixin,
+    register_sti_column_properties_for_all_subclasses,
+    register_sti_columns_for_all_subclasses,
+)
+
+
+# ---------- STI model hierarchy ----------
+
+class Tool(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
+    """Shared STI parent table."""
+    name: str
+
+
+class ExportFunction(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """Declares ``max_size`` with a large realistic default."""
+    # 5 GiB chosen because the real-world production bug used exactly this value.
+    max_size: int = 5 * 1024 * 1024 * 1024
+
+
+class UploadFunction(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """Declares a different default for a different field."""
+    allow_overwrite: bool = True
+
+
+class NoOpFunction(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """The sibling with zero own fields - the purest victim of default leaks."""
+    pass
+
+
+# ---------- Integration scenario ----------
+
+FIVE_GIB = 5 * 1024 * 1024 * 1024
+
+
+def fail(msg: str) -> None:
+    print(f"[FAIL] {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+async def main() -> None:
+    # STI two-phase registration (public API contract).
+    register_sti_columns_for_all_subclasses()
+    configure_mappers()
+    register_sti_column_properties_for_all_subclasses()
+
+    # --- Layer 1: metadata assertions ---
+    shared = Tool.__table__.columns
+    if shared["max_size"].default is not None:
+        fail(
+            f"tool.max_size.default should be None (fix cleared the shared SA "
+            f"default). Got: {shared['max_size'].default!r}"
+        )
+    if shared["max_size"].server_default is not None:
+        fail(f"tool.max_size.server_default should be None")
+    if shared["allow_overwrite"].default is not None:
+        fail(
+            f"tool.allow_overwrite.default should be None. "
+            f"Got: {shared['allow_overwrite'].default!r}"
+        )
+
+    # Pydantic field-level defaults must still be intact.
+    if ExportFunction.model_fields["max_size"].default != FIVE_GIB:
+        fail(
+            f"Pydantic default for ExportFunction.max_size was wiped by the fix: "
+            f"{ExportFunction.model_fields['max_size'].default!r}"
+        )
+
+    # --- Layer 2: behavioural assertions via real async SQLite ---
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    try:
+        async with engine.begin() as conn:
+            await conn.run_sync(SQLModel.metadata.create_all)
+
+        async with AsyncSession(engine) as session:
+            # NoOpFunction does not declare max_size; the shared column must be NULL.
+            noop = NoOpFunction(name="noop")
+            noop = await noop.save(session)
+            result = await session.execute(
+                select(Tool.__table__.c.max_size).where(Tool.__table__.c.id == noop.id)
+            )
+            stored = result.scalar_one()
+            if stored is not None:
+                fail(
+                    f"NoOpFunction.max_size should be NULL (bug: sibling default "
+                    f"leaked from ExportFunction). Got: {stored!r}"
+                )
+
+            # UploadFunction also does not declare max_size.
+            upload = UploadFunction(name="upload")
+            upload = await upload.save(session)
+            result = await session.execute(
+                select(Tool.__table__.c.max_size).where(Tool.__table__.c.id == upload.id)
+            )
+            stored = result.scalar_one()
+            if stored is not None:
+                fail(
+                    f"UploadFunction.max_size should be NULL. Got: {stored!r}"
+                )
+
+            # Happy path: declaring subclass still persists its own Pydantic default.
+            export = ExportFunction(name="export")
+            export = await export.save(session)
+            result = await session.execute(
+                select(Tool.__table__.c.max_size).where(Tool.__table__.c.id == export.id)
+            )
+            stored = result.scalar_one()
+            if stored != FIVE_GIB:
+                fail(
+                    f"ExportFunction.max_size should be {FIVE_GIB}. Got: {stored!r} "
+                    f"- fix may have broken the declaring subclass's default path."
+                )
+    finally:
+        await engine.dispose()
+
+    print("[OK] sqlmodel-ext consumer integration test passed")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{sqlmodel_ext-0.3.2 → sqlmodel_ext-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlmodel-ext"
-version = "0.3.2"
+version = "0.3.3"
 description = "Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types."
 readme = "README.md"
 license = "MIT"

{sqlmodel_ext-0.3.2 → sqlmodel_ext-0.3.3}/src/sqlmodel_ext/__init__.py

@@ -20,7 +20,7 @@ Quick start::
     user = await user.save(session)
     users = await User.get(session, fetch_mode="all")
 """
-__version__ = "0.3.0"
+__version__ = "0.3.3"
 
 # Base
 from sqlmodel_ext.base import SQLModelBase, ExtraIgnoreModelBase

{sqlmodel_ext-0.3.2 → sqlmodel_ext-0.3.3}/src/sqlmodel_ext/_compat.py

@@ -67,10 +67,15 @@ if sys.version_info >= (3, 14):
         # Check field.metadata (Pydantic-processed Annotated types)
         metadata = getattr(field, 'metadata', None)
         if metadata:
+            # Pass field.annotation as source_type so handlers that need the element type
+            # (e.g. _PendingArrayHandler extracting T from list[T] to compute ARRAY(T))
+            # can resolve. handler=None is fine because the sa_type extraction path only
+            # reads metadata['sa_type'] and never invokes the schema itself.
+            field_annotation = getattr(field, 'annotation', None)
             for metadata_item in metadata:
                 if hasattr(metadata_item, '__get_pydantic_core_schema__'):
                     try:
-                        schema = metadata_item.__get_pydantic_core_schema__(None, None)
+                        schema = metadata_item.__get_pydantic_core_schema__(field_annotation, None)
                         if isinstance(schema, dict) and 'metadata' in schema:
                             sa_type = schema['metadata'].get('sa_type')
                             if sa_type is not None:
@@ -105,7 +110,9 @@ if sys.version_info >= (3, 14):
                         for md in inner_args[1:]:
                             if hasattr(md, '__get_pydantic_core_schema__'):
                                 try:
-                                    schema = md.__get_pydantic_core_schema__(None, None)
+                                    # Pass first_arg (the full Annotated alias) as source_type so
+                                    # handlers like _PendingArrayHandler can extract the element type.
+                                    schema = md.__get_pydantic_core_schema__(first_arg, None)
                                     if isinstance(schema, dict) and 'metadata' in schema:
                                         sa_type = schema['metadata'].get('sa_type')
                                         if sa_type is not None:
@@ -153,7 +160,10 @@ if sys.version_info >= (3, 14):
                 for md in args[1:]:
                     if hasattr(md, '__get_pydantic_core_schema__'):
                         try:
-                            schema = md.__get_pydantic_core_schema__(None, None)
+                            # Pass annotation (the full Annotated form) as source_type so
+                            # handlers needing the element type (_PendingArrayHandler etc.)
+                            # can extract T from list[T].
+                            schema = md.__get_pydantic_core_schema__(annotation, None)
                             if isinstance(schema, dict) and 'metadata' in schema:
                                 sa_type = schema['metadata'].get('sa_type')
                                 if sa_type is not None:

{sqlmodel_ext-0.3.2 → sqlmodel_ext-0.3.3}/src/sqlmodel_ext/base.py

@@ -15,7 +15,7 @@ import re
 import sys
 import types
 import typing
-from typing import Any, get_args, get_origin
+from typing import Any, Self, Sequence, get_args, get_origin
 
 from pydantic import ConfigDict, model_validator
 from pydantic.fields import FieldInfo
@@ -102,6 +102,47 @@ def _merge_field_info_attrs(target: SQLModelFieldInfo, source: SQLModelFieldInfo
         target.metadata = list(target_meta) + list(source_meta)
 
 
+def _find_field_info_in_annotated(annotation: Any) -> SQLModelFieldInfo | None:
+    """
+    Extract SQLModel ``FieldInfo`` embedded in ``Annotated[T, Field(...)]`` metadata.
+
+    Used by the metaclass sa_type injection loop. When a field is declared
+    ``Annotated[X, Field(default_factory=list, ...)]`` *without* an explicit
+    ``= ...`` assignment, ``attrs[field_name]`` is ``Undefined``. Replacing
+    it with a fresh ``Field(sa_type=sa_type)`` would discard the user's
+    Field metadata (``default_factory``, ``max_length``, validators, ...)
+    that lives inside the Annotated args. This helper recovers that
+    FieldInfo so the caller can attach ``sa_type`` to the user's Field
+    instead of clobbering it. The bug only surfaces after 2+ levels of
+    inheritance: single-class instantiation goes through Pydantic's native
+    Annotated path and works, but child classes rebuild ``model_fields``
+    from the clobbered ``attrs`` and the field becomes silently
+    ``is_required=True``.
+
+    Multiple FieldInfo args (e.g. ``Annotated[Str64, Field(unique=True)]``
+    expands to ``Annotated[str, Field(max_length=64), Field(unique=True)]``)
+    are merged into a single shallow copy so the shared Annotated metadata
+    singletons are never mutated.
+
+    :param annotation: Field type annotation
+    :returns: Merged SQLModelFieldInfo (shallow copy, safe to mutate), or None
+    """
+    if get_origin(annotation) is not typing.Annotated:
+        return None
+    args = get_args(annotation)
+    if len(args) < 2:
+        return None
+    sqlmodel_fis: list[SQLModelFieldInfo] = [
+        arg for arg in args[1:] if isinstance(arg, SQLModelFieldInfo)
+    ]
+    if not sqlmodel_fis:
+        return None
+    merged = copy.copy(sqlmodel_fis[0])
+    for extra_fi in sqlmodel_fis[1:]:
+        _merge_field_info_attrs(merged, extra_fi)
+    return merged
+
+
 def _make_annotation_optional(annotation: typing.Any) -> typing.Any:
     """
     Convert type annotation to optional: ``T → T | None``
@@ -179,6 +220,27 @@ def _apply_all_fields_optional(
         if original_ann is None:
             continue
 
+        # Bug fix: when a field is declared as ``field: T = Field(gt=..., le=...)`` (non-Annotated form),
+        # MRO ``__annotations__`` only stores the bare ``T``. The ``Field(...)`` constraint metadata
+        # lives on the right-hand-side assignment, so all_fields_optional-derived UpdateRequest classes
+        # lose those constraints (e.g. UFT-style "missing range" warnings fire on derived fields that
+        # had constraints in the source class). Patch: when ``original_ann`` is not already Annotated,
+        # pull constraints from the base class's resolved ``model_fields[name].metadata`` (Pydantic
+        # stores them there as ``[Gt(0), Le(600), ...]``) and re-wrap into ``Annotated[T, *metadata]``,
+        # letting downstream ``_make_annotation_optional`` preserve the constraints when converting
+        # to ``T | None``. The root recommended fix is still to declare fields in Annotated form at
+        # the source; this patch is defense-in-depth for legacy ``field: T = Field(...)`` declarations.
+        if get_origin(original_ann) is not typing.Annotated:
+            for base in bases:
+                base_model_fields = getattr(base, 'model_fields', None)
+                if not base_model_fields:
+                    continue
+                base_field_info = base_model_fields.get(field_name)
+                if base_field_info is None or not base_field_info.metadata:
+                    continue
+                original_ann = typing.Annotated[original_ann, *base_field_info.metadata]
+                break
+
         # Skip Literal type fields (e.g. discriminator):
         # Literal['text'] | None breaks Pydantic discriminated union
         raw_type = original_ann
@@ -268,10 +330,33 @@ def _recover_annotated_sqlmodel_fields(
     all_annotated.update(annotations)
 
     for field_name, field_type in all_annotated.items():
-        if get_origin(field_type) is not typing.Annotated:
+        # Unwrap Optional/Union wrappers: forms like ``Annotated[X, Field(sa_type=BigInteger)] | None``
+        # have ``get_origin() == Union`` (or ``types.UnionType`` for PEP 604 ``|``); we must
+        # peel back to find the inner Annotated to extract the SQLModel FieldInfo. Otherwise
+        # nullable aliases like ``PositiveBigInt | None`` lose ``sa_type`` and the SA column
+        # silently degrades (e.g. BigInteger → Integer → asyncpg int32 overflow on large defaults).
+        annotated_type = field_type
+        union_args: list[typing.Any] | None = None
+        union_origin = get_origin(field_type)
+        # ``X | None`` (PEP 604) has origin ``types.UnionType``; ``Union[X, None]`` is ``typing.Union``.
+        # Match both without depending on ``types`` import inside any version block.
+        is_union = union_origin is typing.Union or (
+            union_origin is not None and getattr(union_origin, '__name__', '') == 'UnionType'
+        )
+        if is_union:
+            union_args = list(get_args(field_type))
+            annotated_in_union = next(
+                (arg for arg in union_args if get_origin(arg) is typing.Annotated),
+                None,
+            )
+            if annotated_in_union is None:
+                continue
+            annotated_type = annotated_in_union
+
+        if get_origin(annotated_type) is not typing.Annotated:
             continue
 
-        args = get_args(field_type)
+        args = get_args(annotated_type)
         if len(args) < 2:
             continue
 
@@ -313,10 +398,24 @@ def _recover_annotated_sqlmodel_fields(
         base_type = args[0]
         remaining_metadata = [a for a in args[1:] if not isinstance(a, SQLModelFieldInfo)]
         if remaining_metadata:
-            new_ann = typing.Annotated[tuple([base_type] + remaining_metadata)]
+            new_inner: typing.Any = typing.Annotated[tuple([base_type] + remaining_metadata)]
         else:
-            new_ann = base_type
-        annotations[field_name] = new_ann
+            new_inner = base_type
+
+        if union_args is not None:
+            # Rebuild Union: replace the inner Annotated with the stripped version, keeping
+            # the other Union members (e.g. ``| None``) intact. Use PEP 604 ``|`` to accumulate
+            # so we don't trip the deprecated-typing.Union warning.
+            new_union_args = [
+                new_inner if get_origin(arg) is typing.Annotated else arg
+                for arg in union_args
+            ]
+            rebuilt: typing.Any = new_union_args[0]
+            for extra in new_union_args[1:]:
+                rebuilt = rebuilt | extra
+            annotations[field_name] = rebuilt
+        else:
+            annotations[field_name] = new_inner
 
 
 def _make_sti_fk_resolver(
@@ -495,7 +594,19 @@ class __DeclarativeMeta(SQLModelMetaclass):
                 field_value = attrs.get(field_name, Undefined)
 
                 if field_value is Undefined:
-                    attrs[field_name] = Field(sa_type=sa_type)
+                    # No explicit ``= Field(...)`` assignment. Prefer recovering
+                    # FieldInfo from inside Annotated[X, Field(default_factory=..., ...)]
+                    # so user-supplied default_factory / max_length / constraints
+                    # survive — clobbering with a fresh Field(sa_type=sa_type)
+                    # would silently make the field required after multi-level
+                    # inheritance.
+                    annotated_fi = _find_field_info_in_annotated(field_type)
+                    if annotated_fi is not None:
+                        if getattr(annotated_fi, 'sa_type', Undefined) is Undefined:
+                            setattr(annotated_fi, 'sa_type', sa_type)
+                        attrs[field_name] = annotated_fi
+                    else:
+                        attrs[field_name] = Field(sa_type=sa_type)
                 elif isinstance(field_value, FieldInfo):
                     if getattr(field_value, 'sa_type', Undefined) is Undefined:
                         setattr(field_value, 'sa_type', sa_type)
@@ -975,6 +1086,11 @@ class SQLModelBase(SQLModel, metaclass=__DeclarativeMeta):
                         prop['description'] = finfo.description
         return json_schema
 
+    @classmethod
+    def validate_list(cls, items: Sequence[Any]) -> list[Self]:
+        """Batch-convert a sequence of ORM instances (or dicts) to this model type."""
+        return [cls.model_validate(item, from_attributes=True) for item in items]
+
     @classmethod
     def get_computed_field_names(cls) -> set[str]:
         """Get the set of computed_field names for this model class."""

{sqlmodel_ext-0.3.2 → sqlmodel_ext-0.3.3}/src/sqlmodel_ext/field_types/__init__.py

@@ -108,6 +108,9 @@ Text5K: TypeAlias = Annotated[str, Field(max_length=5000), _NO_NULL_BYTE]
 Text10K: TypeAlias = Annotated[str, Field(max_length=10000), _NO_NULL_BYTE]
 """10000-character text field"""
 
+Text16K: TypeAlias = Annotated[str, Field(max_length=16000), _NO_NULL_BYTE]
+"""16000-character text field (long-form descriptions, tool docs)"""
+
 Text32K: TypeAlias = Annotated[str, Field(max_length=32000), _NO_NULL_BYTE]
 """32000-character text field"""
 
@@ -120,9 +123,29 @@ Text64K: TypeAlias = Annotated[str, Field(max_length=65536), _NO_NULL_BYTE]
 Text100K: TypeAlias = Annotated[str, Field(max_length=100000), _NO_NULL_BYTE]
 """100000-character text field"""
 
+Text128K: TypeAlias = Annotated[str, Field(max_length=131072), _NO_NULL_BYTE]
+"""131072-character (128 * 1024) text field (large markdown documents etc.)"""
+
 Text1M: TypeAlias = Annotated[str, Field(max_length=1000000), _NO_NULL_BYTE]
 """1000000-character text field (tool call parameters, tool responses, etc.)"""
 
+# NonEmptyStr* — same as Str* but also requires ``min_length=1``, rejecting empty
+# ``""`` strings with a 422 ValidationError. Use for naming fields where the empty
+# string is semantically invalid (e.g. UserFolder.name).
+NonEmptyStr64: TypeAlias = Annotated[str, Field(min_length=1, max_length=64), _NO_NULL_BYTE]
+"""1-64 character non-empty string field"""
+
+NonEmptyStr128: TypeAlias = Annotated[str, Field(min_length=1, max_length=128), _NO_NULL_BYTE]
+"""1-128 character non-empty string field"""
+
+NonEmptyStr256: TypeAlias = Annotated[str, Field(min_length=1, max_length=256), _NO_NULL_BYTE]
+"""1-256 character non-empty string field"""
+
+# Sha256Hex — exactly 64 lowercase hex characters, the canonical SHA-256 hex digest form.
+# The strict regex also implicitly rejects NUL bytes, so no separate _NO_NULL_BYTE is needed.
+Sha256Hex: TypeAlias = Annotated[str, StringConstraints(min_length=64, max_length=64, pattern=r'^[0-9a-f]{64}$')]
+"""64-char lowercase-hex SHA-256 digest (e.g. content hashes)"""
+
 # Numeric range constraints
 Port: TypeAlias = Annotated[int, Field(ge=1, le=65535)]
 """Port number (1-65535)"""