seedgraph 0.1.1__py3-none-any.whl

seedgraph/__init__.py

@@ -0,0 +1,118 @@
+"""seedgraph — referentially-consistent graph seeding for SQLAlchemy models.
+
+Declare a shape, get a coherent object graph: written to the session, every FK
+column verified against the key of the row it points at.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy.orm import DeclarativeBase, Session
+
+from seedgraph.boundary import (
+    UnattachedParentError,
+    check_parents_attached,
+    taken_values,
+    taken_values_async,
+)
+from seedgraph.exceptions import SeedgraphError
+from seedgraph.generators import (
+    FieldGenerator,
+    GeneratorMap,
+    OverrideMap,
+    UniqueValueExhaustedError,
+    UnknownGeneratorColumnError,
+    UnknownOverrideColumnError,
+    UnsupportedPlaceholderError,
+    generation_state,
+)
+from seedgraph.graph import Graph
+from seedgraph.shape import (
+    AmbiguousParentError,
+    AmbiguousShapeKeyError,
+    InvalidShapeCountError,
+    MissingRequiredParentError,
+    UnknownShapeKeyError,
+    UnsupportedShapeDirectionError,
+    build_graph,
+)
+from seedgraph.uniqueness import UniqueRepair
+from seedgraph.verification import IncoherentGraphError, verify_graph
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "AmbiguousParentError",
+    "AmbiguousShapeKeyError",
+    "Graph",
+    "IncoherentGraphError",
+    "InvalidShapeCountError",
+    "MissingRequiredParentError",
+    "SeedgraphError",
+    "UnattachedParentError",
+    "UniqueValueExhaustedError",
+    "UnknownGeneratorColumnError",
+    "UnknownOverrideColumnError",
+    "UnknownShapeKeyError",
+    "UnsupportedPlaceholderError",
+    "UnsupportedShapeDirectionError",
+    "__version__",
+    "seed",
+    "seed_async",
+]
+
+
+def 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.
+    """
+    check_parents_attached(session, parents)
+    state = generation_state(session.info)
+    objects = build_graph(model, shape, generators=generators, overrides=overrides, state=state, parents=parents)
+    repair = UniqueRepair(objects, FieldGenerator(generators, overrides, state))
+    while queries := repair.queries():
+        repair.reject({column: taken_values(session, column, values) for column, values in queries})
+    session.add_all(objects)
+    session.flush()
+    verify_graph(objects)
+    return Graph(objects, model.metadata)
+
+
+async def 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."""
+    check_parents_attached(session.sync_session, parents)
+    state = generation_state(session.sync_session.info)
+    objects = build_graph(model, shape, generators=generators, overrides=overrides, state=state, parents=parents)
+    repair = UniqueRepair(objects, FieldGenerator(generators, overrides, state))
+    while queries := repair.queries():
+        repair.reject({column: await taken_values_async(session, column, values) for column, values in queries})
+    session.add_all(objects)
+    await session.flush()
+    verify_graph(objects)
+    return Graph(objects, model.metadata)

seedgraph/boundary.py

@@ -0,0 +1,47 @@
+"""Read what already exists at the boundary: provided parents, and the values unique columns already hold."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import Column, select
+from sqlalchemy.orm import Session
+
+from seedgraph.exceptions import SeedgraphError
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+__all__ = ["UnattachedParentError", "check_parents_attached", "taken_values", "taken_values_async"]
+
+CHUNK = 500
+
+
+class UnattachedParentError(SeedgraphError):
+    """A provided parent is neither pending nor persistent in the session seeding the graph."""
+
+
+def check_parents_attached(session: Session, parents: Sequence[Any]) -> None:
+    """Refuse any provided parent that the session does not hold, since flushing would insert it silently."""
+    for parent in parents:
+        if parent not in session:
+            raise UnattachedParentError(
+                f"parent {type(parent).__name__} is not in the session — add it, or load it, before seeding"
+            )
+
+
+def taken_values(session: Session, column: Column[Any], candidates: Sequence[Any]) -> set[Any]:
+    """Return the candidates the column already holds in the database."""
+    taken = set()
+    for start in range(0, len(candidates), CHUNK):
+        taken.update(session.scalars(select(column).where(column.in_(candidates[start : start + CHUNK]))))
+    return taken
+
+
+async def taken_values_async(session: AsyncSession, column: Column[Any], candidates: Sequence[Any]) -> set[Any]:
+    """Twin of ``taken_values`` on an AsyncSession."""
+    taken = set()
+    for start in range(0, len(candidates), CHUNK):
+        taken.update(await session.scalars(select(column).where(column.in_(candidates[start : start + CHUNK]))))
+    return taken

seedgraph/exceptions.py

