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 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

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.

	Devel	2.2.x	2.1.x	2.0.x	1.2.x	0.7.x	0.6.x
Sources
Compatibility
CI			-	-	-	-	-
Documentation

Developers

Format, Check, MyPy, Test

Check against at least one of py38 / py310 [1].

# Auto-format your code (if using VSCode, install the ufmt extension)
$ poetry run tox -e format

# Style, Format
$ poetry run tox -e check

# Type-Check
$ poetry run mypy38

# Tests
$ poetry run tox -e py38

[1] CI will test against both python versions for you, but should you wish to do so locally, open up two VSCode windows, one with the project opened in the default py38 devcontainer and the other with the py310 devcontainer.

Generate Documentation

Generate the docs, view them from ./docs/html in a browser.

# Install dependencies
$ poetry install --with docs

# Build
$ poetry run make -C docs html

On Doc dependency changes, export the requirements for ReadTheDocs

$ poetry export -f requirements.txt --with docs -o docs/requirements.txt

Publish to PyPi

If you have permission to publish on pypi:

$ poetry config http-basic.pypi ${POETRY_HTTP_BASIC_PYPI_USERNAME} ${POETRY_HTTP_BASIC_PYPI_PASSWORD}
$ poetry publish

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.

# This:
parallel = py_trees.composite.Parallel(
    name="Parallel",
    policy=py_trees.common.ParallelPolicy.SuccessOnAll()
)

# Is better than:
parallel = py_trees.composite.Parallel()

When upgrading, if you don\'t regularly pass in arguments with keywords, i.e. you do Parallel("Foo") instead of Parallel(name="Foo"), be on the lookout for bugs created by the ordering having changed in the method signatures. Quite often the argument for name had a default and was at the end of the line. With these changes it has moved to the front of the line in order to adopt a consistent convention across the whole library.

Bugfixes

• [display] bugfix off-the-grid bb nodes and render exclusive write edges, #383
• [common] a practical inf, #366
• [composites] avoid redundant stop for non-running children #360
• [display] bugfix unicode use when no unicode for dot #359
• [composites] restart the sequence, but allow children to retain their state #368

2.1.6 (2021-05-31)

• [tests] mypy conformance, #327
• [composites] show ghost states for sequence children, #330 (reverts behaviour introduced in #325)

2.1.5 (2021-05-09)

• [composites] sequences w/o memory, #325
• [composites] selectors with memory, #324
• [display] unicode trees are unicode, not ascii #324

2.1.4 (2021-02-24)

• [behaviours] added BlackboardToStatus, #320
• [idioms] bugfix lost append in blackboard names for either_or, #319
• [docs] contributing guidelines added, #315

2.1.3 (2020-12-13)

• [blackboard] convenience [absolute_name()]{.title-ref} api for blackboard clients, #306

2.1.2 (2020-11-05)

• [sequences] bugfix current child setting whilst moving through children, #304

2.1.1 (2020-08-11)

• [behaviours] generators for variable values in SetBlackboardVariable, #300

2.1.0 (2020-07-20)

• [behaviours] CheckBlackboardVariableValue, WaitForBlackboardVariableValue use comparison expressins, #296
• [idioms] eternal_guard uses blackboard_names (previously blackboard_name_prefix), #295
• [composites] Chooser deprecated, #293
• [composites] chain-able add_children for all composites, #290

2.0.16 (2020-08-11)

• [behaviours] generators for variable values in SetBlackboardVariable, #300

2.0.15 (2020-05-14)

• [composites] fix current_child problems on dynamic child insertion/removal, #289

2.0.14 (2020-04-26)

• [blackboard] bugfix metadata not created on static set, #286

2.0.13 (2020-03-24)

• [composites] parallel bugfix to invalidate correctly, #285

2.0.12 (2020-03-10)

• [idioms] the either_or pattern, designed to replace the Chooser, #283
• [behaviours] TickCounter, a timer based on tree ticks, #283
• [behaviours] CheckBlackboardVariableValues, logical checks across multiple values, #283
• [common] ComparisonExpression, a more concise way of storing checkers, #283
• [composites] protect against adding a child to multiple parents, #281

2.0.11 (2020-03-01)

• [display] completely remove blackboard variables from the dot layout, #280

