angee.base.stages

Ordered, data-owned pipeline stages.

Lifecycles whose vocabulary belongs to code use :class:angee.base.transitions.StateTransitions. A pipeline whose names and ordering belong to users composes :class:Stage into an addon-owned concrete stage model instead. The concrete model supplies only its container relation and optional category field; records compose :class:StagedModelMixin and declare the matching container and stage foreign keys.

StageTone

class StageTone(models.TextChoices)

Semantic stage colors shared with the frontend tone vocabulary.

Stage

class Stage(models.Model)

Abstract base for one user-named stage in a container-scoped pipeline.

A concrete stage model sets :attr:container_field_name to its owning foreign key (for example "queue"). If it stores a closed semantic category, it also sets :attr:category_field_name; consumers read that value through :meth:get_category rather than assuming a field name.

Meta

class Meta()

Django model options for the abstract ordered-stage primitive.

__str__

def __str__() -> str

Return the user-owned stage name.

container_field

@classmethod
def container_field(cls) -> models.Field[Any, Any]

Return the declared container relation, failing fast if misconfigured.

for_container

@classmethod
def for_container(cls, container: models.Model) -> models.QuerySet[Any]

Return every stage configured for container in pipeline order.

resolve_default

@classmethod
def resolve_default(cls, container: models.Model) -> Any | None

Return the container's configured default stage, or its first stage.

The container is the single owner of an explicit default. A stage model never carries an is_default flag; if no explicit default is set, the deterministic ordered first row is the primitive's fallback.

get_category

def get_category() -> Any | None

Return this stage's addon-owned category value, if one is declared.

StagedModelMixin

class StagedModelMixin(models.Model)

Validate a record's stage against its owning container.

Consumers declare ordinary foreign keys named by :attr:stage_field_name and :attr:stage_container_field_name. The mixin owns the cross-container invariant and delegates default resolution to the related stage model.

Meta

class Meta()

Django model options for the abstract staged-record mixin.

stage_model

@classmethod
def stage_model(cls) -> type[Stage]

Return the concrete stage model declared by this record.

resolve_default_stage

def resolve_default_stage() -> Stage | None

Resolve this record's container-owned default stage.

validate_stage_scope

def validate_stage_scope() -> None

Reject a stage that does not belong to this record's container.

clean

def clean() -> None

Run model cleaning, then enforce the stage/container invariant.