Demos

py-trees-demo-action-behaviour

A py_trees demo.

Demonstrates the characteristics of a typical ‘action’ behaviour.

• Mocks an external process and connects to it in the setup() method

• Kickstarts new goals with the external process in the initialise() method

• Monitors the ongoing goal status in the update() method

• Determines RUNNING/SUCCESS pending feedback from the external process

usage: py-trees-demo-action-behaviour [-h]

class py_trees.demos.action.Action(name: str)

Bases: Behaviour

Demonstrates the at-a-distance style action behaviour.

This behaviour connects to a separately running process (initiated in setup()) and proceeeds to work with that subprocess to initiate a task and monitor the progress of that task at each tick until completed. While the task is running the behaviour returns RUNNING.

On completion, the the behaviour returns with success or failure (depending on success or failure of the task itself).

Key point - this behaviour itself should not be doing any work!

Parameters:

name (str) –

__init__(name: str)

Configure the name of the behaviour.

Parameters:

name (str) –

initialise() → None

Reset a counter variable.

Return type:

None

setup(**kwargs: Any) → None

Kickstart the separate process this behaviour will work with.

Ordinarily this process will be already running. In this case, setup is usually just responsible for verifying it exists.

Parameters:

kwargs (Any) –

Return type:

None

terminate(new_status: Status) → None

Nothing to clean up in this example.

Parameters:

new_status (Status) –

Return type:

None

update() → Status

Increment the counter, monitor and decide on a new status.

Return type:

Status

py_trees.demos.action.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.action.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.action.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.action.main() → None

Entry point for the demo script.

Return type:

None

py_trees.demos.action.planning(pipe_connection: Connection) → None

Emulate a (potentially) long running external process.

Parameters:

pipe_connection (Connection) – connection to the planning process

Return type:

None

py_trees/demos/action.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.action
   :func: command_line_argument_parser
   :prog: py-trees-demo-action-behaviour

.. image:: images/action.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import atexit
import multiprocessing
import multiprocessing.connection
import time
import typing

import py_trees.common
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "Demonstrates the characteristics of a typical 'action' behaviour.\n"
    content += "\n"
    content += "* Mocks an external process and connects to it in the setup() method\n"
    content += "* Kickstarts new goals with the external process in the initialise() method\n"
    content += "* Monitors the ongoing goal status in the update() method\n"
    content += "* Determines RUNNING/SUCCESS pending feedback from the external process\n"

    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Action Behaviour".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    return argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )


def planning(pipe_connection: multiprocessing.connection.Connection) -> None:
    """Emulate a (potentially) long running external process.

    Args:
        pipe_connection: connection to the planning process
    """
    idle = True
    percentage_complete = 0
    try:
        while True:
            if pipe_connection.poll():
                pipe_connection.recv()
                percentage_complete = 0
                idle = False
            if not idle:
                percentage_complete += 10
                pipe_connection.send([percentage_complete])
                if percentage_complete == 100:
                    idle = True
            time.sleep(0.5)
    except KeyboardInterrupt:
        pass


class Action(py_trees.behaviour.Behaviour):
    """Demonstrates the at-a-distance style action behaviour.

    This behaviour connects to a separately running process
    (initiated in setup()) and proceeeds to work with that subprocess to
    initiate a task and monitor the progress of that task at each tick
    until completed. While the task is running the behaviour returns
    :data:`~py_trees.common.Status.RUNNING`.

    On completion, the the behaviour returns with success or failure
    (depending on success or failure of the task itself).

    Key point - this behaviour itself should not be doing any work!
    """

    def __init__(self, name: str):
        """Configure the name of the behaviour."""
        super().__init__(name)
        self.logger.debug(f"{self.__class__.__name__}.__init__()")

    def setup(self, **kwargs: typing.Any) -> None:
        """Kickstart the separate process this behaviour will work with.

        Ordinarily this process will be already running. In this case,
        setup is usually just responsible for verifying it exists.
        """
        self.logger.debug(f"{self.__class__.__name__}.setup()->connections to an external process")
        self.parent_connection, self.child_connection = multiprocessing.Pipe()
        self.planning = multiprocessing.Process(target=planning, args=(self.child_connection,))
        atexit.register(self.planning.terminate)
        self.planning.start()

    def initialise(self) -> None:
        """Reset a counter variable."""
        self.logger.debug(f"{self.__class__.__name__}.initialise()->sending new goal")
        self.parent_connection.send(["new goal"])
        self.percentage_completion = 0

    def update(self) -> py_trees.common.Status:
        """Increment the counter, monitor and decide on a new status."""
        new_status = py_trees.common.Status.RUNNING
        if self.parent_connection.poll():
            self.percentage_completion = self.parent_connection.recv().pop()
            if self.percentage_completion == 100:
                new_status = py_trees.common.Status.SUCCESS
        if new_status == py_trees.common.Status.SUCCESS:
            self.feedback_message = "Processing finished"
            self.logger.debug(
                f"{self.__class__.__name__}.update()[{self.status}->{new_status}][{self.feedback_message}]"
            )
        else:
            self.feedback_message = f"{self.percentage_completion}%"
            self.logger.debug(f"{self.__class__.__name__}.update()[{self.status}][{self.feedback_message}]")
        return new_status

    def terminate(self, new_status: py_trees.common.Status) -> None:
        """Nothing to clean up in this example."""
        self.logger.debug(f"{self.__class__.__name__}.terminate()[{self.status}->{new_status}]")


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    command_line_argument_parser().parse_args()

    print(description())

    py_trees.logging.level = py_trees.logging.Level.DEBUG

    action = Action(name="Action")
    action.setup()
    try:
        for _unused_i in range(0, 12):
            action.tick_once()
            time.sleep(0.5)
        print("\n")
    except KeyboardInterrupt:
        pass

py-trees-demo-behaviour-lifecycle

A py_trees demo.

. argparse::

module:

py_trees.demos.lifecycle

func:

command_line_argument_parser

prog:

py-trees-demo-behaviour-lifecycle

class py_trees.demos.lifecycle.Counter(name: str = 'Counter')

Bases: Behaviour

Simple counting behaviour.

• Increments a counter from zero at each tick

• Finishes with success if the counter reaches three

• Resets the counter in the initialise() method.

Parameters:

name (str) –

__init__(name: str = 'Counter')

Configure the name of the behaviour.

Parameters:

name (str) –

initialise() → None

Reset a counter variable.

Return type:

None

setup(**kwargs: Any) → None

No delayed initialisation required for this example.

Parameters:

kwargs (Any) –

Return type:

None

terminate(new_status: Status) → None

Nothing to clean up in this example.

Parameters:

new_status (Status) –

Return type:

None

update() → Status

Increment the counter and decide on a new status.

Return type:

Status

py_trees.demos.lifecycle.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.lifecycle.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.lifecycle.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.lifecycle.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/lifecycle.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

. argparse::
   :module: py_trees.demos.lifecycle
   :func: command_line_argument_parser
   :prog: py-trees-demo-behaviour-lifecycle

.. image:: images/lifecycle.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import time
import typing

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "Demonstrates a typical day in the life of a behaviour.\n\n"
    content += "This behaviour will count from 1 to 3 and then reset and repeat. As it does\n"
    content += "so, it logs and displays the methods as they are called - construction, setup,\n"
    content += "initialisation, ticking and termination.\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Behaviour Lifecycle".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    return argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )


class Counter(py_trees.behaviour.Behaviour):
    """Simple counting behaviour.

    * Increments a counter from zero at each tick
    * Finishes with success if the counter reaches three
    * Resets the counter in the initialise() method.
    """

    def __init__(self, name: str = "Counter"):
        """Configure the name of the behaviour."""
        super().__init__(name)
        self.logger.debug(f"{self.__class__.__name__}.__init__()")

    def setup(self, **kwargs: typing.Any) -> None:
        """No delayed initialisation required for this example."""
        self.logger.debug(f"{self.__class__.__name__}.setup()")

    def initialise(self) -> None:
        """Reset a counter variable."""
        self.logger.debug(f"{self.__class__.__name__}.initialise()")
        self.counter = 0

    def update(self) -> py_trees.common.Status:
        """Increment the counter and decide on a new status."""
        self.counter += 1
        new_status = py_trees.common.Status.SUCCESS if self.counter == 3 else py_trees.common.Status.RUNNING
        if new_status == py_trees.common.Status.SUCCESS:
            self.feedback_message = f"counting...{self.counter} - phew, thats enough for today"
        else:
            self.feedback_message = "still counting"
        self.logger.debug(f"{self.__class__.__name__}.update()[{self.status}->{new_status}][{self.feedback_message}]")
        return new_status

    def terminate(self, new_status: py_trees.common.Status) -> None:
        """Nothing to clean up in this example."""
        self.logger.debug(f"{self.__class__.__name__}.terminate()[{self.status}->{new_status}]")


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    command_line_argument_parser().parse_args()

    print(description())

    py_trees.logging.level = py_trees.logging.Level.DEBUG

    counter = Counter()
    counter.setup()
    try:
        for _unused_i in range(0, 7):
            counter.tick_once()
            time.sleep(0.5)
        print("\n")
    except KeyboardInterrupt:
        print("")
        pass

