py_trees.ports module

Typed input/output ports for py_trees behaviours.

class py_trees.ports.BehaviourWithPorts(name: str, **kwargs: Any)

Bases: PortsMixin, Behaviour

Base class for behaviours with typed input and output ports (see PortsMixin).

Subclassing requirements:

  • Each subclass must implement the input_ports and output_ports class methods to specify its input and output ports.

  • Each subclass must implement the update() method to define its behaviour.

  • Other methods from py_trees.behaviour.Behaviour may be overridden as needed.

Example usage:

class ExampleBehaviour(BehaviourWithPorts):
    @classmethod
    def input_ports(cls):
        return {"input_data": PortInformation(data_type=str, required=True)}

    @classmethod
    def output_ports(cls):
        return {"output_data": PortInformation(data_type=str, required=True)}

    def update(self):
        # Implementation of the behaviour
        ...

Status semantics for update():

  • Returning FAILURE indicates a technical error (e.g. service call failures, exceptions) that may potentially be handled by nodes such as Retry.

  • If not resolved, a FAILURE will cause the entire tree to fail.

  • Do not use FAILURE as an expected logical outcome, just so that nodes like Retry can handle those (e.g. when no objects are detected in an image — that is a valid result, not a failure). Instead, indicate such logical outcomes via node outputs (e.g. an empty list of detected objects).

update() → Status

Subclass-defined tick logic. Must return a Status.

exception py_trees.ports.NoDataAvailable

Bases: Exception

Exception raised when a required data has not (yet) been written to the port.

class py_trees.ports.PortInformation(data_type: Any, required: bool = True, description: str = '')

Bases: object

Static declaration for one typed input or output port.

data_type: Any
description: str = ''
required: bool = True
class py_trees.ports.PortsMixin(*args: Any, behaviour_class_name: str | None = None, **kwargs: Any)

Bases: ABC

Mixin class for enabling input and output ports on behaviour tree nodes.

This mixin provides the core infrastructure needed to wire, validate, and execute data-driven behaviour tree nodes in a modular and reusable way. It is designed to be used as a base class for behaviours, composites, and decorators in behaviour trees.

A class using PortsMixin must:

  1. Inherit from PortsMixin first, followed by a concrete py_trees class (e.g. py_trees.behaviour.Behaviour).

  2. Define its input and output ports as class-level information by implementing the @classmethod s input_ports and output_ports.

A PortsMixin represents a modular unit that interacts with input and output data through well-defined ports. These ports are typed and validated at runtime to ensure consistency and facilitate composability between different nodes.

Subclasses must define their input and output ports as class-level information by implementing the @classmethod s input_ports and output_ports.

  • input_ports(cls): returns a dictionary mapping input port names to port information.

  • output_ports(cls): returns a dictionary mapping output port names to port information.

These methods return the expected port definitions for the class and do not change at runtime. These port definitions are used to:

  1. Register blackboard keys for communication.

  2. Enforce type and presence validation at runtime.

  3. Provide clear contracts for each behaviour’s data dependencies and outputs.

Example usage:

class MyBehaviour(PortsMixin, py_trees.behaviour.Behaviour):
    @classmethod
    def input_ports(cls):
        return {"input": PortInformation(data_type=str, required=True)}

    @classmethod
    def output_ports(cls):
        return {"output": PortInformation(data_type=str, required=True)}

    def __init__(self, name: str):
        super().__init__(name=name)

    def update(self):
        input_val = self.get_input("input")
        self._set_output("output", f"Processed({input_val})")
        return py_trees.common.Status.SUCCESS

Port specification format in input_ports() and output_ports():

{
    "<port_name>": PortInformation(data_type=<expected_type>, required=<bool>),
}

Input and output port names must be unique across both sets; overlapping names are not allowed and will raise a ValueError at instantiation.

Subtrees

PortsMixin is designed to be used in complex behaviour trees that may consist of multiple subtrees. Each behaviour operates within a specified subtree_namespace, allowing multiple instances of the same behaviour to run in parallel without interfering with each other’s blackboard keys. The namespace ensures logical separation between behaviours and enables modular composition of behaviour trees.

Blackboard access

PortsMixin operates within a scoped subtree namespace to ensure its blackboard keys don’t clash when used in multiple subtrees. Always use the blackboard property, as it provides access to the correctly namespaced client. The class abstracts away direct blackboard access in favour of get_input() and _set_output() methods. Direct access to the blackboard is discouraged and only permitted through the blackboard property after setup_ports() has been called. However, be aware that the blackboard is shared with all other behaviours in the same subtree, so care must be taken to avoid key collisions.

Blackboard namespace strategy

When a port is not explicitly remapped (via XML or constructor arguments), a dedicated storage key is generated, so that sibling nodes with the same port name do not accidentally share data. This “synthesised” key is derived from:

  • the current subtree namespace,

  • the node’s name (sanitised to remove characters that py_trees treats as separators),

  • and the node’s UUID.

Behaviours can continue to share ports by wiring the same absolute key on purpose (e.g. /shared/output).

Port remapping

During setup, ports may be remapped to alternate blackboard keys using the port_remappings argument.

Port setup lifecycle

setup_ports() is a separate explicit call rather than part of Behaviour.setup() because port setup requires the full remapping table, which may require parsing the entire tree to compute. The remapping is the “wiring” of ports — connecting one node’s inputs to another node’s outputs — so it presupposes knowledge of the tree topology.

Output write semantics

Output ports are written internally by the node itself (typically inside update()). External callers should not write to output ports in production code; writing from outside is only expected in unit tests where the blackboard is seeded manually.

Composites / decorators scope

