Skip to content

fixtures

Here's the reference for the fixture registry, enums, and loading utilities.

You can import them directly from fastapi_toolsets.fixtures:

from fastapi_toolsets.fixtures import (
    Context,
    LoadStrategy,
    Fixture,
    FixtureRegistry,
    load_fixtures,
    load_fixtures_by_context,
    get_obj_by_attr,
)

fastapi_toolsets.fixtures.enum.Context

Bases: str, Enum

Predefined fixture contexts.

BASE = 'base' class-attribute instance-attribute

Base fixtures loaded in all environments.

DEVELOPMENT = 'development' class-attribute instance-attribute

Development fixtures.

PRODUCTION = 'production' class-attribute instance-attribute

Production-only fixtures.

TESTING = 'testing' class-attribute instance-attribute

Test fixtures.

fastapi_toolsets.fixtures.enum.LoadStrategy

Bases: str, Enum

Strategy for loading fixtures into the database.

INSERT = 'insert' class-attribute instance-attribute

Insert new records. Fails if record already exists.

MERGE = 'merge' class-attribute instance-attribute

Insert or update based on primary key (SQLAlchemy merge).

SKIP_EXISTING = 'skip_existing' class-attribute instance-attribute

Insert only if record doesn't exist (based on primary key).

fastapi_toolsets.fixtures.registry.Fixture dataclass

A fixture definition with metadata.

fastapi_toolsets.fixtures.registry.FixtureRegistry

Registry for managing fixtures with dependencies.

Example 
from fastapi_toolsets.fixtures import FixtureRegistry, Context

fixtures = FixtureRegistry()

@fixtures.register
def roles():
    return [
        Role(id=1, name="admin"),
        Role(id=2, name="user"),
    ]

@fixtures.register(depends_on=["roles"])
def users():
    return [
        User(id=1, username="admin", role_id=1),
    ]

@fixtures.register(depends_on=["users"], contexts=[Context.TESTING])
def test_data():
    return [
        Post(id=1, title="Test", user_id=1),
    ]

get(name)

Get a fixture by name.

get_all()

Get all registered fixtures.

get_by_context(*contexts)

Get fixtures for specific contexts.

include_registry(registry)

Include another FixtureRegistry in the same current FixtureRegistry.

Parameters:

Name Type Description Default
registry FixtureRegistry

The FixtureRegistry to include

 required

Raises:

Type Description
ValueError

If a fixture name already exists in the current registry
Example 
registry = FixtureRegistry()
dev_registry = FixtureRegistry()

@dev_registry.register
def dev_data():
    return [...]

registry.include_registry(registry=dev_registry)

register(func=None, *, name=None, depends_on=None, contexts=None)

Register a fixture function.

Can be used as a decorator with or without arguments.

Parameters:

Name Type Description Default
func Callable[[], Sequence[DeclarativeBase]] | None

Fixture function returning list of model instances

 None
name str | None

Fixture name (defaults to function name)

 None
depends_on list[str] | None

List of fixture names this depends on

 None
contexts list[str | Context] | None

List of contexts this fixture belongs to

 None
Example 
@fixtures.register
def roles():
    return [Role(id=1, name="admin")]

@fixtures.register(depends_on=["roles"], contexts=[Context.TESTING])
def test_users():
    return [User(id=1, username="test", role_id=1)]

resolve_context_dependencies(*contexts)

Resolve all fixtures for contexts with dependencies.

Parameters:

Name Type Description Default
*contexts str | Context

Contexts to load

 ()

Returns:

Type Description
list[str]

List of fixture names in load order

resolve_dependencies(*names)

Resolve fixture dependencies in topological order.

Parameters:

Name Type Description Default
*names str

Fixture names to resolve

 ()

Returns:

Type Description
list[str]

List of fixture names in load order (dependencies first)

Raises:

Type Description
KeyError

If a fixture is not found
ValueError

If circular dependency detected

fastapi_toolsets.fixtures.utils.load_fixtures(session, registry, *names, strategy=LoadStrategy.MERGE) async

Load specific fixtures by name with dependencies.

Parameters:

Name Type Description Default
session AsyncSession

Database session

 required
registry FixtureRegistry

Fixture registry

 required
*names str

Fixture names to load (dependencies auto-resolved)

 ()
strategy LoadStrategy

How to handle existing records

 MERGE

Returns:

Type Description
dict[str, list[DeclarativeBase]]

Dict mapping fixture names to loaded instances
Example 
# Loads 'roles' first (dependency), then 'users'
result = await load_fixtures(session, fixtures, "users")
print(result["users"])  # [User(...), ...]

fastapi_toolsets.fixtures.utils.load_fixtures_by_context(session, registry, *contexts, strategy=LoadStrategy.MERGE) async

Load all fixtures for specific contexts.

Parameters:

Name Type Description Default
session AsyncSession

Database session

 required
registry FixtureRegistry

Fixture registry

 required
*contexts str | Context

Contexts to load (e.g., Context.BASE, Context.TESTING)

 ()
strategy LoadStrategy

How to handle existing records

 MERGE

Returns:

Type Description
dict[str, list[DeclarativeBase]]

Dict mapping fixture names to loaded instances
Example 
# Load base + testing fixtures
await load_fixtures_by_context(
    session, fixtures,
    Context.BASE, Context.TESTING
)

fastapi_toolsets.fixtures.utils.get_obj_by_attr(fixtures, attr_name, value)

Get a SQLAlchemy model instance by matching an attribute value.

Parameters:

Name Type Description Default
fixtures Callable[[], Sequence[T]]

A fixture function registered via @registry.register that returns a sequence of SQLAlchemy model instances.

 required
attr_name str

Name of the attribute to match against.

 required
value Any

Value to match.

 required

Returns:

Type Description
T

The first model instance where the attribute matches the given value.

Raises:

Type Description
StopIteration

If no matching object is found in the fixture group.