Py Trees

[About] [What’s New?] [Documentation] [Getting Started] [Next Steps] [Releases] [Developers]

About

PyTrees is a python implementation of behaviour trees designed to facilitate the rapid development of medium sized decision making engines for use in fields like robotics. Brief feature list:

• Behaviours, Decorators, Sequences, Selectors, Parallels and BehaviourTree.
• Blackboards for data sharing.
• A useful library of behaviours, decorators and idioms.
• Serialise to a dot graph or render to ascii/unicode in a terminal.
• Tested on Linux and Mac (YMMV with Windows).

What’s New?

• [2023-01-28] The [2.2.x Release][new-2.2.x] is out! Sequences and Selectors with AND without memory.
• [2023-01-28] Get Started with py_trees in under 5mins.
• [2023-01-28] This is now a poetry project with configuration governed by pyproject.toml.
  • The vestigial setup.py is only to assist distribution where PEP-517 is not yet well supported.

Documentation

[![devel][docs-devel-image]][docs-devel] [![2.2.x][docs-2.2.x-image]][docs-2.2.x] [![2.1.x][docs-2.1.x-image]][docs-2.1.x] [![0.7.x][docs-0.7.x-image]][docs-0.7.x] [![0.6.x][docs-0.6.x-image]][docs-0.6.x]

Getting Started

You can get started on CodeSpaces (with no mismatched environment issues and in under 5mins) [1]:

1. Fork the project to your personal account
2. Click on Code -> Codespaces -> + Create a Codespace
3. Enter the Terminal

# Install Dependencies
(docker) zen@py_trees:/workspaces/py_trees$ poetry install

# Explore the demos
(docker) zen@py_trees:/workspaces/py_trees$ poetry shell
(py-trees-py3.8) (docker) zen@py_trees:/workspaces/py_trees$ py-trees-demo-<tab>-<tab>
py-trees-demo-action-behaviour            py-trees-demo-context-switching           py-trees-demo-logging
py-trees-demo-behaviour-lifecycle         py-trees-demo-display-modes               py-trees-demo-pick-up-where-you-left-off
py-trees-demo-blackboard                  py-trees-demo-dot-graphs                  py-trees-demo-selector
py-trees-demo-blackboard-namespaces       py-trees-demo-either-or                   py-trees-demo-sequence
py-trees-demo-blackboard-remappings       py-trees-demo-eternal-guard               py-trees-demo-tree-stewardship
(py-trees-py3.8) (docker) zen@py_trees:/workspaces/py_trees$ py-trees-demo-blackboard
...
(py-trees-py3.8) (docker) zen@py_trees:/workspaces/py_trees$ exit

# Hack some Code

# Run the Formatter, Tests, Linters and Mypy
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -l
py38 py310 format check mypy38 mypy310
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e format
...
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e py38
...
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e check
...

# Contribute a PR!
# https://github.com/splintered-reality/py_trees/blob/devel/CONTRIBUTING.md

[1] All of the above will, of course, work in a local environment if you have poetry installed. If you’re using VSCode you don’t even need that, just reopen the project in the devcontainer and be froody.

Next Steps

On PyPi:

• py_trees
• py_trees_js

Examples:

• ReadTheDocs - PyTrees ROS Tutorials - significantly more edifying than the demos, these incrementally walk through the process of building a decision making layer for a robot. These use ROS2 (sparsely), but merely browsing should be enlightening regardless.

Visualisation:

• py_trees_js - a javascript library for building your own runtime visualisation tool

Robotics:

• py_trees_ros - a tree manager and behaviours designed for use specifically with ROS2
• py_trees_ros_viewer - a Qt/ROS2 implementation of py_trees_js

Releases

• 2.2.x - Selectors, Sequences with and without memory. Improved testing and style/type checking.
• 2.1.x - Chooser deprecated. API housekeeping.
• 2.0.x - Blackboards V2!
• 1.2.x - Trees can now shutdown cleanly. StatusToBlackboard and EternalGuard, Visitors get finalise().
• 1.1.x - Fixes for setup, tick-tock, viz.
• 1.0.x - Behaviours, Decorators, Composites, Blackboards, Tree Management and Viz tools.
• 0.y.x - First open source pre-releases.

File truncated at 100 lines see the full file

Release Notes

Forthcoming

• ...

2.2.3 (2023-02-08)

• [decorators] a passthrough for debugging and visualisation, #407

2.2.2 (2023-01-28)

• [docs] 2.2.x release documentation, bugfix for graphviz on read-the-docs, #400

2.2.1 (2023-01-28)

• [tox] format with black, usort and fix flake8 warnings, #397
• [docs] sphinx 1.4 -> 5.3, #391

2.2.x (2023-01-23) - Sequences and Selectors with and without Memory!

Headline Feature

• [composites] sequences and selectors with and without memory (previously experimental in 2.1.6)

This can become confusing, so pay attention and let's define some terminology:

Without Memory - ticking starts with the **first** child
With Memory - ticking attempts to start with the **current** child

Whether the current child exists or not, the composite will always follow the logic above. The only bearing that the current child has on proceedings is in what happens next. Without memory, if the current child is reached, it will tick it without re-initialising it since it is already RUNNING (all other children are not RUNNING and subsequently will be re-initialised). With memory, if no current child is found on that first tick, it will fall back to starting with the first child.

Previously Selectors operated without memory and Sequences with memory. Now both composites support both paradigms. Not only does this bring a pleasing symmetry to the universe that his noodliness would approve of, but it does unlock several practical use cases that previously required rather complex idioms (combinations of behaviours / subtrees).

Refer to the Eternal Guard Demo for an example of a practically useful idiom with two Sequences, one with and the other without memory.

Other New Features

• [decorators] Repeat and Retry, #371
• [devenv] much improved development environment, comprehensive formatting, linting, type-checking and testing
  • [poetry] setuptools -> poetry, #389
  • [common] remove viral ramifications of Any from ComparisonExpression, #386
  • [tests] it's mypy now, by the time this ends, it'll be someone else's py , #380
  • [tests] use tox, flake8 in prem-merge #354
  • [tests] switch from deprecating nose to pytest, #350

Breaking API

• [behaviours, decorators] behaviours.Count -> behaviours.StatusQueue + decorators.Count (new), #376
• [behaviours] StatusSequence -> StatusQueue, #372
• [behaviours, decorators, composites] abstract base classes, #375
• [composites] use explicit composite arguments, #370

The latter is a theme adopted more liberally across (most) of the py_trees library. As this library has grown, it's become apparent that being explicit about passing arguments to constructors is more important than the convenience of eliminating a few characters. Not only does it prevent bugs, it eases refactoring and greatly improves readability of the code. In fact, you'll save time in the long run.

``` python

This:

parallel = py_trees.composite.Parallel(

File truncated at 100 lines see the full file