Fractal Processes

Fractal Processes is a small workflow engine: processes assembled from actions and run against a shared context, so a workflow is data rather than code.

Installation

pip install fractal-processes

Background

A Process is an ordered list of Actions, run against a ProcessContext that carries state from one to the next. Actions cover the ordinary things a workflow does — set a value, fetch or store an entity, dispatch a command, publish an event — and control flow is itself made of actions, so branching, loops and sub-processes live inside the process rather than in Python around it.

That is the whole point. A workflow assembled from data can be stored, inspected, and changed without a deploy; a workflow written as a function cannot. The cost is that you give up Python's syntax for the parts that become actions, which is why this is worth reaching for when a workflow is configuration and not worth it when it is just code.

Self-contained by design: this package imports no other Fractal library except fractal-specifications, which it uses to express conditions.

Usage

from fractal_processes import (
    IfElseAction,
    Process,
    ProcessContext,
    SetContextVariableAction,
    SetValueAction,
    field_gt,
)

process = Process([
    SetContextVariableAction(discount=0),
    IfElseAction(
        field_gt("order.total", 100),
        [SetValueAction("discount", 10)],
        [SetValueAction("discount", 0)],
    ),
])

ctx = ProcessContext({"order": {"total": 250}})
process.run(ctx)

ctx["discount"]      # 10
ctx.order.total      # 250 — attribute access works too

ProcessContext supports dotted keys ("order.total") and attribute access, and merges nested dicts rather than replacing them.

Actions

State — SetContextVariableAction, SetValueAction, GetValueAction, ApplyToValueAction, IncreaseValueAction

Entities — AddEntityAction, UpdateEntityAction, FetchEntityAction, FindEntitiesAction, DeleteEntityAction

Messaging — CommandAction, QueryAction, PublishEventAction

Control flow — IfElseAction, WhileAction, ForEachAction, TryExceptAction, SubProcessAction, ParallelAction

Diagnostics — PrintAction, PrintValueAction, RaiseExceptionAction, CreateSpecificationAction

Conditions

Conditions are specifications, built with helpers that read the context:

from fractal_processes import field_equals, field_gt, field_in, has_field, on_field

field_equals("user.role", "admin")
field_gt("order.total", 100)
field_in("status", ["draft", "review"])
has_field("user.email")
on_field("order.lines", lambda lines: len(lines) > 3)

CallableSpecification wraps any callable, for the cases the helpers do not cover.

Async

AsyncProcess and AsyncAction are the awaitable equivalents. Both provide a synchronous wrapper, so an async process can be run from sync code.

Development

make dev-install
make test
make lint
make format