Actions
Actions are the distributed work primitive. An @action-decorated
async function is registered with the worker bridge and gets dispatched
to a worker each time a workflow calls it. Action arguments and results
round-trip through Postgres, so anything you pass needs to be
pydantic-serializable.
Decorator
action
Decorator for registering async actions.
Actions decorated with @action will automatically resolve dependency markers when called directly (e.g., during pytest runs where workflows bypass the gRPC bridge).
Parameters
- Name
func- Type
- Optional[TAsync]
- Description
Default: None
- Name
name- Type
- Optional[str]
- Description
Default: None
Registry
The action registry is the runtime's map from action name to handler. The worker pool consults it when claiming queue rows.
In-memory registry of user-defined actions.
Actions are keyed by (module, name), allowing the same action name to be used in different modules.
Class Methods
- Name
register- Return type
- None
- Description
Register an action with its module and name.
Args: module: The Python module containing the action. name: The action name (from @action decorator). func: The async function to execute.
Raises: ValueError: If an action with the same module:name is already registered with a different implementation.
- Name
get- Return type
- Optional[AsyncAction]
- Description
Look up an action by module and name.
Args: module: The Python module containing the action. name: The action name.
Returns: The action function if found, None otherwise.
- Name
names- Return type
- list[str]
- Description
Return all registered action keys (module:name format).
- Name
entries- Return type
- list[_ActionEntry]
- Description
Return all registered action entries.
- Name
reset- Return type
- None
- Description
Clear all registered actions.
Dependencies
Actions can declare dependencies the same way Mountaineer and FastAPI
controllers do - via Annotated[T, Depends(...)] parameters. Depends
is re-exported from mountaineer-di; Depend remains as a backward-
compatible alias.
Depend
Compatibility alias for mountaineer_di.Depends.
Parameters
- Name
dependency- Type
- Callable[..., Any] | None
- Description
Default: None
- Name
use_cache- Type
- bool
- Description
Default: True
Result payloads
These helpers handle the serialization layer between an action's
in-process Python objects and the bytes that land in Postgres. Most
users don't touch them directly - the @action decorator handles
serialization automatically - but they're exposed for tooling that
needs to interpret persisted results.
Class Constructor
- Name
result- Type
- Any | None
- Description
- Name
error- Type
- dict[str, Any] | None
- Description
serialize_result_payload
Serialize a successful action result.
Parameters
- Name
value- Type
- Any
- Description
deserialize_result_payload
Deserialize WorkflowArguments produced by serialize_result_payload/error.
Parameters
- Name
payload- Type
- pb2.WorkflowArguments | None
- Description
serialize_error_payload
Serialize an error raised during action execution.
Parameters
- Name
exc- Type
- BaseException
- Description