@@ -0,0 +1,14 @@
+"""seedgraph exceptions."""
+
+__all__ = ["SeedgraphError"]
+
+
+class SeedgraphError(Exception):
+    """Base class for every error seedgraph raises.
+
+    Constructed with one message string naming the exact shape key, column or
+    model at fault.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)

seedgraph/generators.py

@@ -0,0 +1,327 @@
+"""Field generation: a seeded faker, name heuristics, custom overrides, type fallbacks.
+
+Its world is (column, fake) -> value. No session, no shape, no graph.
+"""
+
+from collections.abc import Callable
+from functools import cache
+from typing import Any, TypeAlias
+
+from faker import Faker
+from sqlalchemy import (
+    ARRAY,
+    Boolean,
+    Column,
+    Date,
+    DateTime,
+    Enum,
+    Float,
+    Integer,
+    Interval,
+    LargeBinary,
+    Numeric,
+    String,
+    Table,
+    Time,
+    UniqueConstraint,
+    Uuid,
+)
+from sqlalchemy.orm import class_mapper
+from sqlalchemy.types import TypeEngine
+
+from seedgraph.exceptions import SeedgraphError
+
+__all__ = [
+    "UNSET",
+    "ColumnGenerator",
+    "FieldGenerator",
+    "GenerationContext",
+    "GenerationState",
+    "UniqueValueExhaustedError",
+    "UnknownGeneratorColumnError",
+    "UnknownOverrideColumnError",
+    "UnsupportedPlaceholderError",
+    "database_fills",
+    "generation_state",
+    "is_unique",
+    "validate_column_declarations",
+]
+
+DEFAULT_SEED = 42
+DEFAULT_LOCALE = "en_US"
+SESSION_INFO_KEY = "seedgraph"
+
+UNSET: Any = object()
+
+MAX_INTEGER = 100
+MAX_NUMERIC_LEFT_DIGITS = 6
+MAX_NUMERIC_RIGHT_DIGITS = 2
+MAX_FLOAT_LEFT_DIGITS = 4
+BINARY_LENGTH = 16
+MAX_ARRAY_ITEMS = 3
+MAX_UNIQUE_ATTEMPTS = 100
+MAX_UNIQUE_INTEGER = 2**31 - 1
+
+ColumnGenerator: TypeAlias = Callable[["GenerationContext"], Any]
+ColumnOverride: TypeAlias = ColumnGenerator | Any
+ColumnMap: TypeAlias = dict[str, ColumnOverride]
+GeneratorMap: TypeAlias = dict[type, dict[str, ColumnGenerator]]
+OverrideMap: TypeAlias = dict[type, ColumnMap]
+
+COLUMN_HINTS = {
+    "name": "name",
+    "first_name": "first_name",
+    "last_name": "last_name",
+    "username": "user_name",
+    "user_name": "user_name",
+    "email": "email",
+    "title": "sentence",
+    "body": "paragraph",
+    "description": "paragraph",
+    "content": "paragraph",
+    "phone": "phone_number",
+    "phone_number": "phone_number",
+    "url": "url",
+    "company": "company",
+    "city": "city",
+    "country": "country",
+}
+
+
+class UnsupportedPlaceholderError(SeedgraphError):
+    """A NOT NULL column without default carries a type no generator covers."""
+
+
+class UniqueValueExhaustedError(SeedgraphError):
+    """A unique column's generator kept producing values already used or already in the database."""
+
+
+class UnknownGeneratorColumnError(SeedgraphError):
+    """A column declared in generators does not exist on its model."""
+
+
+class UnknownOverrideColumnError(SeedgraphError):
+    """A column declared in overrides does not exist on its model."""
+
+
+def validate_generators(generators: GeneratorMap | None) -> None:
+    """Reject any declared column that matches no column of its declared model."""
+    validate_column_declarations(generators, None)
+
+
+def validate_column_declarations(generators: GeneratorMap | None, overrides: OverrideMap | None) -> None:
+    """Reject any declared column that matches no column of its declared model."""
+    errors = (
+        (generators, UnknownGeneratorColumnError, "generated"),
+        (overrides, UnknownOverrideColumnError, "overridden"),
+    )
+    for declarations, error, verb in errors:
+        for model, columns in (declarations or {}).items():
+            existing = {column.key for column in class_mapper(model).local_table.columns}
+            for column in columns:
+                if column not in existing:
+                    raise error(f"unknown {verb} column {column!r} for {model.__name__}")
+
+
+class GenerationState:
+    """What generation carries from one seed() to the next on the same session: the faker, the used unique values."""
+
+    def __init__(self) -> None:
+        self.fake: Faker = Faker(locale=DEFAULT_LOCALE)
+        self.fake.seed_instance(DEFAULT_SEED)
+        self.used: dict[tuple[str, str], set[Any]] = {}
+
+    def used_values(self, column: Column[Any]) -> set[Any]:
+        return self.used.setdefault((column.table.key, column.key), set())
+
+
+def generation_state(info: dict[Any, Any]) -> GenerationState:
+    """Return the session's generation state, created on its first seed() from ``session.info``."""
+    return info.setdefault(SESSION_INFO_KEY, GenerationState())
+
+
+class GenerationContext:
+    """The object handed to custom generators: the seeded fake and the column name."""
+
+    def __init__(self, fake: Faker, column: str) -> None:
+        self.fake: Faker = fake
+        self.column: str = column
+
+
+class FieldGenerator:
+    """Generate values for eligible columns through one seeded Faker instance."""
+
+    def __init__(
+        self,
+        generators: GeneratorMap | None = None,
+        overrides: OverrideMap | None = None,
+        state: GenerationState | None = None,
+    ) -> None:
+        self._state = state or GenerationState()
+        self._fake = self._state.fake
+        self._generators: dict[type, dict[str, ColumnGenerator]] = generators or {}
+        self._overrides: OverrideMap = overrides or {}
+
+    def value_for(self, model: type, column: Column[Any]) -> Any:
+        """Return the column's value, or UNSET for a nullable column of a type no provider covers."""
+        override = self.override_for(model, column)
+        if override is not UNSET:
+            return override
+        produce = self._producer(model, column)
+        if produce is None:
+            if column.nullable:
+                return UNSET
+            raise UnsupportedPlaceholderError(
+                f"cannot generate NOT NULL column {column.table.key}.{column.key} of type {column.type}"
+            )
+        if not is_unique(column):
+            return produce()
+        used = self._state.used_values(column)
+        for _ in range(MAX_UNIQUE_ATTEMPTS):
+            value = produce()
+            if value not in used:
+                used.add(value)
+                return value
+        raise UniqueValueExhaustedError(
+            f"no new value for unique column {column.table.key}.{column.key} after {MAX_UNIQUE_ATTEMPTS}"
+            " attempts — widen its generator or declare one in generators"
+        )
+
+    def is_overridden(self, model: type, column: Column[Any]) -> bool:
+        return column.key in self._overrides.get(model, {})
+
+    def remember(self, column: Column[Any], values: set[Any]) -> None:
+        """Mark values as used so the unique column never produces them again."""
+        self._state.used_values(column).update(values)
+
+    def _producer(self, model: type, column: Column[Any]) -> Callable[[], Any] | None:
+        custom = self._generators.get(model)
+        if custom is not None and column.key in custom:
+            return lambda: custom[column.key](GenerationContext(self._fake, column.key))
+        provider = self._provider(column)
+        if provider is None:
+            return None
+        return lambda: _fit(provider(), column.type)
+
+    def override_for(self, model: type, column: Column[Any]) -> Any:
+        """Return the declared override's resolved value for the column, or UNSET when undeclared."""
+        override = self._overrides.get(model)
+        if override is None or column.key not in override:
+            return UNSET
+        return self._resolve(override[column.key], column)
+
+    def _resolve(self, value: ColumnOverride, column: Column[Any]) -> Any:
+        if callable(value):
+            return value(GenerationContext(self._fake, column.key))
+        return value
+
+    def _provider(self, column: Column[Any]) -> Callable[[], Any] | None:
+        if isinstance(column.type, Integer) and is_unique(column):
+            return lambda: self._fake.random_int(min=1, max=MAX_UNIQUE_INTEGER)
+        if _is_text(column.type):
+            hint = COLUMN_HINTS.get(column.key.lower())
+            if hint is not None:
+                return getattr(self._fake, hint)
+        return self._type_provider(column.type)
+
+    def _type_provider(self, type_: TypeEngine[Any]) -> Callable[[], Any] | None:
+        fake = self._fake
+        if isinstance(type_, Enum):
+            choices = list(type_.enum_class) if type_.enum_class is not None else list(type_.enums)
+            return lambda: fake.random_element(choices)
+        if isinstance(type_, Boolean):
+            return fake.boolean
+        if isinstance(type_, Integer):
+            return lambda: fake.random_int(min=0, max=MAX_INTEGER)
+        if isinstance(type_, Float):
+            return lambda: fake.pyfloat(left_digits=MAX_FLOAT_LEFT_DIGITS, right_digits=MAX_NUMERIC_RIGHT_DIGITS)
+        if isinstance(type_, Numeric):
+            return self._numeric_provider(type_)
+        if isinstance(type_, DateTime):
+            return fake.date_time
+        if isinstance(type_, Date):
+            return fake.date_object
+        if isinstance(type_, Time):
+            return fake.time_object
+        if isinstance(type_, Interval):
+            return fake.time_delta
+        if isinstance(type_, Uuid):
+            return (lambda: fake.uuid4(cast_to=None)) if type_.as_uuid else fake.uuid4
+        if isinstance(type_, LargeBinary):
+            return lambda: fake.binary(length=BINARY_LENGTH)
+        if isinstance(type_, ARRAY):
+            return self._array_provider(type_)
+        if isinstance(type_, String):
+            return fake.sentence
+        return None
+
+    def _array_provider(self, type_: ARRAY[Any]) -> Callable[[], Any] | None:
+        item = self._type_provider(type_.item_type)
+        if item is None:
+            return None
+        return lambda: [_fit(item(), type_.item_type) for _ in range(self._fake.random_int(1, MAX_ARRAY_ITEMS))]
+
+    def _numeric_provider(self, type_: Numeric[Any]) -> Callable[[], Any]:
+        right = MAX_NUMERIC_RIGHT_DIGITS if type_.scale is None else type_.scale
+        left = MAX_NUMERIC_LEFT_DIGITS if type_.precision is None else type_.precision - right
+        return lambda: self._fake.pydecimal(left_digits=left, right_digits=right, positive=True)
+
+
+@cache
+def is_unique(column: Column[Any]) -> bool:
+    """A generated column seedgraph keeps unique alone: flagged, alone in a unique constraint or index, or chosen for one.
+
+    A key column the database does not fill counts; in a multi-column constraint, the generated column with the widest values is chosen.
+    """
+    if column.unique or (column.primary_key and not column.foreign_keys and not database_fills(column)):
+        return True
+    return any(_carrier(columns) is column for columns in _unique_column_sets(column.table))
+
+
+def _unique_column_sets(table: Table) -> list[list[Column[Any]]]:
+    constraints = [list(c.columns) for c in table.constraints if isinstance(c, UniqueConstraint)]
+    return constraints + [list(index.columns) for index in table.indexes if index.unique]
+
+
+_VALUE_SPACE = ["text", "identifier", "number", "moment"]
+
+
+def _carrier(columns: list[Column[Any]]) -> Column[Any] | None:
+    if len(columns) == 1:
+        return columns[0]
+    candidates = [
+        column
+        for column in columns
+        if not column.foreign_keys and not database_fills(column) and _value_space(column.type) is not None
+    ]
+    return min(candidates, key=lambda column: _VALUE_SPACE.index(_value_space(column.type)), default=None)
+
+
+def _value_space(type_: TypeEngine[Any]) -> str | None:
+    if isinstance(type_, (Enum, Boolean)):
+        return None
+    if isinstance(type_, String):
+        return "text"
+    if isinstance(type_, (Uuid, LargeBinary)):
+        return "identifier"
+    if isinstance(type_, (Integer, Numeric)):
+        return "number"
+    if isinstance(type_, (Date, DateTime, Time, Interval)):
+        return "moment"
+    return None
+
+
+def database_fills(column: Column[Any]) -> bool:
+    """The database, or the column's own default, gives the value when seedgraph leaves it empty."""
+    return column is column.table.autoincrement_column or column.default is not None or column.server_default is not None
+
+
+def _is_text(type_: TypeEngine[Any]) -> bool:
+    return isinstance(type_, String) and not isinstance(type_, Enum)
+
+
+def _fit(value: Any, type_: TypeEngine[Any]) -> Any:
+    """Cut a generated string to the column's declared length."""
+    if isinstance(value, str) and _is_text(type_) and type_.length:
+        return value[: type_.length].rstrip()
+    return value