py-trees-demo-blackboard

A py_trees demo.

Demonstrates usage of the blackboard and related behaviours.

A sequence is populated with a few behaviours that exercise reading and writing on the Blackboard in interesting ways.

usage: py-trees-demo-blackboard [-h] [-r | --render-with-blackboard-variables]

Named Arguments

-r, --render

render dot tree to file

Default: False

--render-with-blackboard-variables

render dot tree to file with blackboard variables

Default: False

Dot Graph

Console Screenshot

class py_trees.demos.blackboard.BlackboardWriter(name: str)

Bases: Behaviour

Write some more interesting / complex types to the blacbkoard.

Parameters:

name (str) –

__init__(name: str)

Set up the blackboard.

Parameters:

name (str) – behaviour name

update() → Status

Write a dictionary to the blackboard.

This beaviour always returns SUCCESS.

Return type:

Status

class py_trees.demos.blackboard.Nested

Bases: object

A more complex object to interact with on the blackboard.

__init__() → None

Initialise variables to some arbitrary defaults.

Return type:

None

__str__() → str

Return str(self).

Return type:

str

__weakref__

list of weak references to the object

class py_trees.demos.blackboard.ParamsAndState(name: str)

Bases: Behaviour

Parameter and state storage on the blackboard.

This behaviour demonstrates the usage of namespaces and multiple clients to perform getting and setting of parameters and state in a concise and convenient manner.

Parameters:

name (str) –

__init__(name: str)

Set up separate blackboard clients for parameters and state.

Parameters:

name (str) – behaviour name

initialise() → None

Initialise speed from the stored parameter variable on the blackboard.

Return type:

None

update() → Status

Check speed and either increment, or complete if it has reached a threshold.

Returns:

RUNNING if incrementing, SUCCESS otherwise.

Return type:

Status

py_trees.demos.blackboard.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.blackboard.create_root() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.blackboard.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.blackboard.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.blackboard.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/blackboard.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.blackboard
   :func: command_line_argument_parser
   :prog: py-trees-demo-blackboard

.. graphviz:: dot/demo-blackboard.dot
   :align: center
   :caption: Dot Graph

.. figure:: images/blackboard_demo.png
   :align: center

   Console Screenshot
"""

##############################################################################
# Imports
##############################################################################

import argparse
import operator
import sys

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "Demonstrates usage of the blackboard and related behaviours.\n"
    content += "\n"
    content += "A sequence is populated with a few behaviours that exercise\n"
    content += "reading and writing on the Blackboard in interesting ways.\n"

    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Blackboard".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    render_group = parser.add_mutually_exclusive_group()
    render_group.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    render_group.add_argument(
        "--render-with-blackboard-variables",
        action="store_true",
        help="render dot tree to file with blackboard variables",
    )
    return parser


class Nested:
    """A more complex object to interact with on the blackboard."""

    def __init__(self) -> None:
        """Initialise variables to some arbitrary defaults."""
        self.foo = "bar"

    def __str__(self) -> str:
        return str({"foo": self.foo})


class BlackboardWriter(py_trees.behaviour.Behaviour):
    """Write some more interesting / complex types to the blacbkoard."""

    def __init__(self, name: str):
        """Set up the blackboard.

        Args:
            name: behaviour name
        """
        super().__init__(name=name)
        self.blackboard = self.attach_blackboard_client()
        self.blackboard.register_key(key="dude", access=py_trees.common.Access.READ)
        self.blackboard.register_key(key="spaghetti", access=py_trees.common.Access.WRITE)

        self.logger.debug(f"{self.__class__.__name__}.__init__()")

    def update(self) -> py_trees.common.Status:
        """Write a dictionary to the blackboard.

        This beaviour always returns :data:`~py_trees.common.Status.SUCCESS`.
        """
        self.logger.debug(f"{self.__class__.__name__}.update()")
        try:
            _ = self.blackboard.dude
        except KeyError:
            pass
        try:
            _ = self.blackboard.dudette
        except AttributeError:
            pass
        try:
            self.blackboard.dudette = "Jane"
        except AttributeError:
            pass
        self.blackboard.spaghetti = {"type": "Carbonara", "quantity": 1}
        self.blackboard.spaghetti = {"type": "Gnocchi", "quantity": 2}
        try:
            self.blackboard.set("spaghetti", {"type": "Bolognese", "quantity": 3}, overwrite=False)
        except AttributeError:
            pass
        return py_trees.common.Status.SUCCESS


class ParamsAndState(py_trees.behaviour.Behaviour):
    """Parameter and state storage on the blackboard.

    This behaviour demonstrates the usage of namespaces and
    multiple clients to perform getting and setting of
    parameters and state in a concise and convenient manner.
    """

    def __init__(self, name: str):
        """Set up separate blackboard clients for parameters and state.

        Args:
           name: behaviour name
        """
        super().__init__(name=name)
        # namespaces can include the separator or may leave it out
        # they can also be nested, e.g. /agent/state, /agent/parameters
        self.parameters = self.attach_blackboard_client("Params", "parameters")
        self.state = self.attach_blackboard_client("State", "state")
        self.parameters.register_key(key="default_speed", access=py_trees.common.Access.READ)
        self.state.register_key(key="current_speed", access=py_trees.common.Access.WRITE)

    def initialise(self) -> None:
        """Initialise speed from the stored parameter variable on the blackboard."""
        try:
            self.state.current_speed = self.parameters.default_speed
        except KeyError as e:
            raise RuntimeError(f"parameter 'default_speed' not found [{str(e)}]") from e

    def update(self) -> py_trees.common.Status:
        """
        Check speed and either increment, or complete if it has reached a threshold.

        Returns:
            :data:`~py_trees.common.Status.RUNNING` if incrementing, :data:`~py_trees.common.Status.SUCCESS` otherwise.
        """
        if self.state.current_speed > 40.0:
            return py_trees.common.Status.SUCCESS
        else:
            self.state.current_speed += 1.0
            return py_trees.common.Status.RUNNING


def create_root() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    root = py_trees.composites.Sequence(name="Blackboard Demo", memory=True)
    set_blackboard_variable = py_trees.behaviours.SetBlackboardVariable(
        name="Set Nested",
        variable_name="nested",
        variable_value=Nested(),
        overwrite=True,
    )
    write_blackboard_variable = BlackboardWriter(name="Writer")
    check_blackboard_variable = py_trees.behaviours.CheckBlackboardVariableValue(
        name="Check Nested Foo",
        check=py_trees.common.ComparisonExpression(variable="nested.foo", value="bar", operator=operator.eq),
    )
    params_and_state = ParamsAndState(name="ParamsAndState")
    root.add_children(
        [
            set_blackboard_variable,
            write_blackboard_variable,
            check_blackboard_variable,
            params_and_state,
        ]
    )
    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    print(description())
    py_trees.logging.level = py_trees.logging.Level.DEBUG
    py_trees.blackboard.Blackboard.enable_activity_stream(maximum_size=100)
    blackboard = py_trees.blackboard.Client(name="Configuration")
    blackboard.register_key(key="dude", access=py_trees.common.Access.WRITE)
    blackboard.register_key(key="/parameters/default_speed", access=py_trees.common.Access.EXCLUSIVE_WRITE)
    blackboard.dude = "Bob"
    blackboard.parameters.default_speed = 30.0

    root = create_root()

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(root, with_blackboard_variables=False)
        sys.exit()
    if args.render_with_blackboard_variables:
        py_trees.display.render_dot_tree(root, with_blackboard_variables=True)
        sys.exit()

    ####################
    # Execute
    ####################
    root.setup_with_descendants()
    unset_blackboard = py_trees.blackboard.Client(name="Unsetter")
    unset_blackboard.register_key(key="foo", access=py_trees.common.Access.WRITE)
    print("\n--------- Tick 0 ---------\n")
    root.tick_once()
    print("\n")
    print(py_trees.display.unicode_tree(root, show_status=True))
    print("--------------------------\n")
    print(py_trees.display.unicode_blackboard())
    print("--------------------------\n")
    print(py_trees.display.unicode_blackboard(display_only_key_metadata=True))
    print("--------------------------\n")
    unset_blackboard.unset("foo")
    print(py_trees.display.unicode_blackboard_activity_stream())

py-trees-demo-blackboard-namespaces

A py_trees demo.

Demonstrates usage of blackboard namespaces.

usage: py-trees-demo-blackboard-namespaces [-h]

Console Screenshot

py_trees.demos.blackboard_namespaces.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.blackboard_namespaces.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.blackboard_namespaces.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.blackboard_namespaces.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/blackboard_namespaces.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.blackboard_namespaces
   :func: command_line_argument_parser
   :prog: py-trees-demo-blackboard-namespaces

.. figure:: images/blackboard_namespaces.png
   :align: center

   Console Screenshot
"""

