fastapi-toolsets 2.1.0__tar.gz → 2.2.1__tar.gz

{fastapi_toolsets-2.1.0 → fastapi_toolsets-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-toolsets
-Version: 2.1.0
+Version: 2.2.1
 Summary: Production-ready utilities for FastAPI applications
 Keywords: fastapi,sqlalchemy,postgresql
 Author: d3vyce

{fastapi_toolsets-2.1.0 → fastapi_toolsets-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "2.1.0"
+version = "2.2.1"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"

{fastapi_toolsets-2.1.0 → fastapi_toolsets-2.2.1}/src/fastapi_toolsets/__init__.py

@@ -21,4 +21,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "2.1.0"
+__version__ = "2.2.1"

{fastapi_toolsets-2.1.0 → fastapi_toolsets-2.2.1}/src/fastapi_toolsets/crud/factory.py

@@ -14,7 +14,6 @@ from typing import Any, ClassVar, Generic, Literal, Self, cast, overload
 from fastapi import Query
 from pydantic import BaseModel
 from sqlalchemy import Date, DateTime, Float, Integer, Numeric, Uuid, and_, func, select
-from sqlalchemy import delete as sql_delete
 from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy.exc import NoResultFound
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -80,13 +79,13 @@ class AsyncCrud(Generic[ModelType]):
     facet_fields: ClassVar[Sequence[FacetFieldType] | None] = None
     order_fields: ClassVar[Sequence[QueryableAttribute[Any]] | None] = None
     m2m_fields: ClassVar[M2MFieldType | None] = None
-    default_load_options: ClassVar[list[ExecutableOption] | None] = None
+    default_load_options: ClassVar[Sequence[ExecutableOption] | None] = None
     cursor_column: ClassVar[Any | None] = None
 
     @classmethod
     def _resolve_load_options(
-        cls, load_options: list[ExecutableOption] | None
-    ) -> list[ExecutableOption] | None:
+        cls, load_options: Sequence[ExecutableOption] | None
+    ) -> Sequence[ExecutableOption] | None:
         """Return load_options if provided, else fall back to default_load_options."""
         if load_options is not None:
             return load_options
@@ -361,7 +360,7 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         with_for_update: bool = False,
-        load_options: list[ExecutableOption] | None = None,
+        load_options: Sequence[ExecutableOption] | None = None,
         schema: type[SchemaType],
     ) -> Response[SchemaType]: ...
 
@@ -375,7 +374,7 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         with_for_update: bool = False,
-        load_options: list[ExecutableOption] | None = None,
+        load_options: Sequence[ExecutableOption] | None = None,
         schema: None = ...,
     ) -> ModelType: ...
 
@@ -388,7 +387,7 @@ class AsyncCrud(Generic[ModelType]):
         joins: JoinType | None = None,
         outer_join: bool = False,
         with_for_update: bool = False,
-        load_options: list[ExecutableOption] | None = None,
+        load_options: Sequence[ExecutableOption] | None = None,
         schema: type[BaseModel] | None = None,
     ) -> ModelType | Response[Any]:
         """Get exactly one record. Raises NotFoundError if not found.
@@ -410,6 +409,82 @@ class AsyncCrud(Generic[ModelType]):
             NotFoundError: If no record found
             MultipleResultsFound: If more than one record found
         """
