Seeding API

general_manager.seeding.manager_landscape.InvalidSeedTargetError

Bases: ValueError

Raised when a seed target argument cannot be parsed.

general_manager.seeding.manager_landscape.ManagerSelectionError

Bases: ValueError

Raised when manager selection arguments are invalid.

general_manager.seeding.manager_landscape.SeedableManagerCollisionError

Bases: ValueError

Raised when seedable manager discovery finds ambiguous class names.

general_manager.seeding.manager_landscape.ManagerSeedFailure

Bases: RuntimeError

Raised when seeding a manager fails.

general_manager.seeding.manager_landscape.SeedTarget dataclass

Desired minimum row count for one selected manager.

general_manager.seeding.manager_landscape.SeedPlanRow dataclass

Dry-run description for one seed target after dependency ordering.

general_manager.seeding.manager_landscape.SeedFailure dataclass

Failure captured while seeding a manager with continue-on-error enabled.

general_manager.seeding.manager_landscape.SeedExecutionResult dataclass

Summary of created rows and collected failures for a seeding run.

general_manager.seeding.manager_landscape.parse_target_overrides

parse_target_overrides(raw_targets)

Parse repeated NAME=COUNT target override arguments.

None and empty inputs return an empty mapping. Otherwise, each raw target must contain =. Whitespace around the manager name and count is ignored. Counts must parse as positive integers, and each manager name may appear at most once.

Parameters:

Name	Type	Description	Default
raw_targets	list[str] | tuple[str, ...] | None	Repeated raw command-line values, or None.	required

Returns:

Type	Description
dict[str, int]	Mapping from manager name to target minimum count.

Raises:

Type	Description
InvalidSeedTargetError	If a value is not NAME=COUNT, either side is blank, the count is not an integer, the count is below one, or the manager name is duplicated.

general_manager.seeding.manager_landscape.discover_seedable_managers

discover_seedable_managers(managers)

Return managers whose nested Factory exposes callable create_batch.

The returned mapping is keyed by the manager class name in input order. Managers without a factory or without callable Factory.create_batch are ignored. Duplicate class names are rejected because the command-line selection surface accepts class-name keys.

Raises:

Type	Description
SeedableManagerCollisionError	If two different seedable managers share the same class name.

general_manager.seeding.manager_landscape.select_seed_targets

select_seed_targets(
    *,
    managers_by_name,
    selected_names,
    include_all,
    default_count,
    overrides
)

Resolve selected manager names and per-manager target counts.

--all-style selection preserves discovery order. Explicit selection preserves first occurrence order and deduplicates repeated manager names. Target overrides are checked against all known manager names before selection, so unknown overrides raise unknown_manager before unselected override checks. Known overrides must then refer to selected managers.

Raises:

Type	Description
ManagerSelectionError	If default_count is below one, no manager is selected without include_all, a selected or overridden manager is unknown, or an override targets an unselected manager.

general_manager.seeding.manager_landscape.order_targets_by_dependencies

order_targets_by_dependencies(targets, managers_by_name)

Order seed targets so selected required relation dependencies run first.

Duplicate target names keep their first target. Only dependencies that are also selected affect ordering; missing dependencies are reported by build_seed_plan rather than inserted automatically.

general_manager.seeding.manager_landscape.build_seed_plan

build_seed_plan(targets, managers_by_name)

Build dry-run plan rows for ordered seed targets.

Rows are returned in dependency order. missing_dependencies lists required non-null relation managers discovered for each target that are not also selected, by manager class name. The planner does not create or add those dependencies.

general_manager.seeding.manager_landscape.execute_seed_plan

execute_seed_plan(
    *,
    targets,
    managers_by_name,
    batch_size,
    continue_on_error
)

Create missing rows for each seed target.

Targets are dependency-ordered again before execution. The current count is read from manager.all().count() before each ordered target. Every ordered target receives a created entry initialized to zero. If the existing count already meets the target, no factory call is made for that manager. Missing rows are created with Factory.create_batch(size) in batches of at most batch_size.

Each batch runs in its own transaction.atomic() block with no cross-manager atomicity, so prior manager batches and earlier batches for a failing manager can remain committed regardless of continue_on_error. With continue_on_error=True, the failing manager stops after its first failed batch, later managers continue, and partial progress is reported in the returned SeedExecutionResult. The created result is a MappingProxyType and failures is a tuple.

Raises:

Type	Description
ManagerSelectionError	If batch_size is below one.
ManagerSeedFailure	If a batch raises and continue_on_error is false. The exception stores manager name, failed batch size, original error, rows created before failure, and remaining count.

Manager landscape seeding is a thin planning layer over manager factories. A manager is seedable only when its nested Factory exposes callable create_batch(count). Discovery returns a class-name keyed mapping in input order and rejects duplicate seedable class names with SeedableManagerCollisionError; module-qualified names are not selection keys for this helper.

parse_target_overrides(raw_targets) returns {} for None or empty input. Otherwise it accepts repeated NAME=COUNT strings, trims whitespace, requires positive integer counts, and rejects duplicate names. select_seed_targets(...) resolves either explicit manager names or include_all selection, deduplicates repeated explicit names by keeping the first occurrence, and applies per-manager overrides. Override names are validated against all known managers before selection, so an unknown override raises ManagerSelectionError.unknown_manager before the unselected-override check. Known overrides for managers that are not selected raise ManagerSelectionError.unselected_overrides.

order_targets_by_dependencies(...) orders selected targets so required non-null ForeignKey and OneToOneField dependencies run first when both sides are selected. Dependency discovery reads manager.Interface._model._meta.get_fields(), follows each field's remote_field.model._general_manager_class, excludes nullable relations, self-relations, non-relation fields, and managers without model metadata. It does not add unselected dependencies. build_seed_plan(...) returns ordered SeedPlanRow objects and reports unselected required dependencies by manager class name.

execute_seed_plan(...) dependency-orders targets again, reads manager.all().count() for each ordered target, initializes SeedExecutionResult.created[manager_name] = 0 for every ordered target, creates only the missing rows, and calls Factory.create_batch(size) in batches of at most batch_size. Each batch uses its own transaction.atomic() block; there is no cross-manager transaction. Invalid batch sizes raise ManagerSelectionError. Factory failures raise ManagerSeedFailure by default, including the manager name, failed batch size, original error, created count, and remaining count. With continue_on_error=True, the failing manager stops after the first failed batch, the failure is collected as a SeedFailure, and later managers continue. The returned SeedExecutionResult.created value is a concrete immutable MappingProxyType, and failures is a tuple.