feat: add get_obj_by_attr fixture helper function (#4)

* feat: add get_obj_by_attr fixture helper function

* tests: add fixture utils

src/fastapi_toolsets/fixtures/__init__.py

@@ -6,11 +6,13 @@ from .fixtures import (
     load_fixtures_by_context,
 )
 from .pytest_plugin import register_fixtures
+from .utils import get_obj_by_attr
 
 __all__ = [
     "Context",
     "FixtureRegistry",
     "LoadStrategy",
+    "get_obj_by_attr",
     "load_fixtures",
     "load_fixtures_by_context",
     "register_fixtures",

src/fastapi_toolsets/fixtures/utils.py

@@ -0,0 +1,26 @@
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
+
+from sqlalchemy.orm import DeclarativeBase
+
+T = TypeVar("T", bound=DeclarativeBase)
+
+
+def get_obj_by_attr(
+    fixtures: Callable[[], Sequence[T]], attr_name: str, value: Any
+) -> T:
+    """Get a SQLAlchemy model instance by matching an attribute value.
+
+    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.
+
+    Returns:
+        The first model instance where the attribute matches the given value.
+
+    Raises:
+        StopIteration: If no matching object is found.
+    """
+    return next(obj for obj in fixtures() if getattr(obj, attr_name) == value)