PortsMixin can be mixed into any Behaviour subclass — leaves, composites, and decorators. However, this migration does not ship ports-enabled composite or decorator implementations. Those can be contributed in separate follow-up PRs.

Example:

class ConsumerProducer(PortsMixin, py_trees.behaviour.Behaviour):
    @classmethod
    def input_ports(cls):
        return {"input": PortInformation(data_type=str, required=True)}

    @classmethod
    def output_ports(cls):
        return {"output": PortInformation(data_type=str, required=True)}

    def update(self):
        input_val = self.get_input("input")
        self._set_output("output", f"Processed({input_val})")
        return py_trees.common.Status.SUCCESS
property behaviour_class_name: str

Return the name under which this behavior class is registered.

This is typically the class name (e.g., “CheckGraspStatus”), but can also be an alias used for partial instantiations or custom registrations in a behavior registry.

Return:

str: The registered name of this behavior class.

property blackboard_client: Client

Return the scoped blackboard client.

Raises:

RuntimeError: If setup_ports() has not been called before accessing the blackboard.

get_input(port_name: str, default: Any = None) → Any

Read the value of the given input port from the blackboard.

Args:

port_name (str): The name of the input port to read from the blackboard. default (Any): Optional default value to return if the port has no input data. If set to None, no default is accepted.

Return:

Any: The value retrieved from the blackboard for the specified input port or the default.

Raises:

KeyError: If the input port name is not defined. TypeError: If the retrieved value does not match the expected type. NoDataAvailable: If no data is available on the input port and no default is given.

get_last_output(port_name: str) → Any

Return the last output which the node wrote at this port.

Args:

port_name (str): The name of the output port to read from the blackboard.

Return:

Any: The value retrieved from the blackboard for the specified output port.

Raises:

KeyError: If the input port name is not defined. TypeError: If the value does not match the expected type. NoDataAvailable: If no data has (yet) been written to the output port.

get_logger() → PortsLogger

Return the logger instance.

Raises:

RuntimeError: If setup_ports() has not been called before accessing the logger.

classmethod get_port_type(port_name: str) → type

Return the declared type for port_name.

Args:

port_name (str): The name of the input or output port.

Return:

type: The expected data type of the specified port.

Raises:

KeyError: If the port name is not defined in either input or output ports.

abstractmethod classmethod input_ports() → dict[str, PortInformation]

Return a mapping of input port names to port information.

classmethod is_port_required(port_name: str) → bool

Return whether the specified port is marked as required.

Args:

port_name (str): The name of the input or output port.

Return:

bool: True if the specified port is marked as required, False otherwise.

Raises:

KeyError: If the port name is not defined in either input or output ports.

log(level: LogLevel, msg: str, return_only: bool = False, print_name: bool = True) → str

Log a message at the specified severity level and update feedback.

log_debug(msg: str, return_only: bool = False, print_name: bool = True) → str

Log msg at DEBUG level (see log()).

log_error(msg: str, return_only: bool = False, print_name: bool = True) → str

Log msg at ERROR level (see log()).

log_info(msg: str, return_only: bool = False, print_name: bool = True) → str

Log msg at INFO level (see log()).

log_warning(msg: str, return_only: bool = False, print_name: bool = True) → str

Log msg at WARNING level (see log()).

abstractmethod classmethod output_ports() → dict[str, PortInformation]

Return a mapping of output port names to port information.

reset_all_output_ports() → None

Clear all output ports registered on this node.

Keeps the keys registered (READ/WRITE permissions unaffected), but removes the stored values. Intended for use-cases like “new data epoch” where downstream nodes should not read stale outputs.

This will have the effect that subsequent blackboard_client.exists(port_name) returns False again

Raises:

KeyError: if any port is unknown or not registered.

reset_port(port_name: str) → None

Clear the value stored for a (usually output) port.

Keeps the key registered (READ/WRITE permissions unaffected), but removes the stored value. Intended for use-cases like “new data epoch” where downstream nodes should not read stale outputs.

This will have the effect that subsequent blackboard_client.exists(port_name) returns False again

Raises:

KeyError: if the port is unknown or not registered.

setup_ports(port_remappings: dict | None = None, subtree_namespace: str = '/', logger: PortsLogger | None = None) → None

Initialize the ports and prepare the blackboard interface.

Registers all declared input and output ports with the blackboard client, optionally applying custom key remappings, and sets the namespace and logger.

This method must be called before using get_input(), _set_output(), or accessing the blackboard or logger properties.

Port remapping rules

  1. If a port is not in port_remappings, its blackboard key is automatically constructed as /{subtree_namespace}/{port_name}.

  2. If a remapped key starts with /, it is treated as an absolute/global key.

  3. If a remapped key does not start with /, it is treated as a key relative to the given namespace, i.e. /{subtree_namespace}/{remapped_key}.

General notes

  1. The underlying data store is currently the py_trees.blackboard, but this is abstracted.

  2. However, the API of PortsMixin abstracts from the concept of a blackboard, so the underlying implementation could change later.

  3. Think of a “data key” as a generic handle to some shared data storage (like a key in a map), which can be remapped to match external system requirements.

Arguments:

port_remappings (dict): Optional dictionary mapping port names to custom blackboard keys. subtree_namespace (str): Namespace to scope the blackboard client (default: "/"). logger: Optional logger-like object with debug()/info()/warning()/error() methods.

When None, falls back to self.logger (the native py_trees logger).

Raises:

KeyError: If a port in port_remappings is not declared in the port definitions.

This function must be called before using get_input, _set_output, or accessing the blackboard property.

property subtree_namespace: str

Return the namespace associated with the subtree, used to scope blackboard keys.

Raises:

RuntimeError: If setup_ports() has not been called before accessing the namespace.