merge: bring release/0.3.4 (0.3.5 hotfix) into master

PyPI 0.3.4 was published from master before the Array sa_type fix
(9aababf) landed on the release/0.3.4 branch, so the published wheel
silently missed the fix. The release/0.3.4 branch then shipped 0.3.5
to PyPI with the fix. Master and release/0.3.4 were left divergent —
master had the doc-sync work (eee01d5), release had the Array fix
plus README example (9aababf, eca1e5d, 9451fc1). This merge converges
them so master is once again the single source of truth and matches
the wheel on PyPI.

Conflicts: pyproject.toml and src/sqlmodel_ext/__init__.py disagreed
on version. Resolved to 0.3.5 in both — that's what is published.

Net effect on master:
  - keeps the doc-sync (Text16K/Text128K rows, Python 3.12+ tutorial
    prereq, "Design orientation" home section).
  - adds the Array sa_type fix (_durably_set_sa_type / FieldInfoMetadata
    channel) so Array[StrEnum] = Field(default_factory=list) columns
    on table=True models stop raising "<class 'list'> has no matching
    SQLAlchemy type".
  - adds the new tests/test_array_explicit_field_sa_type.py regression
    (note: those tests register table=True models on the global
    SQLModel.metadata and currently pollute SQLite-backed tests in the
    same run — to be cleaned up in a follow-up).
  - adds the README DI / resource-as-dependency example.
  - bumps version to 0.3.5 to match PyPI.

v0.3.5 tag still points at 9451fc1, which is now reachable from master
via this merge commit. No tags rewritten.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Foxerine

README.md

@@ -125,43 +125,75 @@ async def demo(session: AsyncSession):
 A complete REST API -- models, DTOs, and five endpoints:
 
 ```python
+from collections.abc import AsyncGenerator
 from typing import Annotated
 from uuid import UUID
 
 from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlmodel import Field
 from sqlmodel.ext.asyncio.session import AsyncSession
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin, Str64, Text10K,
     ListResponse, TableViewRequest, UUIDIdDatetimeInfoMixin,
 )
 
-# ── Dependencies (defined once, reused everywhere) ────────────────
+# ── Dependency-injection layer: declare once (e.g. in a shared
+#    deps module), every router imports the type aliases ────────────
+
+_engine = create_async_engine("postgresql+asyncpg://localhost/app")
+_Session = async_sessionmaker(_engine, expire_on_commit=True)
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with _Session() as session:
+        yield session
 
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
-TableViewDep = Annotated[TableViewRequest, Depends()]
+"""Request-scoped AsyncSession. The single way endpoints touch the DB."""
 
-# ── Models ────────────────────────────────────────────────────────
+# TableViewRequest is a Pydantic model → FastAPI binds its fields as
+# query params automatically. No hand-written offset/limit/order plumbing.
+TableViewRequestDep = Annotated[TableViewRequest, Depends()]
+
+async def get_current_user(session: SessionDep) -> "User":
+    ...  # decode the bearer token, load the user — your auth, unchanged
+
+CurrentUserDep = Annotated["User", Depends(get_current_user)]
+
+# ── Models: the DTO ladder (Base → Create → Update → Response) ─────
 
 class ArticleBase(SQLModelBase):
     title: Str64
+    """Article title"""
     body: Text10K
+    """Article body (max 10k chars)"""
     is_published: bool = False
+    """Whether the article is publicly visible"""
 
 class Article(ArticleBase, UUIDTableBaseMixin, table=True):
     author_id: UUID = Field(foreign_key='user.id')
 
 class ArticleCreate(ArticleBase):
     pass
 
-class ArticleUpdate(ArticleBase):
-    title: Str64 | None = None       # Override to optional,
-    body: Text10K | None = None      # preserving the original
-    is_published: bool | None = None  # type constraints from Base
+# all_fields_optional flips every inherited field to ``T | None = None``
+# while preserving its Annotated constraints AND attribute docstrings —
+# no hand-maintained per-field overrides.
+class ArticleUpdate(ArticleBase, all_fields_optional=True):
+    pass
 
 class ArticleResponse(ArticleBase, UUIDIdDatetimeInfoMixin):
     author_id: UUID
 
+# ── Resource-as-dependency: wrap "load by id or 404" once, then the
+#    fetched ORM instance is just another injected parameter ────────
+
+async def get_article(session: SessionDep, article_id: UUID) -> Article:
+    return await Article.get_exist_one(session, article_id)
+
+ArticleDep = Annotated[Article, Depends(get_article)]
+"""The Article for {article_id}, or 404 — fetched before the handler runs."""
+
 # ── Endpoints ─────────────────────────────────────────────────────
 
 router = APIRouter(prefix="/articles", tags=["articles"])
@@ -175,32 +207,32 @@ async def create_article(
 
 @router.get("", response_model=ListResponse[ArticleResponse])
 async def list_articles(
-        session: SessionDep, table_view: TableViewDep,
+        session: SessionDep, table_view: TableViewRequestDep,
 ) -> ListResponse[Article]:
     return await Article.get_with_count(
         session,
         Article.is_published == True,
         table_view=table_view,
     )
 
+# article: ArticleDep — the 404 + fetch is the dependency's job, so the
+# single-resource handlers carry no lookup boilerplate at all.
 @router.get("/{article_id}", response_model=ArticleResponse)
-async def get_article(session: SessionDep, article_id: UUID) -> Article:
-    return await Article.get_exist_one(session, article_id)
+async def get_article_detail(article: ArticleDep) -> Article:
+    return article
 
 @router.patch("/{article_id}", response_model=ArticleResponse)
 async def update_article(
-        session: SessionDep, article_id: UUID, data: ArticleUpdate,
+        session: SessionDep, article: ArticleDep, data: ArticleUpdate,
 ) -> Article:
-    article = await Article.get_exist_one(session, article_id)
     return await article.update(session, data)
 
 @router.delete("/{article_id}")
-async def delete_article(session: SessionDep, article_id: UUID) -> None:
-    article = await Article.get_exist_one(session, article_id)
+async def delete_article(session: SessionDep, article: ArticleDep) -> None:
     await Article.delete(session, article)
 ```
 