##############################################################################
# Imports
##############################################################################

import argparse

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "Demonstrates usage of blackboard namespaces.\n"
    content += "\n"

    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Blackboard".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    return parser


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    _ = command_line_argument_parser().parse_args()  # configuration only, no args to process
    print(description())
    print("-------------------------------------------------------------------------------")
    print("$ py_trees.blackboard.Client(name='Blackboard')")
    print("$ foo.register_key(key='dude', access=py_trees.common.Access.WRITE)")
    print("$ foo.register_key(key='/dudette', access=py_trees.common.Access.WRITE)")
    print("$ foo.register_key(key='/foo/bar/wow', access=py_trees.common.Access.WRITE)")
    print("-------------------------------------------------------------------------------")
    blackboard = py_trees.blackboard.Client(name="Blackboard")
    blackboard.register_key(key="dude", access=py_trees.common.Access.WRITE)
    blackboard.register_key(key="/dudette", access=py_trees.common.Access.WRITE)
    blackboard.register_key(key="/foo/bar/wow", access=py_trees.common.Access.WRITE)
    print(blackboard)
    print("-------------------------------------------------------------------------------")
    print("$ blackboard.dude = 'Bob'")
    print("$ blackboard.dudette = 'Jade'")
    print("-------------------------------------------------------------------------------")
    blackboard.dude = "Bob"
    blackboard.dudette = "Jade"
    print(py_trees.display.unicode_blackboard())
    print("-------------------------------------------------------------------------------")
    print("$ blackboard.foo.bar.wow = 'foobar'")
    print("-------------------------------------------------------------------------------")
    blackboard.foo.bar.wow = "foobar"
    print(py_trees.display.unicode_blackboard())
    print("-------------------------------------------------------------------------------")
    print("$ py_trees.blackboard.Client(name='Foo', namespace='foo')")
    print("$ foo.register_key(key='awesome', access=py_trees.common.Access.WRITE)")
    print("$ foo.register_key(key='/brilliant', access=py_trees.common.Access.WRITE)")
    print("$ foo.register_key(key='/foo/clever', access=py_trees.common.Access.WRITE)")
    print("-------------------------------------------------------------------------------")
    foo = py_trees.blackboard.Client(name="Foo", namespace="foo")
    foo.register_key(key="awesome", access=py_trees.common.Access.WRITE)
    # TODO: should /brilliant be namespaced or go directly to root?
    foo.register_key(key="/brilliant", access=py_trees.common.Access.WRITE)
    # absolute names are ok, so long as they include the namespace
    foo.register_key(key="/foo/clever", access=py_trees.common.Access.WRITE)
    print(foo)
    print("-------------------------------------------------------------------------------")
    print("$ foo.awesome = True")
    print("$ foo.set('/brilliant', False)")
    print("$ foo.clever = True")
    print("-------------------------------------------------------------------------------")
    foo.awesome = True
    # Only accessible via set since it's not in the namespace
    foo.set("/brilliant", False)
    # This will fail since it looks for the namespaced /foo/brilliant key
    # foo.brilliant = False
    foo.clever = True
    print(py_trees.display.unicode_blackboard())

py-trees-demo-blackboard-remappings

A py_trees demo.

Demonstrates usage of blackbord remappings.

Demonstration is via an exemplar behaviour making use of remappings..

usage: py-trees-demo-blackboard-remappings [-h]

Console Screenshot

class py_trees.demos.blackboard_remappings.Remap(name: str, remap_to: dict[str, str])

Bases: Behaviour

Custom writer that submits a more complicated variable to the blackboard.

Parameters:

• name (str) –

• remap_to (dict[str, str]) –

__init__(name: str, remap_to: dict[str, str])

Set up the blackboard and remap variables.

Parameters:

• name (str) – behaviour name

• remap_to (dict[str, str]) – remappings (from variable name to variable name)

update() → Status

Write a dictionary to the blackboard.

This beaviour always returns SUCCESS.

Return type:

Status

py_trees.demos.blackboard_remappings.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.blackboard_remappings.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.blackboard_remappings.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.blackboard_remappings.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/blackboard_remappings.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.blackboard_remappings
   :func: command_line_argument_parser
   :prog: py-trees-demo-blackboard-remappings

.. figure:: images/blackboard_remappings.png
   :align: center

   Console Screenshot
"""

##############################################################################
# Imports
##############################################################################

import argparse

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "Demonstrates usage of blackbord remappings.\n"
    content += "\n"
    content += "Demonstration is via an exemplar behaviour making use of remappings..\n"

    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Blackboard".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    return parser


class Remap(py_trees.behaviour.Behaviour):
    """Custom writer that submits a more complicated variable to the blackboard."""

    def __init__(self, name: str, remap_to: dict[str, str]):
        """
        Set up the blackboard and remap variables.

        Args:
            name: behaviour name
            remap_to: remappings (from variable name to variable name)
        """
        super().__init__(name=name)
        self.logger.debug(f"{self.__class__.__name__}.__init__()")
        self.blackboard = self.attach_blackboard_client()
        self.blackboard.register_key(
            key="/foo/bar/wow",
            access=py_trees.common.Access.WRITE,
            remap_to=remap_to["/foo/bar/wow"],
        )

    def update(self) -> py_trees.common.Status:
        """Write a dictionary to the blackboard.

        This beaviour always returns :data:`~py_trees.common.Status.SUCCESS`.
        """
        self.logger.debug(f"{self.__class__.__name__}.update()")
        self.blackboard.foo.bar.wow = "colander"

        return py_trees.common.Status.SUCCESS


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    _ = command_line_argument_parser().parse_args()  # configuration only, no arg processing
    print(description())
    py_trees.logging.level = py_trees.logging.Level.DEBUG
    py_trees.blackboard.Blackboard.enable_activity_stream(maximum_size=100)
    root = Remap(name="Remap", remap_to={"/foo/bar/wow": "/parameters/wow"})

    ####################
    # Execute
    ####################
    root.tick_once()
    print(root.blackboard)
    print(py_trees.display.unicode_blackboard())
    print(py_trees.display.unicode_blackboard_activity_stream())

py-trees-demo-context-switching

A py_trees demo.

Demonstrates context switching with parallels and sequences.

A context switching behaviour is run in parallel with a work sequence. Switching the context occurs in the initialise() and terminate() methods of the context switching behaviour. Note that whether the sequence results in failure or success, the context switch behaviour will always call the terminate() method to restore the context. It will also call terminate() to restore the context in the event of a higher priority parent cancelling this parallel subtree.

usage: py-trees-demo-context-switching [-h] [-r]

Named Arguments

-r, --render

render dot tree to file

Default: False

class py_trees.demos.context_switching.ContextSwitch(name: str = 'ContextSwitch')

Bases: Behaviour

An example of a context switching class.

This class sets (in initialise()) and restores a context (in terminate()). Use in parallel with a sequence/subtree that does the work while in this context.

Attention

Simply setting a pair of behaviours (set and reset context) on either end of a sequence will not suffice for context switching. In the case that one of the work behaviours in the sequence fails, the final reset context switch will never trigger.

Parameters:

name (str) –

__init__(name: str = 'ContextSwitch')

Initialise with a behaviour name.

Parameters:

name (str) –

initialise() → None

Backup and set a new context.

Return type:

None

terminate(new_status: Status) → None

Restore the context with the previously backed up context.

Parameters:

new_status (Status) –

Return type:

None

update() → Status

Just returns RUNNING while it waits for other activities to finish.

Return type:

Status

py_trees.demos.context_switching.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.context_switching.create_root() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.context_switching.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.context_switching.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.context_switching.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/contex_switching.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.context_switching
   :func: command_line_argument_parser
   :prog: py-trees-demo-context-switching

.. graphviz:: dot/demo-context_switching.dot

.. image:: images/context_switching.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import sys
import time

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "Demonstrates context switching with parallels and sequences.\n"
    content += "\n"
    content += "A context switching behaviour is run in parallel with a work sequence.\n"
    content += "Switching the context occurs in the initialise() and terminate() methods\n"
    content += "of the context switching behaviour. Note that whether the sequence results\n"
    content += "in failure or success, the context switch behaviour will always call the\n"
    content += "terminate() method to restore the context. It will also call terminate()\n"
    content += "to restore the context in the event of a higher priority parent cancelling\n"
    content += "this parallel subtree.\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Context Switching".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    return parser


class ContextSwitch(py_trees.behaviour.Behaviour):
    """
    An example of a context switching class.

    This class sets (in ``initialise()``)
    and restores a context (in ``terminate()``). Use in parallel with a
    sequence/subtree that does the work while in this context.

    .. attention:: Simply setting a pair of behaviours (set and reset context) on
        either end of a sequence will not suffice for context switching. In the case
        that one of the work behaviours in the sequence fails, the final reset context
        switch will never trigger.
    """

    def __init__(self, name: str = "ContextSwitch"):
        """Initialise with a behaviour name."""
        super().__init__(name)
        self.feedback_message = "no context"

    def initialise(self) -> None:
        """Backup and set a new context."""
        self.logger.debug(f"{self.__class__.__name__}.initialise()[switch context]")
        # Some actions that:
        #   1. retrieve the current context from somewhere
        #   2. cache the context internally
        #   3. apply a new context
        self.feedback_message = "new context"

    def update(self) -> py_trees.common.Status:
        """Just returns RUNNING while it waits for other activities to finish."""
        self.logger.debug(f"{self.__class__.__name__}.update()[RUNNING][{self.feedback_message}]")
        return py_trees.common.Status.RUNNING

    def terminate(self, new_status: py_trees.common.Status) -> None:
        """Restore the context with the previously backed up context."""
        self.logger.debug(f"{self.__class__.__name__}.terminate()[{self.status}->{new_status}][restore context]")
        # Some actions that:
        #   1. restore the cached context
        self.feedback_message = "restored context"


def create_root() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    root = py_trees.composites.Parallel(name="Parallel", policy=py_trees.common.ParallelPolicy.SuccessOnOne())
    context_switch = ContextSwitch(name="Context")
    sequence = py_trees.composites.Sequence(name="Sequence", memory=True)
    for job in ["Action 1", "Action 2"]:
        success_after_two = py_trees.behaviours.StatusQueue(
            name=job,
            queue=[py_trees.common.Status.RUNNING, py_trees.common.Status.RUNNING],
            eventually=py_trees.common.Status.SUCCESS,
        )
        sequence.add_child(success_after_two)
    root.add_child(context_switch)
    root.add_child(sequence)
    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    print(description())
    py_trees.logging.level = py_trees.logging.Level.DEBUG

    root = create_root()

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(root)
        sys.exit()

    ####################
    # Execute
    ####################
    root.setup_with_descendants()
    for i in range(1, 6):
        try:
            print(f"\n--------- Tick {i} ---------\n")
            root.tick_once()
            print("\n")
            print(f"{py_trees.display.unicode_tree(root, show_status=True)}")
            time.sleep(1.0)
        except KeyboardInterrupt:
            break
    print("\n")

py-trees-demo-dot-graphs

A py_trees demo.

Renders a dot graph for a simple tree, with blackboxes.

usage: py-trees-demo-dot-graphs [-h]
                                [-l {all,fine_detail,detail,component,big_picture}]

Named Arguments

-l, --level

Possible choices: all, fine_detail, detail, component, big_picture

visibility level

Default: 'fine_detail'

py_trees.demos.dot_graphs.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.dot_graphs.create_tree(level: str) → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Parameters:

level (str) –

Return type:

Behaviour

py_trees.demos.dot_graphs.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.dot_graphs.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.dot_graphs.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/dot_graphs.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.dot_graphs
   :func: command_line_argument_parser
   :prog: py-trees-demo-dot-graphs

.. graphviz:: dot/demo-dot-graphs.dot

"""