2.0.10 (2020-02-27)

• [trees] setup timeout error with last behaviour name included in the error message, #279
• [blackboard] rooted variables in namespaced clients working as designed, fixed docs, #277

2.0.9 (2020-02-14)

• [demos] display modes demonstrating usage of various options, #275
• [display] enforce left to right ordering of children in dot graphs

2.0.8 (2020-02-01)

• [display] bugfix and use elipsis on ascii visited only display modes, #273

2.0.7 (2020-01-24)

• [display] option for only visited behaviours in text tree snapshot displays, #272

2.0.5 (2019-12-25)

• [display] enum agnostic display for local and remote activity view displays

2.0.4 (2019-11-25)

• [display] optional show_title in unicode_blackboard_activity_stream

2.0.3 (2019-11-24)

• [trees] revert to using user signals if available to avoid shenanigans with SIGINT, #264
• [trees] play nicely, reset signal handlers after setup, #262
• [visitors] bugfix the snapshot visitor to look for exclusive write keys as well

2.0.1 (2019-11-19)

• [blackboard] static methods have a namespace too (root), use absolute names, #261
• [blackboard] do not register keys on the client when xclusive write aborts the process, #261

2.0.x (2019-11-15) - Blackboards v2!

The [2.0.x]{.title-ref} release wraps up the experimental blackboard improvements being rolled out in [1.3.x]{.title-ref} and [1.4.x]{.title-ref}. At this point, the changes to the blackboard framework are so extensive it makes sense to release it with a major version bump and to consider the [1.2.x]{.title-ref} release as the official goto release for the [1.x.y]{.title-ref} series.

New Features

• [blackboard] exclusive write access, #260
• [blackboard] key remappings, #259
• [blackboard] formalise namespaces with separators, #256
• [blackboard] distinguish primitives vs nested for refined read activity detection, #255

See the 1.3.x and 1.4.x changelog notes for additional details.

1.4.x (2019-11-07)

Breaking API

• [blackboard] fixed read/write ambiguity, now use py_trees.common.Access, #250

# Previously
self.blackboard.register_key(key="foo", write=True)
# Now
self.blackboard.register_key(key="foo", access=py_trees.common.Access.WRITE)

• [blackboard] drop SubBlackboard, it has problems, #249

New Features

• [blackboard] namespaced blackboard clients, #250

# Previously, a single blackboard client exists per behaviour
# Now, no blackboard client on construction, instead attach on demand:
self.blackboard = self.attach_blackboard_client(name="Foo")
self.parameters = self.attach_blackboard_client(
    name="FooParams",
    namespace="parameters_foo_"
)
self.state = self.attach_blackboard_client(
    name="FooState",
    namespace="state_foo_"
)
# create a local key 'speed' that maps to 'state_foo_speed' on the blackboard
self.state.register_key(key="speed", access=py_trees.common.Access.WRITE)
self.state.speed = 30.0

• [blackboard] required keys and batch verification method, #254

self.blackboard = self.attach_blackboard_client(name="Foo")
self.blackboard.register_key(name="foo", access=py_trees.common.Access.READ, required=True)
# ...
self.verify_required_keys_exist()  # KeyError if any required keys do not yet exist on the blackboard

• [visitors] SnapshotVisitor tracking blackboards on the visited path, #250

# Previously tangled in DisplaySnapshotVisitor:
display_snapshot_visitor.visited.keys()  # blackboard client uuid's (also behaviour uuid's), typing.Set[uuid.UUID]
display_snapshot_visitor.visited_keys  # blackboard keys, typing.Set[str]
# Now in SnapshotVisitor:
snapshot_visitor.visited_blackboard_client_ids  # typing.Set[uuid.UUID]
snapshot_visitor.visited_blackboard_keys  # typing.Set[str]

1.3.3 (2019-10-15)

• [blackboard] client Blackboard.unregister_key() method

1.3.2 (2019-10-15)

• [blackboard] global Blackboard.clear() method

1.3.1 (2019-10-15)

• [blackboard] don\'t do any copying, just pass handles around, #239
• [blackboard] client exists() method, #238
• [blackboard] global Blackboard.set() method
• [blackboard] client Blackboard.unset() method, #239

