py_trees

2.4.0 verified Mon Apr 27 auth: no python

A pythonic implementation of behaviour trees for building hierarchical decision-making systems. Currently at version 2.4.0, with support for Python 3.9+ and ROS 2 Humble/Jazzy. Released roughly every 6-12 months.

pip install py-trees

Common errors

error ModuleNotFoundError: No module named 'py_trees' ↓

cause The package is installed with a hyphen: py-trees, not py_trees.

fix

pip install py-trees

error AttributeError: module 'py_trees' has no attribute 'Behaviour' ↓

cause Importing from the top-level instead of submodules.

fix

from py_trees.behaviour import Behaviour

error ValueError: The behaviour tree has not been initialised. Have you remembered to add the tree root to a BehaviourTree? ↓

cause You created a tree but forgot to wrap it in py_trees.trees.BehaviourTree(root).

fix

tree = py_trees.trees.BehaviourTree(root)

Warnings

breaking In v2.2.x, Sequence and Selector were renamed from Sequence and Selector (with memory) to Sequence and Selector (with memory). The old classes without memory are now Sequence and Selector with memory=False. Code using the old names will break. ↓

fix Use the new class names: from py_trees.composites import Sequence, Selector; instantiate with memory=True/False as needed.

deprecated The behaviour 'FailureEveryN' was removed. Use a custom behaviour that returns FAILURE instead. ↓

fix Replace with a custom behaviour that sets status to FAILURE periodically.

gotcha Behaviours may run indefinitely if they don't return SUCCESS or FAILURE. Always ensure your behaviour's update() method terminates. ↓

fix Return py_trees.common.Status.SUCCESS or FAILURE from update().

gotcha The 'parallel' policy FAIL_ON_ONE and SUCCEED_ON_ALL are confusing. FAIL_ON_ONE means the whole parallel fails if any child fails. SUCCEED_ON_ALL means it succeeds only when all succeed. ↓

fix Read the documentation carefully; choose policy = py_trees.common.ParallelPolicy.FailOnOne or SuccessOnAll.

Imports

Behaviour

wrong

from py_trees import Behaviour

correct

from py_trees.behaviour import Behaviour

Behaviour is in its own module, not top-level

Sequence

wrong

from py_trees import Sequence

correct

from py_trees.composites import Sequence

Composites are in py_trees.composites

Selector

wrong

from py_trees import Selector

correct

from py_trees.composites import Selector

Composites are in py_trees.composites

Parallel

wrong

from py_trees import Parallel

correct

from py_trees.composites import Parallel

Composites are in py_trees.composites

Running

wrong

from py_trees import Running

correct

from py_trees.common import Running

Status constants are in py_trees.common

create_tree

wrong

from py_trees import create_tree

correct

from py_trees.console import create_tree

Console utilities are in py_trees.console

Quickstart

Creates a simple sequence with two behaviours and ticks it.

import py_trees

# Create a simple sequence tree
root = py_trees.composites.Sequence(name="Root", memory=True)
move = py_trees.behaviours.SuccessEveryN(name="Move", n=5)
wait = py_trees.behaviours.Running(name="Wait")
root.add_children([move, wait])

# Create the tree
py_trees.trees.BehaviourTree(root)

# Tick the tree
for i in range(3):
    root.tick_once()
    print(f"Tick {i}: {root.status}")