##############################################################################
# Imports
##############################################################################

import argparse
import subprocess

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    name = "py-trees-demo-dot-graphs"
    content = "Renders a dot graph for a simple tree, with blackboxes.\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Dot Graphs".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += console.white
        s += console.bold + "    Generate Full Dot Graph" + console.reset + "\n"
        s += "\n"
        s += console.cyan + f"        {name}" + console.reset + "\n"
        s += "\n"
        s += console.bold + "    With Varying Visibility Levels" + console.reset + "\n"
        s += "\n"
        s += console.cyan + f"        {name}" + console.yellow + " --level=all" + console.reset + "\n"
        s += console.cyan + f"        {name}" + console.yellow + " --level=detail" + console.reset + "\n"
        s += console.cyan + f"        {name}" + console.yellow + " --level=component" + console.reset + "\n"
        s += console.cyan + f"        {name}" + console.yellow + " --level=big_picture" + console.reset + "\n"
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument(
        "-l",
        "--level",
        action="store",
        default="fine_detail",
        choices=["all", "fine_detail", "detail", "component", "big_picture"],
        help="visibility level",
    )
    return parser


def create_tree(level: str) -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    root = py_trees.composites.Selector(name=f"Demo Dot Graphs {level}", memory=False)
    first_blackbox = py_trees.composites.Sequence(name="BlackBox 1", memory=True)
    first_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    first_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    first_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    first_blackbox.blackbox_level = py_trees.common.BlackBoxLevel.BIG_PICTURE
    second_blackbox = py_trees.composites.Sequence(name="Blackbox 2", memory=True)
    second_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    second_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    second_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    second_blackbox.blackbox_level = py_trees.common.BlackBoxLevel.COMPONENT
    third_blackbox = py_trees.composites.Sequence(name="Blackbox 3", memory=True)
    third_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    third_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    third_blackbox.add_child(py_trees.behaviours.Running("Worker"))
    third_blackbox.blackbox_level = py_trees.common.BlackBoxLevel.DETAIL
    root.add_child(first_blackbox)
    root.add_child(second_blackbox)
    first_blackbox.add_child(third_blackbox)
    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    args.enum_level = py_trees.common.string_to_visibility_level(args.level)
    print(description())
    py_trees.logging.level = py_trees.logging.Level.DEBUG

    root = create_tree(args.level)
    py_trees.display.render_dot_tree(root, args.enum_level)

    if py_trees.utilities.which("xdot"):
        try:
            subprocess.call(["xdot", f"demo_dot_graphs_{args.level}.dot"])
        except KeyboardInterrupt:
            pass
    else:
        print("")
        console.logerror("No xdot viewer found, skipping display [hint: sudo apt install xdot]")
        print("")

py-trees-demo-either-or

A py_trees demo.

A demonstration of the ‘either_or’ idiom.

This behaviour tree pattern enables triggering of subtrees with equal priority (first in, first served).

EVENTS

• 3 : joystick one enabled, task one starts

• 5 : task one finishes

• 6 : joystick two enabled, task two starts

• 7 : joystick one enabled, task one ignored, task two continues

• 8 : task two finishes

usage: py-trees-demo-either-or [-h] [-r | -i]

Named Arguments

-r, --render

render dot tree to file

Default: False

-i, --interactive

pause and wait for keypress at each tick

Default: False

py_trees.demos.either_or.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.either_or.create_root() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.either_or.description(root: Behaviour) → str

Print description and usage information about the program.

Returns:

the program description string

Parameters:

root (Behaviour) –

Return type:

str

py_trees.demos.either_or.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.either_or.main() → None

Entry point for the demo script.

Return type:

None

py_trees.demos.either_or.post_tick_handler(snapshot_visitor: SnapshotVisitor, behaviour_tree: BehaviourTree) → None

Print data about the part of the tree visited.

Parameters:

• snapshot_handler – gather data about the part of the tree visited

• behaviour_tree (BehaviourTree) – tree to gather data from

• snapshot_visitor (SnapshotVisitor) –

Return type:

None

py_trees.demos.either_or.pre_tick_handler(behaviour_tree: BehaviourTree) → None

Print a banner with current tick count prior to ticking the tree.

Parameters:

behaviour_tree (BehaviourTree) – the tree to tick (used to fetch the count number)

Return type:

None

py_trees/demos/either_or.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.either_or
   :func: command_line_argument_parser
   :prog: py-trees-demo-either-or

.. graphviz:: dot/demo-either-or.dot

.. image:: images/either_or.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import functools
import operator
import sys
import time

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description(root: py_trees.behaviour.Behaviour) -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "A demonstration of the 'either_or' idiom.\n\n"
    content += "This behaviour tree pattern enables triggering of subtrees\n"
    content += "with equal priority (first in, first served).\n"
    content += "\n"
    content += "EVENTS\n"
    content += "\n"
    content += " -  3 : joystick one enabled, task one starts\n"
    content += " -  5 : task one finishes\n"
    content += " -  6 : joystick two enabled, task two starts\n"
    content += " -  7 : joystick one enabled, task one ignored, task two continues\n"
    content += " -  8 : task two finishes\n"
    content += "\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Either Or".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(create_root()),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    group = parser.add_mutually_exclusive_group()
    group.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    group.add_argument(
        "-i",
        "--interactive",
        action="store_true",
        help="pause and wait for keypress at each tick",
    )
    return parser


def pre_tick_handler(behaviour_tree: py_trees.trees.BehaviourTree) -> None:
    """Print a banner with current tick count prior to ticking the tree.

    Args:
       behaviour_tree: the tree to tick (used to fetch the count number)
    """
    print(f"\n--------- Run {behaviour_tree.count} ---------\n")


