0010. Read py_trees trees live, and import user code only on request¶
- Status: Accepted
- Date: 2026-10-17
Context¶
A py_trees tree has no file format that keeps what the walk needs. It is
built in Python, usually by a function such as create_root(); its dot
export drops decorator parameters and blackboard expressions, and the XML of
py_trees 2.5+ is experimental and only loads through py_trees itself. The
full reference is the py_trees research.
Getting the tree means importing the user's module and calling the function. That runs code. Until now Beehave only ever read files that may come from anywhere (ADR 0005).
Decision¶
- The adapter reads a live tree.
beehave.from_py_trees(root)turns aBehaviouror aBehaviourTreeinto the shared model (ADR 0002). It only reads attributes: it never callssetup(),tick(), anEternalGuardcondition or a callable comparison value. - Importing is a separate, explicit step.
beehave.load_py_trees(spec)andbeehave graph --py-trees module:functionimport and call a factory. Nothing else does: not a file's contents, notbeehave.yaml. Runningbeehavein an untrusted checkout never runs its code unless asked to. - Classes are matched by the class that owns their tick logic, the
nearest class in the MRO that defines
tickorupdate. This tellsWaitFor…apart from theCheck…class it subclasses, and keeps the semantics of a user subclass that only changes__init__. SequenceandSelectormap to the plain or reactive BT.CPP node by theirmemoryflag;EternalGuardbecomes a reactive sequence over its condition; blackboard checks become guards labelled by their expression.- User behaviours are actions unless the config lists their class, or a base
class, under
conditions. A condition's name is part of its identity, because it is often all that tells two instances of one class apart. - New model members:
PASS_THROUGH,STATUS_MAP,RUN_ONCE,ALWAYS_RUNNING,WAITandBLACKBOARD_CONDITION. - py_trees is an optional extra, imported lazily, supported from 2.2.
Consequences¶
- py_trees users get the same graph, renderers and stats as BT.CPP users. The
py_trees versions of our examples give the same graph as the XML ones,
except where py_trees has no equivalent node (no
IfThenElse). --py-treeshas the trust model ofpytest: only point it at code you would run yourself, and treat it like running tests in CI on pull requests.- py_trees XML is refused by the BT.CPP parsers with a pointer to
--py-trees, because it looks like BT.CPP v3 but means something else.