fastapi-sqlalchemy-toolkit 0.8.1__tar.gz → 0.8.2__tar.gz

{fastapi_sqlalchemy_toolkit-0.8.1 → fastapi_sqlalchemy_toolkit-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi_sqlalchemy_toolkit
-Version: 0.8.1
+Version: 0.8.2
 Summary: FastAPI SQLAlchemy Toolkit
 Project-URL: Homepage, https://github.com/e-kondr01/fastapi-sqlalchemy-toolkit
 Author-email: Egor Kondrashov <e.kondr01@gmail.com>

{fastapi_sqlalchemy_toolkit-0.8.1 → fastapi_sqlalchemy_toolkit-0.8.2}/docs/filtering.md

@@ -206,6 +206,80 @@ Unlike the `list` method, the `filter` method:
 2. Does not have the `filter_expressions` parameter, i.e., it will not perform `join`,
     necessary for filtering by fields of related models.
 
+### Filtering with optional expressions
+
+The `optional_where` parameter of the `list` and `paginated_list` methods accepts
+SQLAlchemy expressions that may contain `None` values. Filters with a `None` value
+are automatically skipped.
+
+This is useful in list API endpoints where filtering is optional — if the query parameter
+is not provided (i.e., its value is `None`), the filter is not applied.
+
+The `optional_where` parameter supports three kinds of expressions:
+
+**Case 1: Simple expression** (`MyModel.field == value`)
+
+If `value` is `None`, the filter is skipped entirely. Otherwise it is applied as-is.
+
+```python
+@router.get("/parents")
+async def get_parents(
+    session: Session,
+    title: str | None = None,
+) -> list[ParentListSchema]:
+    return await parent_manager.list(
+        session,
+        optional_where=(Parent.title == title),
+    )
+```
+
+`GET /parents` — no filter applied, all `Parent` objects are returned.
+
+`GET /parents?title=foo` — only `Parent` objects with `title = 'foo'` are returned.
+
+**Case 2: Function or operator expression** (`func.date(MyModel.field) == value`, `MyModel.field.ilike(value)`)
+
+Same behaviour as Case 1 — if `value` is `None`, the filter is skipped.
+
+```python
+@router.get("/parents")
+async def get_parents(
+    session: Session,
+    created_at_date: date | None = None,
+) -> list[ParentListSchema]:
+    return await parent_manager.list(
+        session,
+        optional_where=(func.date(Parent.created_at) == created_at_date),
+    )
+```
+
+**Case 3: Compound expression with `&` or `|`** (`(expr1) & (expr2)`, `(expr1) | (expr2)`)
+
+Sub-expressions whose values are `None` are excluded. The remaining sub-expressions
+are combined using the original operator (`&` or `|`). If all values are `None`,
+the filter is skipped entirely.
+
+```python
+@router.get("/parents")
+async def get_parents(
+    session: Session,
+    title: str | None = None,
+    slug: str | None = None,
+) -> list[ParentListSchema]:
+    return await parent_manager.list(
+        session,
+        optional_where=(Parent.title == title) & (Parent.slug == slug),
+    )
+```
+
+`GET /parents` — no filter applied, all `Parent` objects are returned.
+
+`GET /parents?title=foo` — only the `title` filter is applied.
+
+`GET /parents?title=foo&slug=bar` — both filters are applied with `AND`.
+
+> **Note**: nesting of compound expressions (e.g. `(a & b) | c`) is not supported.
+
 ### Filtering by `null` via API
 
 If in a list API endpoint, you need to be able to filter the field value

{fastapi_sqlalchemy_toolkit-0.8.1 → fastapi_sqlalchemy_toolkit-0.8.2}/docs/ru/filtering.md

@@ -77,7 +77,9 @@ WHERE child.slug = :slug_1
 а не только те, у которых `slug is null`. Поэтому метод `list` (`paginated_list`) отбрасывает фильтрацию
 по этому параметру, если его значение не передано.
 
-## Более сложная фильтрация
+## Фильтрация с выражениями
+
+### filter_expressions
 
 Чтобы использовать фильтрацию не только по точному соответствию атрибуту модели,
 в методах `list` и `paginated_list` можно передать параметр `filter_expressions`.
@@ -182,6 +184,79 @@ WHERE lower(parent.title) LIKE lower(:title_1)
 **Важно**: работает только для моделей, напрямую связанных с основной, и только тогда, когда
 эти модели связывает единственный внешний ключ.
 
+### optional_where
+
+Параметр `optional_where` методов `list` и `paginated_list` принимает выражения SQLAlchemy,
+в которых значения фильтров могут быть `None`. Фильтры со значением `None` автоматически пропускаются.
+
+Это удобно использовать в списочных API эндпоинтах, где фильтрация необязательна —
+если параметр запроса не передан (т. е. его значение `None`), фильтр не применяется.
+
+Параметр `optional_where` поддерживает три вида выражений:
+
+**Кейс 1: Простое выражение** (`MyModel.field == value`)
+
+Если `value` равно `None`, фильтр пропускается. Иначе применяется как есть.
+
+```python
+@router.get("/parents")
+async def get_parents(
+    session: Session,
+    title: str | None = None,
+) -> list[ParentListSchema]:
+    return await parent_manager.list(
+        session,
+        optional_where=(Parent.title == title),
+    )
+```
+
+Запрос `GET /parents` — фильтр не применяется, возвращаются все объекты `Parent`.
+
+Запрос `GET /parents?title=foo` — возвращаются только объекты `Parent` с `title = 'foo'`.
+
+**Кейс 2: Выражение с функцией или оператором** (`func.date(MyModel.field) == value`, `MyModel.field.ilike(value)`)
+
+Аналогично кейсу 1 — если `value` равно `None`, фильтр пропускается.
+
+```python
+@router.get("/parents")
+async def get_parents(
+    session: Session,
+    created_at_date: date | None = None,
+) -> list[ParentListSchema]:
+    return await parent_manager.list(
+        session,
+        optional_where=(func.date(Parent.created_at) == created_at_date),
+    )
+```
+
+**Кейс 3: Составное выражение через `&` или `|`** (`(expr1) & (expr2)`, `(expr1) | (expr2)`)
+
+Части выражения, значения которых равны `None`, исключаются. Оставшиеся части объединяются
+с использованием исходного оператора (`&` или `|`). Если все значения `None`,
+фильтр пропускается полностью.
+
+```python
+@router.get("/parents")
+async def get_parents(
+    session: Session,
+    title: str | None = None,
+    slug: str | None = None,
+) -> list[ParentListSchema]:
+    return await parent_manager.list(
+        session,
+        optional_where=(Parent.title == title) & (Parent.slug == slug),
+    )
+```
+
+Запрос `GET /parents` — фильтр не применяется, возвращаются все объекты `Parent`.
+
+Запрос `GET /parents?title=foo` — применяется только фильтр по `title`.
+
+Запрос `GET /parents?title=foo&slug=bar` — применяются оба фильтра через `AND`.
+
+> **Примечание**: вложенные составные выражения (например, `(a & b) | c`) не поддерживаются.
+
 ## Фильтрация без дополнительной обработки
 
 Для фильтрации без дополнительной обработки в методах `list` и `paginated_list` можно

{fastapi_sqlalchemy_toolkit-0.8.1 → fastapi_sqlalchemy_toolkit-0.8.2}/fastapi_sqlalchemy_toolkit/model_manager.py

@@ -16,6 +16,7 @@ from sqlalchemy import (
     delete,
     func,
     insert,
+    or_,
     select,
     update,
 )
@@ -25,7 +26,7 @@ from sqlalchemy.orm import DeclarativeBase, contains_eager, load_only
 from sqlalchemy.orm.attributes import InstrumentedAttribute
 from sqlalchemy.orm.relationships import Relationship
 from sqlalchemy.sql import Select
-from sqlalchemy.sql.elements import UnaryExpression
+from sqlalchemy.sql.elements import Null, UnaryExpression
 from sqlalchemy.sql.expression import BinaryExpression, ColumnElement
 from sqlalchemy.sql.functions import Function
 from sqlalchemy.sql.schema import ScalarElementColumnDefault
@@ -532,6 +533,7 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
         ) = ...,
         options: List[Any] | Any | None = ...,
         where: Any | None = ...,