def post_tick_handler(
    snapshot_visitor: py_trees.visitors.SnapshotVisitor,
    behaviour_tree: py_trees.trees.BehaviourTree,
) -> None:
    """
    Print data about the part of the tree visited.

    Args:
        snapshot_handler: gather data about the part of the tree visited
        behaviour_tree: tree to gather data from
    """
    print(
        "\n"
        + py_trees.display.unicode_tree(
            root=behaviour_tree.root,
            visited=snapshot_visitor.visited,
            previously_visited=snapshot_visitor.previously_visited,
        )
    )
    print(py_trees.display.unicode_blackboard())


def create_root() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    trigger_one = py_trees.decorators.FailureIsRunning(
        name="FisR", child=py_trees.behaviours.SuccessEveryN(name="Joystick 1", n=4)
    )
    trigger_two = py_trees.decorators.FailureIsRunning(
        name="FisR", child=py_trees.behaviours.SuccessEveryN(name="Joystick 2", n=7)
    )
    enable_joystick_one = py_trees.behaviours.SetBlackboardVariable(
        name="Joy1 - Enabled",
        variable_name="joystick_one",
        variable_value="enabled",
        overwrite=True,
    )
    enable_joystick_two = py_trees.behaviours.SetBlackboardVariable(
        name="Joy2 - Enabled",
        variable_name="joystick_two",
        variable_value="enabled",
        overwrite=True,
    )
    reset_joystick_one = py_trees.behaviours.SetBlackboardVariable(
        name="Joy1 - Disabled",
        variable_name="joystick_one",
        variable_value="disabled",
        overwrite=True,
    )
    reset_joystick_two = py_trees.behaviours.SetBlackboardVariable(
        name="Joy2 - Disabled",
        variable_name="joystick_two",
        variable_value="disabled",
        overwrite=True,
    )
    task_one = py_trees.behaviours.TickCounter(
        name="Task 1", duration=2, completion_status=py_trees.common.Status.SUCCESS
    )
    task_two = py_trees.behaviours.TickCounter(
        name="Task 2", duration=2, completion_status=py_trees.common.Status.SUCCESS
    )
    idle = py_trees.behaviours.Running(name="Idle")
    either_or = py_trees.idioms.either_or(
        name="Either Or",
        conditions=[
            py_trees.common.ComparisonExpression("joystick_one", "enabled", operator.eq),
            py_trees.common.ComparisonExpression("joystick_two", "enabled", operator.eq),
        ],
        subtrees=[task_one, task_two],
        namespace="either_or",
    )
    root = py_trees.composites.Parallel(
        name="Root",
        policy=py_trees.common.ParallelPolicy.SuccessOnAll(synchronise=False),
    )
    reset = py_trees.composites.Sequence(name="Reset", memory=True)
    reset.add_children([reset_joystick_one, reset_joystick_two])
    joystick_one_events = py_trees.composites.Sequence(name="Joy1 Events", memory=True)
    joystick_one_events.add_children([trigger_one, enable_joystick_one])
    joystick_two_events = py_trees.composites.Sequence(name="Joy2 Events", memory=True)
    joystick_two_events.add_children([trigger_two, enable_joystick_two])
    tasks = py_trees.composites.Selector(name="Tasks", memory=False)
    tasks.add_children([either_or, idle])
    root.add_children([reset, joystick_one_events, joystick_two_events, tasks])
    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    # py_trees.logging.level = py_trees.logging.Level.DEBUG
    root = create_root()
    print(description(root))

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(root)
        sys.exit()

    ####################
    # Tree Stewardship
    ####################
    behaviour_tree = py_trees.trees.BehaviourTree(root)
    behaviour_tree.add_pre_tick_handler(pre_tick_handler)
    behaviour_tree.visitors.append(py_trees.visitors.DebugVisitor())
    snapshot_visitor = py_trees.visitors.SnapshotVisitor()
    behaviour_tree.add_post_tick_handler(functools.partial(post_tick_handler, snapshot_visitor))
    behaviour_tree.visitors.append(snapshot_visitor)
    behaviour_tree.setup(timeout=15)

    ####################
    # Tick Tock
    ####################
    if args.interactive:
        py_trees.console.read_single_keypress()
    for _unused_i in range(1, 11):
        try:
            behaviour_tree.tick()
            if args.interactive:
                py_trees.console.read_single_keypress()
            else:
                time.sleep(0.5)
        except KeyboardInterrupt:
            break
    print("\n")

py-trees-demo-eternal-guard

A py_trees demo.

A demonstration of the ‘eternal guard’ concept.

Two binary (F|S) conditional checks will fire every tick, thus providing a fail-fast mechanism for the long running sequence of tasks behind them.

usage: py-trees-demo-eternal-guard [-h] [-r | -i]

Named Arguments

-r, --render

render dot tree to file

Default: False

-i, --interactive

pause and wait for keypress at each tick

Default: False

py_trees.demos.eternal_guard.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.eternal_guard.create_root() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.eternal_guard.description(root: Behaviour) → str

Print description and usage information about the program.

Returns:

the program description string

Parameters:

root (Behaviour) –

Return type:

str

py_trees.demos.eternal_guard.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.eternal_guard.main() → None

Entry point for the demo script.

Return type:

None

py_trees.demos.eternal_guard.post_tick_handler(snapshot_visitor: SnapshotVisitor, behaviour_tree: BehaviourTree) → None

Print data about the part of the tree visited.

Parameters:

• snapshot_handler – gather data about the part of the tree visited

• behaviour_tree (BehaviourTree) – tree to gather data from

• snapshot_visitor (SnapshotVisitor) –

Return type:

None

py_trees.demos.eternal_guard.pre_tick_handler(behaviour_tree: BehaviourTree) → None

Print a banner with current tick count prior to ticking the tree.

Parameters:

behaviour_tree (BehaviourTree) – the tree to tick (used to fetch the count number)

Return type:

None

py_trees/demos/eternal_guard.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.eternal_guard
   :func: command_line_argument_parser
   :prog: py-trees-demo-eternal-guard

.. graphviz:: dot/demo-eternal-guard.dot

.. image:: images/eternal_guard.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import functools
import sys
import time

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description(root: py_trees.behaviour.Behaviour) -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "A demonstration of the 'eternal guard' concept.\n\n"
    content += "Two binary (F|S) conditional checks will fire every\n"
    content += "tick, thus providing a fail-fast mechanism for the\n"
    content += "long running sequence of tasks behind them.\n"
    content += "\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Eternal Guard".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += py_trees.display.unicode_tree(root)
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(create_root()),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    group = parser.add_mutually_exclusive_group()
    group.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    group.add_argument(
        "-i",
        "--interactive",
        action="store_true",
        help="pause and wait for keypress at each tick",
    )
    return parser


def pre_tick_handler(behaviour_tree: py_trees.trees.BehaviourTree) -> None:
    """Print a banner with current tick count prior to ticking the tree.

    Args:
       behaviour_tree: the tree to tick (used to fetch the count number)
    """
    print(f"\n--------- Run {behaviour_tree.count} ---------\n")


def post_tick_handler(
    snapshot_visitor: py_trees.visitors.SnapshotVisitor,
    behaviour_tree: py_trees.trees.BehaviourTree,
) -> None:
    """
    Print data about the part of the tree visited.

    Args:
        snapshot_handler: gather data about the part of the tree visited
        behaviour_tree: tree to gather data from
    """
    print(
        "\n"
        + py_trees.display.unicode_tree(
            root=behaviour_tree.root,
            visited=snapshot_visitor.visited,
            previously_visited=snapshot_visitor.previously_visited,
        )
    )
    print(py_trees.display.unicode_blackboard())


def create_root() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    eternal_guard = py_trees.composites.Sequence(name="Eternal Guard", memory=False)
    condition_one = py_trees.behaviours.StatusQueue(
        name="Condition 1",
        queue=[
            py_trees.common.Status.SUCCESS,
            py_trees.common.Status.FAILURE,
            py_trees.common.Status.SUCCESS,
        ],
        eventually=py_trees.common.Status.SUCCESS,
    )
    condition_two = py_trees.behaviours.StatusQueue(
        name="Condition 2",
        queue=[
            py_trees.common.Status.SUCCESS,
            py_trees.common.Status.SUCCESS,
            py_trees.common.Status.FAILURE,
        ],
        eventually=py_trees.common.Status.SUCCESS,
    )
    task_sequence = py_trees.composites.Sequence(name="Task Sequence", memory=True)
    task_one = py_trees.behaviours.Success(name="Worker 1")
    task_two = py_trees.behaviours.Running(name="Worker 2")

    eternal_guard.add_children([condition_one, condition_two, task_sequence])
    task_sequence.add_children([task_one, task_two])
    return eternal_guard


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    # py_trees.logging.level = py_trees.logging.Level.DEBUG
    root = create_root()
    print(description(root))

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(root)
        sys.exit()

    ####################
    # Tree Stewardship
    ####################
    behaviour_tree = py_trees.trees.BehaviourTree(root)
    behaviour_tree.add_pre_tick_handler(pre_tick_handler)
    behaviour_tree.visitors.append(py_trees.visitors.DebugVisitor())
    snapshot_visitor = py_trees.visitors.SnapshotVisitor()
    behaviour_tree.add_post_tick_handler(functools.partial(post_tick_handler, snapshot_visitor))
    behaviour_tree.visitors.append(snapshot_visitor)
    behaviour_tree.setup(timeout=15)

    ####################
    # Tick Tock
    ####################
    if args.interactive:
        py_trees.console.read_single_keypress()
    for _unused_i in range(1, 11):
        try:
            behaviour_tree.tick()
            if args.interactive:
                py_trees.console.read_single_keypress()
            else:
                time.sleep(0.5)
        except KeyboardInterrupt:
            break
    print("\n")