-No manual SQL, no hand-written pagination logic, no boilerplate session management. The `TableViewDep` gives clients `offset`, `limit`, `desc`, `order`, and four time filters out of the box.
+No manual SQL, no hand-written pagination logic, no boilerplate session management. The `TableViewRequestDep` gives clients `offset`, `limit`, `desc`, `order`, and four time filters out of the box.
 
 **What the client gets from `GET /articles?offset=0&limit=10&desc=true`:**
 
@@ -395,7 +427,7 @@ class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMix
 
 @router.get("/notifications", response_model=ListResponse[NotificationBase])
 async def list_notifications(
-        session: SessionDep, user: CurrentUserDep, table_view: TableViewDep,
+        session: SessionDep, user: CurrentUserDep, table_view: TableViewRequestDep,
 ) -> ListResponse[Notification]:
     return await Notification.get_with_count(
         session,

pyproject.toml

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

src/sqlmodel_ext/__init__.py

@@ -20,7 +20,7 @@ class User(UserBase, UUIDTableBaseMixin, table=True):
     user = await user.save(session)
     users = await User.get(session, fetch_mode="all")
 """
-__version__ = "0.3.4"
+__version__ = "0.3.5"
 
 # Base
 from sqlmodel_ext.base import SQLModelBase, ExtraIgnoreModelBase

src/sqlmodel_ext/base.py

@@ -28,9 +28,15 @@
     is_table_model_class,
     get_relationship_to,
     FieldInfo as SQLModelFieldInfo,  # Internal API: stable since sqlmodel 0.0.22
+    FieldInfoMetadata,  # Internal API: pydantic-rebuild-safe sa_type carrier
     get_column_from_field,  # Internal API: stable since sqlmodel 0.0.22
 )
 
+# sqlmodel's FieldInfoMetadata fields default to sqlmodel's own Undefined
+# sentinel (distinct from pydantic_core PydanticUndefined imported above);
+# capture it to detect "sa_type not yet set" without importing sqlmodel internals.
+_FIM_UNSET_SA_TYPE = FieldInfoMetadata().sa_type
+
 # Import _compat for side effects (Python 3.14 monkey-patches)
 import sqlmodel_ext._compat  # noqa: F401
 
@@ -143,6 +149,49 @@ def _find_field_info_in_annotated(annotation: Any) -> SQLModelFieldInfo | None:
     return merged
 
 
+def _durably_set_sa_type(field_info: Any, sa_type: Any) -> None:
+    """
+    Inject ``sa_type`` so it survives Pydantic's model_fields rebuild.
+
+    Root cause this fixes: the metaclass extracts ``sa_type`` from
+    ``Array[T]`` / custom Annotated handlers and must hand it to SQLModel's
+    column builder. A plain ``setattr(field_info, 'sa_type', sa_type)`` is
+    LOST: ``SQLModelMetaclass.__new__`` (invoked from our ``super().__new__``)
+    runs ``get_column_from_field`` *before* step-7's SQLModelFieldInfo
+    restore, and Pydantic has by then rebuilt ``model_fields`` into fresh
+    FieldInfo objects that never saw the post-hoc attribute. The previous
+    code only fixed the no-``= Field(...)`` branch (c00696c); the explicit
+    ``Array[T] = Field(default_factory=list)`` form still raised
+    ``<class 'list'> has no matching SQLAlchemy type``.
+
+    Fix: write ``sa_type`` into a ``FieldInfoMetadata`` entry inside the
+    FieldInfo's pydantic ``metadata`` list — the exact channel SQLModel's
+    own ``Field(sa_type=...)`` uses and which ``get_sqlalchemy_type``
+    (via ``_get_sqlmodel_field_value``) reads *first*. Pydantic preserves
+    the ``metadata`` list across rebuilds, so the type survives into the
+    column build. The instance attribute is also set as a belt-and-braces
+    fallback for any direct ``getattr(field_info, 'sa_type')`` reader.
+
+    :param field_info: target FieldInfo (user's Field or recovered Annotated FI)
+    :param sa_type: SQLAlchemy type extracted from the annotation handler
+    """
+    md = list(getattr(field_info, 'metadata', None) or [])
+    existing = next(
+        (m for m in md if isinstance(m, FieldInfoMetadata)), None
+    )
+    if existing is not None:
+        if existing.sa_type is _FIM_UNSET_SA_TYPE:
+            existing.sa_type = sa_type
+    else:
+        md.append(FieldInfoMetadata(sa_type=sa_type))
+        field_info.metadata = md
+    if getattr(field_info, 'sa_type', Undefined) is Undefined:
+        try:
+            field_info.sa_type = sa_type
+        except (AttributeError, TypeError):
+            pass
+
+
 def _make_annotation_optional(annotation: typing.Any) -> typing.Any:
     """
     Convert type annotation to optional: ``T → T | None``
@@ -602,14 +651,16 @@ def __new__(cls, name, bases, attrs, **kwargs):
                     # 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)
+                        _durably_set_sa_type(annotated_fi, 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)
+                    # Explicit ``Array[T] = Field(default_factory=list)`` form.
+                    # Must inject sa_type via the pydantic-rebuild-safe
+                    # FieldInfoMetadata channel — plain setattr is dropped
+                    # before SQLModel's column build (see _durably_set_sa_type).
+                    _durably_set_sa_type(field_value, sa_type)
 
         # 5. Save SQLModel FieldInfo from Annotated fields before super().__new__(),
         # because Pydantic rebuilds model_fields with plain FieldInfo that lacks

tests/test_array_explicit_field_sa_type.py

@@ -0,0 +1,116 @@
+"""
+Regression: explicit ``Array[T] = Field(default_factory=list)`` must build a
+PostgreSQL ``ARRAY`` column (not raise ``<class 'list'> has no matching
+SQLAlchemy type``).
+
+Root cause (sqlmodel_ext.base metaclass sa_type injection loop, the
+``elif isinstance(field_value, FieldInfo)`` branch — i.e. the user wrote an
+explicit ``= Field(...)``):
+
+c00696c fixed only the ``field_value is Undefined`` (no ``= Field(...)``)
+branch. The explicit-Field branch still did a plain
+``setattr(field_value, 'sa_type', sa_type)``. That attribute is LOST:
+``SQLModelMetaclass.__new__`` (reached via the metaclass ``super().__new__``)
+runs ``get_column_from_field`` *before* step-7's SQLModelFieldInfo restore,
+and Pydantic has by then rebuilt ``model_fields`` into fresh FieldInfo
+objects that never saw the post-hoc attribute. ``get_sqlalchemy_type``
+reads ``sa_type`` via ``_get_sqlmodel_field_value``, which prefers a
+``FieldInfoMetadata`` entry in the FieldInfo's pydantic ``metadata`` list
+(the rebuild-safe channel SQLModel's own ``Field(sa_type=...)`` uses).
+
+Fix: ``_durably_set_sa_type()`` writes ``sa_type`` into a
+``FieldInfoMetadata`` on the FieldInfo's ``metadata`` list (plus the
+instance attribute as a fallback), so it survives Pydantic's rebuild into
+the column build. Applied to both the explicit-Field branch and the
+recovered-Annotated-FieldInfo path.
+
+This locks in the real-world trigger: an ``Array[StrEnum] =
+Field(default_factory=list)`` column on a ``table=True`` model that also
+inherits a non-table base declaring the same field as a plain ``list``
+(the contract-base / persistence-table split). Such fields were silently
+mistyped (or raised ``<class 'list'> has no matching SQLAlchemy type``),
+500-ing every INSERT into that table.
+"""
+from __future__ import annotations
+
+from enum import StrEnum
+
+import sqlalchemy as sa
+from sqlmodel import Field
+
+from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin
+from sqlmodel_ext.field_types.dialects.postgresql import Array
+
+
+# Module-level enums: with ``from __future__ import annotations`` all
+# annotations are lazy strings; the metaclass resolves them via
+# ``get_type_hints`` against module globals, so referenced names MUST be
+# module-level (function-local names are unresolvable).
+class ScopeLikeEnum(StrEnum):
+    a = "a:b"
+    c = "c:d"
+
+
+DynScopeEnum = StrEnum(
+    "DynScopeEnum",
+    {f"r{i}_{a}": f"r{i}:{a}" for i in range(3) for a in ("read", "write")},
+)
+
+
+class TestExplicitFieldArraySaType:
+    def test_lib_documented_array_str_pattern(self) -> None:
+        """The README/array.py documented form on a table model."""
+
+        class DocTags(SQLModelBase, TableBaseMixin, table=True):
+            tags: Array[str] = Field(default_factory=list)
+
+        col_type = DocTags.__table__.c.tags.type
+        assert isinstance(col_type, sa.ARRAY)
+        assert isinstance(col_type.item_type, sa.String)
+
+    def test_array_enum_overrides_inherited_plain_list(self) -> None:
+        """
+        Production shape: non-table contract base declares ``scopes`` as a
+        plain ``list[Enum]``; the table subclass overrides it with
+        ``Array[Enum]`` to get a real PG ``ARRAY(Enum)`` column.
+        """
+        class ContractBase(SQLModelBase):
+            is_admin: bool = False
+            scopes: list[ScopeLikeEnum] = Field(default_factory=list)
+
+        class ScopeTable(ContractBase, TableBaseMixin, table=True):
+            scopes: Array[ScopeLikeEnum] = Field(default_factory=list)
+            tags: Array[str] = Field(default_factory=list)
+
+        scopes_type = ScopeTable.__table__.c.scopes.type
+        assert isinstance(scopes_type, sa.ARRAY)
+        assert isinstance(scopes_type.item_type, sa.Enum)
+        assert isinstance(ScopeTable.__table__.c.tags.type, sa.ARRAY)
+
+        # default_factory survives (not silently is_required=True)
+        inst = ScopeTable(scopes=[ScopeLikeEnum.a], tags=["x"])
+        assert inst.scopes == [ScopeLikeEnum.a]
+        assert ScopeTable().scopes == []
+
+    def test_array_enum_on_uuid_mixin(self) -> None:
+        """Dynamically-built StrEnum (mirrors ScopeValueEnum) + UUID PK mixin."""
+        class ScopeRow(SQLModelBase, UUIDTableBaseMixin, table=True):
+            scopes: Array[DynScopeEnum] = Field(default_factory=list)
+
+        col_type = ScopeRow.__table__.c.scopes.type
+        assert isinstance(col_type, sa.ARRAY)
+        assert isinstance(col_type.item_type, sa.Enum)
+
+    def test_non_array_field_unaffected(self) -> None:
+        """Guard: ordinary scalar Field columns keep working unchanged."""
+
+        class Plain(SQLModelBase, TableBaseMixin, table=True):
+            name: str = Field(max_length=32, index=True)
+            qty: int = 0
+
+        assert Plain.__table__.c.name.type.__class__.__name__ in (
+            "AutoString",
+            "String",
+            "VARCHAR",
+        )
+        assert isinstance(Plain.__table__.c.qty.type, sa.Integer)