1.3.x (2019-10-03)

Breaking API

• [decorators] updated EternalGuard to accommodate new blackboard variable tracking mechanisms
• [behaviours] blackboard behaviours decoupled - CheckBlackboardVariableExists, WaitForBlackboardVariable
• [behaviours] blackboard behaviours decoupled - CheckBlackboardVariableValue, WaitForBlackboardVariableValue
• [behaviours] blackboard behaviours dropped use of the largely redundant ClearingPolicy
• [visitors] collapsed SnapshotVisitor and WindsOfChangeVisitor functionality, #228

New Features

• [blackboard] read/write access configuration for clients on blackboard keys
• [blackboard] log the activity on the blackboard
• [display] dot graphs now have an option to display blackboard variables
• [display] unicode to console the entire blackboard key-value store
• [display] unicode to console the blackboard activity stream
• [visitors] new DisplaySnapshotVisitor to simplify collection/printing the tree to console, #228

Bugfixes

• [infra] only require test html reports on circle ci builds (saves a dependency requirement), #229

1.2.2 (2019-08-06)

• [trees] standalone setup() method with timer for use on unmanaged trees, #198
• [examples] fix api in skeleton_tree.py, #199

1.2.1 (2019-05-21)

• [decorators] StatusToBlackboard reflects the status of it\'s child to the blackboard, #195
• [decorators] EternalGuard decorator that continuously guards a subtree (c.f. Unreal conditions), #195
• [idioms] eternal_guard counterpart to the decorator whose conditions are behaviours, #195

1.2.x (2019-04-28)

Breaking API

• [trees] removes the curious looking and unused destroy() method, #193
• [display] ascii_tree -> ascii_tree/unicode_tree(), no longer subverts the choice depending on your stdout, #192
• [display] dot_graph -> dot_tree for consistency with the text tree methods, #192

New Features

• [behaviour] shutdown() method to compliment setup(), #193
• [decorators] StatusToBlackboard reflects the status of it\'s child to the blackboard, #195
• [decorators] EternalGuard decorator that continuously guards a subtree (c.f. Unreal conditions), #195
• [display] xhtml_tree provides an xhtml compatible equivalent to the ascii_tree representation, #192
• [idioms] eternal_guard counterpart to the decorator whose conditions are behaviours, #195
• [trees] walks the tree calling shutdown() on each node in it\'s own shutdown() method, #193
• [visitors] get a finalise() method called immediately prior to post tick handlers, #191

1.1.0 (2019-03-19)

Breaking API

• [display] print_ascii_tree -> ascii_tree, #178.
• [display] generate_pydot_graph -> dot_graph, #178.
• [trees] tick_tock(sleep_ms, ..) -> tick_tock(period_ms, ...), #182.

New Features

• [trees] add missing add_visitor() method
• [trees] flexible setup() for children via kwargs
• [trees] convenience method for ascii tree debugging
• [display] highlight the tip in ascii tree snapshots

Bugfixes

• [trees] threaded timers for setup (avoids multiprocessing problems)
• [behaviour|composites] bugfix tip behaviour, add tests
• [display] correct first indent when non-zero in ascii_tree
• [display] apply same formatting to root as children in ascii_tree

1.0.7 (2019-xx-yy)

• [display] optional arguments for generate_pydot_graph

1.0.6 (2019-03-06)

• [decorators] fix missing root feedback message in ascii graphs

1.0.5 (2019-02-28)

• [decorators] fix timeout bug that doesn\'t respect a child\'s last tick

1.0.4 (2019-02-26)

• [display] drop spline curves, it\'s buggy with graphviz 2.38

1.0.3 (2019-02-13)

• [visitors] winds of change visitor and logging demo

1.0.2 (2019-02-13)

• [console] fallbacks for unicode chars when (UTF-8) encoding cannot support them

1.0.1 (2018-02-12)

• [trees] don\'t use multiprocess on setup if not using timeouts

1.0.0 (2019-01-18)

Breaking API

• [behaviour] setup() no longer returns a boolean, catch exceptions instead, #143.
• [behaviour] setup() no longer takes timeouts, responsibility moved to BehaviourTree, #148.
• [decorators] new-style decorators found in py_trees.decorators
• [decorators] new-style decorators stop their running child on completion (SUCCESS||FAILURE)
• [decorators] old-style decorators in py_trees.meta deprecated

