API reference¶
Everything below is importable from seedgraph, except the fixtures, which the pytest plugin registers on its own.
Seeding¶
seedgraph.seed ¶
seed(
session: Session,
model: type[DeclarativeBase],
/,
generators: GeneratorMap | None = None,
overrides: OverrideMap | None = None,
parents: Sequence[Any] = (),
**shape: int,
) -> Graph
Seed a coherent object graph from the declared shape and return it.
The graph is flushed, the database assigns its keys, and every FK column is
verified against the row it points at. generators replaces how a column
generates, overrides pins a value; both are keyed {Model: {"column": ...}}.
parents are objects of the session that links of their type point at.
Raises a SeedgraphError subclass on any bad declaration or broken link.
seedgraph.seed_async
async
¶
seed_async(
session: AsyncSession,
model: type[DeclarativeBase],
/,
generators: GeneratorMap | None = None,
overrides: OverrideMap | None = None,
parents: Sequence[Any] = (),
**shape: int,
) -> Graph
Twin of seed on an AsyncSession: same contract, the flush is awaited.
seedgraph.Graph ¶
Group the seeded objects by table name, exposed as attributes.
Each table of the seeded model's metadata is an attribute holding the list of
generated objects of that table, empty when the shape built none: graph.users.
Custom generators¶
generators= and overrides= are keyed by model, then by column name: {User: {"name": ...}}. A generator, or a callable override, receives this context:
seedgraph.generators.GenerationContext ¶
The object handed to custom generators: the seeded fake and the column name.
pytest fixtures¶
pytest plugin: a fresh sqlite session and a seed callable, served without configuration.
Every fixture carries the seedgraph_ prefix, so it never shadows a project's own session.
seedgraph_session ¶
seedgraph_session() -> Iterator[Session]
Serve a fresh in-memory sqlite Session with foreign keys enforced.
seedgraph_graph ¶
seedgraph_graph(
seedgraph_session: Session,
) -> Callable[..., Graph]
Serve a seed callable on the fresh session; tables are created on demand.
seedgraph_asession
async
¶
seedgraph_asession() -> AsyncIterator[AsyncSession]
Serve a fresh in-memory aiosqlite AsyncSession with foreign keys enforced.
seedgraph_agraph
async
¶
seedgraph_agraph(
seedgraph_asession: AsyncSession,
) -> Callable[..., Any]
Serve an awaited seed callable on the fresh async session; tables on demand.
Errors¶
Every error derives from SeedgraphError, so one except SeedgraphError catches them all.
seedgraph.SeedgraphError ¶
Bases: Exception
Base class for every error seedgraph raises.
Constructed with one message string naming the exact shape key, column or model at fault.
seedgraph.UnknownShapeKeyError ¶
seedgraph.AmbiguousShapeKeyError ¶
Bases: SeedgraphError
A shape key matches several relationships of the model at that point of the path.
seedgraph.InvalidShapeCountError ¶
seedgraph.UnsupportedShapeDirectionError ¶
Bases: SeedgraphError
A shape key walks a relationship that cannot build children: towards a parent, or view-only.
seedgraph.MissingRequiredParentError ¶
Bases: SeedgraphError
A required link has no matching ancestor in the branch and was not declared in the shape.
seedgraph.AmbiguousParentError ¶
Bases: SeedgraphError
A link towards a single parent finds several objects of its type among the provided parents.
seedgraph.UnattachedParentError ¶
Bases: SeedgraphError
A provided parent is neither pending nor persistent in the session seeding the graph.
seedgraph.UnsupportedPlaceholderError ¶
seedgraph.UniqueValueExhaustedError ¶
Bases: SeedgraphError
A unique column's generator kept producing values already used or already in the database.
seedgraph.UnknownGeneratorColumnError ¶
seedgraph.UnknownOverrideColumnError ¶
seedgraph.IncoherentGraphError ¶
Bases: SeedgraphError
A link of the seeded graph carries FK values that differ from the linked object's key.