+        result = await cls.get_or_none(
+            session,
+            filters,
+            joins=joins,
+            outer_join=outer_join,
+            with_for_update=with_for_update,
+            load_options=load_options,
+            schema=schema,
+        )
+        if result is None:
+            raise NotFoundError()
+        return result
+
+    @overload
+    @classmethod
+    async def get_or_none(  # pragma: no cover
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any],
+        *,
+        joins: JoinType | None = None,
+        outer_join: bool = False,
+        with_for_update: bool = False,
+        load_options: Sequence[ExecutableOption] | None = None,
+        schema: type[SchemaType],
+    ) -> Response[SchemaType] | None: ...
+
+    @overload
+    @classmethod
+    async def get_or_none(  # pragma: no cover
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any],
+        *,
+        joins: JoinType | None = None,
+        outer_join: bool = False,
+        with_for_update: bool = False,
+        load_options: Sequence[ExecutableOption] | None = None,
+        schema: None = ...,
+    ) -> ModelType | None: ...
+
+    @classmethod
+    async def get_or_none(
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any],
+        *,
+        joins: JoinType | None = None,
+        outer_join: bool = False,
+        with_for_update: bool = False,
+        load_options: Sequence[ExecutableOption] | None = None,
+        schema: type[BaseModel] | None = None,
+    ) -> ModelType | Response[Any] | None:
+        """Get exactly one record, or ``None`` if not found.
+
+        Like :meth:`get` but returns ``None`` instead of raising
+        :class:`~fastapi_toolsets.exceptions.NotFoundError` when no record
+        matches the filters.
+
+        Args:
+            session: DB async session
+            filters: List of SQLAlchemy filter conditions
+            joins: List of (model, condition) tuples for joining related tables
+            outer_join: Use LEFT OUTER JOIN instead of INNER JOIN
+            with_for_update: Lock the row for update
+            load_options: SQLAlchemy loader options (e.g., selectinload)
+            schema: Pydantic schema to serialize the result into. When provided,
+                the result is automatically wrapped in a ``Response[schema]``.
+
+        Returns:
+            Model instance, ``Response[schema]`` when ``schema`` is given,
+            or ``None`` when no record matches.
+
+        Raises:
+            MultipleResultsFound: If more than one record found
+        """
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
         q = q.where(and_(*filters))
@@ -419,12 +494,40 @@ class AsyncCrud(Generic[ModelType]):
             q = q.with_for_update()
         result = await session.execute(q)
         item = result.unique().scalar_one_or_none()
-        if not item:
-            raise NotFoundError()
-        result = cast(ModelType, item)
+        if item is None:
+            return None
+        db_model = cast(ModelType, item)
         if schema:
-            return Response(data=schema.model_validate(result))
-        return result
+            return Response(data=schema.model_validate(db_model))
+        return db_model
+
+    @overload
+    @classmethod
+    async def first(  # pragma: no cover
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any] | None = None,
+        *,
+        joins: JoinType | None = None,
+        outer_join: bool = False,
+        with_for_update: bool = False,
+        load_options: Sequence[ExecutableOption] | None = None,
+        schema: type[SchemaType],
+    ) -> Response[SchemaType] | None: ...
+
+    @overload
+    @classmethod
+    async def first(  # pragma: no cover
+        cls: type[Self],
+        session: AsyncSession,
+        filters: list[Any] | None = None,
+        *,
+        joins: JoinType | None = None,
+        outer_join: bool = False,
+        with_for_update: bool = False,
+        load_options: Sequence[ExecutableOption] | None = None,
+        schema: None = ...,
+    ) -> ModelType | None: ...
 
     @classmethod
     async def first(
@@ -434,8 +537,10 @@ class AsyncCrud(Generic[ModelType]):
         *,
         joins: JoinType | None = None,
         outer_join: bool = False,
-        load_options: list[ExecutableOption] | None = None,
-    ) -> ModelType | None:
+        with_for_update: bool = False,
+        load_options: Sequence[ExecutableOption] | None = None,
+        schema: type[BaseModel] | None = None,
+    ) -> ModelType | Response[Any] | None:
         """Get the first matching record, or None.
 
         Args:
@@ -443,10 +548,14 @@ class AsyncCrud(Generic[ModelType]):
             filters: List of SQLAlchemy filter conditions
             joins: List of (model, condition) tuples for joining related tables
             outer_join: Use LEFT OUTER JOIN instead of INNER JOIN
-            load_options: SQLAlchemy loader options
+            with_for_update: Lock the row for update
+            load_options: SQLAlchemy loader options (e.g., selectinload)
+            schema: Pydantic schema to serialize the result into. When provided,
+                the result is automatically wrapped in a ``Response[schema]``.
 
         Returns:
-            Model instance or None
+            Model instance, ``Response[schema]`` when ``schema`` is given,
+            or ``None`` when no record matches.
         """
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
@@ -454,8 +563,16 @@ class AsyncCrud(Generic[ModelType]):
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
             q = q.options(*resolved)