New Features

• [blackboard] added a method for clearing the entire blackboard (useful for tests)
• [composites] raise TypeError when children\'s setup methods don\'t return a bool (common mistake)
• [composites] new parallel policies, SuccessOnAll, SuccessOnSelected
• [decorators] oneshot policies for activating on completion or successful completion only
• [meta] behaviours from functions can now automagically generate names

0.8.x (2018-10-18)

Breaking API

• Lower level namespace types no longer exist (PR117), e.g. py_trees.Status{.sourceCode} -> py_trees.common.Status{.sourceCode}
• Python2 support dropped

New Features

• [idioms] \'Pick Up Where You Left Off\'
• [idioms] \'OneShot\'

0.8.0 (2018-10-18)

• [infra] shortcuts to types in __init__.py removed (PR117)
• [bugfix] python3 rosdeps
• [idioms] pick_up_where_you_left_off added

0.7.5 (2018-10-10)

• [idioms] oneshot added
• [bugfix] properly set/reset parents when replacing/removing children in composites

0.7.0 (2018-09-27)

• [announce] python3 only support from this point forward
• [announce] now compatible for ros2 projects

0.6.5 (2018-09-19)

• [bugfix] pick up missing feedback messages in inverters
• [bugfix] eliminate costly/spammy blackboard variable check feedback message

0.6.4 (2018-09-19)

• [bugfix] replace awkward newlines with spaces in ascii trees

0.6.3 (2018-09-04)

• [bugfix] don\'t send the parellel\'s status to running children, invalidate them instead

0.6.2 (2018-08-31)

• [bugfix] oneshot now reacts to priority interrupts correctly

0.6.1 (2018-08-20)

• [bugfix] oneshot no longer permanently modifies the original class

0.6.0 (2018-05-15)

• [infra] python 2/3 compatibility

0.5.10 (2017-06-17)

• [meta] add children monkeypatching for composite imposters
• [blackboard] check for nested variables in WaitForBlackboard

0.5.9 (2017-03-25)

• [docs] bugfix image links and rewrite the motivation

0.5.8 (2017-03-19)

• [infra] setup.py tests_require, not test_require

0.5.7 (2017-03-01)

• [infra] update maintainer email

0.5.5 (2017-03-01)

• [docs] many minor doc updates
• [meta] bugfix so that imposter now ticks over composite children
• [trees] method for getting the tip of the tree
• [programs] py-trees-render program added

0.5.4 (2017-02-22)

• [infra] handle pypi/catkin conflicts with install_requires

0.5.2 (2017-02-22)

• [docs] disable colour when building
• [docs] sidebar headings
• [docs] dont require project installation

0.5.1 (2017-02-21)

• [infra] pypi package enabled

0.5.0 (2017-02-21)

• [ros] components moved to py_trees_ros
• [timeout] bugfix to ensure timeout decorator initialises properly
• [docs] rolled over with napolean style
• [docs] sphinx documentation updated
• [imposter] make sure tip() drills down into composites
• [demos] re-organised into modules

0.4.0 (2017-01-13)

• [trees] add pre/post handlers after setup, just in case setup fails
• [introspection] do parent lookups so you can crawl back up a tree
• [blackboard] permit init of subscriber2blackboard behaviours
• [blackboard] watchers
• [timers] better feedback messages
• [imposter] ensure stop() directly calls the composited behaviour

0.3.0 (2016-08-25)

• failure_is_running decorator (meta).

0.2.0 (2016-06-01)

• do terminate properly amongst relevant classes
• blackboxes
• chooser variant of selectors
• bugfix the decorators
• blackboard updates on change only
• improved dot graph creation
• many bugfixes to composites
• subscriber behaviours
• timer behaviours

0.1.2 (2015-11-16)

• one shot sequences
• abort() renamed more appropriately to stop()

0.1.1 (2015-10-10)

• lots of bugfixing stabilising py_trees for the spain field test
• complement decorator for behaviours
• dot tree views
• ascii tree and tick views
• use generators and visitors to more efficiently walk/introspect trees
• a first implementation of behaviour trees in python