py_trees Documentation

PyTrees is organized into several specialized modules that allow you to build, manage, and visualize behaviour trees:

• py_trees: The main entry point.
• py_trees.behaviour: The core template from which all custom behaviours are derived.
• py_trees.behaviours: A library of pre-built, useful behaviours.
• py_trees.blackboard: Provides a shared data store for communication between behaviours.
• py_trees.composites: Contains behaviours that manage child nodes (e.g., Sequences, Selectors).
• py_trees.decorators: Provides 'hats' (wrappers) for behaviours to modify their execution logic.
• py_trees.idioms: Contains creators for common behaviour tree patterns.
• py_trees.meta: Provides factories for creating behaviours.
• py_trees.trees: Contains tree managers to handle tree execution and lifecycle.
• py_trees.display: Tools for visualizing trees via DOT graphs, strings, or stdout.
• py_trees.timers: Timer-related behaviours.
• py_trees.visitors: Entities that traverse the tree to inspect or modify behaviours during execution.
• py_trees.console: Utilities for console colour and syntax highlighting.
• py_trees.common: Common definitions, methods, and enumerations.
• py_trees.utilities: Assorted utility functions.

Ports provide a structured way to wire data exchange between nodes in a tree. Instead of nodes performing ad-hoc reads and writes to the blackboard, they declare explicit input and output ports.

Key Benefits:

• Explicit Data Contracts: A node's input_ports() and output_ports() declarations serve as its public data-flow API.
• Early Error Detection: Port values are type-checked at runtime (TypeError on mismatch). Missing required inputs raise py_trees.ports.NoDataAvailable instead of returning None.
• Subtree Isolation: Sibling subtrees can reuse the same port names internally because the subtree namespace scopes them on the blackboard to prevent collisions.
• Reusable Subtrees: Subtrees can be reconfigured from the outside by rewiring their port remappings without changing the internal Python code.
• Refactoring Safety: Changing a blackboard key only requires updating the remapping at setup time, rather than searching and replacing key names throughout your node code.

Note: The py_trees.ports module and the XML parser are experimental. Their API may change between releases.

The lifecycle of a behaviour is managed by the parent via the tick() method. The key methods and their responsibilities are:

• __init__: Instantiate the behaviour. Keep this minimal to allow for offline dot graph generation (e.g., in CI). Do not perform hardware connections, middleware connections, or start heavy threads here.
• setup(): Handles one-time initialisation of heavy resources required for execution (e.g., hardware connections, ROS publishers/subscribers).
• initialise(): Configures and resets the behaviour for (repeated) execution. Use this for resetting variables, starting timers, or establishing just-in-time middleware connections.
• update(): The core logic. It must return a py_trees.common.Status. Crucially, update() must never block. It should monitor progress and return RUNNING if the task is ongoing.
• terminate(): Called when the behaviour is finished or cancelled to perform cleanup.

The py_trees.ports framework provides the mechanism for typed input/output ports but does not ship concrete port-aware behaviours, decorators, or composites. To make an existing upstream class (like py_trees.decorators.Retry) port-aware, you must create an adapter class that combines PortsMixin with the upstream class.

Implementation Pattern:

1. Inheritance: Inherit from both PortsMixin and the upstream class.
2. Port Definition: Implement input_ports() and output_ports() class methods using PortInformation to define the schema.
3. Initialization: In __init__, call super().__init__ with safe default values.
4. Runtime Updates: In initialise(), use self.get_input("port_name") to read the current port value and apply it to the upstream class's attributes before calling super().initialise().
5. Namespace: To avoid naming collisions, place your ported class in a ports submodule that mirrors the upstream layout (e.g., yourproject.ports.decorators.Retry).

import py_trees
from py_trees.ports import PortInformation, PortsMixin

class Retry(PortsMixin, py_trees.decorators.Retry):
    """Retry that reads its failure budget from an input port."""

    @classmethod
    def input_ports(cls):
        return {"num_failures": PortInformation(data_type=int, required=True)}

    @classmethod
    def output_ports(cls):
        return {}

    def __init__(
        self, 
        name: str, 
        child: py_trees.behaviour.Behaviour, 
        **kwargs
    ):
        # Start with a safe default; it is overwritten on every initialise().
        super().__init__(
            name=name, child=child, num_failures=1, **kwargs
        )

    def initialise(self) -> None:
        # Read the port value at tick boundary and apply it before
        # the upstream Retry logic runs.
        self.num_failures = self.get_input("num_failures")
        super().initialise()

Behaviour trees are a decision-making engine used for purposeful planning with high reactivity. They are particularly suited for medium-scale decision engines (hundreds of behaviours) that do not require real-time, low-latency safety responses (latency of ~50-200ms is typically sufficient).

Key Features:

• Ticking: The ability to tick allows for work between executions without requiring multi-threading.
• Priority Handling: Natural mechanisms for higher-priority interruptions (often called reactivity).
• Simplicity: A small number of core components makes them easy for designers to use.
• Scalability: They avoid the combinatorial explosion seen in finite state machines as complexity increases.
• Dynamic: The tree graph can be changed on the fly between ticks or by parent behaviours.

Use Cases: Ideal for high-level scenario/application layers in robotics, such as navigation context switching, docking/undocking processes, and interaction logic (LEDs, sound), where low-latency reactive safety is handled by a separate control layer.

Attributes on an XML node tag serve two different purposes depending on whether they match a declared port:

1. Port Remappings: If an attribute name matches a key in input_ports() or output_ports(), it is treated as a port remapping. Values can be {curly_key} references (to wire ports) or literal constants (which are type-converted).
2. Constructor Keyword Arguments: If an attribute name does not match a declared port, it is passed as a keyword argument to the class __init__ method. Values are type-converted based on the constructor's type annotations. Note: {curly_key} references are NOT allowed for constructor arguments and will raise a ValueError.

Example Mapping

<Greeting name="hello_node" name_key="{target}" prefix="Howdy"/>

• name="hello_node": Sets the behaviour name.
• name_key="{target}": A port remap (matches input_ports).
• prefix="Howdy": A constructor kwarg (does not match any port; passed to __init__).