fastapi-sqlalchemy-toolkit 0.8.2.2__tar.gz → 0.8.2.4__tar.gz

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi_sqlalchemy_toolkit
-Version: 0.8.2.2
+Version: 0.8.2.4
 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.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/docs/db_validation.md

@@ -24,4 +24,17 @@ If the uniqueness constraint is violated, an `fastapi.HTTPException` will be rai
 
 If the model defines unique constraints using `sqlalchemy.UniqueConstraint`, then when using the `create` or `update` methods, an SQL query will be executed to verify that no other objects with the same combination of field values in the unique constraint exist.
 
-If the unique constraint is violated, an `fastapi.HTTPException` will be raised.
+If the unique constraint is violated, an `fastapi.HTTPException` will be raised.
+
+## Unique Indexes Validation
+
+If the model defines a unique `sqlalchemy.Index`, then when using the `create` or `update` methods, an SQL query will be executed to verify that no other object violates that index.
+
+For **partial** unique indexes (`postgresql_where=...`), validation runs only when the created/updated row itself matches the `WHERE` predicate. Rows outside the partial index are not checked against it.
+
+Supported `postgresql_where` forms for deciding whether the row is covered:
+
+- Column expressions such as `Model.kind == "main"` (including `and_(...)` of equalities)
+- Simple `text()` equalities such as `text("kind = 'main'")`
+
+Unsupported / complex predicates are treated as matching (fail-safe): validation still runs.

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/docs/filtering.md

