feat: add lateral_load() for efficient Many:One eager loading via JOIN LATERAL

docs/module/db.md

@@ -118,57 +118,6 @@ async def clean(db_session):
     await cleanup_tables(session=db_session, base=Base)
 ```
 
-## Many-to-Many helpers
-
-SQLAlchemy's ORM collection API triggers lazy-loads when you append to a relationship inside a savepoint (e.g. inside `lock_tables` or a nested `get_transaction`). The three `m2m_*` helpers bypass the ORM collection entirely and issue direct SQL against the association table.
-
-### `m2m_add` — insert associations
-
-[`m2m_add`](../reference/db.md#fastapi_toolsets.db.m2m_add) inserts one or more rows into a secondary table without touching the ORM collection:
-
-```python
-from fastapi_toolsets.db import lock_tables, m2m_add
-
-async with lock_tables(session, [Tag]):
-    tag = await TagCrud.create(session, TagCreate(name="python"))
-    await m2m_add(session, post, Post.tags, tag)
-```
-
-Pass `ignore_conflicts=True` to silently skip associations that already exist:
-
-```python
-await m2m_add(session, post, Post.tags, tag, ignore_conflicts=True)
-```
-
-### `m2m_remove` — delete associations
-
-[`m2m_remove`](../reference/db.md#fastapi_toolsets.db.m2m_remove) deletes specific association rows. Removing a non-existent association is a no-op:
-
-```python
-from fastapi_toolsets.db import get_transaction, m2m_remove
-
-async with get_transaction(session):
-    await m2m_remove(session, post, Post.tags, tag1, tag2)
-```
-
-### `m2m_set` — replace the full set
-
-[`m2m_set`](../reference/db.md#fastapi_toolsets.db.m2m_set) atomically replaces all associations: it deletes every existing row for the owner instance then inserts the new set. Passing no related instances clears the association entirely:
-
-```python
-from fastapi_toolsets.db import get_transaction, m2m_set
-
-# Replace all tags
-async with get_transaction(session):
-    await m2m_set(session, post, Post.tags, tag_a, tag_b)
-
-# Clear all tags
-async with get_transaction(session):
-    await m2m_set(session, post, Post.tags)
-```
-
-All three helpers raise `TypeError` if the relationship attribute is not a Many-to-Many (i.e. has no secondary table).
-
 ---
 
 [:material-api: API Reference](../reference/db.md)

docs/reference/db.md

@@ -13,9 +13,6 @@ from fastapi_toolsets.db import (
     create_db_context,
     get_transaction,
     lock_tables,
-    m2m_add,
-    m2m_remove,
-    m2m_set,
     wait_for_row_change,
 )
 ```