py-trees-demo-logging

A py_trees demo.

A demonstration of logging with trees.

This demo utilises a SnapshotVisitor to trigger a post-tick handler to dump a serialisation of the tree to a json log file.

This coupling of visitor and post-tick handler can be used for any kind of event handling - the visitor is the trigger and the post-tick handler the action. Aside from logging, the most common use case is to serialise the tree for messaging to a graphical, runtime monitor.

usage: py-trees-demo-logging [-h] [-r | -i]

Named Arguments

-r, --render

render dot tree to file

Default: False

-i, --interactive

pause and wait for keypress at each tick

Default: False

py_trees.demos.logging.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.logging.create_tree() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.logging.description(root: Behaviour) → str

Print description and usage information about the program.

Returns:

the program description string

Parameters:

root (Behaviour) –

Return type:

str

py_trees.demos.logging.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.logging.logger(snapshot_visitor: DisplaySnapshotVisitor, behaviour_tree: BehaviourTree) → None

Log the tree (relevant parts thereof) to a yaml file.

Use as a post-tick handler for a tree.

Parameters:

• snapshot_visitor (DisplaySnapshotVisitor) –

• behaviour_tree (BehaviourTree) –

Return type:

None

py_trees.demos.logging.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/logging.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.logging
   :func: command_line_argument_parser
   :prog: py-trees-demo-logging

.. graphviz:: dot/demo-logging.dot

.. image:: images/logging.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import functools
import json
import sys
import time
import typing

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description(root: py_trees.behaviour.Behaviour) -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "A demonstration of logging with trees.\n\n"
    content += "This demo utilises a SnapshotVisitor to trigger\n"
    content += "a post-tick handler to dump a serialisation of the\n"
    content += "tree to a json log file.\n"
    content += "\n"
    content += "This coupling of visitor and post-tick handler can be\n"
    content += "used for any kind of event handling - the visitor is the\n"
    content += "trigger and the post-tick handler the action. Aside from\n"
    content += "logging, the most common use case is to serialise the tree\n"
    content += "for messaging to a graphical, runtime monitor.\n"
    content += "\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Logging".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += py_trees.display.unicode_tree(root)
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(create_tree()),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    group = parser.add_mutually_exclusive_group()
    group.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    group.add_argument(
        "-i",
        "--interactive",
        action="store_true",
        help="pause and wait for keypress at each tick",
    )
    return parser


def logger(
    snapshot_visitor: py_trees.visitors.DisplaySnapshotVisitor,
    behaviour_tree: py_trees.trees.BehaviourTree,
) -> None:
    """Log the tree (relevant parts thereof) to a yaml file.

    Use as a post-tick handler for a tree.
    """
    if snapshot_visitor.changed:
        print(console.cyan + "Logging.......................yes\n" + console.reset)
        tree_serialisation = {"tick": behaviour_tree.count, "nodes": []}
        for node in behaviour_tree.root.iterate():
            node_type_str = "Behaviour"
            for behaviour_type in [
                py_trees.composites.Sequence,
                py_trees.composites.Selector,
                py_trees.composites.Parallel,
                py_trees.decorators.Decorator,
            ]:
                if isinstance(node, behaviour_type):
                    node_type_str = behaviour_type.__name__
            if node.tip() is not None:
                node_tip = node.tip()
                assert node_tip is not None  # help mypy
                node_tip_id = str(node_tip.id)
            else:
                node_tip_id = "none"
            node_snapshot = {
                "name": node.name,
                "id": str(node.id),
                "parent_id": str(node.parent.id) if node.parent else "none",
                "child_ids": [str(child.id) for child in node.children],
                "tip_id": node_tip_id,
                "class_name": str(node.__module__) + "." + str(type(node).__name__),
                "type": node_type_str,
                "status": node.status.value,
                "message": node.feedback_message,
                "is_active": True if node.id in snapshot_visitor.visited else False,
            }
            typing.cast(list, tree_serialisation["nodes"]).append(node_snapshot)
        if behaviour_tree.count == 0:
            with open("dump.json", "w+") as outfile:
                json.dump(tree_serialisation, outfile, indent=4)
        else:
            with open("dump.json", "a") as outfile:
                json.dump(tree_serialisation, outfile, indent=4)
    else:
        print(console.yellow + "Logging.......................no\n" + console.reset)


def create_tree() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    every_n_success = py_trees.behaviours.SuccessEveryN("EveryN", 5)
    sequence = py_trees.composites.Sequence(name="Sequence", memory=True)
    guard = py_trees.behaviours.Success("Guard")
    periodic_success = py_trees.behaviours.Periodic("Periodic", 3)
    finisher = py_trees.behaviours.Success("Finisher")
    sequence.add_child(guard)
    sequence.add_child(periodic_success)
    sequence.add_child(finisher)
    sequence.blackbox_level = py_trees.common.BlackBoxLevel.COMPONENT
    idle = py_trees.behaviours.Success("Idle")
    root = py_trees.composites.Selector(name="Logging", memory=False)
    root.add_child(every_n_success)
    root.add_child(sequence)
    root.add_child(idle)
    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    py_trees.logging.level = py_trees.logging.Level.DEBUG
    tree = create_tree()
    print(description(tree))

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(tree)
        sys.exit()

    ####################
    # Tree Stewardship
    ####################
    behaviour_tree = py_trees.trees.BehaviourTree(tree)

    debug_visitor = py_trees.visitors.DebugVisitor()
    snapshot_visitor = py_trees.visitors.DisplaySnapshotVisitor()

    behaviour_tree.visitors.append(debug_visitor)
    behaviour_tree.visitors.append(snapshot_visitor)

    behaviour_tree.add_post_tick_handler(functools.partial(logger, snapshot_visitor))

    behaviour_tree.setup(timeout=15)

    ####################
    # Tick Tock
    ####################
    if args.interactive:
        py_trees.console.read_single_keypress()
    while True:
        try:
            behaviour_tree.tick()
            if args.interactive:
                py_trees.console.read_single_keypress()
            else:
                time.sleep(0.5)
        except KeyboardInterrupt:
            break
    print("\n")

py-trees-demo-selector

A py_trees demo.

Higher priority switching and interruption in the children of a selector.

In this example the higher priority child is setup to fail initially, falling back to the continually running second child. On the third tick, the first child succeeds and cancels the hitherto running child.

usage: py-trees-demo-selector [-h] [-r]

Named Arguments

-r, --render

render dot tree to file

Default: False

py_trees.demos.selector.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.selector.create_root() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.selector.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.selector.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.selector.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/selector.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.selector
   :func: command_line_argument_parser
   :prog: py-trees-demo-selector

.. graphviz:: dot/demo-selector.dot

.. image:: images/selector.gif