seedgraph/graph.py

@@ -0,0 +1,31 @@
+"""The result of seed(): the generated objects, grouped by table name."""
+
+from collections.abc import Sequence
+from typing import Any
+
+from sqlalchemy import MetaData
+from sqlalchemy.orm import class_mapper
+
+__all__ = ["Graph"]
+
+
+class 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``.
+    """
+
+    def __init__(self, objects: Sequence[Any], metadata: MetaData) -> None:
+        self._table_names = sorted(table.name for table in metadata.tables.values())
+        grouped: dict[str, list[Any]] = {}
+        for obj in objects:
+            grouped.setdefault(class_mapper(type(obj)).local_table.name, []).append(obj)
+        for table_name, group in grouped.items():
+            setattr(self, table_name, group)
+
+    def __getattr__(self, name: str) -> list[Any]:
+        if not name.startswith("_") and name in self._table_names:
+            return []
+        known = ", ".join(self._table_names)
+        raise AttributeError(f"the graph has no table {name!r} — known tables: {known}")

seedgraph/pytest_plugin.py

@@ -0,0 +1,98 @@
+"""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``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Iterator, Sequence
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from sqlalchemy import create_engine, event
+from sqlalchemy.orm import Session
+
+from seedgraph import Graph, seed, seed_async
+from seedgraph.generators import GeneratorMap, OverrideMap
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+try:
+    # pytest-asyncio's default strict mode only runs async fixtures declared through its own decorator.
+    from pytest_asyncio import fixture as async_fixture
+except ImportError:
+    async_fixture = pytest.fixture
+
+__all__ = ["seedgraph_agraph", "seedgraph_asession", "seedgraph_graph", "seedgraph_session"]
+
+
+@pytest.fixture()
+def seedgraph_session() -> Iterator[Session]:
+    """Serve a fresh in-memory sqlite Session with foreign keys enforced."""
+    engine = create_engine("sqlite://")
+
+    @event.listens_for(engine, "connect")
+    def enforce_fk(dbapi_conn: Any, _: Any) -> None:
+        dbapi_conn.execute("PRAGMA foreign_keys=ON")
+
+    with Session(engine) as fresh:
+        yield fresh
+    engine.dispose()
+
+
+@pytest.fixture()
+def seedgraph_graph(seedgraph_session: Session) -> Callable[..., Graph]:
+    """Serve a seed callable on the fresh session; tables are created on demand."""
+
+    def make(
+        model: type[Any],
+        /,
+        generators: GeneratorMap | None = None,
+        overrides: OverrideMap | None = None,
+        parents: Sequence[Any] = (),
+        **shape: int,
+    ) -> Graph:
+        model.metadata.create_all(seedgraph_session.get_bind(), checkfirst=True)
+        return seed(seedgraph_session, model, generators=generators, overrides=overrides, parents=parents, **shape)
+
+    return make
+
+
+@async_fixture()
+async def seedgraph_asession() -> AsyncIterator[AsyncSession]:
+    """Serve a fresh in-memory aiosqlite AsyncSession with foreign keys enforced."""
+    # Imported here: sqlalchemy.ext.asyncio needs greenlet, which only the async extra installs.
+    from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+
+    engine = create_async_engine("sqlite+aiosqlite://")
+
+    @event.listens_for(engine.sync_engine, "connect")
+    def enforce_fk(dbapi_conn: Any, _: Any) -> None:
+        dbapi_conn.execute("PRAGMA foreign_keys=ON")
+
+    async with AsyncSession(engine) as fresh:
+        yield fresh
+    await engine.dispose()
+
+
+@async_fixture()
+async def seedgraph_agraph(seedgraph_asession: AsyncSession) -> Callable[..., Any]:
+    """Serve an awaited seed callable on the fresh async session; tables on demand."""
+
+    async def make(
+        model: type[Any],
+        /,
+        generators: GeneratorMap | None = None,
+        overrides: OverrideMap | None = None,
+        parents: Sequence[Any] = (),
+        **shape: int,
+    ) -> Graph:
+        await seedgraph_asession.run_sync(
+            lambda sync_session: model.metadata.create_all(sync_session.get_bind(), checkfirst=True)
+        )
+        return await seed_async(
+            seedgraph_asession, model, generators=generators, overrides=overrides, parents=parents, **shape
+        )
+
+    return make