+        optional_where: Any | None = ...,
         base_stmt: None = ...,
         transformer: Callable | None = ...,
         **simple_filters: Any,
@@ -549,6 +551,7 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
         ) = ...,
         options: List[Any] | Any | None = ...,
         where: Any | None = ...,
+        optional_where: Any | None = ...,
         base_stmt: Select = ...,
         transformer: Callable | None = ...,
         **simple_filters: Any,
@@ -565,6 +568,7 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
         ) = None,
         options: List[Any] | Any | None = None,
         where: Any | None = None,
+        optional_where: Any | None = None,
         base_stmt: Select | None = None,
         transformer: Callable | None = None,
         **simple_filters: Any,
@@ -590,6 +594,12 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
 
         :param where: выражение, которое будет передано в метод .where() SQLAlchemy
 
+        :param optional_where: выражение SQLAlchemy, в котором фильтры со значением None
+        пропускаются. Поддерживает простые выражения (MyModel.field == value),
+        выражения с функциями (func.date(MyModel.field) == value) и составные
+        выражения через & или | ((expr1) & (expr2)). См. раздел "фильтрация"
+        в документации.
+
         :param base_stmt: объект Select для SQL запроса. Если передан, то метод вернёт
         страницу Row, а не ModelT.
         Примечание: фильтрация и сортировка по связанным моделям скорее всего