"""
##############################################################################
# Imports
##############################################################################

import argparse
import sys
import time

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "Higher priority switching and interruption in the children of a selector.\n"
    content += "\n"
    content += "In this example the higher priority child is setup to fail initially,\n"
    content += "falling back to the continually running second child. On the third\n"
    content += "tick, the first child succeeds and cancels the hitherto running child.\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Selectors".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    return parser


def create_root() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    root = py_trees.composites.Selector(name="Selector", memory=False)
    ffs = py_trees.behaviours.StatusQueue(
        name="FFS",
        queue=[
            py_trees.common.Status.FAILURE,
            py_trees.common.Status.FAILURE,
            py_trees.common.Status.SUCCESS,
        ],
        eventually=py_trees.common.Status.SUCCESS,
    )
    always_running = py_trees.behaviours.Running(name="Running")
    root.add_children([ffs, always_running])
    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    print(description())
    py_trees.logging.level = py_trees.logging.Level.DEBUG

    root = create_root()

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(root)
        sys.exit()

    ####################
    # Execute
    ####################
    root.setup_with_descendants()
    for i in range(1, 4):
        try:
            print(f"\n--------- Tick {i} ---------\n")
            root.tick_once()
            print("\n")
            print(py_trees.display.unicode_tree(root=root, show_status=True))
            time.sleep(1.0)
        except KeyboardInterrupt:
            break
    print("\n")

py-trees-demo-sequence

A py_trees demo.

Demonstrates sequences in action.

A sequence is populated with 2-tick jobs that are allowed to run through to completion.

usage: py-trees-demo-sequence [-h] [-r]

Named Arguments

-r, --render

render dot tree to file

Default: False

py_trees.demos.sequence.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.sequence.create_root() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.sequence.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.sequence.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.sequence.main() → None

Entry point for the demo script.

Return type:

None

py_trees/demos/sequence.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.sequence
   :func: command_line_argument_parser
   :prog: py-trees-demo-sequence

.. graphviz:: dot/demo-sequence.dot

.. image:: images/sequence.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import sys
import time

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "Demonstrates sequences in action.\n\n"
    content += "A sequence is populated with 2-tick jobs that are allowed to run through to\n"
    content += "completion.\n"

    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Sequences".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    return parser


def create_root() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    root = py_trees.composites.Sequence(name="Sequence", memory=True)
    for action in ["Action 1", "Action 2", "Action 3"]:
        rssss = py_trees.behaviours.StatusQueue(
            name=action,
            queue=[
                py_trees.common.Status.RUNNING,
                py_trees.common.Status.SUCCESS,
            ],
            eventually=py_trees.common.Status.SUCCESS,
        )
        root.add_child(rssss)
    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    print(description())
    py_trees.logging.level = py_trees.logging.Level.DEBUG

    root = create_root()

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(root)
        sys.exit()

    ####################
    # Execute
    ####################
    root.setup_with_descendants()
    for i in range(1, 6):
        try:
            print(f"\n--------- Tick {i} ---------\n")
            root.tick_once()
            print("\n")
            print(py_trees.display.unicode_tree(root=root, show_status=True))
            time.sleep(1.0)
        except KeyboardInterrupt:
            break
    print("\n")

py-trees-demo-tree-stewardship

A py_trees demo.

A demonstration of tree stewardship.

A slightly less trivial tree that uses a simple stdout pre-tick handler and both the debug and snapshot visitors for logging and displaying the state of the tree.

EVENTS

• 3 : sequence switches from running to success

• 4 : selector’s first child flicks to success once only

• 8 : the fallback idler kicks in as everything else fails

• 14 : the first child kicks in again, aborting a running sequence behind it

usage: py-trees-demo-tree-stewardship [-h]
                                      [-r | --render-with-blackboard-variables | -i]

Named Arguments

-r, --render

render dot tree to file

Default: False

--render-with-blackboard-variables

render dot tree to file with blackboard variables

Default: False

-i, --interactive

pause and wait for keypress at each tick

Default: False

class py_trees.demos.stewardship.Finisher

Bases: Behaviour

Gathers blackboard data from other behaviours and prints a summary.

To be used at the end of the tree run.

__init__() → None

Set up the blackboard.

Return type:

None

update() → Status

Fetch blackboard variables and print a summary.

Returns:

Always returns SUCCESS.

Return type:

Status

class py_trees.demos.stewardship.PeriodicSuccess

Bases: Periodic

Write the period from Periodic as a variable on the blackboard.

__init__() → None

Initialise Periodic and set up the blackboard.

Return type:

None

update() → Status

Run the Periodic update and write to blackboard.

Returns:

Returns the Status of Periodic

Return type:

Status

class py_trees.demos.stewardship.SuccessEveryN

Bases: SuccessEveryN

Add a blackboard counter to SuccessEveryN.

__init__() → None

Set up the blackboard.

Return type:

None

update() → Status

Run the SuccessEveryN update and write to blackboard.

Returns:

Returns the Status of SuccessEveryN

Return type:

Status

py_trees.demos.stewardship.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.stewardship.create_tree() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.stewardship.description() → str

Print description and usage information about the program.

Returns:

the program description string

Return type:

str

py_trees.demos.stewardship.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.stewardship.main() → None

Entry point for the demo script.

Return type:

None

py_trees.demos.stewardship.pre_tick_handler(behaviour_tree: BehaviourTree) → None

Generate a simple pre-tick banner printing to stdout.

Parameters:

behaviour_tree (BehaviourTree) –

Return type:

None

py_trees/demos/stewardship.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.stewardship
   :func: command_line_argument_parser
   :prog: py-trees-demo-tree-stewardship

.. graphviz:: dot/demo-tree-stewardship.dot

.. image:: images/tree_stewardship.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import sys
import time

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description() -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "A demonstration of tree stewardship.\n\n"
    content += "A slightly less trivial tree that uses a simple stdout pre-tick handler\n"
    content += "and both the debug and snapshot visitors for logging and displaying\n"
    content += "the state of the tree.\n"
    content += "\n"
    content += "EVENTS\n"
    content += "\n"
    content += " -  3 : sequence switches from running to success\n"
    content += " -  4 : selector's first child flicks to success once only\n"
    content += " -  8 : the fallback idler kicks in as everything else fails\n"
    content += " - 14 : the first child kicks in again, aborting a running sequence behind it\n"
    content += "\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Trees".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    group = parser.add_mutually_exclusive_group()
    group.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    group.add_argument(
        "--render-with-blackboard-variables",
        action="store_true",
        help="render dot tree to file with blackboard variables",
    )
    group.add_argument(
        "-i",
        "--interactive",
        action="store_true",
        help="pause and wait for keypress at each tick",
    )
    return parser


def pre_tick_handler(behaviour_tree: py_trees.trees.BehaviourTree) -> None:
    """Generate a simple pre-tick banner printing to stdout."""
    print(f"\n--------- Run {behaviour_tree.count} ---------\n")


class SuccessEveryN(py_trees.behaviours.SuccessEveryN):
    """Add a blackboard counter to :class:`~py_trees.behaviours.SuccessEveryN`."""

    def __init__(self) -> None:
        """Set up the blackboard."""
        super().__init__(name="EveryN", n=5)
        self.blackboard = self.attach_blackboard_client(name=self.name)
        self.blackboard.register_key("count", access=py_trees.common.Access.WRITE)

    def update(self) -> py_trees.common.Status:
        """
        Run the :class:`~py_trees.behaviours.SuccessEveryN` update and write to blackboard.

        Returns:
            Returns the :class:`~py_trees.common.Status` of :class:`~py_trees.behaviours.SuccessEveryN`
        """
        status = super().update()
        self.blackboard.count = self.count
        return status


class PeriodicSuccess(py_trees.behaviours.Periodic):
    """Write the period from :class:`~py_trees.behaviours.Periodic` as a variable on the blackboard."""

    def __init__(self) -> None:
        """Initialise :class:`~py_trees.behaviours.Periodic` and set up the blackboard."""
        super().__init__(name="Periodic", n=3)
        self.blackboard = self.attach_blackboard_client(name=self.name)
        self.blackboard.register_key("period", access=py_trees.common.Access.WRITE)

    def update(self) -> py_trees.common.Status:
        """
        Run the :class:`~py_trees.behaviours.Periodic` update and write to blackboard.

        Returns:
            Returns the :class:`~py_trees.common.Status` of :class:`~py_trees.behaviours.Periodic`
        """
        status = super().update()
        self.blackboard.period = self.period
        return status


class Finisher(py_trees.behaviour.Behaviour):
    """
    Gathers blackboard data from other behaviours and prints a summary.

    To be used at the end of the tree run.
    """

    def __init__(self) -> None:
        """Set up the blackboard."""
        super().__init__(name="Finisher")
        self.blackboard = self.attach_blackboard_client(name=self.name)
        self.blackboard.register_key("count", access=py_trees.common.Access.READ)
        self.blackboard.register_key("period", access=py_trees.common.Access.READ)

    def update(self) -> py_trees.common.Status:
        """
        Fetch blackboard variables and print a summary.

        Returns:
            Always returns :data:`~py_trees.common.Status.SUCCESS`.
        """
        print(console.green + "---------------------------" + console.reset)
        print(console.bold + "        Finisher" + console.reset)
        print(console.green + f"  Count : {self.blackboard.count}" + console.reset)
        print(console.green + f"  Period: {self.blackboard.period}" + console.reset)
        print(console.green + "---------------------------" + console.reset)
        return py_trees.common.Status.SUCCESS


def create_tree() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    every_n_success = SuccessEveryN()
    sequence = py_trees.composites.Sequence(name="Sequence", memory=True)
    guard = py_trees.behaviours.Success("Guard")
    periodic_success = PeriodicSuccess()
    finisher = Finisher()
    sequence.add_child(guard)
    sequence.add_child(periodic_success)
    sequence.add_child(finisher)
    idle = py_trees.behaviours.Success("Idle")
    root = py_trees.composites.Selector(name="Demo Tree", memory=False)
    root.add_child(every_n_success)
    root.add_child(sequence)
    root.add_child(idle)
    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    py_trees.logging.level = py_trees.logging.Level.DEBUG
    tree = create_tree()
    print(description())

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(tree)
        sys.exit()

    if args.render_with_blackboard_variables:
        py_trees.display.render_dot_tree(tree, with_blackboard_variables=True)
        sys.exit()

    ####################
    # Tree Stewardship
    ####################
    py_trees.blackboard.Blackboard.enable_activity_stream(100)
    behaviour_tree = py_trees.trees.BehaviourTree(tree)
    behaviour_tree.add_pre_tick_handler(pre_tick_handler)
    behaviour_tree.visitors.append(py_trees.visitors.DebugVisitor())
    behaviour_tree.visitors.append(
        py_trees.visitors.DisplaySnapshotVisitor(display_blackboard=True, display_activity_stream=True)
    )
    behaviour_tree.setup(timeout=15)

    ####################
    # Tick Tock
    ####################
    if args.interactive:
        py_trees.console.read_single_keypress()
    while True:
        try:
            behaviour_tree.tick()
            if args.interactive:
                py_trees.console.read_single_keypress()
            else:
                time.sleep(0.5)
        except KeyboardInterrupt:
            break
    print("\n")

py-trees-demo-pick-up-where-you-left-off

A py_trees demo.

A demonstration of the ‘pick up where you left off’ idiom.

A common behaviour tree pattern that allows you to resume work after being interrupted by a high priority interrupt.

EVENTS

• 2 : task one done, task two running

• 3 : high priority interrupt

• 7 : task two restarts

• 9 : task two done

usage: py-trees-demo-pick-up-where-you-left-off [-h] [-r | -i]

Named Arguments

-r, --render

render dot tree to file

Default: False

-i, --interactive

pause and wait for keypress at each tick

Default: False

py_trees.demos.pick_up_where_you_left_off.command_line_argument_parser() → ArgumentParser

Process command line arguments.

Returns:

the argument parser

Return type:

ArgumentParser

py_trees.demos.pick_up_where_you_left_off.create_root() → Behaviour

Create the root behaviour and its subtree.

Returns:

the root behaviour

Return type:

Behaviour

py_trees.demos.pick_up_where_you_left_off.description(root: Behaviour) → str

Print description and usage information about the program.

Returns:

the program description string

Parameters:

root (Behaviour) –

Return type:

str

py_trees.demos.pick_up_where_you_left_off.epilog() → str | None

Print a noodly epilog for –help.

Returns:

the noodly message

Return type:

str | None

py_trees.demos.pick_up_where_you_left_off.main() → None

Entry point for the demo script.

Return type:

None

py_trees.demos.pick_up_where_you_left_off.post_tick_handler(snapshot_visitor: SnapshotVisitor, behaviour_tree: BehaviourTree) → None

Print an ascii tree with the current snapshot status.

Parameters:

• snapshot_visitor (SnapshotVisitor) –

• behaviour_tree (BehaviourTree) –

Return type:

None

py_trees.demos.pick_up_where_you_left_off.pre_tick_handler(behaviour_tree: BehaviourTree) → None

Print a banner immediately before every tick of the tree.

Parameters:

behaviour_tree (BehaviourTree) – the tree custodian

Return type:

None

py_trees/demos/pick_up_where_you_left_off.py

#!/usr/bin/env python
#
# License: BSD
#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
#
##############################################################################
# Documentation
##############################################################################

"""
A py_trees demo.

