sqlmodel-ext 0.3.4__tar.gz → 0.3.5__tar.gz

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.3.4
+Version: 0.3.5
 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
@@ -170,10 +170,12 @@ 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 (
@@ -181,17 +183,37 @@ from sqlmodel_ext import (
     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')
@@ -199,14 +221,24 @@ class Article(ArticleBase, UUIDTableBaseMixin, table=True):
 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"])
@@ -220,7 +252,7 @@ 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,
@@ -228,24 +260,24 @@ async def list_articles(
         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`:**
 
@@ -440,7 +472,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,

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.3.5}/README.md

@@ -125,10 +125,12 @@ 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 (
@@ -136,17 +138,37 @@ from sqlmodel_ext import (
     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')
@@ -154,14 +176,24 @@ class Article(ArticleBase, UUIDTableBaseMixin, table=True):
 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,7 +207,7 @@ 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,
@@ -183,24 +215,24 @@ async def list_articles(
         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,

{sqlmodel_ext-0.3.4 → sqlmodel_ext-0.3.5}/docs/en/index.md

@@ -34,12 +34,3 @@ features:
   - title: Safe & Reliable
     details: Optimistic locking for concurrency control, @requires_relations to prevent MissingGreenlet, and AST static analysis at startup
 ---
-
-## Design orientation
-
-sqlmodel-ext is not a new ORM. It is a set of **opt-in Mixins** layered on top of SQLModel / Pydantic v2 / SQLAlchemy 2.0. The library only introduces two kinds of machinery:
-
-- **Metaclass enhancements** — automatic SQLAlchemy column setup driven by `Annotated` type hints, `mapper_args` merging, on-demand `*UpdateRequest` DTO generation, attribute-docstring inheritance, and a Python 3.14 (PEP 649) compatibility patch.
-- **Composable Mixins** — `TableBaseMixin` (async CRUD), `PolymorphicBaseMixin` (JTI/STI), `OptimisticLockMixin` (version-column concurrency), `RelationPreloadMixin` (eager loading), `CachedTableBaseMixin` (Redis two-tier cache). Each Mixin stands alone and has no hard dependency on the others.
-
-The underlying `Session`, `select()`, query construction, and migration tooling remain native SQLAlchemy — there is no custom DSL, and the library does not take over `engine` / `session` lifecycle. In practice that means you can drop a single Mixin into an existing SQLModel/SQLAlchemy project without rewriting your data-access layer.