@@ -630,6 +640,10 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
             else:
                 stmt = stmt.filter(filter_expression(value))
 
+        processed_optional_where = self.handle_optional_where(optional_where)
+        if processed_optional_where is not None:
+            stmt = stmt.where(processed_optional_where)
+
         return await paginate(session, stmt, transformer=transformer)
 
     @overload
@@ -730,6 +744,7 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
         ) = ...,
         options: List[Any] | Any | None = ...,
         where: Any | None = ...,
+        optional_where: Any | None = ...,
         base_stmt: None = ...,
         limit: int | None = ...,
         offset: int | None = ...,
@@ -750,6 +765,7 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
         ) = ...,
         options: List[Any] | Any | None = ...,
         where: Any | None = ...,
+        optional_where: Any | None = ...,
         base_stmt: Select = ...,
         limit: int | None = ...,
         offset: int | None = ...,
@@ -769,6 +785,7 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
         ) = None,
         options: List[Any] | Any | None = None,
         where: Any | None = None,
+        optional_where: Any | None = None,
         base_stmt: Select | None = None,
         limit: int | None = None,
         offset: int | None = None,
@@ -797,6 +814,12 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
 
         :param where: выражение, которое будет передано в метод .where() SQLAlchemy
 
+        :param optional_where: выражение SQLAlchemy, в котором фильтры со значением None
+        пропускаются. Поддерживает простые выражения (MyModel.field == value),
+        выражения с функциями (func.date(MyModel.field) == value) и составные
+        выражения через & или | ((expr1) & (expr2)). См. раздел "фильтрация"
+        в документации.
+
         :param unique: определяет необходимость вызова метода .unique()
         у результата SQLAlchemy
 
@@ -848,6 +871,10 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
             else:
                 stmt = stmt.filter(filter_expression(value))
 
+        processed_optional_where = self.handle_optional_where(optional_where)
+        if processed_optional_where is not None:
+            stmt = stmt.where(processed_optional_where)
+
         result = await session.execute(stmt)
 
         if base_stmt is None:
@@ -1208,6 +1235,44 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
         related_pk = _get_model_pk(related_model)
         return relationship.any(related_pk.in_(value))
 