@@ -278,6 +278,27 @@ async def get_parents(
 
 `GET /parents?title=foo&slug=bar` — both filters are applied with `AND`.
 
+**Case 4: Expression with a falsy value** (`MyModel.column.in_(value)`, `MyModel.column.endswith(value)`, `MyModel.column.startswith(value)`)
+
+If `value` is an empty list (`[]`) or an empty string (`""`), the filter is skipped.
+This covers `in_([])`, `endswith("")`, `startswith("")` and similar operators.
+
+```python
+@router.get("/parents")
+async def get_parents(
+    session: Session,
+    slugs: list[str] = Query(default=[]),
+) -> list[ParentListSchema]:
+    return await parent_manager.list(
+        session,
+        optional_where=Parent.slug.in_(slugs),
+    )
+```
+
+`GET /parents` — no filter applied, all `Parent` objects are returned.
+
+`GET /parents?slugs=foo&slugs=bar` — only `Parent` objects whose `slug` is in `['foo', 'bar']` are returned.
+
 > **Note**: nesting of compound expressions (e.g. `(a & b) | c`) is not supported.
 
 **Multiple expressions as separate arguments**

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/docs/ru/benefits.md

@@ -28,14 +28,14 @@ async def get_my_objects(
     if user_id is not None:
         stmt = stmt.filter_by(user_id=user_id)
     if name is not None:
-        stmt = stmt.filter(MyModel.name.ilike == f"%{name}%")
+        stmt = stmt.filter(MyModel.name == "name")
     if parent_name is not None:
         stmt = stmt.join(MyModel.parent)
-        stmt = stmt.filter(ParentModel.name.ilike == f"%{parent_name}%")
+        stmt = stmt.filter(ParentModel.name.ilike == "parent_name")
     return await paginate(session, stmt)
 ```
 
-В `fastapi-sqlalchemy-toolkit` этот эндпоинт выглядит так:
+С `fastapi-sqlalchemy-toolkit` этот эндпоинт выглядит так:
 
 ```python
 from app.managers import my_object_manager
@@ -50,10 +50,10 @@ async def get_my_objects(
     return await my_object_manager.paginated_list(
         session,
         user_id=user_id,
-        filter_expressions={
-            MyObject.name: name,
-            MyObjectParent.name: parent_name
-        }
+        optional_where=(
+            MyObject.name == name,
+            MyObjectParent.name == parent_name
+        )
     )
 ```
 

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/docs/ru/db_validation.md

@@ -32,4 +32,20 @@ Ecли `Post.slug` -- поле, определённое с `unique=True`, и з
 при использовании методов `create` или `update` будет выполнен SQL запрос для проверки
 существования других объектов с таким же набором значений полей, входящих в уникальное огранчение.
 
-Если уникальное ограничение будет нарушено, вызывается `fastapi.HTTPException`.
+Если уникальное ограничение будет нарушено, вызывается `fastapi.HTTPException`.
+
+## Валидация уникальных индексов
+
+Если в модели определён уникальный `sqlalchemy.Index`, то при использовании методов
+`create` или `update` будет выполнен SQL запрос для проверки, что индекс не нарушается.
+
+Для **частичных** уникальных индексов (`postgresql_where=...`) валидация выполняется
+только если создаваемая/обновляемая запись сама попадает под условие `WHERE`.
+Записи вне partial index по этому индексу не проверяются.
+
+Поддерживаемые формы `postgresql_where` для определения покрытия записи:
+
+- выражения по колонкам, например `Model.kind == "main"` (включая `and_(...)` из равенств)
+- простые равенства через `text()`, например `text("kind = 'main'")`
+
+Неподдерживаемые / сложные предикаты считаются подходящими (fail-safe): валидация всё равно выполняется.

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/docs/ru/filtering.md

@@ -72,13 +72,114 @@ FROM child
 WHERE child.slug = :slug_1
 ```
 
-По конвенции `FastAPI`, необязательные параметры запроса типизируются как `slug: str | None = None`.
-При этом клиенты API обычно ожидают, что при запросе `GET /children` будут возвращены все объекты `Child`,
-а не только те, у которых `slug is null`. Поэтому метод `list` (`paginated_list`) отбрасывает фильтрацию
-по этому параметру, если его значение не передано.
+Клиенты API ожидают, что при запросе `GET /children` будут возвращены все объекты `Child`, 
+поэтому метод `list` (`paginated_list`) отбрасывает фильтрацию по параметрам, значения которых 
+не переданы.
 
 ## Фильтрация с выражениями
 
+### optional_where
+
+Параметр `optional_where` методов `list` и `paginated_list` принимает выражения SQLAlchemy, 
+аналогично методу `select().where()`, причём фильтры со значением `None` (`[]`, `""`) автоматически пропускаются.
+
+Это удобно использовать в списочных API эндпоинтах, где фильтрация необязательна:
+если параметр запроса не передан, фильтр не применяется.
+
+Примеры использования  `optional_where`:
+
+**Бинарное выражение** (`MyModel.field == value`)
+
+Если `value` равно `None`, фильтр пропускается. Иначе применяется как есть.
+
+```python
+@router.get("/parents")
+async def get_parents(
+    session: Session,
+    created_at_gte: datetime | None = None,
+) -> list[ParentListSchema]:
+    return await parent_manager.list(
+        session,
+        optional_where=(Parent.created_at >= created_at_gte),
+    )
+```
+
+Запрос `GET /parents` — фильтр не применяется, возвращаются все объекты `Parent`.
+
+Запрос `GET /parents?created_at_gte=2026-01-01T00:00:00Z` — возвращаются только объекты `Parent` с `created_at >= '2026-01-01T00:00:00Z'`.
+
+**Выражение с функцией или оператором** (`func.date(MyModel.field) == value`, `MyModel.field.ilike(value)`)
+
+Если `value` равно `None`, фильтр пропускается.
+
+Также если `value` является пустым списком (`[]`) или пустой строкой (`""`), фильтр пропускается.
+Это распространяется на `in_([])`, `endswith("")`, `startswith("")` и аналогичные операторы, которые
+не допускают передачи `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),
+    )
+```
+
+**Составное выражение через `&` или `|`** (`(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`) не поддерживаются.
+
+**Несколько выражений как отдельные аргументы**
+
+Вместо использования `&` для объединения выражений можно передать их как отдельные
+аргументы в виде кортежа. Каждый аргумент поддерживает все три вида выражений выше.
+Оставшиеся (не-`None`) выражения объединяются через `AND`.
+
+```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`.
+
 ### filter_expressions
 
 Чтобы использовать фильтрацию не только по точному соответствию атрибуту модели,
@@ -184,104 +285,6 @@ 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`) не поддерживаются.
-
-**Несколько выражений как отдельные аргументы**
-
-Вместо использования `&` для объединения выражений можно передать их как отдельные
-аргументы в виде кортежа. Каждый аргумент поддерживает все три вида выражений выше.
-Оставшиеся (не-`None`) выражения объединяются через `AND`.
-
-```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`.
-
 ## Фильтрация без дополнительной обработки
 
 Для фильтрации без дополнительной обработки в методах `list` и `paginated_list` можно

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/fastapi_sqlalchemy_toolkit/model_manager.py

@@ -1,5 +1,6 @@
 # ruff: noqa: UP006
 from collections.abc import Callable, Iterable
+from enum import Enum
 from typing import Any, Generic, List, TypeVar, overload  # noqa: UP035
 
 from fastapi import HTTPException, status
@@ -25,9 +26,16 @@ from sqlalchemy.ext.asyncio import AsyncSession
 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 Null, UnaryExpression
-from sqlalchemy.sql.expression import BinaryExpression, ColumnElement
+from sqlalchemy.sql import Select, operators
+from sqlalchemy.sql.elements import (
+    BinaryExpression,
+    BindParameter,
+    BooleanClauseList,
+    Null,
+    TextClause,
+    UnaryExpression,
+)
+from sqlalchemy.sql.expression import ColumnElement
 from sqlalchemy.sql.functions import Function
 from sqlalchemy.sql.schema import ScalarElementColumnDefault
 from sqlalchemy.sql.selectable import Exists
@@ -46,6 +54,15 @@ def sqlalchemy_model_to_dict(model: DeclarativeBase) -> dict:
     return db_obj_dict
 
 
+def _is_falsy_bind_param(right: Any) -> bool:
+    """Return True if *right* is a BindParameter with a falsy str or list value."""
+    return (
+        isinstance(right, BindParameter)
+        and isinstance(right.value, str | list)
+        and not right.value
+    )
+
+
 def _get_model_pk(model: type[DeclarativeBase]) -> InstrumentedAttribute:
     """Получить атрибут первичного ключа для произвольной модели."""
     pk_columns = list(model.__table__.primary_key.columns)
@@ -1236,16 +1253,20 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
     @classmethod
     def handle_optional_where_expression(cls, optional_where: Any) -> Any:
         """
-        Обрабатывает одно выражение optional_where, пропуская фильтр, если его значение None.
+        Обрабатывает одно выражение optional_where, пропуская фильтр,
+        если его значение None.
 
         Поддерживает:
         1. Простые выражения вида MyModel.field == value
         2. Выражения с функциями/операторами вида func.date(MyModel.field) == value
         3. Составные выражения вида (expr1) & (expr2) или (expr1) | (expr2)
            (без вложенности)
+        4. Выражения с "пустым" значением вида MyModel.column.in_([]),
+           MyModel.column.endswith(""), MyModel.column.startswith("")
 
-        Если value равно None, фильтр не применяется.
-        В составных выражениях исключаются части с value == None,
+        Если value равно None или является пустой строкой/списком,
+        фильтр не применяется.
+        В составных выражениях исключаются части с такими значениями,
         при этом оператор & или | сохраняется.
         """
         if optional_where is None:
@@ -1257,17 +1278,17 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
                 clause
                 for clause in optional_where.clauses
                 if not isinstance(clause.right, Null)
+                and not _is_falsy_bind_param(getattr(clause, "right", None))
             ]
             if not remaining:
                 return None
             if len(remaining) == 1:
                 return remaining[0]
-            if optional_where.operator.__name__ == "and_":
-                return and_(*remaining)
-            return or_(*remaining)
+            combiner = and_ if optional_where.operator.__name__ == "and_" else or_
+            return combiner(*remaining)
 
-        # simple binary expression
-        if isinstance(getattr(optional_where, "right", None), Null):
+        right = getattr(optional_where, "right", None)
+        if isinstance(right, Null) or _is_falsy_bind_param(right):
             return None
         return optional_where
 
@@ -1470,11 +1491,77 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
                         ),
                     )
 
+    @staticmethod
+    def _partial_index_values_equal(actual: Any, expected: Any) -> bool:
+        """Сравнить обычные и Enum-значения из объекта и условия индекса."""
+        actual_normalized = actual.name if isinstance(actual, Enum) else actual
+        expected_normalized = expected.name if isinstance(expected, Enum) else expected
+        if actual_normalized == expected_normalized:
+            return True
+        if isinstance(actual, Enum) and actual.value == expected_normalized:
+            return True
+        if isinstance(expected, Enum) and expected.value == actual_normalized:
+            return True
+        return str(actual_normalized) == str(expected_normalized)
+
+    @classmethod
+    def _matches_partial_index_where(cls, condition: Any, in_obj: ModelDict) -> bool:
+        """
+        Проверить, покрывается ли объект условием partial index.
+
+        Неподдерживаемое условие считается совпавшим, чтобы не пропустить
+        потенциальное нарушение уникальности.
+        """
+        if isinstance(condition, BooleanClauseList):
+            return all(
+                cls._matches_partial_index_where(clause, in_obj) for clause in condition
+            )
+
+        column_name: str | None = None
+        expected: Any = None
+        if isinstance(condition, TextClause):
+            raw_column, separator, raw_expected = condition.text.partition("=")
+            column_name = raw_column.strip()
+            raw_expected = raw_expected.strip()
+            valid_column = column_name.isascii() and column_name.isidentifier()
+
+            if not separator or not valid_column or not raw_expected:
+                column_name = None
+            elif raw_expected[0] in {'"', "'"}:
+                quote = raw_expected[0]
+                if raw_expected[-1] == quote and quote not in raw_expected[1:-1]:
+                    expected = raw_expected[1:-1]
+                else:
+                    column_name = None
+            elif all(char.isalnum() or char in "._" for char in raw_expected):
+                expected = raw_expected
+            else:
+                column_name = None
+        elif (
+            isinstance(condition, BinaryExpression)
+            and condition.operator is operators.eq
+        ):
+            column_name = getattr(condition.left, "name", None) or getattr(
+                condition.left, "key", None
+            )
+            expected = getattr(
+                condition.right,
+                "value",
+                getattr(condition.right, "effective_value", condition.right),
+            )
+
+        if not isinstance(column_name, str) or column_name not in in_obj:
+            return True
+        return cls._partial_index_values_equal(in_obj[column_name], expected)
+
     async def validate_unique_indexes(
         self, session: AsyncSession, in_obj: ModelDict
     ) -> None:
         """
-        Валидирует соблюдение уникальности индексов
+        Валидирует соблюдение уникальности индексов.
+
+        Для partial unique index (`postgresql_where`) проверка выполняется только
+        если создаваемая/обновляемая запись сама попадает под WHERE.
         """
         for index in self.unique_indexes:
             condition = (
@@ -1482,6 +1569,9 @@ class ModelManager(Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
                 if index.dialect_options.get("postgresql")
                 else None
             )
+            if not self._matches_partial_index_where(condition, in_obj):
+                continue
+
             filters = []
 
             for column in index.columns:

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/pyproject.toml

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

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/requirements/test.txt

@@ -1,2 +1,2 @@
-pytest>=8.0.0
+pytest>=9.0.0
 asyncpg>=0.29.0

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/tests/conftest.py

@@ -1,4 +1,4 @@
-from typing import AsyncGenerator
+from collections.abc import AsyncGenerator
 
 import pytest
 from sqlalchemy.ext.asyncio import AsyncConnection, AsyncSession, AsyncTransaction
@@ -7,25 +7,35 @@ from tests.db import async_session_factory, engine
 from tests.models import Base, CustomPKBase
 
 
-@pytest.fixture(autouse=True)
-async def create_metadata():
-    async with engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)
-        await conn.run_sync(CustomPKBase.metadata.create_all)
-
-
 @pytest.fixture(scope="session")
-def anyio_backend():
+def anyio_backend() -> str:
     return "asyncio"
 
 
 @pytest.fixture(scope="session")
-async def connection(anyio_backend) -> AsyncGenerator[AsyncConnection, None]:
+async def connection(
+    anyio_backend: str,  # noqa: ARG001 - activates AnyIO's async-fixture runner
+) -> AsyncGenerator[AsyncConnection, None]:
     async with engine.connect() as connection:
         yield connection
 
 
-@pytest.fixture()
+@pytest.fixture(scope="session", autouse=True)
+async def create_metadata(
+    connection: AsyncConnection,
+) -> AsyncGenerator[None, None]:
+    await connection.run_sync(Base.metadata.create_all)
+    await connection.run_sync(CustomPKBase.metadata.create_all)
+    await connection.commit()
+
+    yield
+
+    await connection.run_sync(CustomPKBase.metadata.drop_all)
+    await connection.run_sync(Base.metadata.drop_all)
+    await connection.commit()
+
+
+@pytest.fixture
 async def transaction(
     connection: AsyncConnection,
 ) -> AsyncGenerator[AsyncTransaction, None]:
@@ -39,7 +49,7 @@ async def persistent_session() -> AsyncGenerator[AsyncSession, None]:
         yield session
 
 
-@pytest.fixture()
+@pytest.fixture
 async def session(
     connection: AsyncConnection, transaction: AsyncTransaction
 ) -> AsyncGenerator[AsyncSession, None]:

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/tests/models.py

@@ -2,7 +2,17 @@ from datetime import datetime
 from uuid import UUID, uuid4
 
 from pydantic import BaseModel
-from sqlalchemy import Column, DateTime, ForeignKey, Table, UniqueConstraint, func
+from sqlalchemy import (
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Table,
+    UniqueConstraint,
+    column,
+    func,
+    text,
+)
 from sqlalchemy.orm import (
     DeclarativeBase,
     Mapped,
@@ -112,3 +122,55 @@ class ItemSchema(BaseModel):
 
 
 item_manager = ModelManager[Item, ItemSchema, ItemSchema](Item)
+
+
+class PartialUniqueText(Base):
+    """Partial unique index via text() postgresql_where."""
+
+    group_id: Mapped[UUID]
+    kind: Mapped[str]
+
+    __table_args__ = (
+        Index(
+            "uix_partial_unique_text_one_main_per_group",
+            "group_id",
+            unique=True,
+            postgresql_where=text("kind = 'main'"),
+        ),
+    )
+
+
+class PartialUniqueTextSchema(BaseModel):
+    group_id: UUID
+    kind: str
+
+
+partial_unique_text_manager = ModelManager[
+    PartialUniqueText, PartialUniqueTextSchema, PartialUniqueTextSchema
+](PartialUniqueText)
+
+
+class PartialUniqueExpr(Base):
+    """Partial unique index via Column expression postgresql_where."""
+
+    group_id: Mapped[UUID]
+    kind: Mapped[str]
+
+    __table_args__ = (
+        Index(
+            "uix_partial_unique_expr_one_main_per_group",
+            "group_id",
+            unique=True,
+            postgresql_where=(column("kind") == "main"),
+        ),
+    )
+
+
+class PartialUniqueExprSchema(BaseModel):
+    group_id: UUID
+    kind: str
+
+
+partial_unique_expr_manager = ModelManager[
+    PartialUniqueExpr, PartialUniqueExprSchema, PartialUniqueExprSchema
+](PartialUniqueExpr)

fastapi_sqlalchemy_toolkit-0.8.2.4/tests/test_partial_where.py

@@ -0,0 +1,115 @@
+# ruff: noqa: S101
+from enum import Enum
+
+from sqlalchemy import Index, and_, text
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from fastapi_sqlalchemy_toolkit.model_manager import ModelManager
+
+
+class _Base(DeclarativeBase):
+    pass
+
+
+class _Kind(Enum):
+    MAIN = "main"
+    EXTRA = "extra"
+
+
+class _Model(_Base):
+    __tablename__ = "partial_where_model"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    kind: Mapped[str]
+    group_id: Mapped[int]
+    active: Mapped[bool]
+
+
+def test_none_condition_matches() -> None:
+    assert ModelManager._matches_partial_index_where(None, {"kind": "extra"}) is True
+
+
+def test_text_clause_main_matches() -> None:
+    for condition in (
+        text("kind = 'main'"),
+        text('kind = "main"'),
+        text("kind = main"),
+    ):
+        assert (
+            ModelManager._matches_partial_index_where(condition, {"kind": "main"})
+            is True
+        )
+        assert (
+            ModelManager._matches_partial_index_where(condition, {"kind": "extra"})
+            is False
+        )
+
+
+def test_binary_expression_matches() -> None:
+    index = Index(
+        "ix",
+        _Model.group_id,
+        unique=True,
+        postgresql_where=(_Model.kind == "main"),
+    )
+    condition = index.dialect_options["postgresql"]["where"]
+    assert (
+        ModelManager._matches_partial_index_where(condition, {"kind": "main"}) is True
+    )
+    assert (
+        ModelManager._matches_partial_index_where(condition, {"kind": "extra"}) is False
+    )
+
+
+def test_binary_expression_with_enum_matches() -> None:
+    index = Index(
+        "ix_enum",
+        _Model.group_id,
+        unique=True,
+        postgresql_where=(_Model.kind == _Kind.MAIN),
+    )
+    condition = index.dialect_options["postgresql"]["where"]
+    assert (
+        ModelManager._matches_partial_index_where(condition, {"kind": "main"}) is True
+    )
+    assert (
+        ModelManager._matches_partial_index_where(condition, {"kind": _Kind.MAIN})
+        is True
+    )
+    assert (
+        ModelManager._matches_partial_index_where(condition, {"kind": "extra"}) is False
+    )
+
+
+def test_boolean_clause_list_matches() -> None:
+    index = Index(
+        "ix_and",
+        _Model.group_id,
+        unique=True,
+        postgresql_where=and_(_Model.kind == "main", _Model.active == True),  # noqa: E712
+    )
+    condition = index.dialect_options["postgresql"]["where"]
+    assert (
+        ModelManager._matches_partial_index_where(
+            condition, {"kind": "main", "active": True}
+        )
+        is True
+    )
+    assert (
+        ModelManager._matches_partial_index_where(
+            condition, {"kind": "main", "active": False}
+        )
+        is False
+    )
+    assert (
+        ModelManager._matches_partial_index_where(
+            condition, {"kind": "extra", "active": True}
+        )
+        is False
+    )
+
+
+def test_unsupported_text_fail_safe() -> None:
+    condition = text("kind IN ('main', 'special')")
+    assert (
+        ModelManager._matches_partial_index_where(condition, {"kind": "extra"}) is True
+    )

{fastapi_sqlalchemy_toolkit-0.8.2.2 → fastapi_sqlalchemy_toolkit-0.8.2.4}/tests/test_public_methods.py

@@ -14,10 +14,14 @@ from tests.models import (
     ItemSchema,
     Parent,
     ParentSchema,
+    PartialUniqueExprSchema,
+    PartialUniqueTextSchema,
     category_manager,
     child_manager,
     item_manager,
     parent_manager,
+    partial_unique_expr_manager,
+    partial_unique_text_manager,
 )
 
 
@@ -1079,6 +1083,122 @@ async def test_list_with_optional_where_multi_all_none(session: AsyncSession):
     assert len(parents) == 2
 
 
+async def test_list_with_optional_where_in_applied(session: AsyncSession):
+    """Case 4: in_ expression, non-empty list — filter is applied."""
+    target_slug = "optional-where-in-slug1"
+    await session.execute(
+        insert(Parent),
+        [
+            {"title": "optional-where-in-title-1", "slug": target_slug},
+            {"title": "optional-where-in-title-2", "slug": "optional-where-in-slug2"},
+        ],
+    )
+    await session.commit()
+
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=Parent.slug.in_([target_slug]),
+    )
+    assert len(parents) == 1
+    assert parents[0].slug == target_slug
+
+
+async def test_list_with_optional_where_in_skipped(session: AsyncSession):
+    """Case 4: in_ expression, empty list — filter is skipped (all returned)."""
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": "optional-where-in-skip-title-1",
+                "slug": "optional-where-in-skip-slug1",
+            },
+            {
+                "title": "optional-where-in-skip-title-2",
+                "slug": "optional-where-in-skip-slug2",
+            },
+        ],
+    )
+    await session.commit()
+
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=Parent.slug.in_([]),
+    )
+    assert len(parents) == 2
+
+
+async def test_list_with_optional_where_endswith_applied(session: AsyncSession):
+    """Case 4: endswith expression, non-empty string — filter is applied."""
+    target_slug = "optional-where-ends-slug-xyz"
+    await session.execute(
+        insert(Parent),
+        [
+            {"title": "optional-where-ends-title-1", "slug": target_slug},
+            {
+                "title": "optional-where-ends-title-2",
+                "slug": "optional-where-ends-slug-abc",
+            },
+        ],
+    )
+    await session.commit()
+
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=Parent.slug.endswith("xyz"),
+    )
+    assert len(parents) == 1
+    assert parents[0].slug == target_slug
+
+
+async def test_list_with_optional_where_endswith_skipped(session: AsyncSession):
+    """Case 4: endswith expression, empty string — filter is skipped (all returned)."""
+    await session.execute(
+        insert(Parent),
+        [
+            {
+                "title": "optional-where-ends-skip-title-1",
+                "slug": "optional-where-ends-skip-slug1",
+            },
+            {
+                "title": "optional-where-ends-skip-title-2",
+                "slug": "optional-where-ends-skip-slug2",
+            },
+        ],
+    )
+    await session.commit()
+
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=Parent.slug.endswith(""),
+    )
+    assert len(parents) == 2
+
+
+async def test_list_with_optional_where_in_compound_one_empty(session: AsyncSession):
+    """Case 4 in compound: in_([]) in & expression — only non-empty filter applied."""
+    target_title = "optional-where-compound-in-title"
+    await session.execute(
+        insert(Parent),
+        [
+            {"title": target_title, "slug": "optional-where-compound-in-slug1"},
+            {"title": target_title, "slug": "optional-where-compound-in-slug2"},
+            {
+                "title": "optional-where-compound-in-other",
+                "slug": "optional-where-compound-in-slug3",
+            },
+        ],
+    )
+    await session.commit()
+
+    parents = await parent_manager.list(
+        session=session,
+        optional_where=(Parent.title == target_title) & Parent.slug.in_([]),
+    )
+    assert len(parents) == 2
+    for parent in parents:
+        assert parent.title == target_title
+
+
 async def test_create_unique_constraint_validation(session: AsyncSession):
     await parent_manager.create(
         session=session,
@@ -1306,3 +1426,67 @@ async def test_custom_pk_unique_validation_on_update(session: AsyncSession):
     with pytest.raises(HTTPException) as exc_info:
         await item_manager.update(session, item1, ItemSchema(name="upd-unique-2"))
     assert exc_info.value.status_code == 422
+
+
+async def test_partial_unique_index_text_allows_non_matching_kind(
+    session: AsyncSession,
+):
+    group_id = uuid4()
+    await partial_unique_text_manager.create(
+        session, PartialUniqueTextSchema(group_id=group_id, kind="main")
+    )
+    extra = await partial_unique_text_manager.create(
+        session, PartialUniqueTextSchema(group_id=group_id, kind="extra")
+    )
+    assert extra.kind == "extra"
+
+
+async def test_partial_unique_index_text_rejects_second_main(session: AsyncSession):
+    group_id = uuid4()
+    await partial_unique_text_manager.create(
+        session, PartialUniqueTextSchema(group_id=group_id, kind="main")
+    )
+    with pytest.raises(HTTPException) as exc_info:
+        await partial_unique_text_manager.create(
+            session, PartialUniqueTextSchema(group_id=group_id, kind="main")
+        )
+    assert exc_info.value.status_code == 400
+    assert "group_id" in exc_info.value.detail
+
+
+async def test_partial_unique_index_text_allows_main_for_other_group(
+    session: AsyncSession,
+):
+    await partial_unique_text_manager.create(
+        session, PartialUniqueTextSchema(group_id=uuid4(), kind="main")
+    )
+    other = await partial_unique_text_manager.create(
+        session, PartialUniqueTextSchema(group_id=uuid4(), kind="main")
+    )
+    assert other.kind == "main"
+
+
+async def test_partial_unique_index_expr_allows_non_matching_kind(
+    session: AsyncSession,
+):
+    group_id = uuid4()
+    await partial_unique_expr_manager.create(
+        session, PartialUniqueExprSchema(group_id=group_id, kind="main")
+    )
+    extra = await partial_unique_expr_manager.create(
+        session, PartialUniqueExprSchema(group_id=group_id, kind="extra")
+    )
+    assert extra.kind == "extra"
+
+
+async def test_partial_unique_index_expr_rejects_second_main(session: AsyncSession):
+    group_id = uuid4()
+    await partial_unique_expr_manager.create(
+        session, PartialUniqueExprSchema(group_id=group_id, kind="main")
+    )
+    with pytest.raises(HTTPException) as exc_info:
+        await partial_unique_expr_manager.create(
+            session, PartialUniqueExprSchema(group_id=group_id, kind="main")
+        )
+    assert exc_info.value.status_code == 400
+    assert "group_id" in exc_info.value.detail