py_trees reference for the Beehave adapter¶
This document is the reference for Beehave's py_trees adapter: the code that takes a live py_trees tree, built in Python, and converts it to the format-agnostic model (beehave.model), so that the existing flatten, walk and render steps apply unchanged (ADR 0002). It gives the tick semantics of every class a py_trees tree can contain as a rule for the continuation-passing walk, compile(node, on_success, on_failure) -> entry, a mapping table from py_trees classes to NodeKind and Semantics, and a recommended API and CLI.
Everything here was checked against the source of py_trees 2.6.0, the latest release on PyPI. The PyPI wheel is byte-identical to tag 2.6.0 (commit 35dc6d3) of the upstream repository. The default branch, devel (commit 41ec377, 2026-09-17), differs from the tag only in py_trees/ports.py (longer error messages), so every line reference below holds for both. The semantics were then confirmed by building tiny trees and ticking them: the snippets and their real output are in §3. They give identical output on Python 3.10.20 and 3.12.3.
Notation, as in the BT.CPP v3 reference: S and F are the success and failure continuations passed to compile. An activation of a node runs from its first tick until it returns SUCCESS or FAILURE. A single static pass is one activation in which every child that is ticked completes. "Exact" means the rule reproduces every success/failure path of one activation. "Approximated" means Phase 1 draws the single-pass edges only and reports the node, following ADR 0004. RUNNING is an outcome the walk does not model. It matters only where it changes which child runs next, and those cases are flagged.
1. Summary: mapping table¶
New marks a proposed Semantics member (see §1.4). Approximation messages in quotes are the ones walk.py already emits for that member. The others are proposed, in the same style.
1.1 Composites (py_trees.composites)¶
| py_trees class | Kind | Semantics | Walk rule compile(n, S, F) |
Phase 1 | Notes and approximation message |
|---|---|---|---|---|---|
Sequence(memory=True) |
control | SEQUENCE |
c1 -S-> c2 -S-> … cn -S-> S, every ci -F-> F |
exact | Resumes at the RUNNING child. Restarts at c1 after SUCCESS or FAILURE. This is BT.CPP's plain Sequence, not SequenceStar (§3.1). |
Sequence(memory=False) |
control | REACTIVE_SEQUENCE |
same as Sequence |
approximated | "walked like a Sequence; its conditions are re-checked every tick, but preemption edges are not shown yet". Earlier children, actions included, are ticked again on every tick. |
Selector(memory=True) |
control | FALLBACK |
c1 -F-> c2 -F-> … cn -F-> F, every ci -S-> S |
exact | BT.CPP's plain Fallback. |
Selector(memory=False) |
control | REACTIVE_FALLBACK |
same as Fallback |
approximated | "walked like a Fallback; its conditions are re-checked every tick, but preemption edges are not shown yet". This is the usual py_trees priority selector: every Selector in the demos and tutorials uses it (§3.1). |
Parallel(SuccessOnAll) |
control | PARALLEL |
walked like a Sequence | approximated | "children are shown as if they ran one after another". Ports: policy, synchronise, success_threshold="-1", failure_threshold="1". |
Parallel(SuccessOnOne) |
control | PARALLEL |
walked like a Sequence | approximated | Proposed: "children are shown as if they ran one after another; one SUCCESS is enough while the others are RUNNING, and those edges are not shown yet". Ports as above with success_threshold="1". |
Parallel(SuccessOnSelected) |
control | PARALLEL |
walked like a Sequence | approximated | As above, plus a selected port with child indices (names are not unique). |
empty Sequence / Parallel / Selector |
control | as above | entry = S / S / F |
exact | Verified in §3.2. |
user Composite subclass that defines its own tick |
control | CUSTOM |
walked like a Sequence | approximated | Existing unknown-control diagnostic. |
1.2 Decorators (py_trees.decorators)¶
The child is decorator.decorated, which is always decorator.children[0] (decorators.py L111-L114).
| py_trees class (parameter attributes) | Kind | Semantics | Walk rule | Phase 1 | Notes and approximation message |
|---|---|---|---|---|---|
Inverter |
decorator | INVERTER |
compile(c, F, S) |
exact | RUNNING passes through. |
SuccessIsFailure |
decorator | FORCE_FAILURE |
compile(c, F, F) |
exact | |
FailureIsSuccess |
decorator | FORCE_SUCCESS |
compile(c, S, S) |
exact | |
SuccessIsRunning |
decorator | KEEP_RUNNING_UNTIL_FAILURE |
e = compile(c, e, F) |
approximated | "never succeeds (a successful child is ticked again); walked as transparent, the loop is not shown yet". Same status map as BT.CPP KeepRunningUntilFailure. |
FailureIsRunning |
decorator | RETRY, no count port |
e = compile(c, S, e) |
approximated | "the retry loop is folded into a note; the loop edge is not shown yet". Unbounded: F is unreachable. |
Condition(status=SUCCESS) (succeed_status) |
decorator | RETRY, port status |
e = compile(c, S, e) |
approximated | Same status map as FailureIsRunning (§3.3). Never returns FAILURE. |
Condition(status=FAILURE) |
decorator | new STATUS_MAP |
e = compile(c, e, S) |
approximated | Proposed: "waits for its child to fail; a successful child is ticked again, the loop is not shown yet". Phase 1 draws compile(c, S, S). |
Condition(status=RUNNING) |
decorator | new STATUS_MAP |
SUCCESS once the child is RUNNING; otherwise tick the child again | approximated | Proposed: "succeeds as soon as its child is RUNNING; not modelled, walked as transparent". |
RunningIsFailure |
decorator | new STATUS_MAP |
compile(c, S, F) plus "still running" edges to F |
approximated | Proposed: "a RUNNING child is halted and counts as FAILURE; those edges are not shown yet". Used by the pick_up_where_you_left_off demo. |
RunningIsSuccess |
decorator | new STATUS_MAP |
compile(c, S, F) plus "still running" edges to S |
approximated | Proposed: "a RUNNING child is halted and counts as SUCCESS; those edges are not shown yet". |
Retry (num_failures) |
decorator | RETRY, port num_failures |
e = compile(c, S, R), R = e if k < N else F |
approximated, exact if N ≤ 1 |
N is the number of attempts. -1 does not mean forever: any N ≤ 1 fails on the first failure (§3.4). |
Repeat (num_success) |
decorator | REPEAT, port num_success |
e = compile(c, L, F), L = e if k < N else S |
approximated, exact if N = 1 |
Any N ≤ 0, including the documented -1, never succeeds (§3.4). |
Timeout (duration, seconds, default 5.0) |
decorator | TIMEOUT, port duration |
compile(c, S, F) plus timeout edges to F |
approximated | "can also fail when time runs out; those failure edges are not shown yet". |
EternalGuard (condition, blackboard) |
control (desugared) | REACTIVE_SEQUENCE over [guard condition, c] |
[cond] -> compile(c, S, F), else F |
approximated | The adapter emits a synthetic condition node as the first child (§3.5). The reactive message applies: the guard is checked before every tick. |
OneShot (policy) |
decorator | new RUN_ONCE, port policy |
first activation: compile(c, S, F) |
approximated | Proposed: "after its child completes, later activations return that result without running it; not shown yet". |
Count, PassThrough |
decorator | new PASS_THROUGH |
compile(c, S, F) |
exact | |
StatusToBlackboard (variable_name) |
decorator | new PASS_THROUGH, port variable_name |
compile(c, S, F) |
exact | Also writes the child's status to the blackboard. |
ForEach (source_key, target_key, since 2.4.0) |
decorator | REPEAT, ports source_key, target_key |
like Repeat with N = len(items) |
approximated | Proposed: "repeats its child once per item of {source_key}; the loop is not shown yet". With an empty list the child still runs once and its result is ignored (§3.5). |
user Decorator subclass that defines its own tick or update |
decorator | CUSTOM |
transparent | approximated | Existing unknown-decorator diagnostic. |
1.3 Behaviours (leaves: py_trees.behaviours, py_trees.timers)¶
| py_trees class (parameter attributes) | Kind | Semantics | Walk rule | Phase 1 | Notes |
|---|---|---|---|---|---|
Success |
action (constant) | ALWAYS_SUCCESS |
entry = S |
exact | |
Failure |
action (constant) | ALWAYS_FAILURE |
entry = F |
exact | |
Running, Dummy |
action | new ALWAYS_RUNNING |
a box with no outgoing edge | approximated | Usually the lowest-priority "Idle" child. Until the member exists: a CUSTOM action plus an adapter diagnostic, "never finishes; its SUCCESS and FAILURE edges are unreachable". |
CheckBlackboardVariableValue (check) |
condition | new BLACKBOARD_CONDITION |
branch [battery_level < 20] |
exact | Label and key built from the ComparisonExpression (§3.7). |
CheckBlackboardVariableExists (variable_name) |
condition | new BLACKBOARD_CONDITION |
branch [battery_level is set] |
exact | |
CheckBlackboardVariableValues (checks, operator, namespace) |
condition | new BLACKBOARD_CONDITION |
branch [(a == 1) xor (b == 2)] |
exact | Also writes each result under namespace when one is given. either_or relies on this. |
CompareBlackboardVariables (var1_key, var2_key, operator, since 2.4.0) |
condition | new BLACKBOARD_CONDITION |
branch [speed <= limit] |
exact | |
SuccessEveryN (every_n) |
condition | CUSTOM, port n |
branch | exact | Never RUNNING. It is stateful: it counts its own ticks. |
BlackboardToStatus (variable_name) |
condition | CUSTOM, port variable_name |
branch [variable_name is SUCCESS] |
approximated | Returns whatever status is stored, RUNNING included. |
WaitForBlackboardVariable (variable_name), WaitForBlackboardVariableValue (check) |
action (a wait) | CUSTOM, port expression |
a box | approximated | They block (RUNNING) instead of failing, so the FAILURE edge is unreachable. They subclass the Check… classes (§3.7). |
SetBlackboardVariable(overwrite=True) (variable_name) |
action | SET_BLACKBOARD |
entry = S |
exact | Always SUCCESS. |
SetBlackboardVariable(overwrite=False) |
action | CUSTOM |
box with -S-> and -F-> |
exact | FAILURE if the variable already exists. |
UnsetBlackboardVariable (key) |
action | SET_BLACKBOARD |
entry = S |
exact | Always SUCCESS. |
timers.Timer (duration, seconds) |
action | new SLEEP |
box with a single -S-> edge |
approximated | RUNNING until the time is up, then SUCCESS, never FAILURE. BT.CPP v4 Sleep is the same node. |
Periodic, StatusQueue, TickCounter, ProbabilisticBehaviour |
action | CUSTOM |
box with -S-> and -F-> |
exact | Test and demo stand-ins for real work. |
user Behaviour subclass |
action, or condition from the config | CUSTOM |
box, or branch | exact | py_trees has no "condition" base class (§4.4). |
py_trees has no subtree reference node. A live tree is always fully inlined (helper functions and the 2.5+ XML parser both build plain composites), so NodeKind.SUBTREE is never produced and flattening is the identity.
1.4 Proposed model and walk changes¶
Each new member needs an ADR (ADR 0002: "If a format has a concept the model cannot express, we extend the model with a new ADR"). Three of them will also be needed by the BT.CPP v4 parser.
| Proposed member | Used for | Walk rule | Also needed for |
|---|---|---|---|
BLACKBOARD_CONDITION (condition leaf) |
the four Check…/Compare… behaviours |
Condition(key=ports["expression"], label=ports["expression"]) |
v4 ScriptCondition with a simple comparison |
PASS_THROUGH (decorator) |
PassThrough, Count, StatusToBlackboard |
transparent, exact | |
STATUS_MAP (decorator, ports on_success, on_failure, on_running) |
RunningIsFailure, RunningIsSuccess, Condition(FAILURE), Condition(RUNNING) |
compile(c, T(on_success), T(on_failure)) with T(SUCCESS)=S, T(FAILURE)=F, T(RUNNING)= the child's own outcome (Phase 1) or entry(c) (Phase 2) |
|
RUN_ONCE (decorator, port policy) |
OneShot |
transparent on the first activation | v4 RunOnce |
ALWAYS_RUNNING (action leaf) |
Running, Dummy |
a vertex with no outgoing edge | |
SLEEP (action leaf) |
timers.Timer |
a vertex with a single SUCCESS edge | v4 Sleep |
Only BLACKBOARD_CONDITION and PASS_THROUGH are needed for readable Phase 1 output. The others can be emulated with today's members plus an adapter diagnostic, as the trial in §6.5 does.
Small walk changes, independent of the new members:
_LOOP_NOTESreadsnum_attempts(BT.CPP) ornum_failures(py_trees) forRETRY, andnum_cyclesornum_successforREPEAT, so the action box readsretry ×3.- The
PARALLELapproximation message depends on thepolicyport (§1.1). - The key of a
CUSTOMcondition should include the instance name. Today it istype(ports), so two instances of one user class with different constructor arguments, such asIsAt("kitchen")andIsAt("door"), would share a key. They would then be treated as one check, and real paths would be dropped as contradictory (§4.4).
Pipeline¶
flowchart LR
SPEC["module:function<br/>or file.py:function"] --> IMP[Import and call<br/>the factory]
OBJ["Behaviour or<br/>BehaviourTree object"] --> AD
IMP --> AD[Adapt<br/>classify every node,<br/>read parameters]
AD --> DOC["Document<br/>format='py_trees'"]
DOC --> FL[Flatten<br/>identity]
FL --> W[Walk<br/>compile node, S, F]
W --> R[Render<br/>text / Mermaid / DOT / JSON]
2. Versions, packaging and ROS 2¶
| Item | Value | Source |
|---|---|---|
| Latest release | 2.6.0, tagged 2026-09-10, uploaded to PyPI 2026-09-10 | PyPI JSON API, git tag |
| Previous releases | 2.5.0 (2026-07-13), 2.4.0 (2025-11-13), 2.3.0 (2025-01-11), 2.2.3 (2023-02-08) | CHANGELOG.rst |
| Python | No Requires-Python in the metadata. It is commented out on purpose, because colcon build cannot parse it (pyproject.toml L16-L20). The intended floor is 3.10 (the commented value is >=3.10,<4.0, and ruff and ty target py310). Verified to import and run on 3.10.20 and 3.12.3, and to import on 3.13.16. |
wheel METADATA |
| Runtime dependencies | pydot>=1.4, which pulls in pyparsing. import py_trees imports pydot, because py_trees/__init__.py imports display. The Graphviz dot binary is only needed to render images. |
METADATA, __init__.py |
| Licence | BSD-3-Clause | pyproject.toml L15, package.xml |
| Typing | ships py.typed |
wheel contents |
Changes that matter to the adapter:
| Version | Change |
|---|---|
| 2.2.0 | memory became a required argument of Sequence and Selector, with the semantics of §3.1. In 2.1.x it was an optional, experimental flag: a Sequence had memory by default and a Selector did not. Repeat and Retry were added. The eternal_guard idiom was removed (commit a43e07f, 2023-01-03), in favour of Sequence(memory=False) and the EternalGuard decorator. |
| 2.2.3 | PassThrough decorator. |
| 2.3.0 | ProbabilisticBehaviour. |
| 2.4.0 | ForEach, CompareBlackboardVariables, a callable value in ComparisonExpression. |
| 2.5.0 | Typed ports (PortsMixin, BehaviourWithPorts) and an experimental XML parser (§5.4). |
| 2.6.0 | Port fixes, and "Recover memory sequences after child replacement" (#505). |
Recommendation: support py_trees ≥ 2.2, and look up classes added later with getattr(module, name, None).
ROS 2. py_trees is released into ROS 2 from ros2-gbp/py_trees-release. In rosdistro master (read 2026-10-17), Humble, Jazzy, Kilted and Rolling all list release 2.6.0-1. The release tags show the history:
- Humble:
2.2.3-2,2.3.0-1,2.4.0-1/2,2.5.0-1/2,2.6.0-1. Itssourcebranch is stillrelease/2.2.x(status maintained). - Jazzy:
2.2.1-4through2.6.0-1(status developed).
A Humble machine can therefore have any version from 2.2.3 to 2.6.0, depending on when it was last updated. All of them have the 2.2 semantics.
py_trees_ros (2.6.0-1 on Humble and Jazzy) adds ROS behaviours (subscribers, publishers, action and service clients) and py_trees_ros.trees.BehaviourTree, a subclass of py_trees.trees.BehaviourTree, so .root works the same way. It imports rclpy and ROS message packages at module level. py_trees_ros_tutorials (2.6.0-1) ships the tutorial trees as factory functions (§5.1).
3. Tick semantics, verified¶
3.0 Rules that apply to every node¶
Source: Behaviour.tick (behaviour.py L264-L305), Behaviour.stop (L344-L370), Decorator.tick and Decorator.stop (decorators.py L116-L155), and Status (common.py L32-L42).
- Statuses are
SUCCESS,FAILURE,RUNNINGandINVALID.INVALIDmeans "not active". It plays the role of BT.CPP's IDLE. initialise()runs whenever a node is ticked while not RUNNING. A completed child that is ticked again therefore starts over.stop(INVALID)is the halt. It calls the user'sterminate(INVALID). Unlike BT.CPP, which halts only RUNNING children, py_trees calls it on children that had already finished too, when their parent resets them. The snippets log this asreset.- A decorator ticks its child first, then computes its own status in
update(). If that status is not RUNNING and the child is still RUNNING, the child is halted. This is whyRunningIsFailurehalts a running child.
The snippets use this helper. Probe is a scripted leaf that logs each update and each stop(INVALID):
# probe.py
import py_trees
from py_trees.common import Status
S, F, R = Status.SUCCESS, Status.FAILURE, Status.RUNNING
LOG: list[str] = []
class Probe(py_trees.behaviour.Behaviour):
"""A leaf that returns the scripted statuses in turn (the last one repeats).
Every update is logged as ``name:S|F|R``. ``stop(INVALID)`` is logged as
``name:halted`` when the leaf was RUNNING, and as ``name:reset`` when it had
already finished (py_trees calls it in both cases).
"""
def __init__(self, name: str, *script: Status) -> None:
super().__init__(name)
self.script = list(script)
def update(self) -> Status:
status = self.script.pop(0) if len(self.script) > 1 else self.script[0]
LOG.append(f"{self.name}:{status.name[0]}")
return status
def terminate(self, new_status: Status) -> None:
if new_status == Status.INVALID:
LOG.append(f"{self.name}:{'halted' if self.status == Status.RUNNING else 'reset'}")
def run(root: py_trees.behaviour.Behaviour, ticks: int) -> None:
"""Tick ``root`` and print what each tick did."""
for i in range(1, ticks + 1):
LOG.clear()
root.tick_once()
print(f" tick {i}: {' '.join(LOG) or '(no leaf ticked)':<28} -> {root.status.name}")
3.1 Sequence and Selector, with and without memory¶
Sources: Selector.tick (composites.py L372-L448) and Sequence.tick (L509-L566). Both constructors are (name, memory, children=None) and store self.memory (L363-L370, L500-L507).
| Node | Where a tick starts | On child SUCCESS | On child FAILURE | On child RUNNING | Next activation |
|---|---|---|---|---|---|
Sequence(memory=True) |
at the RUNNING child if the sequence is RUNNING, else at c1 |
tick next child in the same tick; after the last, SUCCESS | FAILURE | RUNNING | starts at c1 |
Sequence(memory=False) |
always at c1 |
same | halt the later children, FAILURE | halt the later children, RUNNING | starts at c1 |
Selector(memory=True) |
at the RUNNING child if the selector is RUNNING, else at c1 |
halt the later children, SUCCESS | tick next child; after the last, FAILURE | halt the later children, RUNNING | starts at c1 |
Selector(memory=False) |
always at c1 |
halt the later children, SUCCESS | same | halt the later children, RUNNING | starts at c1 |
"Memory" in py_trees means only "resume at the child that was RUNNING". After any SUCCESS or FAILURE, the next activation starts at c1 again, whatever memory says. Hence the BT.CPP equivalents:
| py_trees | BT.CPP equivalent | Beehave Semantics |
|---|---|---|
Sequence(memory=True) |
Sequence |
SEQUENCE |
Sequence(memory=False) |
ReactiveSequence |
REACTIVE_SEQUENCE |
Selector(memory=True) |
Fallback |
FALLBACK |
Selector(memory=False) |
ReactiveFallback |
REACTIVE_FALLBACK |
Mapping memory=True to SEQUENCE_WITH_MEMORY would be wrong. BT.CPP's SequenceStar (v3) and SequenceWithMemory (v4) keep their index after a FAILURE, so the next activation resumes at the child that failed (btcpp-v3-xml.md §3.1). A py_trees memory sequence restarts at c1 (snippet below). py_trees has no built-in node with that behaviour. The pick_up_where_you_left_off idiom (§3.8) gets it with blackboard flags.
memory=False is exactly BT.CPP's reactive behaviour, verified below. While a child is RUNNING, every earlier child is ticked again on every tick. Earlier actions run again too, because a completed child starts over. If an earlier child of a Sequence fails, the running child is halted and the Sequence fails. If an earlier child of a Selector returns SUCCESS or RUNNING, the lower-priority running child is halted. The single static pass is the same as with memory: c1 -S-> … -S-> S with ci -F-> F for a Sequence, and the dual for a Selector. Phase 2 preemption edges matter more for py_trees than for BT.CPP. In py_trees_ros_tutorials, all 12 Selectors are memory=False and all 18 Sequences are memory=True. In the py_trees demos, the counts are 6 and 17, plus one Sequence(memory=False) (the eternal guard demo).
# v01_sequence.py
from probe import F, R, S, Probe, run
from py_trees.composites import Sequence
for memory in (True, False):
print(f"Sequence(memory={memory}), B is RUNNING twice:")
run(Sequence("seq", memory=memory, children=[Probe("A", S), Probe("B", R, R, S)]), 3)
print("Sequence(memory=False), A fails while B is RUNNING:")
run(Sequence("seq", memory=False, children=[Probe("A", S, F), Probe("B", R)]), 2)
print("Sequence(memory=True), next activation after a FAILURE:")
run(Sequence("seq", memory=True, children=[Probe("A", S), Probe("B", F, S)]), 2)
Sequence(memory=True), B is RUNNING twice:
tick 1: A:S B:R -> RUNNING
tick 2: B:R -> RUNNING
tick 3: B:S -> SUCCESS
Sequence(memory=False), B is RUNNING twice:
tick 1: A:S B:R -> RUNNING
tick 2: A:S B:R -> RUNNING
tick 3: A:S B:S -> SUCCESS
Sequence(memory=False), A fails while B is RUNNING:
tick 1: A:S B:R -> RUNNING
tick 2: A:F B:halted -> FAILURE
Sequence(memory=True), next activation after a FAILURE:
tick 1: A:S B:F -> FAILURE
tick 2: A:reset B:reset A:S B:S -> SUCCESS
# v02_selector.py
from probe import F, R, S, Probe, run
from py_trees.composites import Selector
for memory in (False, True):
print(f"Selector(memory={memory}), A fails then succeeds, B is RUNNING:")
run(Selector("sel", memory=memory, children=[Probe("A", F, S), Probe("B", R)]), 2)
print("Selector(memory=True), next activation after a SUCCESS:")
run(Selector("sel", memory=True, children=[Probe("A", F), Probe("B", S)]), 2)
print("Selector(memory=False), A becomes RUNNING while B is RUNNING:")
run(Selector("sel", memory=False, children=[Probe("A", F, R), Probe("B", R)]), 2)
Selector(memory=False), A fails then succeeds, B is RUNNING:
tick 1: A:F B:R -> RUNNING
tick 2: A:S B:halted -> SUCCESS
Selector(memory=True), A fails then succeeds, B is RUNNING:
tick 1: A:F B:R -> RUNNING
tick 2: A:reset B:R -> RUNNING
Selector(memory=True), next activation after a SUCCESS:
tick 1: A:F B:S -> SUCCESS
tick 2: A:F B:S -> SUCCESS
Selector(memory=False), A becomes RUNNING while B is RUNNING:
tick 1: A:F B:R -> RUNNING
tick 2: A:R B:halted -> RUNNING
3.2 Parallel¶
Sources: Parallel.tick (composites.py L662-L732), ParallelPolicy (common.py L71-L143). Constructor: Parallel(name, policy, children=None). The policy object is parallel.policy.
- Every tick, every child is ticked, in order. If
policy.synchroniseis true, children that already returned SUCCESS in this activation are skipped. A child is ticked even after an earlier one failed in the same tick. - Then: if any child has FAILURE, the parallel fails, so failure takes precedence over success. Otherwise:
SuccessOnAll: SUCCESS when all children have SUCCESS.SuccessOnOne: SUCCESS when at least one has SUCCESS.SuccessOnSelected(children): SUCCESS when every selected child has SUCCESS. The selection ispolicy.children, a list of child objects. It is validated insetup()and on every tick.- Otherwise RUNNING.
- On SUCCESS or FAILURE, children that are still RUNNING are halted (L734-L749).
synchronisedefaults differ by policy:SuccessOnAll()andSuccessOnSelected(...)default toTrue,SuccessOnOneis alwaysFalse, and theBasedefault isFalse(common.py L77, L97, L115-L117, L132). The py_trees_ros tutorials mostly useSuccessOnAll(synchronise=False)at the root, so successful children are ticked again on every tick.
In BT.CPP v3 port terms, SuccessOnAll is success_threshold = N (-1) with failure_threshold = 1, and SuccessOnOne is success_threshold = 1 with failure_threshold = 1. BT.CPP decides after each child, while py_trees ticks all of them first and lets FAILURE win, so the single pass agrees but the order of events does not. Recording these ports lets the Phase 2 fork/join rule for BT.CPP Parallel apply unchanged. SuccessOnSelected has no BT.CPP equivalent.
# v03_parallel.py
from probe import F, R, S, Probe, run
from py_trees.common import ParallelPolicy
from py_trees.composites import Parallel
for sync in (False, True):
print(f"SuccessOnAll(synchronise={sync}):")
run(
Parallel(
"par",
ParallelPolicy.SuccessOnAll(synchronise=sync),
children=[Probe("A", S), Probe("B", R, S)],
),
2,
)
print("SuccessOnOne, A succeeds while B runs:")
run(Parallel("par", ParallelPolicy.SuccessOnOne(), children=[Probe("A", S), Probe("B", R)]), 1)
print("SuccessOnOne, A succeeds and B fails in the same tick:")
run(Parallel("par", ParallelPolicy.SuccessOnOne(), children=[Probe("A", S), Probe("B", F)]), 1)
print("SuccessOnAll, A fails first: B is still ticked in that tick, then halted:")
run(Parallel("par", ParallelPolicy.SuccessOnAll(), children=[Probe("A", F), Probe("B", R)]), 1)
a, b = Probe("A", S), Probe("B", R)
print("SuccessOnSelected([A]):")
run(Parallel("par", ParallelPolicy.SuccessOnSelected([a]), children=[a, b]), 1)
from py_trees.composites import Selector, Sequence
for empty in (
Sequence("seq", memory=True),
Selector("sel", memory=False),
Parallel("par", ParallelPolicy.SuccessOnAll()),
):
empty.tick_once()
print(f"empty {type(empty).__name__} -> {empty.status.name}")
SuccessOnAll(synchronise=False):
tick 1: A:S B:R -> RUNNING
tick 2: A:S B:S -> SUCCESS
SuccessOnAll(synchronise=True):
tick 1: A:S B:R -> RUNNING
tick 2: B:S -> SUCCESS
SuccessOnOne, A succeeds while B runs:
tick 1: A:S B:R B:halted -> SUCCESS
SuccessOnOne, A succeeds and B fails in the same tick:
tick 1: A:S B:F -> FAILURE
SuccessOnAll, A fails first: B is still ticked in that tick, then halted:
tick 1: A:F B:R B:halted -> FAILURE
SuccessOnSelected([A]):
tick 1: A:S B:R B:halted -> SUCCESS
empty Sequence -> SUCCESS
empty Selector -> FAILURE
empty Parallel -> SUCCESS
3.3 Status-mapping decorators¶
Sources: decorators.py L660-L869. None of these decorators has parameters, except Condition, whose status argument is stored as succeed_status (L823), and StatusToBlackboard, which stores variable_name. A decorator that returns RUNNING for a completed child makes the child start over on the next tick, which is a loop.
# v04_status_maps.py
"""One tick of each status-mapping decorator over a child that returns S, F or R."""
import py_trees.decorators as d
from probe import LOG, F, R, S, Probe
from py_trees.common import Status
cases = {
"Inverter": lambda c: d.Inverter("x", c),
"SuccessIsFailure": lambda c: d.SuccessIsFailure("x", c),
"FailureIsSuccess": lambda c: d.FailureIsSuccess("x", c),
"SuccessIsRunning": lambda c: d.SuccessIsRunning("x", c),
"FailureIsRunning": lambda c: d.FailureIsRunning("x", c),
"RunningIsFailure": lambda c: d.RunningIsFailure("x", c),
"RunningIsSuccess": lambda c: d.RunningIsSuccess("x", c),
"Condition(SUCCESS)": lambda c: d.Condition("x", c, status=Status.SUCCESS),
"Condition(FAILURE)": lambda c: d.Condition("x", c, status=Status.FAILURE),
"Condition(RUNNING)": lambda c: d.Condition("x", c, status=Status.RUNNING),
"PassThrough": lambda c: d.PassThrough("x", c),
"Count": lambda c: d.Count("x", c),
"StatusToBlackboard": lambda c: d.StatusToBlackboard("x", c, variable_name="st"),
}
print(f"{'decorator':<20} child S child F child R")
for label, make in cases.items():
cells = []
for status in (S, F, R):
LOG.clear()
node = make(Probe("c", status))
node.tick_once()
halted = " (c halted)" if "c:halted" in LOG else ""
cells.append(f"{node.status.name[0]}{halted}")
print(f"{label:<20} " + " ".join(f"{c:<7}" for c in cells))
decorator child S child F child R
Inverter F S R
SuccessIsFailure F F R
FailureIsSuccess S S R
SuccessIsRunning R F R
FailureIsRunning S R R
RunningIsFailure S F F (c halted)
RunningIsSuccess S F S (c halted)
Condition(SUCCESS) S R R
Condition(FAILURE) R S R
Condition(RUNNING) R R S (c halted)
PassThrough S F R
Count S F R
StatusToBlackboard S F R
Reading the table as walk rules. An R in the S or F column is a loop back to entry(c), and an S or F in the R column is an abort edge from every action in c that can be RUNNING:
Inverter(c) = compile(c, F, S)
SuccessIsFailure(c) = compile(c, F, F) # FORCE_FAILURE
FailureIsSuccess(c) = compile(c, S, S) # FORCE_SUCCESS
SuccessIsRunning(c) = e where e = compile(c, e, F) # KEEP_RUNNING_UNTIL_FAILURE
FailureIsRunning(c) = e where e = compile(c, S, e) # RETRY, unbounded
Condition[SUCCESS](c) = e where e = compile(c, S, e) # identical to FailureIsRunning
Condition[FAILURE](c) = e where e = compile(c, e, S) # STATUS_MAP
Condition[RUNNING](c) = e where e = compile(c, e, e), RUNNING -> S
RunningIsFailure(c) = compile(c, S, F), RUNNING -> F # STATUS_MAP
RunningIsSuccess(c) = compile(c, S, F), RUNNING -> S # STATUS_MAP
PassThrough(c) = Count(c) = StatusToBlackboard(c) = compile(c, S, F)
3.4 Loops: Retry, Repeat, SuccessIsRunning¶
Sources: Repeat (decorators.py L178-L225) and Retry (L228-L273). Both reset their counter in initialise(), so it lives for one activation. Unlike BT.CPP, they tick the child again on the next tick, returning RUNNING in between. The edges are the same.
Retry(name, child, num_failures): a child FAILURE incrementsfailures. Iffailures < num_failuresthe decorator returns RUNNING, else FAILURE. A child SUCCESS is SUCCESS. Sonum_failurescounts attempts, like BT.CPP'snum_attempts. Any value ≤ 1, including-1, fails on the first failure. There is no "retry forever" value. UseFailureIsRunningfor that.Repeat(name, child, num_success): a child SUCCESS incrementssuccess. Ifsuccess == num_successthe decorator returns SUCCESS, else RUNNING. A child FAILURE is FAILURE at once. The test is==, so anynum_success ≤ 0repeats forever, not only the documented-1.
# v05_loops.py
from probe import F, R, S, Probe, run
from py_trees.decorators import Repeat, Retry, SuccessIsRunning
print("Retry(num_failures=3) over F, F, F:")
run(Retry("retry", Probe("A", F, F, F), num_failures=3), 3)
print("Retry(num_failures=3) over F, S:")
run(Retry("retry", Probe("A", F, S), num_failures=3), 2)
for n in (1, 0, -1):
print(f"Retry(num_failures={n}) over F:")
run(Retry("retry", Probe("A", F), num_failures=n), 1)
print("Repeat(num_success=3) over S:")
run(Repeat("repeat", Probe("A", S), num_success=3), 3)
print("Repeat(num_success=3) over S, F:")
run(Repeat("repeat", Probe("A", S, F), num_success=3), 2)
for n in (-1, 0):
print(f"Repeat(num_success={n}) over S:")
run(Repeat("repeat", Probe("A", S), num_success=n), 4)
print("SuccessIsRunning over S, S, F (the child is re-run every tick):")
run(SuccessIsRunning("sir", Probe("A", S, S, F)), 3)
Retry(num_failures=3) over F, F, F:
tick 1: A:F -> RUNNING
tick 2: A:F -> RUNNING
tick 3: A:F -> FAILURE
Retry(num_failures=3) over F, S:
tick 1: A:F -> RUNNING
tick 2: A:S -> SUCCESS
Retry(num_failures=1) over F:
tick 1: A:F -> FAILURE
Retry(num_failures=0) over F:
tick 1: A:F -> FAILURE
Retry(num_failures=-1) over F:
tick 1: A:F -> FAILURE
Repeat(num_success=3) over S:
tick 1: A:S -> RUNNING
tick 2: A:S -> RUNNING
tick 3: A:S -> SUCCESS
Repeat(num_success=3) over S, F:
tick 1: A:S -> RUNNING
tick 2: A:F -> FAILURE
Repeat(num_success=-1) over S:
tick 1: A:S -> RUNNING
tick 2: A:S -> RUNNING
tick 3: A:S -> RUNNING
tick 4: A:S -> RUNNING
Repeat(num_success=0) over S:
tick 1: A:S -> RUNNING
tick 2: A:S -> RUNNING
tick 3: A:S -> RUNNING
tick 4: A:S -> RUNNING
SuccessIsRunning over S, S, F (the child is re-run every tick):
tick 1: A:S -> RUNNING
tick 2: A:S -> RUNNING
tick 3: A:F -> FAILURE
CPS rules (Phase 2, with the loop edges; Phase 1 is transparent plus a note):
Retry[N](c) = e where e = compile(c, S, RETRY), RETRY = branch[k < N] -> e | F (N <= 1: compile(c, S, F), exact)
Repeat[N](c) = e where e = compile(c, LOOP, F), LOOP = branch[k < N] -> e | S (N == 1: exact; N <= 0: LOOP = e)
3.5 Stateful decorators: Timeout, OneShot, EternalGuard, ForEach¶
Timeout(name, child, duration=5.0)(L444-L496). The deadline is set ininitialise()withtime.monotonic(). Each tick, the child is ticked first. If it is still RUNNING after the deadline, it is halted and the decorator returns FAILURE. Otherwise the decorator returns the child's status. This is the same as BT.CPPTimeout.OneShot(name, child, policy)(L584-L657), withpolicyfromcommon.OneShotPolicy(common.py L146-L156). The decorator is transparent until the child completes with a status inpolicy.value.ON_SUCCESSFUL_COMPLETIONis[SUCCESS], so failures are retried on the next activation.ON_COMPLETIONis[SUCCESS, FAILURE]. After that, the stored status is infinal_status, and the decorator returns it without ticking the child, for the rest of the process. This is BT.CPP v4'sRunOncewiththen_skip="false".EternalGuard(name, child, condition, blackboard_keys=None)(L313-L441). Before every tick,condition()is called. It may return aboolor aStatus, and FAILURE counts as false. If the condition is false, the decorator stops with FAILURE and halts a RUNNING child. If it is true, the decorator ticks the child and returns the child's status. If the callable has a parameter namedblackboard, the decorator storesfunctools.partial(condition, self.blackboard)in.condition. So the user's function isguard.condition.funcin that case, andguard.conditionotherwise. The docstring (L377-L380) callsSequence(memory=False)with the check first the "alternative means of implementing the eternal guard". That is exactly the desugaring proposed in §1.2:ReactiveSequence[guard, child].ForEach(name, child, source_key, target_key)(L872-L936, since 2.4.0). Oninitialise(), the decorator reads the iterable atsource_keyand writes the first item totarget_key. A child SUCCESS moves to the next item (RUNNING), or returns SUCCESS after the last one. A child FAILURE is FAILURE. BecauseDecorator.tickticks the child beforeupdate(), the child runs once even when the list is empty, and its result is then ignored. An item equal toNonealso ends the loop, becauseNoneis the "exhausted" marker.
# v06_stateful.py
import time
import py_trees
from probe import LOG, F, R, S, Probe, run
from py_trees.common import OneShotPolicy
from py_trees.decorators import EternalGuard, ForEach, OneShot, Timeout
print("Timeout(duration=0.05) over a RUNNING child, ticked at t=0 and t=0.06 s:")
node = Timeout("timeout", Probe("A", R), duration=0.05)
for i in (1, 2):
LOG.clear()
node.tick_once()
print(
f" tick {i}: {' '.join(LOG):<28} -> {node.status.name} ({node.feedback_message.split(' [')[0]})"
)
time.sleep(0.06)
for policy in (OneShotPolicy.ON_SUCCESSFUL_COMPLETION, OneShotPolicy.ON_COMPLETION):
print(f"OneShot(policy={policy.name}) over F, S, F:")
run(OneShot("once", Probe("A", F, S, F), policy=policy), 3)
flags = [True, False]
print("EternalGuard: condition holds on tick 1, not on tick 2; the child is RUNNING:")
run(EternalGuard("guard", Probe("A", R), condition=lambda: flags.pop(0)), 2)
bb = py_trees.blackboard.Client(name="seed")
bb.register_key("items", access=py_trees.common.Access.WRITE)
for items in ([1, 2], []):
bb.items = items
print(f"ForEach over items={items}, child succeeds:")
run(ForEach("each", Probe("A", S), source_key="items", target_key="item"), 2)
Timeout(duration=0.05) over a RUNNING child, ticked at t=0 and t=0.06 s:
tick 1: A:R -> RUNNING (time still ticking ...)
tick 2: A:R A:halted -> FAILURE (timed out)
OneShot(policy=ON_SUCCESSFUL_COMPLETION) over F, S, F:
tick 1: A:F -> FAILURE
tick 2: A:S -> SUCCESS
tick 3: (no leaf ticked) -> SUCCESS
OneShot(policy=ON_COMPLETION) over F, S, F:
tick 1: A:F -> FAILURE
tick 2: (no leaf ticked) -> FAILURE
tick 3: (no leaf ticked) -> FAILURE
EternalGuard: condition holds on tick 1, not on tick 2; the child is RUNNING:
tick 1: A:R -> RUNNING
tick 2: A:halted -> FAILURE
ForEach over items=[1, 2], child succeeds:
tick 1: A:S -> RUNNING
tick 2: A:S -> SUCCESS
ForEach over items=[], child succeeds:
tick 1: A:S -> SUCCESS
tick 2: A:S -> SUCCESS
3.6 Behaviours¶
Sources: behaviours.py and timers.py L25-L87. Success, Failure, Running and Dummy are classes created at import time by meta.create_behaviour_from_function (behaviours.py L85-L100, meta.py L34-L74). Their default name is the class name.
| Class | Constructor | Attributes to read | Returns | Class for Beehave |
|---|---|---|---|---|
Success / Failure |
(name="Success") |
none | always SUCCESS / FAILURE | constant |
Running / Dummy |
(name="Running") |
none | always RUNNING | action, never finishes |
Periodic |
(name, n) |
period |
RUNNING, SUCCESS, FAILURE in turn, n ticks each; not reset by initialise() |
action (stub) |
StatusQueue |
(name, queue, eventually) |
queue, eventually |
pops the queue, then eventually (or cycles if None) |
action (stub) |
SuccessEveryN |
(name, n) |
every_n |
SUCCESS on every n-th tick, FAILURE otherwise, never RUNNING | condition |
TickCounter |
(name, duration, completion_status) |
duration, completion_status |
RUNNING for duration ticks, then completion_status |
action (stub) |
ProbabilisticBehaviour |
(name, weights=None) |
_weights |
random S/F/R | action (stub) |
BlackboardToStatus |
(name, variable_name) |
variable_name |
the stored Status; raises if missing or not a Status |
condition (approx.) |
CheckBlackboardVariableExists |
(name, variable_name) |
variable_name |
SUCCESS if the variable exists, else FAILURE | condition |
WaitForBlackboardVariable |
(name, variable_name) |
variable_name |
SUCCESS if it exists, else RUNNING | action (wait) |
CheckBlackboardVariableValue |
(name, check) |
check (a ComparisonExpression) |
SUCCESS if the variable exists and the comparison holds, else FAILURE | condition |
WaitForBlackboardVariableValue |
(name, check) |
check |
SUCCESS if it holds, else RUNNING | action (wait) |
CheckBlackboardVariableValues |
(name, checks, operator, namespace=None) |
checks, operator |
functools.reduce(operator, results); FAILURE if a variable is missing |
condition |
CompareBlackboardVariables |
(name, var1_key, var2_key, operator) |
var1_key, var2_key, operator |
operator(v1, v2); FAILURE if a variable is missing |
condition |
SetBlackboardVariable |
(name, variable_name, variable_value, overwrite) |
variable_name, overwrite |
SUCCESS; FAILURE if overwrite=False and the variable exists; raises KeyError for a nested name whose parent key is missing |
action (bookkeeping) |
UnsetBlackboardVariable |
(name, key) |
key |
always SUCCESS | action (bookkeeping) |
timers.Timer |
(name="Timer", duration=5.0) |
duration |
RUNNING until duration seconds have passed (wall clock), then SUCCESS |
action (wait) |
"Condition" here means a side-effect-free check that returns SUCCESS or FAILURE and never RUNNING. CheckBlackboardVariableValues with a namespace writes its partial results, which is a side effect that later checks read (either_or, §3.8). The WaitFor… behaviours are not conditions: they never fail, they block. Drawing them as an action box ("waiting for battery_level < 20") is what an operator needs to see. Drawing them as a branch would invent a FAILURE edge.
3.7 Blackboard checks and readable guard labels¶
Source: ComparisonExpression (common.py L189-L230). It has three attributes:
variable: the blackboard name, possibly nested, for examplebattery.level.operator: a callable, usually from theoperatormodule.value_generator: always a callable. A constantvalueis wrapped aslambda: value. Since 2.4.0,valuemay also be the user's own callable.
To build a label like battery_level < 20 without running user code:
- Map the operator to a symbol:
lt <,le <=,eq ==,ne !=,ge >=,gt >. ForCheckBlackboardVariableValues,and_,or_andxorbecome words. Any other callable keeps its__name__, as inwithin(battery_level, 20). - Read the value from the closure when
value_generator.__qualname__isComparisonExpression.__init__.<locals>.<lambda>: it isvalue_generator.__closure__[0].cell_contents. Show strings withrepr,Statusmembers by name, and anything else withstr. If the value is the user's own callable, showthreshold()and do not call it. - Negated label: keep the default
not battery_level < 20. A missing variable also gives FAILURE, sobattery_level >= 20would be wrong. - Key: the expression itself. Two checks of the same expression in one tick agree, unless something writes the variable between them. That caveat is the same as for BT.CPP
BlackboardCheck.
Classification trap: WaitForBlackboardVariableValue is a subclass of CheckBlackboardVariableValue, and WaitForBlackboardVariable of CheckBlackboardVariableExists. isinstance would classify the waits as conditions. §4.3 gives a rule that does not fall into this.
Label choice: use the expression, not the behaviour name. Built-in checks are often named generically: every guard of pick_up_where_you_left_off is called Done?, and every option guard of either_or is called Enabled?. Keep the name available for a later "show names" option.
# v07_blackboard_checks.py
import functools
import operator
import py_trees
from py_trees.behaviours import (
CheckBlackboardVariableExists,
CheckBlackboardVariableValue,
CheckBlackboardVariableValues,
CompareBlackboardVariables,
WaitForBlackboardVariable,
WaitForBlackboardVariableValue,
)
from py_trees.common import Access, ComparisonExpression
check = CheckBlackboardVariableValue(
name="Battery Low?",
check=ComparisonExpression(variable="battery_level", value=20, operator=operator.lt),
)
expr = check.check
print("variable:", expr.variable)
print("operator:", expr.operator, "->", expr.operator.__name__)
print("value_generator:", expr.value_generator.__qualname__)
print("constant from the closure (not called):", expr.value_generator.__closure__[0].cell_contents)
writer = py_trees.blackboard.Client(name="writer")
writer.register_key("battery_level", access=Access.WRITE)
wait = WaitForBlackboardVariableValue(
name="Wait", check=ComparisonExpression("battery_level", 20, operator.lt)
)
for value in (None, 50, 15):
if value is not None:
writer.battery_level = value
check.tick_once()
wait.tick_once()
print(f"battery_level={value}: Check -> {check.status.name}, WaitFor -> {wait.status.name}")
print(
"WaitForBlackboardVariableValue is a CheckBlackboardVariableValue:",
isinstance(wait, CheckBlackboardVariableValue),
)
print(
"WaitForBlackboardVariable is a CheckBlackboardVariableExists:",
isinstance(WaitForBlackboardVariable("w", "x"), CheckBlackboardVariableExists),
)
values = CheckBlackboardVariableValues(
name="XOR",
checks=[
ComparisonExpression("joy1", "enabled", operator.eq),
ComparisonExpression("joy2", "enabled", operator.eq),
],
operator=operator.xor,
)
print(
"CheckBlackboardVariableValues:",
values.operator.__name__,
[(c.variable, c.operator.__name__) for c in values.checks],
)
compare = CompareBlackboardVariables("cmp", "speed", "limit", operator.le)
print("CompareBlackboardVariables:", compare.var1_key, compare.operator.__name__, compare.var2_key)
def threshold() -> float:
return 20.0
dynamic = ComparisonExpression("battery_level", threshold, operator.lt)
print("callable value:", dynamic.value_generator.__qualname__)
def low(blackboard) -> bool:
return blackboard.battery_low_warning
guard = py_trees.decorators.EternalGuard(
"Battery Low?",
py_trees.behaviours.Success(),
condition=low,
blackboard_keys={"battery_low_warning"},
)
print("EternalGuard condition:", type(guard.condition).__name__, guard.condition.func.__qualname__)
lam = py_trees.decorators.EternalGuard("g", py_trees.behaviours.Success(), condition=lambda: True)
print("EternalGuard lambda condition:", lam.condition.__qualname__)
variable: battery_level
operator: <built-in function lt> -> lt
value_generator: ComparisonExpression.__init__.<locals>.<lambda>
constant from the closure (not called): 20
battery_level=None: Check -> FAILURE, WaitFor -> RUNNING
battery_level=50: Check -> FAILURE, WaitFor -> RUNNING
battery_level=15: Check -> SUCCESS, WaitFor -> SUCCESS
WaitForBlackboardVariableValue is a CheckBlackboardVariableValue: True
WaitForBlackboardVariable is a CheckBlackboardVariableExists: True
CheckBlackboardVariableValues: xor [('joy1', 'eq'), ('joy2', 'eq')]
CompareBlackboardVariables: speed le limit
callable value: threshold
EternalGuard condition: partial low
EternalGuard lambda condition: <lambda>
For the synthetic EternalGuard condition, recommended values are: type = the callable's __module__ and __qualname__, plus @<line> for a lambda, because <lambda> names collide. Name (the label) = the guard's instance name, such as Battery Low? in tutorial two. Port blackboard_keys = the sorted keys.
3.8 Idioms (py_trees.idioms)¶
py_trees 2.6.0 has three idioms (idioms.py). Each is a function that builds a subtree out of plain composites and blackboard behaviours. The walk handles them without special cases, so recognising them is optional. It would only help to collapse them into one annotated box (Phase 2), and it would have to key on the tree shape plus the hard-coded names below.
| Idiom | Shape built (names are hard-coded) | What the static walk shows |
|---|---|---|
pick_up_where_you_left_off(name, tasks) (L25-L91) |
Sequence(name, memory=True) [ for each task: Selector("Do or Don't", memory=False) [ CheckBlackboardVariableValue("Done?", <task>_done == True), Sequence("Worker", memory=True) [ task, SetBlackboardVariable("Mark\n<task>_done") ] ], then for each task UnsetBlackboardVariable("Clear\n<task>_done") ] |
Exactly the intended "skip the tasks already done" guards (trial below). This is how py_trees gets BT.CPP SequenceStar-like resumption. |
either_or(conditions, subtrees, name="Either Or", namespace=None) (L94-L185) |
Sequence(name, memory=True) [ CheckBlackboardVariableValues("XOR", conditions, xor, namespace), Selector("Chooser", memory=False) [ for each: Sequence("Option k", memory=True) [ CheckBlackboardVariableValue("Enabled?", <namespace>/k == True), subtree ] ] ] |
Guards on the internal <namespace>/k variables that XOR writes. Correct, but the variables are internal to the idiom. |
oneshot(behaviour, name="Oneshot", variable_name="oneshot", policy=ON_SUCCESSFUL_COMPLETION) (L188-L259) |
Selector(name, memory=False) [ Sequence("Oneshot w/ Guard", memory=True) [ Inverter("Not Completed?", CheckBlackboardVariableExists("Completed?")), Sequence("OneShot") [ behaviour, SetBlackboardVariable("Mark Done\n[SUCCESS]") ], or, for ON_COMPLETION, that sequence under a Selector("Oneshot Handler") with a Bookkeeping branch ], CheckBlackboardVariableValue("Oneshot Result", oneshot == SUCCESS) ] |
One infeasible path: Calibrate --[failure and oneshot == SUCCESS]--> SUCCESS. The walk does not know that the earlier SetBlackboardVariable decides that check (§7). |
eternal_guard (removed in 2.2.0; present in 2.0.0 to 2.1.6) |
Parallel(SuccessOnAll(synchronise=False)) [ StatusToBlackboard(cond_i)…, Selector("Guarded Tasks") [ CheckBlackboardVariableValue("Abort on\n…", == FAILURE)…, subtree ] ] |
Only in trees written for py_trees < 2.2, which Beehave does not support. py_trees_ros_tutorials still mentions it in a docstring (two_battery_check.py L38). |
Node names built by the idioms contain newlines ("Mark\ntask_1_done"). The adapter should replace \n with a space before the name reaches a renderer.
Trial output. oneshot and pick_up_where_you_left_off were built over TickCounter tasks and walked with the prototype adapter of §6.5:
=== oneshot (ON_SUCCESSFUL_COMPLETION)
START --[oneshot is set and oneshot == SUCCESS]--> SUCCESS
START --[oneshot is set and not oneshot == SUCCESS]--> FAILURE
START --[not oneshot is set]--> Calibrate
Calibrate --[success]--> SUCCESS
Calibrate --[failure and oneshot == SUCCESS]--> SUCCESS
Calibrate --[failure and not oneshot == SUCCESS]--> FAILURE
=== pick_up_where_you_left_off
START --[task_a_done == True and task_b_done == True]--> SUCCESS
START --[task_a_done == True and not task_b_done == True]--> Task B
START --[not task_a_done == True]--> Task A
Task A --[success and task_b_done == True]--> SUCCESS
Task A --[success and not task_b_done == True]--> Task B
Task A --[failure]--> FAILURE
Task B --[success]--> SUCCESS
Task B --[failure]--> FAILURE
4. Walking a live tree¶
4.1 Entry points¶
py_trees.trees.BehaviourTree(root)stores the root in.root(trees.py L167-L176).py_trees_ros.trees.BehaviourTreeis a subclass. Construction does not tick or callsetup(). py_trees_ros creates its ROS node only insetup().- A root
Behaviour: any instance ofpy_trees.behaviour.Behaviour. Most factories return this (§5.1). - The adapter should accept both, unwrapping with
isinstance(obj, py_trees.trees.BehaviourTree). It should reject anything else with a clear error.
4.2 Children, names and identity¶
- Children:
node.childrenis the list for both composites and decorators. A decorator puts its child inchildren[0]and aliases it asdecorated(decorators.py L111-L114). Leaves have[]. Recurse in list order with a path tuple, as the walk already does. Do not useBehaviour.iterate(), which is post-order (behaviour.py L307-L330). - Names:
nameis a required argument ofBehaviour.__init__(L65), even though the docstring says it defaults to the class name. Composites and decorators always need one. Generated leaves default to their class name (Success,Running).Timerdefaults to"Timer". Names are not unique, and they can contain newlines. - Identity:
node.idis a randomuuid4, so it is not stable between runs and must not reach the output (snapshot tests). Key nodes by tree path.node.parentis set when a child is added. - Sharing:
add_childrefuses a child that already has a parent, butinsert_childandprepend_childdo not check (composites.py L292-L321). One instance can therefore appear twice, or form a cycle. The adapter must trackid(node)and fail cleanly. - Never call
setup(),tick(),tick_once(),ComparisonExpression.value_generator()for a user callable, or anEternalGuardcondition. All of them run user code, and the first can reach middleware.
4.3 Classifying a node robustly¶
The family comes from isinstance, checked in this order: py_trees.composites.Composite, then py_trees.decorators.Decorator (a direct subclass of Behaviour, not of Composite), then a leaf. A leaf that has children is a hand-made composite: report it.
The precise class needs more care. isinstance against leaf classes falls into the WaitFor…/Check… trap (§3.7). An exact type(node) is X lookup misses harmless user subclasses, such as class MySequence(Sequence) with only an __init__. The rule that works is to take the nearest class in the MRO that defines the tick logic:
def owner(cls: type) -> type:
"""The nearest class in the MRO that defines `tick` or `update`."""
return next(k for k in cls.__mro__ if "tick" in vars(k) or "update" in vars(k))
Look owner(type(node)) up in the table of §1. If it is a py_trees class, use its semantics. If it is a user class, use CUSTOM with the family's kind. Every one of the 40 built-in classes is its own owner, so the rule distinguishes them all (snippet below).
4.4 User behaviours: actions or conditions?¶
py_trees has no condition base class or flag. Its terminology only describes a guard as "a behaviour at the start of a sequence that checks for a particular condition (e.g. is battery low?)" (docs/terminology.rst L36-L39). Recommendation:
- Default every user leaf to action, as for BT.CPP.
- Let the existing config keys
conditions:andactions:name user classes, by__name__or bymodule.__qualname__.Node.typeis the class__name__. - Do not guess from names by default. py_trees users often end check names with
?(Battery Low?,Done?,Enabled?). That could become an opt-in heuristic later, but a?name can also sit on a composite or on a blocking behaviour. - Condition keys must tell instances apart. For
IsAt(name="At kitchen?", place="kitchen")andIsAt(name="At door?", place="door"), the type and ports are equal, so the key needs the instance name. Optionally, the adapter can expose simple public instance attributes, such asplace, and the keys registered by the node's blackboard clients (client.read/client.write) as ports:
# v11_blackboard_clients.py
import operator
import py_trees
from py_trees.common import Access, ComparisonExpression
class IsAt(py_trees.behaviour.Behaviour):
"""A user condition: is the robot at a named place?"""
def __init__(self, name: str, place: str) -> None:
super().__init__(name)
self.place = place
self.bb = self.attach_blackboard_client(namespace="robot")
self.bb.register_key("pose", access=Access.READ)
def update(self) -> py_trees.common.Status:
return py_trees.common.Status.SUCCESS
for node in (
IsAt("At kitchen?", "kitchen"),
py_trees.behaviours.CheckBlackboardVariableValue(
"Battery Low?", ComparisonExpression("battery.level", 20, operator.lt)
),
py_trees.behaviours.SetBlackboardVariable("Mark done", "task_done", True, overwrite=True),
):
for client in node.blackboards:
print(
f"{node.name!r}: read={sorted(client.read)} write={sorted(client.write)} "
f"exclusive={sorted(client.exclusive)} remappings={client.remappings}"
)
print(
"user instance attributes:", {k: v for k, v in vars(IsAt("x", "door")).items() if k == "place"}
)
'At kitchen?': read=['/robot/pose'] write=[] exclusive=[] remappings={'/robot/pose': '/robot/pose'}
'Battery Low?': read=['/battery'] write=[] exclusive=[] remappings={'/battery': '/battery'}
'Mark done': read=[] write=['/task_done'] exclusive=[] remappings={'/task_done': '/task_done'}
user instance attributes: {'place': 'door'}
Source locations: for a user class, inspect.getsourcefile(cls) and inspect.getsourcelines(cls)[1] give the file and line of the class definition. They raise OSError for generated classes such as Success, so wrap them. py_trees does not record where an instance was created. The factory's own location is a good Tree.location.
4.5 Verification of §4.1 to §4.3¶
# v08_walking.py
import inspect
import py_trees
from py_trees import behaviour, behaviours, composites, decorators
root = composites.Sequence("root", memory=True)
inv = decorators.Inverter("inv", behaviours.Failure())
root.add_children([inv, behaviours.Success()])
tree = py_trees.trees.BehaviourTree(root)
print("BehaviourTree(root).root is root:", tree.root is root)
print("decorator .children == [.decorated]:", inv.children == [inv.decorated])
print(
"default leaf names:",
[c.name for c in (behaviours.Success(), behaviours.Running(), behaviours.Dummy())],
)
try:
composites.Sequence(memory=True)
except TypeError as exc:
print("Sequence without a name:", exc)
print("ids are uuid4:", type(root.id).__name__, root.id.version)
print("post-order iterate():", [n.name for n in root.iterate()])
shared = behaviours.Success("shared")
a = composites.Sequence("a", memory=True, children=[shared])
try:
composites.Sequence("b", memory=True, children=[shared])
except RuntimeError as exc:
print("add_child twice:", exc)
b = composites.Sequence("b", memory=True)
b.insert_child(shared, 0)
print(
"insert_child does not check: shared in a and b:", shared in a.children and shared in b.children
)
def owner(cls: type) -> type:
"""The nearest class in the MRO that defines the tick logic (tick or update)."""
return next(k for k in cls.__mro__ if "tick" in vars(k) or "update" in vars(k))
public = [
obj
for module in (composites, decorators, behaviours)
for _, obj in inspect.getmembers(module, inspect.isclass)
if issubclass(obj, behaviour.Behaviour) and obj.__module__ == module.__name__
]
mismatch = [c.__qualname__ for c in public if owner(c) is not c]
print(f"{len(public)} built-in classes; owner(cls) is not cls for:", mismatch)
class GoTo(behaviour.Behaviour):
def update(self):
return py_trees.common.Status.SUCCESS
class MySequence(composites.Sequence):
def __init__(self, name):
super().__init__(name, memory=False)
class LowBattery(behaviours.CheckBlackboardVariableValue):
pass
for cls in (GoTo, MySequence, LowBattery):
print(f"owner({cls.__name__}) = {owner(cls).__module__}.{owner(cls).__qualname__}")
BehaviourTree(root).root is root: True
decorator .children == [.decorated]: True
default leaf names: ['Success', 'Running', 'Dummy']
Sequence without a name: Sequence.__init__() missing 1 required positional argument: 'name'
ids are uuid4: UUID 4
post-order iterate(): ['Failure', 'inv', 'Success', 'root']
add_child twice: behaviour 'shared' already has parent 'a'
insert_child does not check: shared in a and b: True
40 built-in classes; owner(cls) is not cls for: []
owner(GoTo) = __main__.GoTo
owner(MySequence) = py_trees.composites.Sequence
owner(LowBattery) = py_trees.behaviours.CheckBlackboardVariableValue
The 40 classes are the 4 in composites (including Composite), the 18 in decorators (including Decorator) and the 18 in behaviours. timers.Timer and ports.BehaviourWithPorts are the only other Behaviour subclasses in the package, apart from the demos.
5. How py_trees trees are shipped¶
5.1 Factory functions¶
In practice, a py_trees tree is the return value of a function. No file describes it. The convention is visible in three places:
- the demos, where each function is called
create_root()orcreate_tree(); - py_trees_ros_tutorials, where each module has
tutorial_create_root()and atutorial_main()that ticks the tree; py-trees-render, which takes a dotted path to such a function. The tutorials' own docstrings saypy-trees-render -b py_trees_ros_tutorials.two_battery_check.tutorial_create_root.
py_trees demos usable as test fixtures (no ROS needed). Each was imported and called in a fresh process, measuring output and blackboard state before and after:
Factory (module:function) |
Root | Nodes | Classes in the tree | Side effects of the call |
|---|---|---|---|---|
py_trees.demos.sequence:create_root |
Sequence "Sequence" |
4 | StatusQueue |
none |
py_trees.demos.selector:create_root |
Selector "Selector" (no memory) |
3 | StatusQueue, Running |
none |
py_trees.demos.eternal_guard:create_root |
Sequence "Eternal Guard" (no memory) |
6 | StatusQueue, Success, Running |
none |
py_trees.demos.pick_up_where_you_left_off:create_root |
Selector "Root" |
16 | RunningIsFailure, CheckBlackboardVariableValue, SetBlackboardVariable, UnsetBlackboardVariable, Periodic, StatusQueue |
registers 6 blackboard clients |
py_trees.demos.either_or:create_root |
Parallel "Root" |
23 | FailureIsRunning, SuccessEveryN, TickCounter, CheckBlackboardVariableValue(s), SetBlackboardVariable, Running |
registers 8 blackboard clients |
py_trees.demos.context_switching:create_root |
Parallel "Parallel" |
5 | StatusQueue, demo class ContextSwitch |
none |
py_trees.demos.blackboard:create_root |
Sequence "Blackboard Demo" |
5 | CheckBlackboardVariableValue, SetBlackboardVariable, demo classes BlackboardWriter, ParamsAndState |
registers 5 blackboard clients |
py_trees.demos.display_modes:create_root |
Sequence "root" |
9 | StatusQueue |
none |
py_trees.demos.logging:create_tree |
Selector "Logging" |
7 | Periodic, Success, SuccessEveryN |
none |
py_trees.demos.stewardship:create_tree |
Selector "Demo Tree" |
7 | Success, demo classes Finisher, PeriodicSuccess, SuccessEveryN |
registers 3 blackboard clients |
py_trees.demos.dot_graphs:create_tree (needs level=, one of all, fine_detail, detail, component, big_picture) |
Selector "Demo Dot Graphs all" |
13 | Running |
none |
Measured side effects: importing any of these modules prints nothing and changes no blackboard state. Calling a factory prints nothing, writes no blackboard values, adds no logging handlers and does not enable the activity stream. Some factories register blackboard clients in the process-global py_trees.blackboard.Blackboard.clients registry, as listed. Tests should therefore run each fixture in a fresh process, or clear Blackboard between tests (py_trees offers Blackboard.clear()).
The logging and stewardship trees have the same shape, but stewardship defines its own SuccessEveryN class. That makes them a ready-made test that user classes are classified by owner class and not by name.
Demos without a factory: action and lifecycle (one behaviour), blackboard_namespaces and blackboard_remappings (blackboard only), and ports.basic, ports.remapping, ports.nested_subtrees and ports.xml_tree. The ports demos build or parse their tree inside main() or a helper. The last two load nested_subtrees.xml and xml_tree.xml with the XML parser, which is useful for §5.4.
py_trees_ros_tutorials (tag 2.6.0, read but not run: they need rclpy and ROS message packages): py_trees_ros_tutorials.one_data_gathering:tutorial_create_root, two_battery_check, five_action_clients, six_context_switching, seven_docking_cancelling_failing and eight_dynamic_application_loading, all with :tutorial_create_root. They use Parallel(SuccessOnAll(synchronise=False)) roots, Selector(memory=False) priorities, EternalGuard, Running("Idle"), timers.Timer and py_trees_ros behaviours. Those behaviours (subscribers.ToBlackboard, EventToBlackboard, CheckData, WaitForData, action_clients.FromBlackboard, …) would be user classes to Beehave. A config preset for them is a natural follow-up, for example CheckData as a condition and ToBlackboard as bookkeeping.
5.2 Is there a file format to parse instead?¶
| Candidate | What it contains | Usable as Beehave input? |
|---|---|---|
py_trees.display.dot_tree / py-trees-render output (display.py L399-L497) |
Node shape by family (octagon for a selector, box for a sequence, parallelogram for a parallel, ellipse otherwise), the name, a memory symbol, the parallel policy name and, with --verbose, the qualified class name |
No. It has no decorator parameters, no comparison expressions, no EternalGuard condition and no OneShot policy, and it names nodes by their non-unique names. Rendering also needs a live tree. |
ascii_tree, unicode_tree, xhtml_tree |
Indented names with type symbols such as {-} and [o] |
No, for the same reasons. |
py_trees_ros snapshot stream (~/snapshots, py_trees_ros_interfaces/BehaviourTree messages) |
Per behaviour: name, class_name (module.Class), type (SEQUENCE, SELECTOR, PARALLEL, DECORATOR, BEHAVIOUR…), additional_detail (WithMemory, parallel policy), child ids, blackboard access, status, tip_id |
Not for the adapter: it has no decorator parameters and no expressions, and it needs a running ROS system. It is however exactly the stream the Phase 3 "live status" feature needs: the active tip and its status. |
| py_trees XML (2.5+, experimental) | A tree description that py_trees turns into a live tree (§5.4) | Indirectly, through py_trees' own parser. |
Recommendation: import the user's module and call a factory (module:function). This is how py_trees users and py-trees-render already work, and it is the only form that keeps every parameter the walk needs.
5.3 Importing user code: resolution and security¶
How comparable tools resolve user code, checked by running them:
py-trees-render(programs/render.py L161-L205) takespkg.module.functionorpkg.module.Class.method, plus--kwargsas JSON, and callsimportlib.import_module. It does not put the working directory onsys.path. Run aspy-trees-render mission.create_rootnext tomission.py, it fails withModuleNotFoundError: No module named 'mission', then crashes with aValueErrorin its "maybe it's a class" fallback. WithPYTHONPATH=.it works.- uvicorn takes
module:attr.--app-dir"Defaults to the current working directory", which is added to the path.--factorytreatsattras a zero-argument factory. - pytest imports test files with
--import-mode=prependby default: it puts each file's directory first onsys.path. - The standard library has
pkgutil.resolve_name(Python ≥ 3.9). It resolves bothpkg.mod:attrandpkg.mod.attr, which was checked onpy_trees.demos.sequence:create_root.
Security. Importing a module runs arbitrary code with the user's rights, and so does calling the factory. This changes Beehave's threat model. The BT.CPP path never runs code: ADR 0005 notes that Beehave "reads files that may come from anywhere", and the XML reader refuses DOCTYPE. The py_trees path has the same trust model as pytest or python -c "import mission". Therefore:
- It must be an explicit opt-in, through a dedicated CLI flag or API call. It must never be triggered by detecting a file's contents, and never named in
beehave.yaml: runningbeehave graphin an untrusted checkout must not execute code from that checkout. - The docs must say "this imports and runs your module; only point it at code you would run yourself". CI jobs that run it on pull requests from forks need the same care as running their tests.
- Beehave must run in the environment of the tree: the ROS workspace sourced, and the project's virtualenv active. The factory imports the project's dependencies (
rclpy, message packages…), and they must be importable.
5.4 The py_trees XML dialect¶
py_trees 2.5.0 added an experimental parser, py_trees.parsers.behaviour_tree_xml.parse_behaviour_tree_xml(xml_file, main_tree_id=None, node_registry="auto", …) (L295). It builds a live tree, so the adapter covers it with no extra work: import the module that defines the node classes (that registers them), parse, then adapt. Verified on the ports.xml_tree demo:
# v12_xml_route.py
import pathlib
import py_trees
import py_trees.demos.ports.xml_tree as demo # importing registers its PortsMixin classes
from py_trees.parsers.behaviour_tree_xml import parse_behaviour_tree_xml
xml = pathlib.Path(demo.__file__).with_name("xml_tree.xml")
root = parse_behaviour_tree_xml(str(xml))
print(py_trees.display.ascii_tree(root), end="")
for node in root.iterate():
if isinstance(node, py_trees.ports.PortsMixin):
ports = {
p: node._get_blackboard_key(p) for p in (*node.input_ports(), *node.output_ports())
}
print(f"{node.name}: {type(node).__name__} {ports}")
print(
"memory of the parsed Sequences:",
[n.memory for n in root.iterate() if isinstance(n, py_trees.composites.Sequence)],
)
{-} MainSeq
{-} MainSeq.Composer1.ComposeSeq
--> MainSeq.Composer1.ComposeSeq.producer
--> MainSeq.Composer1.ComposeSeq.suffixer
--> MainSeq.consumer
MainSeq.Composer1.ComposeSeq.producer: GreetingProducer {'output': '/Composer1/greeting'}
MainSeq.Composer1.ComposeSeq.suffixer: AddSuffix {'input': '/Composer1/greeting', 'suffix': '/Composer1/MainSeq_Composer1_ComposeSeq_suffixer_5528f26a-7bb7-4d4b-8e46-a5246508b538/suffix__const', 'output': '/final_message'}
MainSeq.consumer: PrintConsumer {'input': '/final_message'}
memory of the parsed Sequences: [True, True]
_get_blackboard_key is private, and constants are stored under keys that contain a random UUID. If ports are exposed, show the constant value instead.
Detection hazard. A py_trees XML file looks like BT.CPP v3 XML: <root main_tree_to_execute="…">, <BehaviorTree ID>, <Sequence>, <SubTree>, and no BTCPP_format. Its meaning differs:
- Its
<Sequence>,<Selector>and<Fallback>takememory="true|false", defaulttrue(L836). <Parallel policy=…>defaults tosuccess_on_one(L843).- Decorators are lower-cased py_trees class names (
<retry num_failures="3">, L135-L141). <SubTree>uses v4-style{key}remapping.
Beehave's v3 parser would either reject such a file (unknown attributes) or misread it. The format detector should recognise memory= on control nodes, or policy= on Parallel, and say "this looks like py_trees XML; load it with --py-trees".
6. Recommended adapter API and CLI¶
6.1 Where the code lives¶
Put the adapter in src/beehave/parsers/pytrees.py. The file name is deliberately not py_trees.py, so nobody confuses it with the real package. In line with ADR 0002, it is a parser that produces a Document. The module must not import py_trees at import time:
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING: # py_trees ships py.typed
import py_trees
def from_py_trees(
tree: py_trees.behaviour.Behaviour | py_trees.trees.BehaviourTree,
*,
config: Config | None = None,
) -> Document:
py_trees = (
_require_py_trees()
) # imports lazily; raises UnsupportedFormatError if missing or < 2.2
...
beehave/__init__.py can then export from_py_trees without making py_trees a dependency. The error message should name the fix: "the py_trees adapter needs py_trees >= 2.2: pip install 'beehave-bt[py-trees]'". Read the version from py_trees.version.__version__, which exists in every release and does not depend on how py_trees was installed.
6.2 Python API¶
import beehave
doc = beehave.from_py_trees(root) # Behaviour or BehaviourTree -> Document(format="py_trees")
result = beehave.analyze_py_trees(root) # -> Analysis, like analyze() for XML files
print(beehave.to_mermaid(result.graph))
from_py_trees(tree, *, config=None) -> Document. The document holds oneTree, whoseidis the root's name with newlines replaced, asmain_tree. The adapter's diagnostics (approximated leaves, shared nodes, a leaf with children) go inDocument.diagnostics, as the BT.CPP parser's do.analyze_py_trees(tree, *, config=None, max_paths=DEFAULT_MAX_PATHS) -> Analysis. Implement it by factoring the body ofapi.analyzeinto a private_analyze(document, tree_id, max_paths), which both functions use.- A helper for the CLI and for tests:
load_py_trees(spec: str, **kwargs) -> Behaviourresolves a factory and calls it (§6.3). Keep it separate fromfrom_py_trees, so that importing user code always happens on purpose. - Accept a
BehaviourTree, including py_trees_ros's, by unwrapping.root. Accept aBehaviouras the root. Reject anything else with aBeehaveError.
6.3 CLI¶
beehave graph --py-trees my_robot.trees:create_root -f mermaid
beehave graph --py-trees trees/mission.py:create_root
beehave graph --py-trees py_trees.demos.dot_graphs:create_tree --kwargs '{"level": "all"}'
beehave stats --py-trees my_robot.trees:create_root --json
--py-trees SPECreplaces the positionalFILE…. The two are mutually exclusive, and-t/--treedoes not apply.SPECismodule.path:attrorpath/to/file.py:attr. For the dotted path, put the working directory first onsys.path(likepython -mand uvicorn's--app-dir), then usepkgutil.resolve_name. This also accepts py-trees-render'smodule.path.functionform, so commands in tutorial docstrings can be pasted. For a.pypath, load it withimportlib.util.spec_from_file_location, with its directory first onsys.path(pytest'sprependmode), so that sibling imports work.attrmay be aBehaviourorBehaviourTreeobject, used as is, or a callable, which is called with--kwargs(a JSON object, as in py-trees-render). Anything else is an error.- Errors from the import or the call are reported as
beehave: error: calling my_robot.trees:create_root raised ValueError: …, with exit code 1, like otherBeehaveErrors. beehave trees --py-trees SPECprints the root's name.
6.4 Packaging, tests and typing¶
- Add an optional extra:
[project.optional-dependencies] py-trees = ["py_trees>=2.2"], installed withpip install 'beehave-bt[py-trees]'. It pulls inpydotandpyparsing. It is consistent with ADR 0005, which allows optional dependencies behind an extra. - ROS caveat: under ROS, py_trees comes from the distro (
/opt/ros/<distro>/…). Installing the extra would add a second copy from PyPI, and which copy wins depends onsys.pathorder. ROS users shouldpip install beehave-btwithout the extra and source their workspace. The adapter uses whatever py_trees is importable. - Add
py_trees>=2.2to thetestandlintdependency groups. Thenmypy --strictsees its types (it shipspy.typed), and coverage, which must stay at 95 % or more, includes the adapter. Tests can usepytest.importorskip("py_trees"), so that a bare install still passes. CI should cover the oldest supported version (2.2.3, the long-time Humble release) and the newest (2.6.0). - Fixtures: the demo factories of §5.1, plus small trees built in the tests. Expected output must not depend on
uuid4values, and the global blackboard client registry must be cleared between tests.
6.5 Trial run¶
A throwaway prototype of the §1 mapping was run against every demo factory and the existing flatten, build_graph and to_text, imported from src/. It was not committed. It used only today's Semantics members, emulating the proposed ones: PASS_THROUGH as DELAY, BLACKBOARD_CONDITION as a CUSTOM condition named after its expression, and STATUS_MAP, RUN_ONCE, ALWAYS_RUNNING and SLEEP as transparent nodes or CUSTOM actions plus an adapter diagnostic. Every demo converted and walked. The pick_up_where_you_left_off demo gives the same guards as the idiom trial in §3.8, with one approximation diagnostic for its RunningIsFailure and three for its Selector(memory=False) nodes. The eternal guard demo:
=== py_trees.demos.eternal_guard:create_root
START --> Condition 1
Condition 1 --[success]--> Condition 2
Condition 1 --[failure]--> FAILURE
Condition 2 --[success]--> Worker 2
Condition 2 --[failure]--> FAILURE
Worker 2 --[success]--> SUCCESS
Worker 2 --[failure]--> FAILURE
! warning: Running: never finishes; its SUCCESS and FAILURE edges are unreachable (proposed ALWAYS_RUNNING) [approximated]
! warning: Sequence: walked like a Sequence; its conditions are re-checked every tick, but preemption edges are not shown yet [approximated]
What the trial shows:
- In
eternal_guard, "Condition 1/2" areStatusQueuestand-ins, so they are walked as actions. In a real tree they would be conditions, named in the config. "Worker 1" isSuccess, a constant, so it draws no box. "Worker 2" isRunning: both of its outgoing edges are drawn, but neither can ever be taken. The proposedALWAYS_RUNNINGmember removes them. - In
either_or,FailureIsRunning(SuccessEveryN)means "wait until the joystick fires". Walked asRETRYover a condition, it draws a[not Joystick 1] -> FAILUREedge that cannot happen. ARETRYwith no bound whose child is a condition should become "wait until …" in Phase 2. - The message
Sequence: walked like a Sequence; …reads oddly. For py_trees, the diagnostic should name the configuration, as inSequence(memory=False): ….
7. Limits and open points¶
- Blackboard data flow is not tracked. py_trees idioms pass decisions through the blackboard (
oneshot,either_or,StatusToBlackboard/BlackboardToStatus), so a static walk shows some infeasible guard combinations (§3.8). This is a Phase 2 question for BT.CPP too (SetBlackboardfollowed by a check). BlackboardToStatushides control flow. Its own docstring warns that "the graph of the tree communicates the local consequences, but not the reflected consequences" (behaviours.py L300-L307). Report it.- Trees that change at run time.
BehaviourTree.insert_subtree,replace_subtreeandprune_subtree, and "dynamic application loading" (tutorial eight), change the tree while it runs. The adapter sees the tree as the factory returns it. - Not verified by running: the py_trees_ros and py_trees_ros_tutorials factories, which need
rclpyand ROS messages (read from source at tag 2.6.0 only); which py_trees version the Humble and Jazzy binary packages ship today (rosdistro lists2.6.0-1, but the timing of binary syncs was not checked); and py_trees on Python 3.14.
Sources¶
- py_trees 2.6.0: PyPI wheel
py_trees-2.6.0-py3-none-any.whl, identical to tag2.6.0(commit35dc6d3a7fb34dd7f830e7299b55a247faef3ada). Files cited:composites.py,decorators.py,behaviours.py,behaviour.py,common.py,meta.py,trees.py,idioms.py,timers.py,display.py,programs/render.py,parsers/behaviour_tree_xml.py,demos/,pyproject.toml,CHANGELOG.rst,docs/terminology.rst.develchecked at commit41ec377. The history of theeternal_guardidiom is from tags 2.0.0 to 2.2.0 and commita43e07f. - py_trees_ros tag 2.6.0 (
trees.py,conversions.py,subscribers.py), py_trees_ros_tutorials tag 2.6.0, and py_trees_ros_interfacesmsg/Behaviour.msg. - ROS 2 releases: rosdistro
humble/,jazzy/,kilted/androlling/distribution.yamlonmaster(read 2026-10-17), and the release tags ofros2-gbp/py_trees-releaseandros2-gbp/py_trees_ros-release. - Comparable tools:
pytest --help(pytest 9.1.1),uvicorn --help(uvicorn 0.54.0), and the Python standard library documentation forpkgutil.resolve_name. - The verification snippets in §3 to §5 were run with py_trees 2.6.0 on CPython 3.10.20 and 3.12.3, with identical output. The demo side-effect measurements in §5.1 and the trial in §6.5 used CPython 3.12.3.