.. argparse::
   :module: py_trees.demos.pick_up_where_you_left_off
   :func: command_line_argument_parser
   :prog: py-trees-demo-pick-up-where-you-left-off

.. graphviz:: dot/pick_up_where_you_left_off.dot

.. image:: images/pick_up_where_you_left_off.gif
"""

##############################################################################
# Imports
##############################################################################

import argparse
import functools
import sys
import time

import py_trees
import py_trees.console as console

##############################################################################
# Classes
##############################################################################


def description(root: py_trees.behaviour.Behaviour) -> str:
    """
    Print description and usage information about the program.

    Returns:
       the program description string
    """
    content = "A demonstration of the 'pick up where you left off' idiom.\n\n"
    content += "A common behaviour tree pattern that allows you to resume\n"
    content += "work after being interrupted by a high priority interrupt.\n"
    content += "\n"
    content += "EVENTS\n"
    content += "\n"
    content += " -  2 : task one done, task two running\n"
    content += " -  3 : high priority interrupt\n"
    content += " -  7 : task two restarts\n"
    content += " -  9 : task two done\n"
    content += "\n"
    if py_trees.console.has_colours:
        banner_line = console.green + "*" * 79 + "\n" + console.reset
        s = banner_line
        s += console.bold_white + "Pick Up Where you Left Off".center(79) + "\n" + console.reset
        s += banner_line
        s += "\n"
        s += content
        s += "\n"
        s += py_trees.display.unicode_tree(root)
        s += "\n"
        s += banner_line
    else:
        s = content
    return s


def epilog() -> str | None:
    """
    Print a noodly epilog for --help.

    Returns:
       the noodly message
    """
    if py_trees.console.has_colours:
        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
    else:
        return None


def command_line_argument_parser() -> argparse.ArgumentParser:
    """
    Process command line arguments.

    Returns:
        the argument parser
    """
    parser = argparse.ArgumentParser(
        description=description(create_root()),
        epilog=epilog(),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    group = parser.add_mutually_exclusive_group()
    group.add_argument("-r", "--render", action="store_true", help="render dot tree to file")
    group.add_argument(
        "-i",
        "--interactive",
        action="store_true",
        help="pause and wait for keypress at each tick",
    )
    return parser


def pre_tick_handler(behaviour_tree: py_trees.trees.BehaviourTree) -> None:
    """Print a banner immediately before every tick of the tree.

    Args:
        behaviour_tree (:class:`~py_trees.trees.BehaviourTree`): the tree custodian

    """
    print(f"\n--------- Run {behaviour_tree.count} ---------\n")


def post_tick_handler(
    snapshot_visitor: py_trees.visitors.SnapshotVisitor,
    behaviour_tree: py_trees.trees.BehaviourTree,
) -> None:
    """Print an ascii tree with the current snapshot status."""
    print(
        "\n"
        + py_trees.display.unicode_tree(
            root=behaviour_tree.root,
            visited=snapshot_visitor.visited,
            previously_visited=snapshot_visitor.previously_visited,
        )
    )


def create_root() -> py_trees.behaviour.Behaviour:
    """
    Create the root behaviour and its subtree.

    Returns:
        the root behaviour
    """
    task_one = py_trees.behaviours.StatusQueue(
        name="Task 1",
        queue=[
            py_trees.common.Status.RUNNING,
            py_trees.common.Status.RUNNING,
        ],
        eventually=py_trees.common.Status.SUCCESS,
    )
    task_two = py_trees.behaviours.StatusQueue(
        name="Task 2",
        queue=[
            py_trees.common.Status.RUNNING,
            py_trees.common.Status.RUNNING,
        ],
        eventually=py_trees.common.Status.SUCCESS,
    )
    high_priority_interrupt = py_trees.decorators.RunningIsFailure(
        name="Running is Failure",
        child=py_trees.behaviours.Periodic(name="High Priority", n=3),
    )
    piwylo = py_trees.idioms.pick_up_where_you_left_off(name="Pick Up\nWhere You\nLeft Off", tasks=[task_one, task_two])
    root = py_trees.composites.Selector(name="Root", memory=False)
    root.add_children([high_priority_interrupt, piwylo])

    return root


##############################################################################
# Main
##############################################################################


def main() -> None:
    """Entry point for the demo script."""
    args = command_line_argument_parser().parse_args()
    py_trees.logging.level = py_trees.logging.Level.DEBUG
    root = create_root()
    print(description(root))

    ####################
    # Rendering
    ####################
    if args.render:
        py_trees.display.render_dot_tree(root)
        sys.exit()

    ####################
    # Tree Stewardship
    ####################
    behaviour_tree = py_trees.trees.BehaviourTree(root)
    behaviour_tree.add_pre_tick_handler(pre_tick_handler)
    behaviour_tree.visitors.append(py_trees.visitors.DebugVisitor())
    snapshot_visitor = py_trees.visitors.SnapshotVisitor()
    behaviour_tree.add_post_tick_handler(functools.partial(post_tick_handler, snapshot_visitor))
    behaviour_tree.visitors.append(snapshot_visitor)
    behaviour_tree.setup(timeout=15)

    ####################
    # Tick Tock
    ####################
    if args.interactive:
        py_trees.console.read_single_keypress()
    for _unused_i in range(1, 11):
        try:
            behaviour_tree.tick()
            if args.interactive:
                py_trees.console.read_single_keypress()
            else:
                time.sleep(0.5)
        except KeyboardInterrupt:
            break
    print("\n")