seedgraph/shape.py

@@ -0,0 +1,279 @@
+"""Build the object graph declared by a shape: root count first, children level by level."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from sqlalchemy import Column, inspect
+from sqlalchemy.orm import DeclarativeBase, class_mapper
+from sqlalchemy.orm.relationships import Relationship
+
+from seedgraph.exceptions import SeedgraphError
+from seedgraph.generators import (
+    UNSET,
+    FieldGenerator,
+    GenerationState,
+    GeneratorMap,
+    OverrideMap,
+    UnsupportedPlaceholderError,
+    database_fills,
+    validate_column_declarations,
+)
+
+__all__ = [
+    "AmbiguousParentError",
+    "AmbiguousShapeKeyError",
+    "InvalidShapeCountError",
+    "MissingRequiredParentError",
+    "UnknownShapeKeyError",
+    "UnsupportedPlaceholderError",
+    "UnsupportedShapeDirectionError",
+    "build_graph",
+]
+
+DEFAULT_COUNT = 3
+
+
+class UnknownShapeKeyError(SeedgraphError):
+    """A shape key matches no relationship of the model at that point of the path."""
+
+
+class AmbiguousShapeKeyError(SeedgraphError):
+    """A shape key matches several relationships of the model at that point of the path."""
+
+
+class InvalidShapeCountError(SeedgraphError):
+    """A shape count is not an integer greater than or equal to zero."""
+
+
+class UnsupportedShapeDirectionError(SeedgraphError):
+    """A shape key walks a relationship that cannot build children: towards a parent, or view-only."""
+
+
+class MissingRequiredParentError(SeedgraphError):
+    """A required link has no matching ancestor in the branch and was not declared in the shape."""
+
+
+class AmbiguousParentError(SeedgraphError):
+    """A link towards a single parent finds several objects of its type among the provided parents."""
+
+
+def build_graph(
+    model: type[DeclarativeBase],
+    shape: Mapping[str, int],
+    generators: GeneratorMap | None = None,
+    overrides: OverrideMap | None = None,
+    state: GenerationState | None = None,
+    parents: Sequence[Any] = (),
+) -> list[Any]:
+    """Build the declared shape's objects, level by level, and link their parents.
+
+    A link takes the nearest ancestor of its type in the branch, then the provided parent of that type;
+    a required link still unset gets a parent generated once per type and shared, added to the result.
+    """
+    counts = dict(shape)
+    root_key = model.__name__.lower()
+    root_count = counts.pop(root_key, DEFAULT_COUNT)
+    _check_count(root_key, root_count)
+    tree = _resolve_tree(model, counts)
+    validate_column_declarations(generators, overrides)
+    objects: list[Any] = []
+    generator = FieldGenerator(generators, overrides, state)
+    linker = _ParentLinker(generator, objects, parents)
+    for _ in range(root_count):
+        root = _build_object(model, generator)
+        linker.link(root, [])
+        objects.append(root)
+        _attach_children(root, tree, objects, generator, linker, [])
+    return objects
+
+
+def _resolve_tree(model: type[DeclarativeBase], counts: Mapping[str, int]) -> dict[str, Any]:
+    """Resolve every shape key into a navigated tree — errors fire before anything is built."""
+    root = {"children": {}}
+    for key, count in counts.items():
+        _check_count(key, count)
+        node = root
+        current = model
+        for segment in key.split("__"):
+            relationship = _resolve_segment(current, segment)
+            current = relationship.mapper.class_
+            node = node["children"].setdefault(
+                relationship.key, {"relationship": relationship, "count": None, "children": {}}
+            )
+        node["count"] = count
+    return root
+
+
+def _resolve_segment(model: type[DeclarativeBase], segment: str) -> Relationship:
+    """Resolve one shape segment: exact relationship key first, then the model it points at."""
+    mapper = class_mapper(model)
+    exact = [rel for rel in mapper.relationships if rel.key == segment]
+    if exact:
+        relationship = exact[0]
+    else:
+        matches = [
+            rel for rel in mapper.relationships
+            if rel.mapper.class_.__name__.lower() == segment and not rel.viewonly
+        ]
+        if not matches:
+            raise UnknownShapeKeyError(f"unknown shape key {segment!r} for {model.__name__}")
+        if len(matches) > 1:
+            names = ", ".join(sorted(rel.key for rel in matches))
+            raise AmbiguousShapeKeyError(
+                f"shape key {segment!r} matches several relationships of {model.__name__}"
+                f" — address it by its relationship key instead: {names}"
+            )
+        relationship = matches[0]
+    return _check_relationship(model, segment, relationship)
+
+
+def _check_relationship(model: type[DeclarativeBase], segment: str, relationship: Relationship) -> Relationship:
+    walked = f"shape key {segment!r} walks {model.__name__}.{relationship.key}"
+    if relationship.viewonly:
+        raise UnsupportedShapeDirectionError(f"{walked}, a viewonly relationship — nothing would be written")
+    if relationship.direction.name == "MANYTOONE":
+        raise UnsupportedShapeDirectionError(
+            f"{walked}, which points at a parent — parents are linked or generated on their own,"
+            " pass existing ones in parents"
+        )
+    return relationship
+
+
+def _attach_children(
+    parent: Any,
+    node: dict[str, Any],
+    objects: list[Any],
+    generator: FieldGenerator,
+    linker: "_ParentLinker",
+    ancestors: list[Any],
+) -> None:
+    branch = [*ancestors, parent]
+    for child_node in node["children"].values():
+        relationship = child_node["relationship"]
+        count = DEFAULT_COUNT if child_node["count"] is None else child_node["count"]
+        for _ in range(count):
+            child = _build_object(relationship.mapper.class_, generator)
+            getattr(parent, relationship.key).append(child)
+            linker.link(child, branch)
+            objects.append(child)
+            _attach_children(child, child_node, objects, generator, linker, branch)
+
+
+class _ParentLinker:
+    def __init__(self, generator: FieldGenerator, objects: list[Any], parents: Sequence[Any]) -> None:
+        self._generator = generator
+        self._objects = objects
+        self._provided = _index_parents(parents)
+        self._generated: dict[type, Any] = {}
+        self._in_progress: list[type] = []
+
+    def link(self, obj: Any, ancestors: Sequence[Any]) -> None:
+        state = inspect(obj)
+        for relationship in state.mapper.relationships:
+            if relationship.viewonly:
+                continue
+            if relationship.direction.name == "MANYTOMANY":
+                self._share(obj, relationship)
+                continue
+            if relationship.direction.name != "MANYTOONE":
+                continue
+            if relationship.key not in state.unloaded and getattr(obj, relationship.key) is not None:
+                continue
+            parent = self._parent_for(obj, relationship, ancestors)
+            if parent is not None:
+                setattr(obj, relationship.key, parent)
+
+    def _parent_for(self, obj: Any, relationship: Relationship, ancestors: Sequence[Any]) -> Any:
+        target = relationship.mapper.class_
+        required = _is_required(relationship)
+        if required:
+            for ancestor in reversed(ancestors):
+                if type(ancestor) is target:
+                    return ancestor
+        candidates = self._provided.get(target, [])
+        if len(candidates) > 1:
+            raise AmbiguousParentError(
+                f"{type(obj).__name__}.{relationship.key} links one {target.__name__}, but {len(candidates)}"
+                " were passed in parents — pass one"
+            )
+        if candidates:
+            return candidates[0]
+        if not required:
+            return None
+        if target in self._generated:
+            return self._generated[target]
+        if target is type(obj) or target in self._in_progress:
+            raise MissingRequiredParentError(self._unreachable(obj, relationship, target))
+        return self._generate(target)
+
+    def _share(self, obj: Any, relationship: Relationship) -> None:
+        collection = getattr(obj, relationship.key)
+        for shared in self._provided.get(relationship.mapper.class_, []):
+            if shared not in collection:
+                collection.append(shared)
+
+    def _generate(self, target: type[DeclarativeBase]) -> Any:
+        self._in_progress.append(target)
+        parent = _build_object(target, self._generator)
+        self.link(parent, [])
+        self._in_progress.pop()
+        self._generated[target] = parent
+        self._objects.append(parent)
+        return parent
+
+    def _unreachable(self, obj: Any, relationship: Relationship, target: type) -> str:
+        where = f"{type(obj).__name__}.{relationship.key} requires a {target.__name__}"
+        if target is type(obj):
+            return (
+                f"{where}: the first object of a self-referential branch cannot have a required parent"
+                " — make the FK nullable, or pass an existing one in parents"
+            )
+        loop = " -> ".join(model.__name__ for model in [*self._in_progress, target])
+        return f"{where}, but required links form a loop ({loop}) — pass one of them in parents"
+
+
+def _index_parents(parents: Sequence[Any]) -> dict[type, list[Any]]:
+    provided: dict[type, list[Any]] = {}
+    for parent in parents:
+        provided.setdefault(type(parent), []).append(parent)
+    return provided
+
+
+def _is_required(relationship: Relationship) -> bool:
+    """A link is required when any of its local FK columns is NOT NULL."""
+    return any(not local_column.nullable for local_column, _ in relationship.local_remote_pairs)
+
+
+def _check_count(key: str, count: object) -> None:
+    if not isinstance(count, int) or isinstance(count, bool) or count < 0:
+        raise InvalidShapeCountError(f"shape count for {key!r} must be an integer >= 0, got {count!r}")
+
+
+def _build_object(model: type[DeclarativeBase], generator: FieldGenerator) -> Any:
+    """Build one object of the model: generate eligible columns, apply declared overrides elsewhere."""
+    obj = model()
+    mapper = class_mapper(type(obj))
+    for column in mapper.local_table.columns:
+        if column.foreign_keys:
+            continue
+        key = mapper.get_property_by_column(column).key
+        if column.primary_key:
+            _fill_primary_key(obj, key, model, column, generator)
+            continue
+        if column.default is not None or column.server_default is not None:
+            override = generator.override_for(model, column)
+            if override is not UNSET:
+                setattr(obj, key, override)
+            continue
+        value = generator.value_for(model, column)
+        if value is not UNSET:
+            setattr(obj, key, value)
+    return obj
+
+
+def _fill_primary_key(
+    obj: Any, key: str, model: type[DeclarativeBase], column: Column[Any], generator: FieldGenerator
+) -> None:
+    if database_fills(column):
+        return
+    setattr(obj, key, generator.value_for(model, column))

seedgraph/uniqueness.py

@@ -0,0 +1,59 @@
+"""Replace generated unique values the database already holds, round by round, without doing any IO itself."""
+
+from collections.abc import Sequence
+from typing import Any
+
+from sqlalchemy import Column
+from sqlalchemy.orm import class_mapper
+
+from seedgraph.generators import FieldGenerator, UniqueValueExhaustedError, is_unique
+
+__all__ = ["UniqueRepair"]
+
+MAX_ROUNDS = 10
+
+
+class UniqueRepair:
+    """Hand out the generated unique values to check, then regenerate those the database reports as taken."""
+
+    def __init__(self, objects: Sequence[Any], generator: FieldGenerator) -> None:
+        self._generator = generator
+        self._rounds = 0
+        self._slots: list[tuple[Any, Column[Any], str]] = []
+        for obj in objects:
+            mapper = class_mapper(type(obj))
+            for column in mapper.local_table.columns:
+                if column.foreign_keys or not is_unique(column):
+                    continue
+                if generator.is_overridden(type(obj), column):
+                    continue
+                attribute = mapper.get_property_by_column(column).key
+                if getattr(obj, attribute) is not None:
+                    self._slots.append((obj, column, attribute))
+
+    def queries(self) -> list[tuple[Column[Any], list[Any]]]:
+        """Return each column with the values still to check, empty once none is left."""
+        if not self._slots:
+            return []
+        if self._rounds == MAX_ROUNDS:
+            _, column, _ = self._slots[0]
+            raise UniqueValueExhaustedError(
+                f"unique column {column.table.key}.{column.key} still collides with existing rows"
+                f" after {MAX_ROUNDS} rounds — widen its generator or declare one in generators"
+            )
+        self._rounds += 1
+        by_column: dict[Column[Any], list[Any]] = {}
+        for obj, column, attribute in self._slots:
+            by_column.setdefault(column, []).append(getattr(obj, attribute))
+        return list(by_column.items())
+
+    def reject(self, taken: dict[Column[Any], set[Any]]) -> None:
+        """Regenerate every slot whose value is taken; only those are checked again."""
+        still = []
+        for obj, column, attribute in self._slots:
+            value = getattr(obj, attribute)
+            if value in taken.get(column, ()):
+                self._generator.remember(column, taken[column])
+                setattr(obj, attribute, self._generator.value_for(type(obj), column))
+                still.append((obj, column, attribute))
+        self._slots = still

seedgraph/verification.py

@@ -0,0 +1,41 @@
+"""The exit contract of seed(): every set link's FK columns equal the linked object's key."""
+
+from collections.abc import Sequence
+from typing import Any
+
+from sqlalchemy import Column, inspect
+from sqlalchemy.orm import class_mapper
+
+from seedgraph.exceptions import SeedgraphError
+
+__all__ = ["IncoherentGraphError", "verify_graph"]
+
+
+class IncoherentGraphError(SeedgraphError):
+    """A link of the seeded graph carries FK values that differ from the linked object's key."""
+
+
+def verify_graph(objects: Sequence[Any]) -> None:
+    """Raise IncoherentGraphError on the first set link whose FK columns disagree with its target."""
+    for obj in objects:
+        state = inspect(obj)
+        for relationship in state.mapper.relationships:
+            if relationship.direction.name == "MANYTOMANY" or relationship.key in state.unloaded:
+                continue
+            value = getattr(obj, relationship.key)
+            if value is None:
+                continue
+            linked = list(value) if relationship.direction.name == "ONETOMANY" else [value]
+            for other in linked:
+                for local_column, remote_column in relationship.local_remote_pairs:
+                    local_value = _column_value(obj, local_column)
+                    remote_value = _column_value(other, remote_column)
+                    if local_value != remote_value:
+                        raise IncoherentGraphError(
+                            f"{type(obj).__name__}.{relationship.key}: {local_column.name}={local_value!r}"
+                            f" vs {remote_column.name}={remote_value!r}"
+                        )
+
+
+def _column_value(obj: Any, column: Column[Any]) -> Any:
+    return getattr(obj, class_mapper(type(obj)).get_property_by_column(column).key)