+        if with_for_update:
+            q = q.with_for_update()
         result = await session.execute(q)
-        return cast(ModelType | None, result.unique().scalars().first())
+        item = result.unique().scalars().first()
+        if item is None:
+            return None
+        db_model = cast(ModelType, item)
+        if schema:
+            return Response(data=schema.model_validate(db_model))
+        return db_model
 
     @classmethod
     async def get_multi(
@@ -465,7 +582,7 @@ class AsyncCrud(Generic[ModelType]):
         filters: list[Any] | None = None,
         joins: JoinType | None = None,
         outer_join: bool = False,
-        load_options: list[ExecutableOption] | None = None,
+        load_options: Sequence[ExecutableOption] | None = None,
         order_by: OrderByClause | None = None,
         limit: int | None = None,
         offset: int | None = None,
@@ -674,8 +791,10 @@ class AsyncCrud(Generic[ModelType]):
             ``None``, or ``Response[None]`` when ``return_response=True``.
         """
         async with get_transaction(session):
-            q = sql_delete(cls.model).where(and_(*filters))
-            await session.execute(q)
+            result = await session.execute(select(cls.model).where(and_(*filters)))
+            objects = result.scalars().all()
+            for obj in objects:
+                await session.delete(obj)
         if return_response:
             return Response(data=None)
         return None
@@ -741,7 +860,7 @@ class AsyncCrud(Generic[ModelType]):
         filters: list[Any] | None = None,
         joins: JoinType | None = None,
         outer_join: bool = False,
-        load_options: list[ExecutableOption] | None = None,
+        load_options: Sequence[ExecutableOption] | None = None,
         order_by: OrderByClause | None = None,
         page: int = 1,
         items_per_page: int = 20,
@@ -852,7 +971,7 @@ class AsyncCrud(Generic[ModelType]):
         filters: list[Any] | None = None,
         joins: JoinType | None = None,
         outer_join: bool = False,
-        load_options: list[ExecutableOption] | None = None,
+        load_options: Sequence[ExecutableOption] | None = None,
         order_by: OrderByClause | None = None,
         items_per_page: int = 20,
         search: str | SearchConfig | None = None,
@@ -993,7 +1112,7 @@ def CrudFactory(
     facet_fields: Sequence[FacetFieldType] | None = None,
     order_fields: Sequence[QueryableAttribute[Any]] | None = None,
     m2m_fields: M2MFieldType | None = None,
-    default_load_options: list[ExecutableOption] | None = None,
+    default_load_options: Sequence[ExecutableOption] | None = None,
     cursor_column: Any | None = None,
 ) -> type[AsyncCrud[ModelType]]:
     """Create a CRUD class for a specific model.
@@ -1092,12 +1211,26 @@ def CrudFactory(
         )
         ```
     """
+    pk_key = model.__mapper__.primary_key[0].key
+    assert pk_key is not None
+    pk_col = getattr(model, pk_key)
+
+    if searchable_fields is None:
+        effective_searchable = [pk_col]
+    else:
+        existing_keys = {f.key for f in searchable_fields if not isinstance(f, tuple)}
+        effective_searchable = (
+            [pk_col, *searchable_fields]
+            if pk_key not in existing_keys
+            else list(searchable_fields)
+        )
+
     cls = type(
         f"Async{model.__name__}Crud",
         (AsyncCrud,),
         {
             "model": model,
-            "searchable_fields": searchable_fields,
+            "searchable_fields": effective_searchable,
             "facet_fields": facet_fields,
             "order_fields": order_fields,
             "m2m_fields": m2m_fields,