Actions¶
Generic action, field, and result contracts.
Consumers own the verbs and the effects. Groundskeeping owns the repeatable operator sequence around those verbs: describe fields, parse input, ask policy whether to proceed, run with progress/cancellation context, and render a generic outcome.
Preflight
module-attribute
¶
Preflight = Callable[
[Mapping[str, object]], Sequence[ValidationIssue]
]
ActionContext
dataclass
¶
ActionContext(
progress: ProgressSink,
cancellation: CancellationToken,
action_id: str,
)
Everything a runner may touch while the action is in flight.
Deliberately narrow: a runner reports progress and checks for cancellation through this object, so long-running domain work never needs to import a widget or reach the app.
emit ¶
emit(
event: str,
*,
phase: str | None = None,
completed: int = 0,
total: int | None = None,
unit: str | None = None,
message: str | None = None,
) -> None
ActionOutcome
dataclass
¶
ActionOutcome(
status: SemanticStatus,
summary: str,
view: SurfaceView,
detail: object | None = None,
refresh_pages: frozenset[str] = frozenset(),
)
ActionRegistry ¶
ActionRegistry(
actions: Sequence[ActionSpec],
*,
page_keys: Sequence[str] | None = None,
)
ActionRunner ¶
Bases: Protocol
ActionSpec
dataclass
¶
ActionSpec(
key: str,
page_key: str,
label: str,
summary: str,
runner: ActionRunner,
command_hint: str | None = None,
fields: tuple[FieldSpec, ...] = (),
execution: ExecutionKind = ExecutionKind.QUICK,
cancellation: CancellationMode = CancellationMode.UNSUPPORTED,
effect_refs: frozenset[str] = frozenset(),
resource_refs: frozenset[str] = frozenset(),
preflight: Preflight | None = None,
)
Declaration of one operator-facing command and the runner that performs it.
The spec carries everything the shell needs to present, gate, and execute the command without knowing what it does: fields to parse, resources and effects for the operation policy to reason about, and the cancellation mode the runner honours.
cancellation
class-attribute
instance-attribute
¶
cancellation: CancellationMode = (
CancellationMode.UNSUPPORTED
)
preflight
class-attribute
instance-attribute
¶
preflight: Preflight | None = field(
default=None, compare=False, repr=False
)
parse_params ¶
parse_params(
raw: Mapping[str, object] | None = None,
) -> tuple[dict[str, object], dict[str, object]]
AllowAllOperationPolicy ¶
Default policy for demos and tests; production consumers should be explicit.
ChoiceOption
dataclass
¶
ChoiceOption(
value: str, label: str, description: str | None = None
)
Confirmation
dataclass
¶
Confirmation(
title: str,
message: str,
confirm_label: str = "Run",
dangerous: bool = False,
)
DefaultResultPresenter ¶
Present plain runner results without imposing a consumer report schema.
ExecutionKind ¶
FieldKind ¶
Bases: StrEnum
FieldSpec
dataclass
¶
FieldSpec(
key: str,
label: str,
kind: FieldKind = FieldKind.TEXT,
required: bool = True,
default: object | None = None,
help: str | None = None,
placeholder: str | None = None,
choices: tuple[ChoiceOption, ...] = (),
minimum: Decimal | int | None = None,
maximum: Decimal | int | None = None,
disabled: bool = False,
read_only: bool = False,
sensitive: bool = False,
secret_clearable: bool = False,
validator: Validator | None = None,
)
OperationPolicy ¶
ParsedField
dataclass
¶
ParsedField(key: str, value: object, redacted: object)
ResultPresenter ¶
Bases: Protocol
ValidationIssue
dataclass
¶
ValidationIssue(
message: str,
field_key: str | None = None,
status: SemanticStatus = SemanticStatus.ERROR,
)
run_action_sync ¶
run_action_sync(
action: ActionSpec,
raw_params: Mapping[str, object] | None,
cancellation: CancellationToken,
*,
presenter: ResultPresenter | None = None,
action_id: str | None = None,
) -> ActionOutcome
Run an action synchronously for tests, demos, and simple quick actions.