seedgraph-0.1.1.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: seedgraph
+Version: 0.1.1
+Summary: Seed your SQLAlchemy models as a referentially-consistent graph — one call, shared parents, real PKs.
+Project-URL: Homepage, https://github.com/jrachid/seedgraph
+Project-URL: Repository, https://github.com/jrachid/seedgraph
+Project-URL: Issues, https://github.com/jrachid/seedgraph/issues
+Author: Rachid Jeffali
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fixtures,foreign-keys,orm,seed,sqlalchemy,testing
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: faker>=30
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: async
+Requires-Dist: aiosqlite>=0.17; extra == 'async'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.17; extra == 'dev'
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: greenlet>=3.0; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: testcontainers[postgres]>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# seedgraph
+
+> Seed your SQLAlchemy models as a referentially-consistent graph — one call, shared parents, verified links.
+
+**seedgraph fills your test database with a coherent graph of objects, in a single call.** You declare what you want — "3 users, each with 2 posts, each post with 3 comments" — and the library builds the objects, links them, writes them to your session and then verifies every foreign key against the row it points at. Values are realistic and reproducible ("Jose Bishop", not "user-0"), generated by Faker with a fixed seed, valid for each column's type, and unique where the schema says so — even against rows already in the database. You can pin any column, replace how any column is generated, and attach the new graph to rows you already have. It plugs into pytest with no configuration.
+
+**Status: pre-alpha.** Every guarantee below is backed by a named test, on SQLite and on PostgreSQL.
+
+---
+
+## Why
+
+Every Python team that seeds a relational test database eventually hand-rolls the same plumbing: generate rows, stage commits so primary keys exist, chase those keys into FK columns, repeat for every relationship, and hope the graph stays consistent.
+
+After empirically testing the landscape (SQLAlchemy 2.x era, August 2026), none of the existing options does it:
+
+| Tool | What you get on a `User ← Post ← Comment` schema |
+|------|---------------------------------------------------|
+| `polyfactory` | Builds related objects, **but every FK column is a random int pointing at nothing**: `post.author_id != post.author.id`. Silent data corruption — tests pass on garbage unless you enable FK enforcement (most don't). |
+| `faker-sqlalchemy` (unmaintained since 2022, pinned to SQLAlchemy 1.x) | `RecursionError` on standard `backref` relationships, on self-referential FKs, and its `overrides` API silently drops FK values. |
+| `sqlalchemyseed` | Seeds data *you already have* (JSON/YAML), doesn't generate. |
+| `sqlseed`, `sowdb` | Solid fillers, but schema-level and flat: "N rows per table". They work from raw SQL schemas, not your models, and can't express a graph shape like *"3 users → 2 posts each → 5 comments per post"*. |
+
+The one-line failure seedgraph fixes:
+
+```python
+p = PostFactory.build()
+p.author_id == p.author.id   # False. Every FK in the graph is disconnected.
+```
+
+### "But other libraries do this too, don't they?"
+
+They create linked objects. Three differences survive a closer look:
+
+**1. A verified exit contract, not just object creation.** factory_boy, pytest-factoryboy or mixer build the graph and stop there. `seed()` flushes the graph, lets the database assign the keys, then walks every link and raises `IncoherentGraphError` if a foreign key disagrees with the row it points at.
+
+**2. Coexistence with a populated database.** The database assigns the keys, so seeding on top of existing rows never collides on ids, never desynchronises a PostgreSQL sequence, and stays safe when two sessions seed the same tables at once. Unique columns are checked against the rows already there before anything is written.
+
+**3. Determinism wired into pytest.** A new session replays the same values from the same seed; consecutive calls on one session continue the sequence instead of repeating it — inside a two-line fixture.
+
+## Quick start
+
+Declare a **shape** from a root model; each key walks a one-to-many or many-to-many relationship, by relationship name or by target class name:
+
+```python
+from seedgraph import seed
+
+graph = seed(session, User, post=2, post__comment=3)   # 3 users by default
+
+assert len(graph.users) == 3
+assert len(graph.posts) == 6
+post = graph.users[0].posts[0]
+assert post.author_id == graph.users[0].id          # real key, assigned by the database
+assert graph.labels == []                           # any table of the model, empty if not seeded
+```
+
+`seed()` returns once the graph is flushed and verified; commit or roll back as your test needs. `seed_async(async_session, ...)` is its twin for an `AsyncSession`.
+
+### Existing and missing parents
+
+```python
+alice = session.get(User, 1)
+graph = seed(session, Post, parents=[alice])   # every post's author is alice; alice is not in graph.users
+
+graph = seed(session, Comment)   # one Post and one User are generated, shared by all comments
+```
+
+A link first takes the nearest ancestor of its type in the shape, then the object of that type passed in `parents` (optional links included). A required link still empty gets **one** generated parent per type, shared by every object that needs it. Several objects of one type are accepted in `parents`; a link towards a single parent refuses to choose between them with `AmbiguousParentError`.
+
+### Many-to-many
+
+```python
+graph = seed(session, Article, article=5, tags=3)            # 15 new tags, 3 per article
+graph = seed(session, Article, article=5, parents=[python, sql])   # every article tagged with both existing tags
+```
+
+A count keeps its one-to-many meaning: new objects for each parent. Objects passed in `parents` join every many-to-many collection of their type, next to the ones the shape builds. SQLAlchemy writes the association rows itself.
+
+### Pinning and generating values
+
+```python
+graph = seed(
+    session,
+    User,
+    post=2,
+    generators={User: {"name": lambda ctx: ctx.fake.first_name()}},   # replace how a column is generated
+    overrides={Post: {"title": "Imposed", "subtitle": None}},        # pin a value, None included
+)
+```
+
+`ctx.fake` is the session's seeded Faker; `ctx.column` is the column name. An override can also be a callable taking the same context.
+
+### pytest
+
+Installing seedgraph registers four fixtures, prefixed so they never shadow your own `session` or `graph`:
+
+```python
+def test_feed(seedgraph_graph):
+    graph = seedgraph_graph(User, post=2)       # fresh in-memory SQLite, FK enforced, tables created on demand
+    assert len(graph.posts) == 6
+
+async def test_feed_async(seedgraph_agraph):
+    graph = await seedgraph_agraph(User, post=2)
+```
+
+`seedgraph_session` and `seedgraph_asession` expose the sessions behind them. To seed your own database, call `seed()` on your own session.
+
+## Guarantees and the tests that prove them
+
+| Guarantee | Test |
+|---|---|
+| Every link of the returned graph is verified after flush | `test_verification.py::test_seed_returns_a_graph_already_written_with_real_keys`, `::test_verify_graph_names_the_link_whose_foreign_key_disagrees` |
+| Seeding on top of existing rows keeps PostgreSQL sequences intact | `test_postgres.py::test_the_application_still_inserts_after_a_seed_on_top_of_its_rows` |
+| Two sessions seeding the same tables at once do not collide | `test_postgres.py::test_two_sessions_seeding_the_same_tables_at_once_do_not_collide` |
+| Unique columns skip values already in the database | `test_unique.py::test_a_new_session_on_a_populated_database_skips_the_values_already_taken`, `::test_postgres_rows_from_an_earlier_run_do_not_block_a_new_seed` |
+| Same seed, same values; consecutive calls do not repeat | `test_generators.py::test_a_new_session_replays_the_same_values`, `::test_two_seeds_in_one_session_continue_the_same_faker_sequence` |
+| Generated values fit the column type (enum, length, precision, arrays) | `test_types.py` |
+| Many-to-many shapes build new objects per parent; existing objects are shared | `test_many_to_many.py::test_a_many_to_many_count_builds_new_objects_for_each_parent`, `::test_existing_objects_passed_as_parents_are_shared_by_every_generated_object` |
+| Natural and composite primary keys are generated and never collide | `test_verification.py::test_a_natural_text_key_is_generated`, `::test_natural_keys_skip_the_ones_already_in_the_database`, `::test_a_composite_integer_key_and_its_composite_foreign_key_are_generated` |
+| Multi-column unique constraints hold | `test_unique.py::test_many_rows_under_one_parent_keep_a_multi_column_constraint`, `::test_a_second_session_keeps_a_multi_column_constraint` |
+| Existing rows serve as parents; missing required parents are generated once | `test_parents.py::test_a_parent_already_in_the_database_is_linked_and_left_out_of_the_graph`, `::test_a_child_seeded_alone_gets_one_generated_parent_shared_by_all` |
+| Plugin fixtures live beside a project's own `session` and `graph` | `test_fixtures.py::test_the_prefixed_fixtures_live_beside_a_project_own_session_and_graph` |
+
+## Limits
+
+- **`seed()` flushes the session.** The keys come from the database; the objects are no longer pending when it returns.
+- **A shape key towards a parent is refused**, as parents are linked or generated on their own; pass existing ones in `parents`. View-only relationships are refused too, since nothing would be written.
+- **Required columns of uncovered types** (JSON, custom `TypeDecorator`, arrays of those) raise `UnsupportedPlaceholderError`; declare a generator for them. Nullable ones are left empty.
+- **A multi-column unique constraint whose generated columns are only booleans or enums** is left to the database. For the others, one generated column is kept unique on its own, which is stricter than the constraint.
+- **An association class whose primary key combines its two foreign keys** holds one row per parent pair: the generated parent is shared, so two rows under the same parent collide. Seed one per parent, or use a many-to-many relationship.
+- **A loop of required links between tables**, or a required link to its own table, cannot be generated; pass one side in `parents`.
+- **Determinism holds for a given Faker version.** Faker may change its data between releases.
+
+## Design principles
+
+1. **Model-first, not schema-first.** Works from your SQLAlchemy ORM models and relationships.
+2. **Referential consistency is verified, not hoped for.** The database assigns the keys, seedgraph checks every link afterwards.
+3. **Shared parents are the point.** Realistic data shares parents (one author, many posts). One object per FK is not a graph.
+4. **Deterministic.** A new session with the same calls produces the same graph.
+5. **Self-references and mutually referencing tables are normal.** `Category.parent` and tables pointing at each other are supported; only unsatisfiable loops of required links are refused.
+6. **Stop generating at the boundary.** Existing rows are usable as parents; only missing parents get generated.
+
+## Roadmap
+
+- [x] Shape API (`relation=n`, nesting, shared parents)
+- [x] Custom field generators (Faker under the hood)
+- [x] Overriding specific attributes on generated objects
+- [x] pytest fixture helpers
+- [x] Self-referential and cyclic FKs
+- [x] Async sessions support
+- [x] Database-assigned keys and post-flush verification, PostgreSQL in the test suite
+- [x] Type-valid values, uniqueness against existing rows, existing and generated parents
+- [x] Many-to-many shapes, generated natural keys, multi-column uniqueness, arrays
+- [ ] Publication on PyPI
+
+## Installation
+
+```bash
+pip install seedgraph
+pip install "seedgraph[async]"  # for seed_async and the async pytest fixtures
+```
+
+Requires Python 3.11+, SQLAlchemy 2.x and Faker 30+. The async extra adds greenlet (through `sqlalchemy[asyncio]`) and aiosqlite. The PostgreSQL tests of the suite need Docker and are skipped without it.
+
+## License
+
+MIT

seedgraph-0.1.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+seedgraph/__init__.py,sha256=VrapARKPdcB4TmBftOQlrSCAkUp6MV7wKLLNwwfP3Ng,3918
+seedgraph/boundary.py,sha256=FLb_VZRo3BMSJNFnbuI-AYu6IcPnRCn4STYupeLkZCs,1824
+seedgraph/exceptions.py,sha256=927q_ldHKPWnJUf9kWpJIrO2TvbLTXzHpThk-k8pZI0,333
+seedgraph/generators.py,sha256=Nj7VQo1qTN3fGbNhjsG9IyZWG_-8w5b-agDLQbvAIfQ,12160
+seedgraph/graph.py,sha256=MNpYD-6qgDrFp_XMtTySbY1tPIbbO5m0ErjsfphdD8s,1186
+seedgraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+seedgraph/pytest_plugin.py,sha256=Q-aOUbYtOpIDAhfMbuqq76eqEp3edAMdJg_jIvjkWMk,3337
+seedgraph/shape.py,sha256=d_bOCrSjLRnWNUus6dWpjBZyRjmn7kJUxQGYXhKz7bU,11040
+seedgraph/uniqueness.py,sha256=gFJGIVlYOyDJcd0W93ouozT3jZ4CQ0vOPdW8DL8dDz0,2553
+seedgraph/verification.py,sha256=vUXC25zEFzVnPlFmowv4ve0rYJP8Zkqqi80tB7SSDf4,1772
+seedgraph-0.1.1.dist-info/METADATA,sha256=UKHCUz9nQMAThcCGoWOiEcXP_TdSkbSFJvy27WKtpAk,12781
+seedgraph-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+seedgraph-0.1.1.dist-info/entry_points.txt,sha256=T_-BycY7DSgOwrDJtKH8ugZWo2VuLNks9blD6ojB-Ng,47
+seedgraph-0.1.1.dist-info/licenses/LICENSE,sha256=eCHmfhsEWXn7Hlw1UZuEJpp7JTf6UTYRnl1aqZVW_g0,1071
+seedgraph-0.1.1.dist-info/RECORD,,

seedgraph-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

seedgraph-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+seedgraph = seedgraph.pytest_plugin

seedgraph-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rachid Jeffali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.