+    @staticmethod
+    def handle_optional_where(optional_where: Any) -> Any:
+        """
+        Обрабатывает выражение optional_where, пропуская фильтры, значения которых None.
+
+        Поддерживает:
+        1. Простые выражения вида MyModel.field == value
+        2. Выражения с функциями/операторами вида func.date(MyModel.field) == value
+        3. Составные выражения вида (expr1) & (expr2) или (expr1) | (expr2)
+           (без вложенности)
+
+        Если value равно None, фильтр не применяется.
+        В составных выражениях исключаются части с value == None,
+        при этом оператор & или | сохраняется.
+        """
+        if optional_where is None:
+            return None
+
+        # compound expression (& or |) — has .clauses attribute
+        if hasattr(optional_where, "clauses"):
+            remaining = [
+                clause
+                for clause in optional_where.clauses
+                if not isinstance(clause.right, Null)
+            ]
+            if not remaining:
+                return None
+            if len(remaining) == 1:
+                return remaining[0]
+            if optional_where.operator.__name__ == "and_":
+                return and_(*remaining)
+            return or_(*remaining)
+
+        # simple binary expression
+        if isinstance(getattr(optional_where, "right", None), Null):
+            return None
+        return optional_where
+
     def assemble_stmt(
         self,
         base_stmt: Select | None = None,

{fastapi_sqlalchemy_toolkit-0.8.1 → fastapi_sqlalchemy_toolkit-0.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi_sqlalchemy_toolkit"
-version = "0.8.1"
+version = "0.8.2"
 authors = [
   { name="Egor Kondrashov", email="e.kondr01@gmail.com" },
 ]

{fastapi_sqlalchemy_toolkit-0.8.1 → fastapi_sqlalchemy_toolkit-0.8.2}/tests/test_public_methods.py

@@ -31,9 +31,9 @@ async def test_get(session: AsyncSession):
     category_to_check = await session.execute(
         select(Category).where(Category.title == "test-get-category-title")
     )
-    assert category == category_to_check.scalars().first(), (
-        "Got not equal to object in database"
-    )
+    assert (
+        category == category_to_check.scalars().first()
+    ), "Got not equal to object in database"
 
     nonexistent = await session.execute(
         select(Category).where(Category.title == "nonexistent-test-get-category-title")
@@ -279,9 +279,9 @@ async def test_create(session: AsyncSession):
     category_to_check = await session.execute(
         select(Category).where(Category.title == "test-create-category-title")
     )
-    assert created == category_to_check.scalars().first(), (
-        "Created not equal to object in database"
-    )
+    assert (
+        created == category_to_check.scalars().first()
+    ), "Created not equal to object in database"
 
 
 async def test_create_unique_filed_validation(session: AsyncSession):
@@ -339,9 +339,9 @@ async def test_update(session: AsyncSession):
     category_to_check = await session.execute(
         select(Category).where(Category.title == "UPDATED-test-update-category-title")
     )
-    assert updated == category_to_check.scalars().first(), (
-        "Updated not equal to object in database"
-    )
+    assert (
+        updated == category_to_check.scalars().first()
+    ), "Updated not equal to object in database"
 
 
 async def test_update_unique_filed_validation(session: AsyncSession):
@@ -729,6 +729,267 @@ async def test_list_with_where(session: AsyncSession):
         assert parent.title == same_title
 
 
+# ########################################################################
+# Tests for optional_where parameter
+# ########################################################################
+
+
+async def test_list_with_optional_where_case1_applied(session: AsyncSession):
+    """Case 1: simple expression, value is not None — filter is applied."""
+    target_title = "optional-where-title-target"
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": target_title,
+                "slug": "optional-where-slug1",
+            },
+            {
+                "title": "optional-where-title-other",
+                "slug": "optional-where-slug2",
+            },
+        ],
+    )
+    await session.commit()
+
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(Parent.title == target_title),
+    )
+    assert len(parents) == 1
+    assert parents[0].title == target_title
+
+
+async def test_list_with_optional_where_case1_skipped(session: AsyncSession):
+    """Case 1: simple expression, value is None — filter is skipped (all returned)."""
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": "optional-where-title-1",
+                "slug": "optional-where-slug1",
+            },
+            {
+                "title": "optional-where-title-2",
+                "slug": "optional-where-slug2",
+            },
+        ],
+    )
+    await session.commit()
+
+    none_value = None
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(Parent.title == none_value),
+    )
+    assert len(parents) == 2
+
+
+async def test_list_with_optional_where_case2_applied(session: AsyncSession):
+    """Case 2: func expression, value is not None — filter is applied."""
+    from sqlalchemy import func
+
+    target_slug = "optional-where-func-slug1"
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": "optional-where-func-title-1",
+                "slug": target_slug,
+            },
+            {
+                "title": "optional-where-func-title-2",
+                "slug": "optional-where-func-slug2",
+            },
+        ],
+    )
+    await session.commit()
+
+    # Use func.lower() on the slug to simulate a function expression
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(func.lower(Parent.slug) == target_slug),
+    )
+    assert len(parents) == 1
+    assert parents[0].slug == target_slug
+
+
+async def test_list_with_optional_where_case2_skipped(session: AsyncSession):
+    """Case 2: func expression, value is None — filter is skipped (all returned)."""
+    from sqlalchemy import func
+
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": "optional-where-func-title-1",
+                "slug": "optional-where-func-slug1",
+            },
+            {
+                "title": "optional-where-func-title-2",
+                "slug": "optional-where-func-slug2",
+            },
+        ],
+    )
+    await session.commit()
+
+    none_value = None
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(func.lower(Parent.slug) == none_value),
+    )
+    assert len(parents) == 2
+
+
+async def test_list_with_optional_where_case3_and_both_applied(session: AsyncSession):
+    """Case 3: compound & expression, both values not None — both filters applied."""
+    target_title = "optional-where-and-title"
+    target_slug = "optional-where-and-slug1"
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": target_title,
+                "slug": target_slug,
+            },
+            {
+                "title": target_title,
+                "slug": "optional-where-and-slug2",
+            },
+            {
+                "title": "optional-where-and-title-other",
+                "slug": "optional-where-and-slug3",
+            },
+        ],
+    )
+    await session.commit()
+
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(Parent.title == target_title) & (Parent.slug == target_slug),
+    )
+    assert len(parents) == 1
+    assert parents[0].title == target_title
+    assert parents[0].slug == target_slug
+
+
+async def test_list_with_optional_where_case3_and_one_none(session: AsyncSession):
+    """Case 3: compound & expression, one value is None — only non-None filter applied."""
+    target_title = "optional-where-one-none-title"
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": target_title,
+                "slug": "optional-where-one-none-slug1",
+            },
+            {
+                "title": target_title,
+                "slug": "optional-where-one-none-slug2",
+            },
+            {
+                "title": "optional-where-one-none-title-other",
+                "slug": "optional-where-one-none-slug3",
+            },
+        ],
+    )
+    await session.commit()
+
+    none_value = None
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(Parent.title == target_title) & (Parent.slug == none_value),
+    )
+    assert len(parents) == 2
+    for parent in parents:
+        assert parent.title == target_title
+
+
+async def test_list_with_optional_where_case3_all_none(session: AsyncSession):
+    """Case 3: compound expression, all values are None — filter skipped (all returned)."""
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": "optional-where-all-none-title-1",
+                "slug": "optional-where-all-none-slug1",
+            },
+            {
+                "title": "optional-where-all-none-title-2",
+                "slug": "optional-where-all-none-slug2",
+            },
+        ],
+    )
+    await session.commit()
+
+    none_value = None
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(Parent.title == none_value) & (Parent.slug == none_value),
+    )
+    assert len(parents) == 2
+
+
+async def test_list_with_optional_where_case3_or_both_applied(session: AsyncSession):
+    """Case 3: compound | expression, both values not None — both filters applied as OR."""
+    title_a = "optional-where-or-title-a"
+    title_b = "optional-where-or-title-b"
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": title_a,
+                "slug": "optional-where-or-slug1",
+            },
+            {
+                "title": title_b,
+                "slug": "optional-where-or-slug2",
+            },
+            {
+                "title": "optional-where-or-title-other",
+                "slug": "optional-where-or-slug3",
+            },
+        ],
+    )
+    await session.commit()
+
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(Parent.title == title_a) | (Parent.title == title_b),
+    )
+    assert len(parents) == 2
+    titles = {p.title for p in parents}
+    assert title_a in titles
+    assert title_b in titles
+
+
+async def test_list_with_optional_where_case3_or_one_none(session: AsyncSession):
+    """Case 3: compound | expression, one value is None — only non-None filter applied."""
+    target_title = "optional-where-or-none-title"
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": target_title,
+                "slug": "optional-where-or-none-slug1",
+            },
+            {
+                "title": "optional-where-or-none-title-other",
+                "slug": "optional-where-or-none-slug2",
+            },
+        ],
+    )
+    await session.commit()
+
+    none_value = None
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(Parent.title == target_title) | (Parent.slug == none_value),
+    )
+    assert len(parents) == 1
+    assert parents[0].title == target_title
+
+
 async def test_create_unique_constraint_validation(session: AsyncSession):
     await parent_manager.create(
         session=session,