@@ -35,9 +32,3 @@ from fastapi_toolsets.db import (
 ## ::: fastapi_toolsets.db.create_database
 
 ## ::: fastapi_toolsets.db.cleanup_tables
-
-## ::: fastapi_toolsets.db.m2m_add
-
-## ::: fastapi_toolsets.db.m2m_remove
-
-## ::: fastapi_toolsets.db.m2m_set

pyproject.toml

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

src/fastapi_toolsets/__init__.py

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

src/fastapi_toolsets/crud/__init__.py

@@ -15,12 +15,13 @@ from ..types import (
     OrderFieldType,
     SearchFieldType,
 )
-from .factory import AsyncCrud, CrudFactory
+from .factory import AsyncCrud, CrudFactory, lateral_load
 from .search import SearchConfig, get_searchable_fields
 
 __all__ = [
     "AsyncCrud",
     "CrudFactory",
+    "lateral_load",
     "FacetFieldType",
     "get_searchable_fields",
     "InvalidFacetFilterError",

src/fastapi_toolsets/crud/factory.py

@@ -10,15 +10,32 @@ from collections.abc import Awaitable, Callable, Sequence
 from datetime import date, datetime
 from decimal import Decimal
 from enum import Enum
-from typing import Any, ClassVar, Generic, Literal, Self, cast, overload
+from typing import Any, ClassVar, Generic, Literal, NamedTuple, 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 (
+    Date,
+    DateTime,
+    Float,
+    Integer,
+    Numeric,
+    Uuid,
+    and_,
+    func,
+    select,
+    true,
+)
 from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy.exc import NoResultFound
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import DeclarativeBase, QueryableAttribute, selectinload
+from sqlalchemy.orm import (
+    DeclarativeBase,
+    QueryableAttribute,
+    RelationshipProperty,
+    contains_eager,
+    selectinload,
+)
 from sqlalchemy.sql.base import ExecutableOption
 from sqlalchemy.sql.roles import WhereHavingRole
 
@@ -35,6 +52,7 @@ from ..schemas import (
 from ..types import (
     FacetFieldType,
     JoinType,
+    LateralJoinType,
     M2MFieldType,
     ModelType,
     OrderByClause,
@@ -115,6 +133,78 @@ def _apply_joins(q: Any, joins: JoinType | None, outer_join: bool) -> Any:
     return q
 
 
+class _ResolvedLateral(NamedTuple):
+    joins: LateralJoinType
+    eager: list[ExecutableOption]
+
+
+class _LateralLoad:
+    """Marker used inside ``default_load_options`` for lateral join loading.
+
+    Supports only Many:One and One:One relationships (single row per parent).
+    """
+
+    __slots__ = ("rel_attr",)
+
+    def __init__(self, rel_attr: QueryableAttribute) -> None:
+        prop = rel_attr.property
+        if not isinstance(prop, RelationshipProperty):
+            raise TypeError(
+                f"lateral_load() requires a relationship attribute, got {type(prop).__name__}. "
+                "Example: lateral_load(User.team)"
+            )
+        if prop.secondary is not None:
+            raise ValueError(
+                f"lateral_load({rel_attr}) does not support Many:Many relationships. "
+                "Use selectinload() instead."
+            )
+        if prop.uselist:
+            raise ValueError(
+                f"lateral_load({rel_attr}) does not support One:Many relationships. "
+                "Use selectinload() instead."
+            )
+        self.rel_attr = rel_attr
+
+
+def lateral_load(rel_attr: QueryableAttribute) -> _LateralLoad:
+    """Mark a Many:One or One:One relationship for lateral join loading.
+
+    Raises ``ValueError`` for One:Many or Many:Many relationships.
+    """
+    return _LateralLoad(rel_attr)
+
+
+def _build_lateral_from_relationship(
+    rel_attr: QueryableAttribute,
+) -> tuple[Any, Any, ExecutableOption]:
+    """Introspect a Many:One relationship and build (lateral_subquery, true(), contains_eager)."""
+    prop = rel_attr.property
+    target_class = prop.mapper.class_
+    parent_class = prop.parent.class_
+
+    conditions = [
+        getattr(target_class, remote_col.key) == getattr(parent_class, local_col.key)
+        for local_col, remote_col in prop.local_remote_pairs
+    ]
+
+    lateral_sub = (
+        select(target_class)
+        .where(and_(*conditions))
+        .correlate(parent_class)
+        .lateral(f"_lateral_{prop.key}")
+    )
+    return lateral_sub, true(), contains_eager(rel_attr, alias=lateral_sub)
+
+
+def _apply_lateral_joins(q: Any, lateral_joins: LateralJoinType | None) -> Any:
+    """Apply lateral subqueries as LEFT JOIN LATERAL to preserve all parent rows."""
+    if not lateral_joins:
+        return q
+    for subquery, condition in lateral_joins:
+        q = q.outerjoin(subquery, condition)
+    return q
+
+
 def _apply_search_joins(q: Any, search_joins: list[Any]) -> Any:
     """Apply relationship-based outer joins (from search/filter_by) to a query."""
     seen: set[str] = set()
@@ -132,12 +222,17 @@ class AsyncCrud(Generic[ModelType]):
     Subclass this and set the `model` class variable, or use `CrudFactory`.
     """
 
+    _resolved_lateral: ClassVar[_ResolvedLateral | None] = None
+
     model: ClassVar[type[DeclarativeBase]]
     searchable_fields: ClassVar[Sequence[SearchFieldType] | None] = None
     facet_fields: ClassVar[Sequence[FacetFieldType] | None] = None
     order_fields: ClassVar[Sequence[OrderFieldType] | None] = None
     m2m_fields: ClassVar[M2MFieldType | None] = None
-    default_load_options: ClassVar[Sequence[ExecutableOption] | None] = None
+    default_load_options: ClassVar[Sequence[ExecutableOption | _LateralLoad] | None] = (
+        None
+    )
+    lateral_joins: ClassVar[LateralJoinType | None] = None
     cursor_column: ClassVar[Any | None] = None
 
     @classmethod
@@ -161,14 +256,48 @@ class AsyncCrud(Generic[ModelType]):
             ):
                 cls.searchable_fields = [pk_col, *raw_fields]
 
+        raw_default_opts = cls.__dict__.get("default_load_options", None)
+        if raw_default_opts:
+            joins: LateralJoinType = []
+            eager: list[ExecutableOption] = []
+            clean: list[ExecutableOption] = []
+            for opt in raw_default_opts:
+                if isinstance(opt, _LateralLoad):
+                    lat_sub, condition, eager_opt = _build_lateral_from_relationship(
+                        opt.rel_attr
+                    )
+                    joins.append((lat_sub, condition))
+                    eager.append(eager_opt)
+                else:
+                    clean.append(opt)
+            if joins:
+                cls._resolved_lateral = _ResolvedLateral(joins=joins, eager=eager)
+                cls.default_load_options = clean or None
+
+    @classmethod
+    def _get_lateral_joins(cls) -> LateralJoinType | None:
+        """Merge manual lateral_joins with ones resolved from default_load_options."""
+        resolved = cls._resolved_lateral
+        all_lateral = [
+            *(cls.lateral_joins or []),
+            *(resolved.joins if resolved else []),
+        ]
+        return all_lateral or None
+
     @classmethod
     def _resolve_load_options(
         cls, load_options: Sequence[ExecutableOption] | None
     ) -> Sequence[ExecutableOption] | None:
-        """Return load_options if provided, else fall back to default_load_options."""
+        """Return merged load options."""
         if load_options is not None:
-            return load_options
+            return list(load_options) or None
-        return cls.default_load_options
+        resolved = cls._resolved_lateral
+        # default_load_options is cleaned of _LateralLoad markers in __init_subclass__,
+        # but its declared type still includes them — cast to reflect the runtime invariant.
+        base = cast(list[ExecutableOption], cls.default_load_options or [])
+        lateral = resolved.eager if resolved else []
+        merged = [*base, *lateral]
+        return merged or None
 
     @classmethod
     async def _reload_with_options(
@@ -861,6 +990,8 @@ class AsyncCrud(Generic[ModelType]):
         """
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
         q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
             q = q.options(*resolved)
@@ -933,6 +1064,8 @@ class AsyncCrud(Generic[ModelType]):
         """
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
         if filters:
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
@@ -978,6 +1111,8 @@ class AsyncCrud(Generic[ModelType]):
         """
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
         if filters:
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
@@ -1300,6 +1435,10 @@ class AsyncCrud(Generic[ModelType]):
         # Apply explicit joins
         q = _apply_joins(q, joins, outer_join)
 
+        # Apply lateral joins (Many:One relationship loading, excluded from count query)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
+
         # Apply search joins (always outer joins for search)
         q = _apply_search_joins(q, search_joins)
 
@@ -1398,7 +1537,9 @@ class AsyncCrud(Generic[ModelType]):
                 tables.
             outer_join: Use LEFT OUTER JOIN instead of INNER JOIN.
             load_options: SQLAlchemy loader options. Falls back to
-                ``default_load_options`` when not provided.
+                ``default_load_options`` (including any lateral joins) when not
+                provided. When explicitly supplied, the caller takes full control
+                and lateral joins are skipped.
             order_by: Additional ordering applied after the cursor column.
             items_per_page: Number of items per page (default 20).
             search: Search query string or SearchConfig object.
@@ -1455,6 +1596,10 @@ class AsyncCrud(Generic[ModelType]):
         # Apply explicit joins
         q = _apply_joins(q, joins, outer_join)
 
+        # Apply lateral joins (Many:One relationship loading)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
+
         # Apply search joins (always outer joins)
         q = _apply_search_joins(q, search_joins)
 

src/fastapi_toolsets/db.py

@@ -4,13 +4,11 @@ import asyncio
 from collections.abc import AsyncGenerator, Callable
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from enum import Enum
-from typing import Any, TypeVar, cast
+from typing import Any, TypeVar
 
-from sqlalchemy import Table, delete, text, tuple_
+from sqlalchemy import text
-from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
-from sqlalchemy.orm import DeclarativeBase, QueryableAttribute
+from sqlalchemy.orm import DeclarativeBase
-from sqlalchemy.orm.relationships import RelationshipProperty
 
 from .exceptions import NotFoundError
 
@@ -22,9 +20,6 @@ __all__ = [
     "create_db_dependency",
     "get_transaction",
     "lock_tables",
-    "m2m_add",
-    "m2m_remove",
-    "m2m_set",
     "wait_for_row_change",
 ]
 
@@ -344,140 +339,3 @@ async def wait_for_row_change(
         current = {col: getattr(instance, col) for col in watch_cols}
         if current != initial:
             return instance
-
-
-def _m2m_prop(rel_attr: QueryableAttribute) -> RelationshipProperty:  # type: ignore[type-arg]
-    """Return the validated M2M RelationshipProperty for *rel_attr*.
-
-    Raises TypeError if *rel_attr* is not a Many-to-Many relationship.
-    """
-    prop = rel_attr.property
-    if not isinstance(prop, RelationshipProperty) or prop.secondary is None:
-        raise TypeError(
-            f"m2m helpers require a Many-to-Many relationship attribute, "
-            f"got {rel_attr!r}. Use a relationship with a secondary table."
-        )
-    return prop
-
-
-async def m2m_add(
-    session: AsyncSession,
-    instance: DeclarativeBase,
-    rel_attr: QueryableAttribute,
-    *related: DeclarativeBase,
-    ignore_conflicts: bool = False,
-) -> None:
-    """Insert rows into a Many-to-Many association table without loading the ORM collection.
-
-    Args:
-        session: DB async session.
-        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
-        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
-        *related: One or more related instances to associate with ``instance``.
-        ignore_conflicts: When ``True``, silently skip rows that already exist
-            in the association table (``ON CONFLICT DO NOTHING``).
-
-    Raises:
-        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
-    """
-    prop = _m2m_prop(rel_attr)
-    if not related:
-        return
-
-    secondary = cast(Table, prop.secondary)
-    assert secondary is not None  # guaranteed by _m2m_prop
-    sync_pairs = prop.secondary_synchronize_pairs
-    assert sync_pairs is not None  # set whenever secondary is set
-
-    # synchronize_pairs:           [(parent_col, assoc_col), ...]
-    # secondary_synchronize_pairs: [(related_col, assoc_col), ...]
-    rows: list[dict[str, Any]] = []
-    for rel_instance in related:
-        row: dict[str, Any] = {}
-        for parent_col, assoc_col in prop.synchronize_pairs:
-            row[assoc_col.name] = getattr(instance, cast(str, parent_col.key))
-        for related_col, assoc_col in sync_pairs:
-            row[assoc_col.name] = getattr(rel_instance, cast(str, related_col.key))
-        rows.append(row)
-
-    stmt = pg_insert(secondary).values(rows)
-    if ignore_conflicts:
-        stmt = stmt.on_conflict_do_nothing()
-    await session.execute(stmt)
-
-
-async def m2m_remove(
-    session: AsyncSession,
-    instance: DeclarativeBase,
-    rel_attr: QueryableAttribute,
-    *related: DeclarativeBase,
-) -> None:
-    """Remove rows from a Many-to-Many association table without loading the ORM collection.
-
-    Args:
-        session: DB async session.
-        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
-        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
-        *related: One or more related instances to disassociate from ``instance``.
-
-    Raises:
-        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
-    """
-    prop = _m2m_prop(rel_attr)
-    if not related:
-        return
-
-    secondary = cast(Table, prop.secondary)
-    assert secondary is not None  # guaranteed by _m2m_prop
-    related_pairs = prop.secondary_synchronize_pairs
-    assert related_pairs is not None  # set whenever secondary is set
-
-    parent_where = [
-        assoc_col == getattr(instance, cast(str, parent_col.key))
-        for parent_col, assoc_col in prop.synchronize_pairs
-    ]
-
-    if len(related_pairs) == 1:
-        related_col, assoc_col = related_pairs[0]
-        related_values = [getattr(r, cast(str, related_col.key)) for r in related]
-        related_where = assoc_col.in_(related_values)
-    else:
-        assoc_cols = [ac for _, ac in related_pairs]
-        rel_cols = [rc for rc, _ in related_pairs]
-        related_values_t = [
-            tuple(getattr(r, cast(str, rc.key)) for rc in rel_cols) for r in related
-        ]
-        related_where = tuple_(*assoc_cols).in_(related_values_t)
-
-    await session.execute(delete(secondary).where(*parent_where, related_where))
-
-
-async def m2m_set(
-    session: AsyncSession,
-    instance: DeclarativeBase,
-    rel_attr: QueryableAttribute,
-    *related: DeclarativeBase,
-) -> None:
-    """Replace the entire Many-to-Many association set atomically.
-
-    Args:
-        session: DB async session.
-        instance: The "owner" side model instance (e.g. the ``A`` in ``A.b_list``).
-        rel_attr: The M2M relationship attribute on the model class (e.g. ``A.b_list``).
-        *related: The new complete set of related instances.
-
-    Raises:
-        TypeError: If ``rel_attr`` is not a Many-to-Many relationship.
-    """
-    prop = _m2m_prop(rel_attr)
-    secondary = cast(Table, prop.secondary)
-    assert secondary is not None  # guaranteed by _m2m_prop
-
-    parent_where = [
-        assoc_col == getattr(instance, cast(str, parent_col.key))
-        for parent_col, assoc_col in prop.synchronize_pairs
-    ]
-    await session.execute(delete(secondary).where(*parent_where))
-
-    if related:
-        await m2m_add(session, instance, rel_attr, *related)

src/fastapi_toolsets/fixtures/__init__.py

@@ -2,18 +2,12 @@
 
 from .enum import LoadStrategy
 from .registry import Context, FixtureRegistry
-from .utils import (
+from .utils import get_obj_by_attr, load_fixtures, load_fixtures_by_context
-    get_field_by_attr,
-    get_obj_by_attr,
-    load_fixtures,
-    load_fixtures_by_context,
-)
 
 __all__ = [
     "Context",
     "FixtureRegistry",
     "LoadStrategy",
-    "get_field_by_attr",
     "get_obj_by_attr",
     "load_fixtures",
     "load_fixtures_by_context",

src/fastapi_toolsets/fixtures/utils.py

@@ -250,31 +250,6 @@ def get_obj_by_attr(
         ) from None
 
 
-def get_field_by_attr(
-    fixtures: Callable[[], Sequence[ModelType]],
-    attr_name: str,
-    value: Any,
-    *,
-    field: str = "id",
-) -> Any:
-    """Get a single field value from a fixture object matched by an attribute.
-
-    Args:
-        fixtures: A fixture function registered via ``@registry.register``
-            that returns a sequence of SQLAlchemy model instances.
-        attr_name: Name of the attribute to match against.
-        value: Value to match.
-        field: Attribute name to return from the matched object (default: ``"id"``).
-
-    Returns:
-        The value of ``field`` on the first matching model instance.
-
-    Raises:
-        StopIteration: If no matching object is found in the fixture group.
-    """
-    return getattr(get_obj_by_attr(fixtures, attr_name, value), field)
-
-
 async def load_fixtures(
     session: AsyncSession,
     registry: FixtureRegistry,

src/fastapi_toolsets/pytest/plugin.py

@@ -1,13 +1,11 @@
 """Pytest plugin for using FixtureRegistry fixtures in tests."""
 
 from collections.abc import Callable, Sequence
-from typing import Any, cast
+from typing import Any
 
 import pytest
-from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import DeclarativeBase, selectinload
+from sqlalchemy.orm import DeclarativeBase
-from sqlalchemy.orm.interfaces import ExecutableOption, ORMOption
 
 from ..db import get_transaction
 from ..fixtures import FixtureRegistry, LoadStrategy
@@ -114,7 +112,7 @@ def _create_fixture_function(
                 elif strategy == LoadStrategy.MERGE:
                     merged = await session.merge(instance)
                     loaded.append(merged)
-                elif strategy == LoadStrategy.SKIP_EXISTING:  # pragma: no branch
+                elif strategy == LoadStrategy.SKIP_EXISTING:
                     pk = _get_primary_key(instance)
                     if pk is not None:
                         existing = await session.get(type(instance), pk)
@@ -127,11 +125,6 @@ def _create_fixture_function(
                         session.add(instance)
                         loaded.append(instance)
 
-        if loaded:  # pragma: no branch
-            load_options = _relationship_load_options(type(loaded[0]))
-            if load_options:
-                return await _reload_with_relationships(session, loaded, load_options)
-
         return loaded
 
     # Update function signature to include dependencies
@@ -148,54 +141,6 @@ def _create_fixture_function(
     return created_func
 
 
-def _relationship_load_options(model: type[DeclarativeBase]) -> list[ExecutableOption]:
-    """Build selectinload options for all direct relationships on a model."""
-    return [
-        selectinload(getattr(model, rel.key)) for rel in model.__mapper__.relationships
-    ]
-
-
-async def _reload_with_relationships(
-    session: AsyncSession,
-    instances: list[DeclarativeBase],
-    load_options: list[ExecutableOption],
-) -> list[DeclarativeBase]:
-    """Reload instances in a single bulk query with relationship eager-loading.
-
-    Uses one SELECT … WHERE pk IN (…) so selectinload can batch all relationship
-    queries — 1 + N_relationships round-trips regardless of how many instances
-    there are, instead of one session.get() per instance.
-
-    Preserves the original insertion order.
-    """
-    model = type(instances[0])
-    mapper = model.__mapper__
-    pk_cols = mapper.primary_key
-
-    if len(pk_cols) == 1:
-        pk_attr = getattr(model, pk_cols[0].key)
-        pks = [getattr(inst, pk_cols[0].key) for inst in instances]
-        result = await session.execute(
-            select(model).where(pk_attr.in_(pks)).options(*load_options)
-        )
-        by_pk = {getattr(row, pk_cols[0].key): row for row in result.unique().scalars()}
-        return [by_pk[pk] for pk in pks]
-
-    # Composite PK: fall back to per-instance reload
-    reloaded: list[DeclarativeBase] = []
-    for instance in instances:
-        pk = _get_primary_key(instance)
-        refreshed = await session.get(
-            model,
-            pk,
-            options=cast(list[ORMOption], load_options),
-            populate_existing=True,
-        )
-        if refreshed is not None:  # pragma: no branch
-            reloaded.append(refreshed)
-    return reloaded
-
-
 def _get_primary_key(instance: DeclarativeBase) -> Any | None:
     """Get the primary key value of a model instance."""
     mapper = instance.__class__.__mapper__

src/fastapi_toolsets/types.py

@@ -16,6 +16,7 @@ SchemaType = TypeVar("SchemaType", bound=BaseModel)
 
 # CRUD type aliases
 JoinType = list[tuple[type[DeclarativeBase] | Any, Any]]
+LateralJoinType = list[tuple[Any, Any]]
 M2MFieldType = Mapping[str, QueryableAttribute[Any]]
 OrderByClause = ColumnElement[Any] | QueryableAttribute[Any]
 

tests/test_crud.py

@@ -6,9 +6,15 @@ import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
-from fastapi_toolsets.crud import CrudFactory, PaginationType
+from fastapi_toolsets.crud import CrudFactory, PaginationType, lateral_load
-from fastapi_toolsets.crud.factory import AsyncCrud, _CursorDirection
+from fastapi_toolsets.crud.factory import (
+    AsyncCrud,
+    _CursorDirection,
+    _LateralLoad,
+    _ResolvedLateral,
+)
 from fastapi_toolsets.exceptions import NotFoundError
+from fastapi_toolsets.schemas import PydanticBase
 
 from .conftest import (
     EventCreate,
@@ -51,6 +57,12 @@ from .conftest import (
 )
 
 
+class UserWithRoleRead(PydanticBase):
+    id: uuid.UUID
+    username: str
+    role: RoleRead | None = None
+
+
 class TestCrudFactory:
     """Tests for CrudFactory."""
 
@@ -208,11 +220,11 @@ class TestResolveLoadOptions:
         assert crud._resolve_load_options(None) is None
 
     def test_empty_list_overrides_default(self):
-        """An empty list is a valid override and disables default_load_options."""
+        """An explicit empty list disables default_load_options (no options applied)."""
         default = [selectinload(User.role)]
         crud = CrudFactory(User, default_load_options=default)
-        # Empty list is not None, so it should replace default
+        # Empty list replaces default; None and [] are both falsy → no options applied
-        assert crud._resolve_load_options([]) == []
+        assert not crud._resolve_load_options([])
 
 
 class TestResolveSearchColumns:
@@ -359,13 +371,6 @@ class TestDefaultLoadOptionsIntegration:
         self, db_session: AsyncSession
     ):
         """default_load_options loads relationships automatically on offset_paginate()."""
-        from fastapi_toolsets.schemas import PydanticBase
-
-        class UserWithRoleRead(PydanticBase):
-            id: uuid.UUID
-            username: str
-            role: RoleRead | None = None
-
         UserWithDefaultLoad = CrudFactory(
             User, default_load_options=[selectinload(User.role)]
         )
@@ -2462,12 +2467,7 @@ class TestCursorPaginateExtraOptions:
     @pytest.mark.anyio
     async def test_with_load_options(self, db_session: AsyncSession):
         """cursor_paginate passes load_options to the query."""
-        from fastapi_toolsets.schemas import CursorPagination, PydanticBase
+        from fastapi_toolsets.schemas import CursorPagination
-
-        class UserWithRoleRead(PydanticBase):
-            id: uuid.UUID
-            username: str
-            role: RoleRead | None = None
 
         role = await RoleCrud.create(db_session, RoleCreate(name="manager"))
         for i in range(3):
@@ -2833,3 +2833,445 @@ class TestPaginate:
 
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count is None
+
+
+class TestLateralLoadValidation:
+    """lateral_load() raises immediately for bad relationship types."""
+
+    def test_valid_many_to_one_returns_marker(self):
+        """lateral_load() on a Many:One rel returns a _LateralLoad with rel_attr set."""
+        marker = lateral_load(User.role)
+        assert isinstance(marker, _LateralLoad)
+        assert marker.rel_attr is User.role
+
+    def test_raises_type_error_for_plain_column(self):
+        """lateral_load() raises TypeError when passed a plain column."""
+        with pytest.raises(TypeError, match="relationship attribute"):
+            lateral_load(User.username)
+
+    def test_raises_value_error_for_many_to_many(self):
+        """lateral_load() raises ValueError for Many:Many (secondary table)."""
+        with pytest.raises(ValueError, match="Many:Many"):
+            lateral_load(Post.tags)
+
+    def test_raises_value_error_for_one_to_many(self):
+        """lateral_load() raises ValueError for One:Many (uselist=True)."""
+        with pytest.raises(ValueError, match="One:Many"):
+            lateral_load(Role.users)
+
+
+class TestLateralLoadInSubclass:
+    """lateral_load() markers in default_load_options are processed at class definition."""
+
+    def test_marker_extracted_from_default_load_options(self):
+        """_LateralLoad is removed from default_load_options and stored in _resolved_lateral."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        assert UserLateralCrud.default_load_options is None
+        assert UserLateralCrud._resolved_lateral is not None
+
+    def test_resolved_lateral_has_one_join_and_eager(self):
+        """_resolved_lateral contains exactly one join and one eager option."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        resolved = UserLateralCrud._resolved_lateral
+        assert isinstance(resolved, _ResolvedLateral)
+        assert len(resolved.joins) == 1
+        assert len(resolved.eager) == 1
+
+    def test_regular_options_preserved_alongside_lateral(self):
+        """Non-lateral opts stay in default_load_options; lateral marker is extracted."""
+        regular = selectinload(User.role)
+
+        class UserMixedCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role), regular]
+
+        assert UserMixedCrud._resolved_lateral is not None
+        assert UserMixedCrud.default_load_options == [regular]
+
+    def test_no_lateral_leaves_default_load_options_untouched(self):
+        """When no lateral marker is present, default_load_options is unchanged."""
+        opts = [selectinload(User.role)]
+
+        class UserNormalCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = opts
+
+        assert UserNormalCrud.default_load_options is opts
+        assert UserNormalCrud._resolved_lateral is None
+
+    def test_no_default_load_options_leaves_resolved_lateral_none(self):
+        """_resolved_lateral stays None when default_load_options is not set."""
+
+        class UserPlainCrud(AsyncCrud[User]):
+            model = User
+
+        assert UserPlainCrud._resolved_lateral is None
+
+
+class TestResolveLoadOptionsWithLateral:
+    """_resolve_load_options always appends lateral eager options."""
+
+    def test_lateral_eager_included_when_no_call_site_opts(self):
+        """contains_eager from lateral_load is returned when load_options=None."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        resolved = UserLateralCrud._resolve_load_options(None)
+        assert resolved is not None
+        assert len(resolved) == 1  # the contains_eager
+
+    def test_call_site_opts_bypass_lateral_eager(self):
+        """When call-site load_options are provided, lateral eager is NOT appended."""
+        extra = selectinload(User.role)
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        resolved = UserLateralCrud._resolve_load_options([extra])
+        assert resolved is not None
+        assert len(resolved) == 1  # only the call-site option; lateral eager skipped
+
+    def test_lateral_eager_appended_to_default_load_options(self):
+        """default_load_options (regular) + lateral eager are both returned."""
+        regular = selectinload(User.role)
+
+        class UserMixedCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role), regular]
+
+        resolved = UserMixedCrud._resolve_load_options(None)
+        assert resolved is not None
+        assert len(resolved) == 2
+
+
+class TestGetLateralJoins:
+    """_get_lateral_joins merges auto-resolved and manual lateral_joins."""
+
+    def test_returns_none_when_no_lateral_configured(self):
+        """Returns None when neither lateral_joins nor lateral_load is set."""
+
+        class UserPlainCrud(AsyncCrud[User]):
+            model = User
+
+        assert UserPlainCrud._get_lateral_joins() is None
+
+    def test_returns_resolved_lateral_joins(self):
+        """Returns the join tuple built from lateral_load()."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        joins = UserLateralCrud._get_lateral_joins()
+        assert joins is not None
+        assert len(joins) == 1
+
+    def test_manual_lateral_joins_included(self):
+        """Manual lateral_joins class var is included in _get_lateral_joins."""
+        from sqlalchemy import select, true
+
+        manual_sub = select(Role).where(Role.id == User.role_id).lateral("_manual_role")
+
+        class UserManualCrud(AsyncCrud[User]):
+            model = User
+            lateral_joins = [(manual_sub, true())]
+
+        joins = UserManualCrud._get_lateral_joins()
+        assert joins is not None
+        assert len(joins) == 1
+
+    def test_manual_and_auto_lateral_joins_merged(self):
+        """Both manual lateral_joins and auto-resolved from lateral_load are combined."""
+        from sqlalchemy import select, true
+
+        manual_sub = select(Role).where(Role.id == User.role_id).lateral("_manual_role")
+
+        class UserBothCrud(AsyncCrud[User]):
+            model = User
+            lateral_joins = [(manual_sub, true())]
+            default_load_options = [lateral_load(User.role)]
+
+        joins = UserBothCrud._get_lateral_joins()
+        assert joins is not None
+        assert len(joins) == 2
+
+
+class TestLateralLoadIntegration:
+    """lateral_load() in real DB queries: relationship loaded, pagination correct."""
+
+    @pytest.mark.anyio
+    async def test_get_loads_relationship(self, db_session: AsyncSession):
+        """get() populates the relationship via lateral join."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        user = await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
+        )
+
+        fetched = await UserLateralCrud.get(db_session, [User.id == user.id])
+        assert fetched.role is not None
+        assert fetched.role.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_get_null_fk_preserved(self, db_session: AsyncSession):
+        """User with null role_id still returned (LEFT JOIN behaviour)."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        user = await UserCrud.create(
+            db_session, UserCreate(username="bob", email="bob@test.com")
+        )
+
+        fetched = await UserLateralCrud.get(db_session, [User.id == user.id])
+        assert fetched is not None
+        assert fetched.role is None
+
+    @pytest.mark.anyio
+    async def test_first_loads_relationship(self, db_session: AsyncSession):
+        """first() populates the relationship via lateral join."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="editor"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="carol", email="carol@test.com", role_id=role.id),
+        )
+
+        user = await UserLateralCrud.first(db_session)
+        assert user is not None
+        assert user.role is not None
+        assert user.role.name == "editor"
+
+    @pytest.mark.anyio
+    async def test_get_multi_loads_relationship(self, db_session: AsyncSession):
+        """get_multi() populates the relationship via lateral join for all rows."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="member"))
+        for i in range(3):
+            await UserCrud.create(
+                db_session,
+                UserCreate(
+                    username=f"user{i}", email=f"u{i}@test.com", role_id=role.id
+                ),
+            )
+
+        users = await UserLateralCrud.get_multi(db_session)
+        assert len(users) == 3
+        assert all(u.role is not None and u.role.name == "member" for u in users)
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_correct_count(self, db_session: AsyncSession):
+        """offset_paginate total_count is not inflated by the lateral join."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        for i in range(5):
+            await UserCrud.create(
+                db_session,
+                UserCreate(
+                    username=f"user{i}", email=f"u{i}@test.com", role_id=role.id
+                ),
+            )
+
+        result = await UserLateralCrud.offset_paginate(
+            db_session, schema=UserWithRoleRead, items_per_page=10
+        )
+        assert result.pagination.total_count == 5
+        assert len(result.data) == 5
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_loads_relationship(self, db_session: AsyncSession):
+        """offset_paginate serializes relationship data loaded via lateral."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
+        )
+
+        result = await UserLateralCrud.offset_paginate(
+            db_session, schema=UserWithRoleRead, items_per_page=10
+        )
+        assert result.data[0].role is not None
+        assert result.data[0].role.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_mixed_null_fk(self, db_session: AsyncSession):
+        """offset_paginate returns all users including those with null role_id."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="with_role", email="a@test.com", role_id=role.id),
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="no_role", email="b@test.com")
+        )
+
+        result = await UserLateralCrud.offset_paginate(
+            db_session, schema=UserWithRoleRead, items_per_page=10
+        )
+        assert result.pagination.total_count == 2
+
+    @pytest.mark.anyio
+    async def test_cursor_paginate_loads_relationship(self, db_session: AsyncSession):
+        """cursor_paginate populates the relationship via lateral join."""
+
+        class UserLateralCursorCrud(AsyncCrud[User]):
+            model = User
+            cursor_column = User.id
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        for i in range(3):
+            await UserCrud.create(
+                db_session,
+                UserCreate(
+                    username=f"user{i}", email=f"u{i}@test.com", role_id=role.id
+                ),
+            )
+
+        result = await UserLateralCursorCrud.cursor_paginate(
+            db_session, schema=UserWithRoleRead, items_per_page=10
+        )
+        assert len(result.data) == 3
+        assert all(item.role is not None for item in result.data)
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_with_search_and_lateral(
+        self, db_session: AsyncSession
+    ):
+        """search filter works alongside lateral join."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+            searchable_fields = [User.username]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="a@test.com", role_id=role.id),
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com", role_id=role.id)
+        )
+
+        result = await UserLateralCrud.offset_paginate(
+            db_session, schema=UserWithRoleRead, search="alice", items_per_page=10
+        )
+        assert result.pagination.total_count == 1
+        assert result.data[0].username == "alice"
+
+    @pytest.mark.anyio
+    async def test_first_call_site_load_options_bypasses_lateral(
+        self, db_session: AsyncSession
+    ):
+        """When load_options is provided, lateral join is skipped (no conflict)."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        user = await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
+        )
+
+        # Passing explicit load_options bypasses the lateral join — role loaded via selectinload
+        fetched = await UserLateralCrud.first(
+            db_session,
+            filters=[User.id == user.id],
+            load_options=[selectinload(User.role)],
+        )
+        assert fetched is not None
+        assert fetched.role is not None
+        assert fetched.role.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_get_multi_call_site_load_options_bypasses_lateral(
+        self, db_session: AsyncSession
+    ):
+        """When load_options is provided, lateral join is skipped (no conflict)."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="viewer"))
+        for i in range(2):
+            await UserCrud.create(
+                db_session,
+                UserCreate(username=f"u{i}", email=f"u{i}@test.com", role_id=role.id),
+            )
+
+        # Passing explicit load_options bypasses the lateral join — role loaded via selectinload
+        users = await UserLateralCrud.get_multi(
+            db_session, load_options=[selectinload(User.role)]
+        )
+        assert len(users) == 2
+        assert all(u.role is not None and u.role.name == "viewer" for u in users)
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_call_site_load_options_bypasses_lateral(
+        self, db_session: AsyncSession
+    ):
+        """When load_options is provided, lateral join is skipped (no conflict)."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="editor"))
+        for i in range(3):
+            await UserCrud.create(
+                db_session,
+                UserCreate(username=f"e{i}", email=f"e{i}@test.com", role_id=role.id),
+            )
+
+        # Passing explicit load_options bypasses the lateral join — role loaded via selectinload
+        result = await UserLateralCrud.offset_paginate(
+            db_session,
+            schema=UserWithRoleRead,
+            items_per_page=10,
+            load_options=[selectinload(User.role)],
+        )
+        assert result.pagination.total_count == 3
+        assert all(item.role is not None for item in result.data)

tests/test_db.py

@@ -4,26 +4,10 @@ import asyncio
 import uuid
 
 import pytest
-from sqlalchemy import (
+from sqlalchemy import text
-    Column,
-    ForeignKey,
-    ForeignKeyConstraint,
-    String,
-    Table,
-    Uuid,
-    select,
-    text,
-)
 from sqlalchemy.engine import make_url
-from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
-from sqlalchemy.orm import (
+from sqlalchemy.orm import DeclarativeBase
-    DeclarativeBase,
-    Mapped,
-    mapped_column,
-    relationship,
-    selectinload,
-)
 
 from fastapi_toolsets.db import (
     LockMode,
@@ -33,15 +17,12 @@ from fastapi_toolsets.db import (
     create_db_dependency,
     get_transaction,
     lock_tables,
-    m2m_add,
-    m2m_remove,
-    m2m_set,
     wait_for_row_change,
 )
 from fastapi_toolsets.exceptions import NotFoundError
 from fastapi_toolsets.pytest import create_db_session
 
-from .conftest import DATABASE_URL, Base, Post, Role, RoleCrud, Tag, User, UserCrud
+from .conftest import DATABASE_URL, Base, Role, RoleCrud, User, UserCrud
 
 
 class TestCreateDbDependency:
@@ -100,21 +81,6 @@ class TestCreateDbDependency:
 
         await engine.dispose()
 
-    @pytest.mark.anyio
-    async def test_no_commit_when_not_in_transaction(self):
-        """Dependency skips commit if the session is no longer in a transaction on exit."""
-        engine = create_async_engine(DATABASE_URL, echo=False)
-        session_factory = async_sessionmaker(engine, expire_on_commit=False)
-        get_db = create_db_dependency(session_factory)
-
-        async for session in get_db():
-            # Manually commit — session exits the transaction
-            await session.commit()
-            assert not session.in_transaction()
-            # The dependency's post-yield path must not call commit again (no error)
-
-        await engine.dispose()
-
     @pytest.mark.anyio
     async def test_update_after_lock_tables_is_persisted(self):
         """Changes made after lock_tables exits (before endpoint returns) are committed.
@@ -514,417 +480,3 @@ class TestCleanupTables:
         async with create_db_session(DATABASE_URL, Base, drop_tables=True) as session:
             # Should not raise
             await cleanup_tables(session, EmptyBase)
-
-
-class TestM2MAdd:
-    """Tests for m2m_add helper."""
-
-    @pytest.mark.anyio
-    async def test_adds_single_related(self, db_session: AsyncSession):
-        """Associates one related instance via the secondary table."""
-        user = User(username="m2m_author", email="m2m@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        post = Post(title="Post A", author_id=user.id)
-        tag = Tag(name="python")
-        db_session.add_all([post, tag])
-        await db_session.flush()
-
-        async with get_transaction(db_session):
-            await m2m_add(db_session, post, Post.tags, tag)
-
-        result = await db_session.execute(
-            select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
-        )
-        loaded = result.scalar_one()
-        assert len(loaded.tags) == 1
-        assert loaded.tags[0].id == tag.id
-
-    @pytest.mark.anyio
-    async def test_adds_multiple_related(self, db_session: AsyncSession):
-        """Associates multiple related instances in a single call."""
-        user = User(username="m2m_author2", email="m2m2@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        post = Post(title="Post B", author_id=user.id)
-        tag1 = Tag(name="web")
-        tag2 = Tag(name="api")
-        tag3 = Tag(name="async")
-        db_session.add_all([post, tag1, tag2, tag3])
-        await db_session.flush()
-
-        async with get_transaction(db_session):
-            await m2m_add(db_session, post, Post.tags, tag1, tag2, tag3)
-
-        result = await db_session.execute(
-            select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
-        )
-        loaded = result.scalar_one()
-        assert {t.id for t in loaded.tags} == {tag1.id, tag2.id, tag3.id}
-
-    @pytest.mark.anyio
-    async def test_noop_for_empty_related(self, db_session: AsyncSession):
-        """Calling with no related instances is a no-op."""
-        user = User(username="m2m_author3", email="m2m3@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        post = Post(title="Post C", author_id=user.id)
-        db_session.add(post)
-        await db_session.flush()
-
-        async with get_transaction(db_session):
-            await m2m_add(db_session, post, Post.tags)  # no related instances
-
-        result = await db_session.execute(
-            select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
-        )
-        loaded = result.scalar_one()
-        assert loaded.tags == []
-
-    @pytest.mark.anyio
-    async def test_ignore_conflicts_true(self, db_session: AsyncSession):
-        """Duplicate inserts are silently skipped when ignore_conflicts=True."""
-        user = User(username="m2m_author4", email="m2m4@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        post = Post(title="Post D", author_id=user.id)
-        tag = Tag(name="duplicate_tag")
-        db_session.add_all([post, tag])
-        await db_session.flush()
-
-        async with get_transaction(db_session):
-            await m2m_add(db_session, post, Post.tags, tag)
-
-        # Second call with ignore_conflicts=True must not raise
-        async with get_transaction(db_session):
-            await m2m_add(db_session, post, Post.tags, tag, ignore_conflicts=True)
-
-        result = await db_session.execute(
-            select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
-        )
-        loaded = result.scalar_one()
-        assert len(loaded.tags) == 1
-
-    @pytest.mark.anyio
-    async def test_ignore_conflicts_false_raises(self, db_session: AsyncSession):
-        """Duplicate inserts raise IntegrityError when ignore_conflicts=False (default)."""
-        user = User(username="m2m_author5", email="m2m5@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        post = Post(title="Post E", author_id=user.id)
-        tag = Tag(name="conflict_tag")
-        db_session.add_all([post, tag])
-        await db_session.flush()
-
-        async with get_transaction(db_session):
-            await m2m_add(db_session, post, Post.tags, tag)
-
-        with pytest.raises(IntegrityError):
-            async with get_transaction(db_session):
-                await m2m_add(db_session, post, Post.tags, tag)
-
-    @pytest.mark.anyio
-    async def test_non_m2m_raises_type_error(self, db_session: AsyncSession):
-        """Passing a non-M2M relationship attribute raises TypeError."""
-        user = User(username="m2m_author6", email="m2m6@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        role = Role(name="type_err_role")
-        db_session.add(role)
-        await db_session.flush()
-
-        with pytest.raises(TypeError, match="Many-to-Many"):
-            await m2m_add(db_session, user, User.role, role)
-
-    @pytest.mark.anyio
-    async def test_works_inside_lock_tables(self, db_session: AsyncSession):
-        """m2m_add works correctly inside a lock_tables nested transaction."""
-        user = User(username="m2m_lock_author", email="m2m_lock@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        async with lock_tables(db_session, [Tag]):
-            tag = Tag(name="locked_tag")
-            db_session.add(tag)
-            await db_session.flush()
-
-            post = Post(title="Post Lock", author_id=user.id)
-            db_session.add(post)
-            await db_session.flush()
-
-            await m2m_add(db_session, post, Post.tags, tag)
-
-        result = await db_session.execute(
-            select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
-        )
-        loaded = result.scalar_one()
-        assert len(loaded.tags) == 1
-        assert loaded.tags[0].name == "locked_tag"
-
-
-class _LocalBase(DeclarativeBase):
-    pass
-
-
-_comp_assoc = Table(
-    "_comp_assoc",
-    _LocalBase.metadata,
-    Column("owner_id", Uuid, ForeignKey("_comp_owners.id"), primary_key=True),
-    Column("item_group", String(50), primary_key=True),
-    Column("item_code", String(50), primary_key=True),
-    ForeignKeyConstraint(
-        ["item_group", "item_code"],
-        ["_comp_items.group_id", "_comp_items.item_code"],
-    ),
-)
-
-
-class _CompOwner(_LocalBase):
-    __tablename__ = "_comp_owners"
-    id: Mapped[uuid.UUID] = mapped_column(Uuid, primary_key=True, default=uuid.uuid4)
-    items: Mapped[list["_CompItem"]] = relationship(secondary=_comp_assoc)
-
-
-class _CompItem(_LocalBase):
-    __tablename__ = "_comp_items"
-    group_id: Mapped[str] = mapped_column(String(50), primary_key=True)
-    item_code: Mapped[str] = mapped_column(String(50), primary_key=True)
-
-
-class TestM2MRemove:
-    """Tests for m2m_remove helper."""
-
-    async def _setup(
-        self, session: AsyncSession, username: str, email: str, *tag_names: str
-    ):
-        """Create a user, post, and tags; associate all tags with the post."""
-        user = User(username=username, email=email)
-        session.add(user)
-        await session.flush()
-
-        post = Post(title=f"Post {username}", author_id=user.id)
-        tags = [Tag(name=n) for n in tag_names]
-        session.add(post)
-        session.add_all(tags)
-        await session.flush()
-
-        async with get_transaction(session):
-            await m2m_add(session, post, Post.tags, *tags)
-
-        return post, tags
-
-    async def _load_tags(self, session: AsyncSession, post: Post) -> list[Tag]:
-        result = await session.execute(
-            select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
-        )
-        return result.scalar_one().tags
-
-    @pytest.mark.anyio
-    async def test_removes_single(self, db_session: AsyncSession):
-        """Removes one association, leaving others intact."""
-        post, (tag1, tag2) = await self._setup(
-            db_session, "rm_author1", "rm1@test.com", "tag_rm_a", "tag_rm_b"
-        )
-
-        async with get_transaction(db_session):
-            await m2m_remove(db_session, post, Post.tags, tag1)
-
-        remaining = await self._load_tags(db_session, post)
-        assert len(remaining) == 1
-        assert remaining[0].id == tag2.id
-
-    @pytest.mark.anyio
-    async def test_removes_multiple(self, db_session: AsyncSession):
-        """Removes multiple associations in one call."""
-        post, (tag1, tag2, tag3) = await self._setup(
-            db_session, "rm_author2", "rm2@test.com", "tag_rm_c", "tag_rm_d", "tag_rm_e"
-        )
-
-        async with get_transaction(db_session):
-            await m2m_remove(db_session, post, Post.tags, tag1, tag3)
-
-        remaining = await self._load_tags(db_session, post)
-        assert len(remaining) == 1
-        assert remaining[0].id == tag2.id
-
-    @pytest.mark.anyio
-    async def test_noop_for_empty_related(self, db_session: AsyncSession):
-        """Calling with no related instances is a no-op."""
-        post, (tag,) = await self._setup(
-            db_session, "rm_author3", "rm3@test.com", "tag_rm_f"
-        )
-
-        async with get_transaction(db_session):
-            await m2m_remove(db_session, post, Post.tags)
-
-        remaining = await self._load_tags(db_session, post)
-        assert len(remaining) == 1
-
-    @pytest.mark.anyio
-    async def test_idempotent_for_missing_association(self, db_session: AsyncSession):
-        """Removing a non-existent association does not raise."""
-        post, (tag1,) = await self._setup(
-            db_session, "rm_author4", "rm4@test.com", "tag_rm_g"
-        )
-        tag2 = Tag(name="tag_rm_h")
-        db_session.add(tag2)
-        await db_session.flush()
-
-        # tag2 was never associated — should not raise
-        async with get_transaction(db_session):
-            await m2m_remove(db_session, post, Post.tags, tag2)
-
-        remaining = await self._load_tags(db_session, post)
-        assert len(remaining) == 1
-
-    @pytest.mark.anyio
-    async def test_non_m2m_raises_type_error(self, db_session: AsyncSession):
-        """Passing a non-M2M relationship attribute raises TypeError."""
-        user = User(username="rm_author5", email="rm5@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        role = Role(name="rm_type_err_role")
-        db_session.add(role)
-        await db_session.flush()
-
-        with pytest.raises(TypeError, match="Many-to-Many"):
-            await m2m_remove(db_session, user, User.role, role)
-
-    @pytest.mark.anyio
-    async def test_removes_composite_pk_related(self):
-        """Composite-PK branch: DELETE uses tuple IN when related side has multi-col PK."""
-        engine = create_async_engine(DATABASE_URL, echo=False)
-        async with engine.begin() as conn:
-            await conn.run_sync(_LocalBase.metadata.create_all)
-
-        session_factory = async_sessionmaker(engine, expire_on_commit=False)
-        try:
-            async with session_factory() as session:
-                owner = _CompOwner()
-                item1 = _CompItem(group_id="g1", item_code="c1")
-                item2 = _CompItem(group_id="g1", item_code="c2")
-                session.add_all([owner, item1, item2])
-                await session.flush()
-
-                async with get_transaction(session):
-                    await m2m_add(session, owner, _CompOwner.items, item1, item2)
-
-                async with get_transaction(session):
-                    await m2m_remove(session, owner, _CompOwner.items, item1)
-
-                await session.commit()
-
-            async with session_factory() as verify:
-                from sqlalchemy import select
-                from sqlalchemy.orm import selectinload
-
-                result = await verify.execute(
-                    select(_CompOwner)
-                    .where(_CompOwner.id == owner.id)
-                    .options(selectinload(_CompOwner.items))
-                )
-                loaded = result.scalar_one()
-                assert len(loaded.items) == 1
-                assert (loaded.items[0].group_id, loaded.items[0].item_code) == (
-                    "g1",
-                    "c2",
-                )
-        finally:
-            async with engine.begin() as conn:
-                await conn.run_sync(_LocalBase.metadata.drop_all)
-            await engine.dispose()
-
-
-class TestM2MSet:
-    """Tests for m2m_set helper."""
-
-    async def _load_tags(self, session: AsyncSession, post: Post) -> list[Tag]:
-        result = await session.execute(
-            select(Post).where(Post.id == post.id).options(selectinload(Post.tags))
-        )
-        return result.scalar_one().tags
-
-    @pytest.mark.anyio
-    async def test_replaces_existing_set(self, db_session: AsyncSession):
-        """Replaces the full association set atomically."""
-        user = User(username="set_author1", email="set1@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        post = Post(title="Post Set A", author_id=user.id)
-        tag1 = Tag(name="tag_set_a")
-        tag2 = Tag(name="tag_set_b")
-        tag3 = Tag(name="tag_set_c")
-        db_session.add_all([post, tag1, tag2, tag3])
-        await db_session.flush()
-
-        async with get_transaction(db_session):
-            await m2m_add(db_session, post, Post.tags, tag1, tag2)
-
-        async with get_transaction(db_session):
-            await m2m_set(db_session, post, Post.tags, tag3)
-
-        remaining = await self._load_tags(db_session, post)
-        assert len(remaining) == 1
-        assert remaining[0].id == tag3.id
-
-    @pytest.mark.anyio
-    async def test_clears_all_when_no_related(self, db_session: AsyncSession):
-        """Passing no related instances clears all associations."""
-        user = User(username="set_author2", email="set2@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        post = Post(title="Post Set B", author_id=user.id)
-        tag = Tag(name="tag_set_d")
-        db_session.add_all([post, tag])
-        await db_session.flush()
-
-        async with get_transaction(db_session):
-            await m2m_add(db_session, post, Post.tags, tag)
-
-        async with get_transaction(db_session):
-            await m2m_set(db_session, post, Post.tags)
-
-        remaining = await self._load_tags(db_session, post)
-        assert remaining == []
-
-    @pytest.mark.anyio
-    async def test_set_on_empty_then_populate(self, db_session: AsyncSession):
-        """m2m_set works on a post with no existing associations."""
-        user = User(username="set_author3", email="set3@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        post = Post(title="Post Set C", author_id=user.id)
-        tag1 = Tag(name="tag_set_e")
-        tag2 = Tag(name="tag_set_f")
-        db_session.add_all([post, tag1, tag2])
-        await db_session.flush()
-
-        async with get_transaction(db_session):
-            await m2m_set(db_session, post, Post.tags, tag1, tag2)
-
-        remaining = await self._load_tags(db_session, post)
-        assert {t.id for t in remaining} == {tag1.id, tag2.id}
-
-    @pytest.mark.anyio
-    async def test_non_m2m_raises_type_error(self, db_session: AsyncSession):
-        """Passing a non-M2M relationship attribute raises TypeError."""
-        user = User(username="set_author4", email="set4@test.com")
-        db_session.add(user)
-        await db_session.flush()
-
-        role = Role(name="set_type_err_role")
-        db_session.add(role)
-        await db_session.flush()
-
-        with pytest.raises(TypeError, match="Many-to-Many"):
-            await m2m_set(db_session, user, User.role, role)

tests/test_fixtures.py

@@ -10,7 +10,6 @@ from fastapi_toolsets.fixtures import (
     Context,
     FixtureRegistry,
     LoadStrategy,
-    get_field_by_attr,
     get_obj_by_attr,
     load_fixtures,
     load_fixtures_by_context,
@@ -952,41 +951,6 @@ class TestGetObjByAttr:
             get_obj_by_attr(self.roles, "id", "not-a-uuid")
 
 
-class TestGetFieldByAttr:
-    """Tests for get_field_by_attr helper function."""
-
-    def setup_method(self):
-        self.registry = FixtureRegistry()
-        self.role_id_1 = uuid.uuid4()
-        self.role_id_2 = uuid.uuid4()
-        role_id_1 = self.role_id_1
-        role_id_2 = self.role_id_2
-
-        @self.registry.register
-        def roles() -> list[Role]:
-            return [
-                Role(id=role_id_1, name="admin"),
-                Role(id=role_id_2, name="user"),
-            ]
-
-        self.roles = roles
-
-    def test_returns_id_by_default(self):
-        """Returns the id field when no field is specified."""
-        result = get_field_by_attr(self.roles, "name", "admin")
-        assert result == self.role_id_1
-
-    def test_returns_specified_field(self):
-        """Returns the requested field instead of id."""
-        result = get_field_by_attr(self.roles, "id", self.role_id_2, field="name")
-        assert result == "user"
-
-    def test_no_match_raises_stop_iteration(self):
-        """Propagates StopIteration from get_obj_by_attr when no match found."""
-        with pytest.raises(StopIteration, match="No object with name=missing"):
-            get_field_by_attr(self.roles, "name", "missing")
-
-
 class TestGetPrimaryKey:
     """Unit tests for the _get_primary_key helper (composite PK paths)."""
 

tests/test_pytest.py

@@ -1,18 +1,17 @@
 """Tests for fastapi_toolsets.pytest module."""
 
 import uuid
-from typing import cast
 
 import pytest
 from fastapi import Depends, FastAPI
 from httpx import AsyncClient
-from sqlalchemy import ForeignKey, String, select, text
+from sqlalchemy import select, text
 from sqlalchemy.engine import make_url
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
-from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+from sqlalchemy.orm import selectinload
 
 from fastapi_toolsets.db import get_transaction
-from fastapi_toolsets.fixtures import Context, FixtureRegistry, LoadStrategy
+from fastapi_toolsets.fixtures import Context, FixtureRegistry
 from fastapi_toolsets.pytest import (
     create_async_client,
     create_db_session,
@@ -20,23 +19,9 @@ from fastapi_toolsets.pytest import (
     register_fixtures,
     worker_database_url,
 )
-from fastapi_toolsets.pytest.plugin import (
-    _get_primary_key,
-    _relationship_load_options,
-    _reload_with_relationships,
-)
 from fastapi_toolsets.pytest.utils import _get_xdist_worker
 
-from .conftest import (
+from .conftest import DATABASE_URL, Base, Role, RoleCrud, User, UserCrud
-    DATABASE_URL,
-    Base,
-    IntRole,
-    Permission,
-    Role,
-    RoleCrud,
-    User,
-    UserCrud,
-)
 
 test_registry = FixtureRegistry()
 
@@ -151,8 +136,14 @@ class TestGeneratedFixtures:
     async def test_fixture_relationships_work(
         self, db_session: AsyncSession, fixture_users: list[User]
     ):
-        """Loaded fixtures have working relationships directly accessible."""
+        """Loaded fixtures have working relationships."""
-        user = next(u for u in fixture_users if u.id == USER_ADMIN_ID)
+        # Load user with role relationship
+        user = await UserCrud.get(
+            db_session,
+            [User.id == USER_ADMIN_ID],
+            load_options=[selectinload(User.role)],
+        )
+
         assert user.role is not None
         assert user.role.name == "plugin_admin"
 
@@ -186,15 +177,6 @@ class TestGeneratedFixtures:
         assert users[0].username == "plugin_admin"
         assert users[1].username == "plugin_user"
 
-    @pytest.mark.anyio
-    async def test_fixture_auto_loads_relationships(
-        self, db_session: AsyncSession, fixture_users: list[User]
-    ):
-        """Fixtures automatically eager-load all direct relationships."""
-        user = next(u for u in fixture_users if u.username == "plugin_admin")
-        assert user.role is not None
-        assert user.role.name == "plugin_admin"
-
     @pytest.mark.anyio
     async def test_multiple_fixtures_in_same_test(
         self,
@@ -534,192 +516,3 @@ class TestCreateWorkerDatabase:
             )
             assert result.scalar() is None
         await engine.dispose()
-
-
-class _LocalBase(DeclarativeBase):
-    pass
-
-
-class _Group(_LocalBase):
-    __tablename__ = "_test_groups"
-    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
-    name: Mapped[str] = mapped_column(String(50))
-
-
-class _CompositeItem(_LocalBase):
-    """Model with composite PK and a relationship — exercises the fallback path."""
-
-    __tablename__ = "_test_composite_items"
-    group_id: Mapped[uuid.UUID] = mapped_column(
-        ForeignKey("_test_groups.id"), primary_key=True
-    )
-    item_code: Mapped[str] = mapped_column(String(50), primary_key=True)
-    group: Mapped["_Group"] = relationship()
-
-
-class TestGetPrimaryKey:
-    """Unit tests for _get_primary_key — no DB needed."""
-
-    def test_single_pk_returns_value(self):
-        rid = uuid.UUID("00000000-0000-0000-0000-000000000001")
-        role = Role(id=rid, name="x")
-        assert _get_primary_key(role) == rid
-
-    def test_composite_pk_all_set_returns_tuple(self):
-        perm = Permission(subject="posts", action="read")
-        assert _get_primary_key(perm) == ("posts", "read")
-
-    def test_composite_pk_partial_none_returns_none(self):
-        perm = Permission(subject=None, action="read")
-        assert _get_primary_key(perm) is None
-
-    def test_composite_pk_all_none_returns_none(self):
-        perm = Permission(subject=None, action=None)
-        assert _get_primary_key(perm) is None
-
-
-class TestRelationshipLoadOptions:
-    """Unit tests for _relationship_load_options — no DB needed."""
-
-    def test_empty_for_model_with_no_relationships(self):
-        assert _relationship_load_options(IntRole) == []
-
-    def test_returns_options_for_model_with_relationships(self):
-        opts = _relationship_load_options(User)
-        assert len(opts) >= 1
-
-
-class TestFixtureStrategies:
-    """Integration tests covering INSERT, SKIP_EXISTING, empty fixture, no-rels model."""
-
-    @pytest.mark.anyio
-    async def test_empty_fixture_returns_empty_list(self, db_session: AsyncSession):
-        """Fixture function returning [] produces an empty list."""
-        registry = FixtureRegistry()
-
-        @registry.register()
-        def empty() -> list[Role]:
-            return []
-
-        local_ns: dict = {}
-        register_fixtures(registry, local_ns, session_fixture="db_session")
-        inner = local_ns["fixture_empty"].__wrapped__  # type: ignore[attr-defined]
-        result = await inner(db_session=db_session)
-        assert result == []
-
-    @pytest.mark.anyio
-    async def test_insert_strategy_no_relationships(self, db_session: AsyncSession):
-        """INSERT strategy adds instances; model with no rels skips reload (line 135)."""
-        registry = FixtureRegistry()
-
-        @registry.register()
-        def int_roles() -> list[IntRole]:
-            return [IntRole(name="insert_role")]
-
-        local_ns: dict = {}
-        register_fixtures(
-            registry,
-            local_ns,
-            session_fixture="db_session",
-            strategy=LoadStrategy.INSERT,
-        )
-        inner = local_ns["fixture_int_roles"].__wrapped__  # type: ignore[attr-defined]
-        result = await inner(db_session=db_session)
-        assert len(result) == 1
-        assert result[0].name == "insert_role"
-
-    @pytest.mark.anyio
-    async def test_skip_existing_inserts_new_record(self, db_session: AsyncSession):
-        """SKIP_EXISTING inserts when the record does not yet exist."""
-        registry = FixtureRegistry()
-        role_id = uuid.uuid4()
-
-        @registry.register()
-        def new_roles() -> list[Role]:
-            return [Role(id=role_id, name="skip_new")]
-
-        local_ns: dict = {}
-        register_fixtures(
-            registry,
-            local_ns,
-            session_fixture="db_session",
-            strategy=LoadStrategy.SKIP_EXISTING,
-        )
-        inner = local_ns["fixture_new_roles"].__wrapped__  # type: ignore[attr-defined]
-        result = await inner(db_session=db_session)
-        assert len(result) == 1
-        assert result[0].id == role_id
-
-    @pytest.mark.anyio
-    async def test_skip_existing_returns_existing_record(
-        self, db_session: AsyncSession
-    ):
-        """SKIP_EXISTING returns the existing DB record when PK already present."""
-        role_id = uuid.uuid4()
-        existing = Role(id=role_id, name="already_there")
-        db_session.add(existing)
-        await db_session.flush()
-
-        registry = FixtureRegistry()
-
-        @registry.register()
-        def dup_roles() -> list[Role]:
-            return [Role(id=role_id, name="should_not_overwrite")]
-
-        local_ns: dict = {}
-        register_fixtures(
-            registry,
-            local_ns,
-            session_fixture="db_session",
-            strategy=LoadStrategy.SKIP_EXISTING,
-        )
-        inner = local_ns["fixture_dup_roles"].__wrapped__  # type: ignore[attr-defined]
-        result = await inner(db_session=db_session)
-        assert len(result) == 1
-        assert result[0].name == "already_there"
-
-    @pytest.mark.anyio
-    async def test_skip_existing_null_pk_inserts(self, db_session: AsyncSession):
-        """SKIP_EXISTING with null PK (auto-increment) falls through to session.add()."""
-        registry = FixtureRegistry()
-
-        @registry.register()
-        def auto_roles() -> list[IntRole]:
-            return [IntRole(name="auto_int")]
-
-        local_ns: dict = {}
-        register_fixtures(
-            registry,
-            local_ns,
-            session_fixture="db_session",
-            strategy=LoadStrategy.SKIP_EXISTING,
-        )
-        inner = local_ns["fixture_auto_roles"].__wrapped__  # type: ignore[attr-defined]
-        result = await inner(db_session=db_session)
-        assert len(result) == 1
-        assert result[0].name == "auto_int"
-
-
-class TestReloadWithRelationshipsCompositePK:
-    """Integration test for _reload_with_relationships composite-PK fallback."""
-
-    @pytest.mark.anyio
-    async def test_composite_pk_fallback_loads_relationships(self):
-        """Models with composite PKs are reloaded per-instance via session.get()."""
-        async with create_db_session(DATABASE_URL, _LocalBase) as session:
-            group = _Group(id=uuid.uuid4(), name="g1")
-            session.add(group)
-            await session.flush()
-
-            item = _CompositeItem(group_id=group.id, item_code="A")
-            session.add(item)
-            await session.flush()
-
-            load_opts = _relationship_load_options(_CompositeItem)
-            assert load_opts  # _CompositeItem has 'group' relationship
-
-            reloaded = await _reload_with_relationships(session, [item], load_opts)
-            assert len(reloaded) == 1
-            reloaded_item = cast(_CompositeItem, reloaded[0])
-            assert reloaded_item.group is not None
-            assert reloaded_item.group.name == "g1"

uv.lock

@@ -251,7 +251,7 @@ wheels = [
 
 [[package]]
 name = "fastapi-toolsets"
-version = "3.1.0"
+version = "3.0.3"
 source = { editable = "." }
 dependencies = [
     { name = "asyncpg" },
@@ -916,7 +916,7 @@ wheels = [
 
 [[package]]
 name = "pytest"
-version = "9.0.3"
+version = "9.0.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
@@ -925,9 +925,9 @@ dependencies = [
     { name = "pluggy" },
     { name = "pygments" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
 ]
 
 [[package]]
@@ -1064,27 +1064,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.9"
+version = "0.15.8"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e6/97/e9f1ca355108ef7194e38c812ef40ba98c7208f47b13ad78d023caa583da/ruff-0.15.9.tar.gz", hash = "sha256:29cbb1255a9797903f6dde5ba0188c707907ff44a9006eb273b5a17bfa0739a2", size = 4617361, upload-time = "2026-04-02T18:17:20.829Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/14/b0/73cf7550861e2b4824950b8b52eebdcc5adc792a00c514406556c5b80817/ruff-0.15.8.tar.gz", hash = "sha256:995f11f63597ee362130d1d5a327a87cb6f3f5eae3094c620bcc632329a4d26e", size = 4610921, upload-time = "2026-03-26T18:39:38.675Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/0b/1f/9cdfd0ac4b9d1e5a6cf09bedabdf0b56306ab5e333c85c87281273e7b041/ruff-0.15.9-py3-none-linux_armv6l.whl", hash = "sha256:6efbe303983441c51975c243e26dff328aca11f94b70992f35b093c2e71801e1", size = 10511206, upload-time = "2026-04-02T18:16:41.574Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/92/c445b0cd6da6e7ae51e954939cb69f97e008dbe750cfca89b8cedc081be7/ruff-0.15.8-py3-none-linux_armv6l.whl", hash = "sha256:cbe05adeba76d58162762d6b239c9056f1a15a55bd4b346cfd21e26cd6ad7bc7", size = 10527394, upload-time = "2026-03-26T18:39:41.566Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/f6/32bfe3e9c136b35f02e489778d94384118bb80fd92c6d92e7ccd97db12ce/ruff-0.15.9-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:4965bac6ac9ea86772f4e23587746f0b7a395eccabb823eb8bfacc3fa06069f7", size = 10923307, upload-time = "2026-04-02T18:17:08.645Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/92/f1c662784d149ad1414cae450b082cf736430c12ca78367f20f5ed569d65/ruff-0.15.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:d3e3d0b6ba8dca1b7ef9ab80a28e840a20070c4b62e56d675c24f366ef330570", size = 10905693, upload-time = "2026-03-26T18:39:30.364Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/25/de55f52ab5535d12e7aaba1de37a84be6179fb20bddcbe71ec091b4a3243/ruff-0.15.9-py3-none-macosx_11_0_arm64.whl", hash = "sha256:eaf05aad70ca5b5a0a4b0e080df3a6b699803916d88f006efd1f5b46302daab8", size = 10316722, upload-time = "2026-04-02T18:16:44.206Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/f2/7a631a8af6d88bcef997eb1bf87cc3da158294c57044aafd3e17030613de/ruff-0.15.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:6ee3ae5c65a42f273f126686353f2e08ff29927b7b7e203b711514370d500de3", size = 10323044, upload-time = "2026-03-26T18:39:33.37Z" },
-    { url = "https://files.pythonhosted.org/packages/48/11/690d75f3fd6278fe55fff7c9eb429c92d207e14b25d1cae4064a32677029/ruff-0.15.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9439a342adb8725f32f92732e2bafb6d5246bd7a5021101166b223d312e8fc59", size = 10623674, upload-time = "2026-04-02T18:16:50.951Z" },
+    { url = "https://files.pythonhosted.org/packages/67/18/1bf38e20914a05e72ef3b9569b1d5c70a7ef26cd188d69e9ca8ef588d5bf/ruff-0.15.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdce027ada77baa448077ccc6ebb2fa9c3c62fd110d8659d601cf2f475858d94", size = 10629135, upload-time = "2026-03-26T18:39:44.142Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/ec/176f6987be248fc5404199255522f57af1b4a5a1b57727e942479fec98ad/ruff-0.15.9-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9c5e6faf9d97c8edc43877c3f406f47446fc48c40e1442d58cfcdaba2acea745", size = 10351516, upload-time = "2026-04-02T18:16:57.206Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/e9/138c150ff9af60556121623d41aba18b7b57d95ac032e177b6a53789d279/ruff-0.15.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:12e617fc01a95e5821648a6df341d80456bd627bfab8a829f7cfc26a14a4b4a3", size = 10348041, upload-time = "2026-03-26T18:39:52.178Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/fc/51cffbd2b3f240accc380171d51446a32aa2ea43a40d4a45ada67368fbd2/ruff-0.15.9-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7b34a9766aeec27a222373d0b055722900fbc0582b24f39661aa96f3fe6ad901", size = 11150202, upload-time = "2026-04-02T18:17:06.452Z" },
+    { url = "https://files.pythonhosted.org/packages/02/f1/5bfb9298d9c323f842c5ddeb85f1f10ef51516ac7a34ba446c9347d898df/ruff-0.15.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:432701303b26416d22ba696c39f2c6f12499b89093b61360abc34bcc9bf07762", size = 11121987, upload-time = "2026-03-26T18:39:55.195Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/d4/25292a6dfc125f6b6528fe6af31f5e996e19bf73ca8e3ce6eb7fa5b95885/ruff-0.15.9-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:89dd695bc72ae76ff484ae54b7e8b0f6b50f49046e198355e44ea656e521fef9", size = 11988891, upload-time = "2026-04-02T18:17:18.575Z" },
+    { url = "https://files.pythonhosted.org/packages/10/11/6da2e538704e753c04e8d86b1fc55712fdbdcc266af1a1ece7a51fff0d10/ruff-0.15.8-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d910ae974b7a06a33a057cb87d2a10792a3b2b3b35e33d2699fdf63ec8f6b17a", size = 11951057, upload-time = "2026-03-26T18:39:19.18Z" },
-    { url = "https://files.pythonhosted.org/packages/13/e1/1eebcb885c10e19f969dcb93d8413dfee8172578709d7ee933640f5e7147/ruff-0.15.9-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ce187224ef1de1bd225bc9a152ac7102a6171107f026e81f317e4257052916d5", size = 11480576, upload-time = "2026-04-02T18:16:52.986Z" },
+    { url = "https://files.pythonhosted.org/packages/83/f0/c9208c5fd5101bf87002fed774ff25a96eea313d305f1e5d5744698dc314/ruff-0.15.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2033f963c43949d51e6fdccd3946633c6b37c484f5f98c3035f49c27395a8ab8", size = 11464613, upload-time = "2026-03-26T18:40:06.301Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/6b/a1548ac378a78332a4c3dcf4a134c2475a36d2a22ddfa272acd574140b50/ruff-0.15.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2b0c7c341f68adb01c488c3b7d4b49aa8ea97409eae6462d860a79cf55f431b6", size = 11254525, upload-time = "2026-04-02T18:17:02.041Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/22/d7f2fabdba4fae9f3b570e5605d5eb4500dcb7b770d3217dca4428484b17/ruff-0.15.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f29b989a55572fb885b77464cf24af05500806ab4edf9a0fd8977f9759d85b1", size = 11257557, upload-time = "2026-03-26T18:39:57.972Z" },
-    { url = "https://files.pythonhosted.org/packages/42/aa/4bb3af8e61acd9b1281db2ab77e8b2c3c5e5599bf2a29d4a942f1c62b8d6/ruff-0.15.9-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:55cc15eee27dc0eebdfcb0d185a6153420efbedc15eb1d38fe5e685657b0f840", size = 11204072, upload-time = "2026-04-02T18:17:13.581Z" },
+    { url = "https://files.pythonhosted.org/packages/71/8c/382a9620038cf6906446b23ce8632ab8c0811b8f9d3e764f58bedd0c9a6f/ruff-0.15.8-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:ac51d486bf457cdc985a412fb1801b2dfd1bd8838372fc55de64b1510eff4bec", size = 11169440, upload-time = "2026-03-26T18:39:22.205Z" },
-    { url = "https://files.pythonhosted.org/packages/69/48/d550dc2aa6e423ea0bcc1d0ff0699325ffe8a811e2dba156bd80750b86dc/ruff-0.15.9-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a6537f6eed5cda688c81073d46ffdfb962a5f29ecb6f7e770b2dc920598997ed", size = 10594998, upload-time = "2026-04-02T18:16:46.369Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/0d/0994c802a7eaaf99380085e4e40c845f8e32a562e20a38ec06174b52ef24/ruff-0.15.8-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:c9861eb959edab053c10ad62c278835ee69ca527b6dcd72b47d5c1e5648964f6", size = 10605963, upload-time = "2026-03-26T18:39:46.682Z" },
-    { url = "https://files.pythonhosted.org/packages/63/47/321167e17f5344ed5ec6b0aa2cff64efef5f9e985af8f5622cfa6536043f/ruff-0.15.9-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:6d3fcbca7388b066139c523bda744c822258ebdcfbba7d24410c3f454cc9af71", size = 10359769, upload-time = "2026-04-02T18:17:10.994Z" },
+    { url = "https://files.pythonhosted.org/packages/19/aa/d624b86f5b0aad7cef6bbf9cd47a6a02dfdc4f72c92a337d724e39c9d14b/ruff-0.15.8-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8d9a5b8ea13f26ae90838afc33f91b547e61b794865374f114f349e9036835fb", size = 10357484, upload-time = "2026-03-26T18:39:49.176Z" },
-    { url = "https://files.pythonhosted.org/packages/67/5e/074f00b9785d1d2c6f8c22a21e023d0c2c1817838cfca4c8243200a1fa87/ruff-0.15.9-py3-none-musllinux_1_2_i686.whl", hash = "sha256:058d8e99e1bfe79d8a0def0b481c56059ee6716214f7e425d8e737e412d69677", size = 10850236, upload-time = "2026-04-02T18:16:48.749Z" },
+    { url = "https://files.pythonhosted.org/packages/35/c3/e0b7835d23001f7d999f3895c6b569927c4d39912286897f625736e1fd04/ruff-0.15.8-py3-none-musllinux_1_2_i686.whl", hash = "sha256:c2a33a529fb3cbc23a7124b5c6ff121e4d6228029cba374777bd7649cc8598b8", size = 10830426, upload-time = "2026-03-26T18:40:03.702Z" },
-    { url = "https://files.pythonhosted.org/packages/76/37/804c4135a2a2caf042925d30d5f68181bdbd4461fd0d7739da28305df593/ruff-0.15.9-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:8e1ddb11dbd61d5983fa2d7d6370ef3eb210951e443cace19594c01c72abab4c", size = 11358343, upload-time = "2026-04-02T18:16:55.068Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/51/ab20b322f637b369383adc341d761eaaa0f0203d6b9a7421cd6e783d81b9/ruff-0.15.8-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:75e5cd06b1cf3f47a3996cfc999226b19aa92e7cce682dcd62f80d7035f98f49", size = 11345125, upload-time = "2026-03-26T18:39:27.799Z" },
-    { url = "https://files.pythonhosted.org/packages/88/3d/1364fcde8656962782aa9ea93c92d98682b1ecec2f184e625a965ad3b4a6/ruff-0.15.9-py3-none-win32.whl", hash = "sha256:bde6ff36eaf72b700f32b7196088970bf8fdb2b917b7accd8c371bfc0fd573ec", size = 10583382, upload-time = "2026-04-02T18:17:04.261Z" },
+    { url = "https://files.pythonhosted.org/packages/37/e6/90b2b33419f59d0f2c4c8a48a4b74b460709a557e8e0064cf33ad894f983/ruff-0.15.8-py3-none-win32.whl", hash = "sha256:bc1f0a51254ba21767bfa9a8b5013ca8149dcf38092e6a9eb704d876de94dc34", size = 10571959, upload-time = "2026-03-26T18:39:36.117Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/56/5c7084299bd2cacaa07ae63a91c6f4ba66edc08bf28f356b24f6b717c799/ruff-0.15.9-py3-none-win_amd64.whl", hash = "sha256:45a70921b80e1c10cf0b734ef09421f71b5aa11d27404edc89d7e8a69505e43d", size = 11744969, upload-time = "2026-04-02T18:16:59.611Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/a2/ef467cb77099062317154c63f234b8a7baf7cb690b99af760c5b68b9ee7f/ruff-0.15.8-py3-none-win_amd64.whl", hash = "sha256:04f79eff02a72db209d47d665ba7ebcad609d8918a134f86cb13dd132159fc89", size = 11743893, upload-time = "2026-03-26T18:39:25.01Z" },
-    { url = "https://files.pythonhosted.org/packages/03/36/76704c4f312257d6dbaae3c959add2a622f63fcca9d864659ce6d8d97d3d/ruff-0.15.9-py3-none-win_arm64.whl", hash = "sha256:0694e601c028fd97dc5c6ee244675bc241aeefced7ef80cd9c6935a871078f53", size = 11005870, upload-time = "2026-04-02T18:17:15.773Z" },
+    { url = "https://files.pythonhosted.org/packages/15/e2/77be4fff062fa78d9b2a4dea85d14785dac5f1d0c1fb58ed52331f0ebe28/ruff-0.15.8-py3-none-win_arm64.whl", hash = "sha256:cf891fa8e3bb430c0e7fac93851a5978fc99c8fa2c053b57b118972866f8e5f2", size = 11048175, upload-time = "2026-03-26T18:40:01.06Z" },
 ]
 
 [[package]]
@@ -1228,26 +1228,26 @@ wheels = [
 
 [[package]]
 name = "ty"
-version = "0.0.31"
+version = "0.0.27"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/31/cc/5ea5d3a72216c8c2bf77d83066dd4f3553532d0aacc03d4a8397dd9845e1/ty-0.0.31.tar.gz", hash = "sha256:4a4094292d9671caf3b510c7edf36991acd9c962bb5d97205374ffed9f541c45", size = 5516619, upload-time = "2026-04-15T15:47:59.87Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f4/de/e5cf1f151cf52fe1189e42d03d90909d7d1354fdc0c1847cbb63a0baa3da/ty-0.0.27.tar.gz", hash = "sha256:d7a8de3421d92420b40c94fe7e7d4816037560621903964dd035cf9bd0204a73", size = 5424130, upload-time = "2026-03-31T19:07:20.806Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b0/10/ea805cbbd75d5d50792551a2b383de8521eeab0c44f38c73e12819ced65e/ty-0.0.31-py3-none-linux_armv6l.whl", hash = "sha256:761651dc17ad7bc0abfc1b04b3f0e84df263ed435d34f29760b3da739ab02d35", size = 10834749, upload-time = "2026-04-15T15:48:14.877Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/20/2a9ea661758bd67f2bfd54ce9daacb5a26c56c5f8b49fbd9a43b365a8a7d/ty-0.0.27-py3-none-linux_armv6l.whl", hash = "sha256:eb14456b8611c9e8287aa9b633f4d2a0d9f3082a31796969e0b50bdda8930281", size = 10571211, upload-time = "2026-03-31T19:07:23.28Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/4c/fabf951850401d24d36b21bced088a366c6827e1c37dab4523afff84c4b2/ty-0.0.31-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:c529922395a07231c27488f0290651e05d27d149f7e0aa807678f1f7e9c58a5e", size = 10626012, upload-time = "2026-04-15T15:48:22.554Z" },
+    { url = "https://files.pythonhosted.org/packages/da/b2/8887a51f705d075ddbe78ae7f0d4755ef48d0a90235f67aee289e9cee950/ty-0.0.27-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:02e662184703db7586118df611cf24a000d35dae38d950053d1dd7b6736fd2c4", size = 10427576, upload-time = "2026-03-31T19:07:15.499Z" },
-    { url = "https://files.pythonhosted.org/packages/04/b0/4a5aff88d2544f19514a59c8f693d63144aa7307fe2ee5df608333ab5460/ty-0.0.31-py3-none-macosx_11_0_arm64.whl", hash = "sha256:5f345df2b87d747859e72c2cbc9be607ea1bbc8bc93dd32fa3d03ea091cb4fee", size = 10075790, upload-time = "2026-04-15T15:47:46.959Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/c3/79d88163f508fb709ce19bc0b0a66c7c64b53d372d4caa56172c3d9b3ae8/ty-0.0.27-py3-none-macosx_11_0_arm64.whl", hash = "sha256:be5fc2899441f7f8f7ef40f9ffd006075a5ff6b06c44e8d2aa30e1b900c12f51", size = 9870359, upload-time = "2026-03-31T19:07:36.852Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/73/9d4dcad12cd4e85274014f2c0510ef93f590b2a1e5148de3a9f276098dad/ty-0.0.31-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d4b207eddcfbafd376132689d3435b14efcb531289cb59cd961c6a611133bd54", size = 10590286, upload-time = "2026-04-15T15:48:06.222Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/4d/ed1b0db0e1e46b5ed4976bbfe0d1825faf003b4e3774ef28c785ed73e4bb/ty-0.0.27-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:30231e652b14742a76b64755e54bf0cb1cd4c128bcaf625222e0ca92a2094887", size = 10380488, upload-time = "2026-03-31T19:07:31.268Z" },
-    { url = "https://files.pythonhosted.org/packages/47/45/fe40adde18692359ded174ae7ddbfac056e876eb0f43b65be74fde7f6072/ty-0.0.31-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:663778b220f357067488ce68bfc52335ccbd161549776f70dcbde6bbde82f77a", size = 10623824, upload-time = "2026-04-15T15:48:12.965Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/f2/20372f6d510b01570028433064880adec2f8abe68bf0c4603be61a560bef/ty-0.0.27-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5a119b1168f64261b3205a37e40b5b6c4aac8fd58e4587988f4e4b22c3c79847", size = 10390248, upload-time = "2026-03-31T19:07:28.345Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/e8/0ffa2e09b548e6daa9ebc368d68b767dc2405ca4cbeadb7ede0e2cb21059/ty-0.0.31-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3506cfe87dfade0fb2960dd4fffd4fd8089003587b3445c0a1a295c9d83764fb", size = 11156864, upload-time = "2026-04-15T15:48:08.473Z" },
+    { url = "https://files.pythonhosted.org/packages/45/4b/46b31a7311306be1a560f7f20fdc37b5bf718787f60626cd265d9b637554/ty-0.0.27-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e38f4e187b6975d2cbebf0f1eb1221f8f64f6e509bad14d7bb2a91afc97e4956", size = 10878479, upload-time = "2026-03-31T19:07:39.393Z" },
-    { url = "https://files.pythonhosted.org/packages/08/e9/fd44c2075115d569593ee9473d7e2a38b750fd7e783421c95eb528c15df5/ty-0.0.31-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8b3f3d8492f08e81916026354c1d1599e9ddfa1241804141a74d5662fc710085", size = 11696401, upload-time = "2026-04-15T15:48:17.355Z" },
+    { url = "https://files.pythonhosted.org/packages/42/ba/5231a2a1fb1cebe053a25de8fded95e1a30a1e77d3628a9e58487297bafc/ty-0.0.27-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a07b1a8fbb23844f6d22091275430d9ac617175f34aa99159b268193de210389", size = 11461232, upload-time = "2026-03-31T19:07:02.518Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/50/35aad8eadf964d23e2a4faa5b38a206aa85c78833c8ce335dddd2c34ba63/ty-0.0.31-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a97de32ee6a619393a4c495e056a1c547de7877510f3152e61345c71d774d2d0", size = 11374903, upload-time = "2026-04-15T15:47:55.893Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/37/558abab3e1f6670493524f61280b4dfcc3219555f13889223e733381dfab/ty-0.0.27-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d3ec4033031f240836bb0337274bac5c49dde312c7c6d7575451ed719bf8ffa3", size = 11133002, upload-time = "2026-03-31T19:07:18.371Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/37/01eccd25d23f5aaa7f7ff1a87b5b215469f6b202cf689a1812b71c1e7f6b/ty-0.0.31-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c906354ce441e342646582bc9b8f48a676f79f3d061e25de15ff870e015ca14e", size = 11206624, upload-time = "2026-04-15T15:47:51.778Z" },
+    { url = "https://files.pythonhosted.org/packages/32/38/188c14a57f52160407ce62c6abb556011718fd0bcbe1dca690529ce84c46/ty-0.0.27-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:924a8849afd500d260bf5b7296165a05b7424fbb6b19113f30f3b999d682873f", size = 10986624, upload-time = "2026-03-31T19:07:13.066Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/70/baad2914cb097453f127a221f8addb2b41926098059cd773c75e6a662fc4/ty-0.0.31-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:275bb7c82afcbf89fe2dbef1b2692f2bc98451f1ee2c8eb809ddd91317822388", size = 10575089, upload-time = "2026-04-15T15:47:49.448Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/f1/667a71393f47d2cd6ba9ed07541b8df3eb63aab1f2ee658e77d91b8362fa/ty-0.0.27-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:d8270026c07e7423a1b3a3fd065b46ed1478748f0662518b523b57744f3fa025", size = 10366721, upload-time = "2026-03-31T19:07:00.131Z" },
-    { url = "https://files.pythonhosted.org/packages/83/12/bae3a7bba2e785eb72ce00f9da70eedcb8c5e8299efecbd16e6e436abd82/ty-0.0.31-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:405da247027c6efd1e264886b6ac4a86ab3a4f09200b02e33630efe85f119e53", size = 10642315, upload-time = "2026-04-15T15:48:19.661Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/aa/8edafe41be898bda774249abc5be6edd733e53fb1777d59ea9331e38537d/ty-0.0.27-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:e26e9735d3bdfd95d881111ad1cf570eab8188d8c3be36d6bcaad044d38984d8", size = 10412239, upload-time = "2026-03-31T19:07:05.297Z" },
-    { url = "https://files.pythonhosted.org/packages/93/9e/cad04d5d839bc60355cea98c7e09d724ea65f47184def0fae8b90dc54591/ty-0.0.31-py3-none-musllinux_1_2_i686.whl", hash = "sha256:54d9835608eed196853d6643f645c50ce83bcc7fe546cdb3e210c1bcf7c58c09", size = 10834473, upload-time = "2026-04-15T15:48:02.091Z" },
+    { url = "https://files.pythonhosted.org/packages/53/ff/8bafaed4a18d38264f46bdfc427de7ea2974cf9064e4e0bdb1b6e6c724e3/ty-0.0.27-py3-none-musllinux_1_2_i686.whl", hash = "sha256:7c09cc9a699810609acc0090af8d0db68adaee6e60a7c3e05ab80cc954a83db7", size = 10573507, upload-time = "2026-03-31T19:06:57.064Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/ba/84112d280182d37690d3d2b4018b2667e42bc281585e607015635310016a/ty-0.0.31-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:5ee11be9b07e8c0c6b455ff075a0abe4f194de9476f57624db98eec9df618355", size = 11315785, upload-time = "2026-04-15T15:48:10.754Z" },
+    { url = "https://files.pythonhosted.org/packages/16/2e/63a8284a2fefd08ab56ecbad0fde7dd4b2d4045a31cf24c1d1fcd9643227/ty-0.0.27-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:2d3e02853bb037221a456e034b1898aaa573e6374fbb53884e33cb7513ccb85a", size = 11090233, upload-time = "2026-03-31T19:07:34.139Z" },
-    { url = "https://files.pythonhosted.org/packages/50/9f/ac42dc223d7e0950e97a1854567a8b3e7fe09ad7375adbf91bfb43290482/ty-0.0.31-py3-none-win32.whl", hash = "sha256:7286587aacf3eef0956062d6492b893b02f82b0f22c5e230008e13ff0d216a8b", size = 10187657, upload-time = "2026-04-15T15:48:04.264Z" },
+    { url = "https://files.pythonhosted.org/packages/14/d3/d6fa1cafdfa2b34dbfa304fc6833af8e1669fc34e24d214fa76d2a2e5a25/ty-0.0.27-py3-none-win32.whl", hash = "sha256:34e7377f2047c14dbbb7bf5322e84114db7a5f2cb470db6bee63f8f3550cfc1e", size = 9984415, upload-time = "2026-03-31T19:07:07.98Z" },
-    { url = "https://files.pythonhosted.org/packages/75/3e/57ba7ea7ecb2f4751644ba91756e2be70e33ef5952c0c41a256a0e4c2437/ty-0.0.31-py3-none-win_amd64.whl", hash = "sha256:81134e25d2a2562ab372f24de8f9bd05034d27d30377a5d7540f259791c6234c", size = 11205258, upload-time = "2026-04-15T15:47:53.759Z" },
+    { url = "https://files.pythonhosted.org/packages/85/e6/dd4e27da9632b3472d5711ca49dbd3709dbd3e8c73f3af6db9c254235ca9/ty-0.0.27-py3-none-win_amd64.whl", hash = "sha256:3f7e4145aad8b815ed69b324c93b5b773eb864dda366ca16ab8693ff88ce6f36", size = 10961535, upload-time = "2026-03-31T19:07:10.566Z" },
-    { url = "https://files.pythonhosted.org/packages/88/39/bca669095ccf0a400af941fdf741578d4c2d6719f1b7f10e6dbec10aa862/ty-0.0.31-py3-none-win_arm64.whl", hash = "sha256:e9cb15fad26545c6a608f40f227af3a5513cb376998ca6feddd47ca7d93ffafa", size = 10590392, upload-time = "2026-04-15T15:47:57.968Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/1a/824b3496d66852ed7d5d68d9787711131552b68dce8835ce9410db32e618/ty-0.0.27-py3-none-win_arm64.whl", hash = "sha256:95bf8d01eb96bb2ba3ffc39faff19da595176448e80871a7b362f4d2de58476c", size = 10376689, upload-time = "2026-03-31T19:07:25.732Z" },
 ]
 
 [[package]]
@@ -1324,7 +1324,7 @@ wheels = [
 
 [[package]]
 name = "zensical"
-version = "0.0.32"
+version = "0.0.31"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "click" },
@@ -1334,18 +1334,18 @@ dependencies = [
     { name = "pymdown-extensions" },
     { name = "pyyaml" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/7a/94/4a49ca9329136445f4111fda60e4bfcbe68d95e18e9aa02e4606fba5df4a/zensical-0.0.32.tar.gz", hash = "sha256:0f857b09a2b10c99202b3712e1ffc4d1d1ffa4c7c2f1aa0fafb1346b2d8df604", size = 3891955, upload-time = "2026-04-07T11:41:29.203Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d5/1a/9b6f5285c5aef648db38f9132f49a7059bd2c9d748f68ef0c52ed8afcff3/zensical-0.0.31.tar.gz", hash = "sha256:9c12f07bde70c4bfdb13d6cae1bedf8d18064d257a6e81128a152502b28a8fc3", size = 3891758, upload-time = "2026-04-01T11:30:21.88Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/73/e1/dd03762447f1c2a4c8aff08e8f047ec17c73421714a0600ef71c361a5934/zensical-0.0.32-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:7ed181c76c03fec4c2dd5db207810044bf9c3fa87097fbdbabd633661e20fc70", size = 12416474, upload-time = "2026-04-07T11:40:55.888Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/db/cc4e555d2e816f2d91304ff969d62cc3a401ee477dbb7c720b874bec67d6/zensical-0.0.31-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:b489936d670733dd204f16b689a2acc0e45b69e42cc4901f5131ae57658b8fbc", size = 12419980, upload-time = "2026-04-01T11:29:44.01Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/a6/2f1babb00842c6efa5ae755b3ab414e4688ae8e47bdd2e785c0c37ef625d/zensical-0.0.32-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:8cde82bf256408f75ae2b07bffcaac7d080b6aad5f7acf210c438cb7413c3081", size = 12292801, upload-time = "2026-04-07T11:40:59.648Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/c1/6789f73164c7f5821f5defb8a80b1dba8d5af24bdec7db36876793c5afd9/zensical-0.0.31-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:d9f678efc0d9918e45eeb8bc62847b2cce23db7393c8c59c1be6d1c064bbaacd", size = 12292301, upload-time = "2026-04-01T11:29:47.277Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/f1/d32706de06fd30fb07ae514222a79dd17d4578cd1634e5b692e0c790a61e/zensical-0.0.32-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:60e60e2358249b2a2c5e1c5c04586d8dbba27e577441cc9dd32fe8d879c6951e", size = 12658847, upload-time = "2026-04-07T11:41:02.347Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/9a/6a83ad209081a953e0285d5056e5452c4fbcabd2f104f3797d53e4bdd96f/zensical-0.0.31-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fb2b50ecf674997f818e53f12f2a67875a21b0c79ed74c151dfaef2f1475e5bf", size = 12661472, upload-time = "2026-04-01T11:29:50.706Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/42/a3daf4047c86382749a59795c4e7acd59952b4f6f37f329cd2d41cc37a0f/zensical-0.0.32-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ec79b4304009138e7a38ebe24e8a8e9dbc15d38922185f8a84470a7757d7b73f", size = 12604777, upload-time = "2026-04-07T11:41:05.227Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/4a/a82f5c81893b7a607cf9d439b75c3c3894b4ef4d3e92d5d818b4fa5c6f23/zensical-0.0.31-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:6fb5c634fe88254770a2d4db5c05b06f1c3ee5e29d2ae3e7efdae8905e435b1d", size = 12603784, upload-time = "2026-04-01T11:29:53.623Z" },
-    { url = "https://files.pythonhosted.org/packages/59/11/4af61d3fb07713cd3f77981c1b3017a60c2b210b36f1b04353f9116d03ca/zensical-0.0.32-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:fc92fa7d0860ec6d95426a5f545cfc5493c60f8ab44fcc11611a4251f34f1b70", size = 12956242, upload-time = "2026-04-07T11:41:07.58Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/1c/79c198628b8e006be32dfb1c5b73561757a349a6cf3069600a67ffa62495/zensical-0.0.31-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:94e64630552793274db1ec66c971e49a15ad351536d5d12de67ec6da7358ac50", size = 12959832, upload-time = "2026-04-01T11:29:56.736Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/34/e9b5f4376bbf460f8c07a77af59bd169c7c68ed719a074e6667ba41109f8/zensical-0.0.32-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:07f69019396060e310c9c3b18747ce8982ad56d67fbab269b61e74a6a5bdcb4a", size = 12701954, upload-time = "2026-04-07T11:41:10.532Z" },
+    { url = "https://files.pythonhosted.org/packages/db/9d/45839d9ca0f69622e8a3b944f2d8d7f7d2b7c2da78201079c4feb275feb6/zensical-0.0.31-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:738a2fd5832e3b3c10ff642eebaf89c89ca1d28e4451dad0f36fdac53c415577", size = 12704024, upload-time = "2026-04-01T11:29:59.836Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/43/a52e5dcb324f38a1d22f7fafd4eec273385d04de52a7ab5ac7b444cf2bdc/zensical-0.0.32-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:d096c9ed20a48e5ff095eca218eef94f67e739cdf0abf7e1f7e232e78f6d980c", size = 12835464, upload-time = "2026-04-07T11:41:13.152Z" },
+    { url = "https://files.pythonhosted.org/packages/df/5f/451d7f4d94092bc38bd8d514826fb7b0329c188db506795b1d20bd07d517/zensical-0.0.31-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:bd601f6132e285ef6c3e4c3852be2094fc0473295a8080003db76a79760f84fb", size = 12837788, upload-time = "2026-04-01T11:30:03.048Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/95/bede89ecb4932bbd29db7b61bf530a962aed09d3a8d5aa71a64af1d4920f/zensical-0.0.32-cp310-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:bf5576b7154bde18cebd9a7b065d3ab8b334c6e73d5b2e83abe2b17f9d00a992", size = 12876574, upload-time = "2026-04-07T11:41:16.085Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/39/390a8fc384fb174ebd4450343a0aa2877b3a31ddcedf5ef0b8d26944e12c/zensical-0.0.31-cp310-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:dc3b6a9dfb5903c0aa779ef65cd6185add2b8aa1db237be840874b8c9db761b8", size = 12876822, upload-time = "2026-04-01T11:30:06.418Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/e8/9b25fda22bf729ca2598cc42cefe9b20e751d12d23e35c70ea0c7939d20a/zensical-0.0.32-cp310-abi3-musllinux_1_2_i686.whl", hash = "sha256:f33905a1e0b03a2ad548554a157b7f7c398e6f41012d1e755105ae2bc60eab8a", size = 13022702, upload-time = "2026-04-07T11:41:18.947Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/60/640da2f095782cf38974cd851fb7afa62651d09a36543a1d8942b31aabdc/zensical-0.0.31-cp310-abi3-musllinux_1_2_i686.whl", hash = "sha256:ddd4321b275e82c4897aa45b05038ce204b88fb311ad55f8c2af572173a9b56c", size = 13024036, upload-time = "2026-04-01T11:30:09.501Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/35/0c6d0b57187bd470a05e8a391c0edd1d690eb429e12b9755c99cf60a370e/zensical-0.0.32-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:0a73a53b1dd41fd239875a3cb57c4284747989c45b6933f18e9b51f1b5f3d8ef", size = 12975593, upload-time = "2026-04-07T11:41:21.436Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/06/0564377cbfccea3653254adfa851c1b20d1696e4b16770c7b2e1dd1ef1d7/zensical-0.0.31-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:147ab4bc17f3088f703aa6c4b9c416411f4ea8ca64d26f6586beae49d97fd3c7", size = 12975505, upload-time = "2026-04-01T11:30:12.268Z" },
-    { url = "https://files.pythonhosted.org/packages/ee/2d/4e88bcefc33b7af22f0637fd002d3cf5384e8354f0a7f8a9dbfcd40cfa24/zensical-0.0.32-cp310-abi3-win32.whl", hash = "sha256:f8cb579bdb9b56f1704b93f4e17b42895c8cb466e8eec933fbe0153b5b1e3459", size = 12012163, upload-time = "2026-04-07T11:41:23.975Z" },
+    { url = "https://files.pythonhosted.org/packages/35/4b/b8a0c4e5937cb05882dcce667798403e00897135080a69f92363e5e3ff9f/zensical-0.0.31-cp310-abi3-win32.whl", hash = "sha256:03fa11e629a308507693489541f43e751697784e94365e7435b02104aefd1c2c", size = 12011233, upload-time = "2026-04-01T11:30:15.496Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/ae/a80a2f15fd10201fe3dfd6b5cdf85351165f820cf5b29e3c3b24092c158c/zensical-0.0.32-cp310-abi3-win_amd64.whl", hash = "sha256:6d662f42b5d0eadfac6d281e9d86574bc7a9f812f1ed496335d15f2d581d4b28", size = 12205948, upload-time = "2026-04-07T11:41:27.056Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/99/0eacdb466d344c0c86596932201268517be42f3e0bb6c78b2b0cd84c55f6/zensical-0.0.31-cp310-abi3-win_amd64.whl", hash = "sha256:d6621d4bb46af4143560045d4a18c8c76302db56bf1dbb6e2ce107d7fb643e09", size = 12207545, upload-time = "2026-04-01T11:30:19.054Z" },
 ]