Py Trees

https://py-trees.readthedocs.io/en/devel
Admin
Py Trees is a Python library for creating and managing behavior trees, commonly used in AI and...
Tokens:152,748
Snippets:1,114
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### setup(timeout, visitor, **kwargs)

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/trees.html

Initializes the tree by calling setup on each behaviour.

```APIDOC
## setup(timeout: float | common.Duration = common.Duration.INFINITE, visitor: visitors.VisitorBase | None = None, **kwargs: typing.Any) -> None

### Description
Crawls across the tree calling setup on each behaviour. Optionally accepts a visitor for node-by-node analysis.

### Parameters
- **timeout** (float | common.Duration) - Optional - Time to wait for setup.
- **visitor** (visitors.VisitorBase) - Optional - Entity to run on each node after setup.
- **kwargs** (typing.Any) - Optional - Arguments to distribute to behaviours.

### Raises
- **Exception** - If any behaviour raises an exception.
- **RuntimeError** - If the setup times out.
```

--------------------------------

### Setup the behaviour tree

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/trees.html

Initializes all behaviours in the tree by calling their setup methods. Supports optional visitors for node-by-node analysis during setup.

```python
    def setup(
        self,
        timeout: float | common.Duration = common.Duration.INFINITE,
        visitor: visitors.VisitorBase | None = None,
        **kwargs: typing.Any,
    ) -> None:
        """
        Crawl across the tree calling :meth:`~py_trees.behaviour.Behaviour.setup` on each behaviour.

        Visitors can optionally be provided to provide a node-by-node analysis
        on the result of each node's :meth:`~py_trees.behaviour.Behaviour.setup`
        before the next node's :meth:`~py_trees.behaviour.Behaviour.setup` is called.
        This is useful on trees with relatively long setup times to progressively
        report out on the current status of the operation.

        Args:
            timeout: time (s) to wait (use common.Duration.INFINITE to block indefinitely)
            visitor: runnable entities on each node after its setup
            **kwargs: distribute args to this behaviour and in turn, to its children

        Raises:
            Exception: be ready to catch if any of the behaviours raise an exception
            RuntimeError: in case setup() times out
        """
        setup(root=self.root, timeout=timeout, visitor=visitor, **kwargs)
```

--------------------------------

### BehaviourTree.setup

Source: https://py-trees.readthedocs.io/en/devel/modules.html

Crawl across the tree calling setup() on each behaviour.

```APIDOC
## setup(timeout, visitor, **kwargs)

### Description
Crawl across the tree calling setup() on each behaviour. Visitors can optionally be provided to provide a node-by-node analysis on the result of each node’s setup() before the next node’s setup() is called.

### Parameters
- **timeout** (float | py_trees.common.Duration) - Optional - time (s) to wait (use common.Duration.INFINITE to block indefinitely)
- **visitor** (py_trees.visitors.VisitorBase | None) - Optional - runnable entities on each node after its setup
- **kwargs** (Any) - Optional - distribute args to this behaviour and in turn, to its children

### Returns
- **None** (None) - Operation result

### Raises
- **Exception** - be ready to catch if any of the behaviours raise an exception
- **RuntimeError** - in case setup() times out
```

--------------------------------

### Override the setup callback

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/behaviour.html

The setup method is used for infrastructure configuration and validation. It should be used instead of __init__ to ensure resources are available.

```python
def setup(self, **kwargs: typing.Any) -> None:  # noqa: B027
        """
        Set up and verify infrastructure (middleware connections, etc) is available.

        Users should override this method for any configuration and/or validation
        that is necessary prior to ticking the tree. Such construction is best
        done here rather than in __init__ since there is no guarantee at __init__
        that the infrastructure is ready or even available (e.g. you may be just
        rendering dot graphs of the trees, no robot around).

        Examples:
         * establishing a middleware connection to a sensor or driver
         * ensuring a sensor or driver is in a 'ready' state
```

--------------------------------

### Setup a Behaviour Tree

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/trees.html

Initializes a tree by calling setup on all behaviours in the subtree. Supports optional visitors for analysis and timeouts to prevent blocking.

```python
def setup(
    root: behaviour.Behaviour,
    timeout: float | common.Duration = common.Duration.INFINITE,
    visitor: visitors.VisitorBase | None = None,
    **kwargs: typing.Any,
) -> None:
    """
    Crawl across a (sub)tree of behaviours calling :meth:`~py_trees.behaviour.Behaviour.setup` on each behaviour.

    Visitors can optionally be provided to provide a node-by-node analysis
    on the result of each node's :meth:`~py_trees.behaviour.Behaviour.setup`
    before the next node's :meth:`~py_trees.behaviour.Behaviour.setup` is called.
    This is useful on trees with relatively long setup times to progressively
    report out on the current status of the operation.

    Args:
        root: unmanaged (sub)tree root behaviour
        timeout: time (s) to wait (use common.Duration.INFINITE to block indefinitely)
        visitor: runnable entities on each node after its setup
        **kwargs: dictionary of args to distribute to all behaviours in the (sub)tree

    Raises:
        Exception: be ready to catch if any of the behaviours raise an exception
        RuntimeError: in case setup() times out
    """
    # SIGUSR1 is a better choice since it's a user defined operation, but these
    # are not available on windows, so overload one of the standard definitions
    try:
        _SIGNAL = signal.SIGUSR1  # noqa
    except AttributeError:  # windows...
        # SIGINT can get you into trouble if for example, you are using a
        # process manager that plays shenanigans with SIGINT. Nonetheless,
        # it will work in most situations. If a windows user is running into
        # problems, work with them to resolve it.
        _SIGNAL = signal.SIGINT  # noqa
    # Track progress for timeout diagnostics in the signal handler.
    current_behaviour_name: str | None = None

    def on_timer_timed_out() -> None:
        os.kill(os.getpid(), _SIGNAL)

    def signal_handler(
        unused_signum: int,
        unused_frame: types.FrameType,
        original_signal_handler: signal.Handlers | None,
    ) -> None:
        signal.signal(_SIGNAL, original_signal_handler)
        raise RuntimeError(f"tree setup interrupted or timed out [{current_behaviour_name}]")

    def visited_setup() -> None:
        nonlocal current_behaviour_name
        if visitor is not None:
            visitor.initialise()
        for node in root.iterate():
            current_behaviour_name = node.name
            node.setup(**kwargs)
            if visitor is not None:
                node.visit(visitor)
        if visitor is not None:
            visitor.finalise()

    if isinstance(timeout, common.Duration):
        timeout = timeout.value
    if timeout == common.Duration.INFINITE.value:  # math.inf
        visited_setup()
    else:
        original_signal_handler = signal.getsignal(_SIGNAL)
        signal.signal(
            _SIGNAL,
            functools.partial(  # type: ignore
                signal_handler,
                original_signal_handler=original_signal_handler,  # type: ignore
            ),
        )
        try:
            timer = threading.Timer(interval=timeout, function=on_timer_timed_out)
            timer.start()
            visited_setup()
        finally:
            timer.cancel()  # this only works if the timer is still waiting
            signal.signal(_SIGNAL, original_signal_handler)
```

--------------------------------

### Main Entry Point

Source: https://py-trees.readthedocs.io/en/devel/demos.html

Initializes the tree and parses arguments to start the demo.

```python
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()
```

--------------------------------

### Main entry point for the demo

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/demos/pick_up_where_you_left_off.html

Handles command line arguments, tree setup, and the execution loop.

```python
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")
```

--------------------------------

### shutdown()

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/behaviour.html

Destroys setup infrastructure. Users should override this method for custom destruction of resources initialized in setup().

```APIDOC
## shutdown()

### Description
Destroy setup infrastructure (the antithesis of setup). Users should override this method for any custom destruction of infrastructure usually brought into being in setup().

### Returns
- None
```

--------------------------------

### setup(kwargs: Any) -> None

Source: https://py-trees.readthedocs.io/en/devel/modules.html

Prepares the behaviour for execution. This method is typically called before the first tick to verify readiness and initialize middleware or runtime dependencies.

```APIDOC
## setup(kwargs: Any) -> None

### Description
Prepares the behaviour for execution. This method is typically called before the first tick to verify readiness and initialize middleware or runtime dependencies.

### Parameters
- **kwargs** (Any) - Optional - Distribute arguments to this behaviour and its children.

### Returns
- **None**
```

--------------------------------

### setup_with_descendants()

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/behaviour.html

Recursively calls setup on the current behaviour and all of its descendants.

```APIDOC
## setup_with_descendants()

### Description
Call setup on this child, its children, and its children's children.
```

--------------------------------

### py_trees.trees.setup

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/trees.html

Crawl across a (sub)tree of behaviours calling setup on each behaviour.

```APIDOC
## py_trees.trees.setup(root, timeout=common.Duration.INFINITE, visitor=None, **kwargs)

### Description
Crawl across a (sub)tree of behaviours calling :meth:`~py_trees.behaviour.Behaviour.setup` on each behaviour. Visitors can optionally be provided to provide a node-by-node analysis on the result of each node's setup before the next node's setup is called.

### Parameters
- **root** (behaviour.Behaviour) - Required - Unmanaged (sub)tree root behaviour.
- **timeout** (float | common.Duration) - Optional - Time (s) to wait (use common.Duration.INFINITE to block indefinitely).
- **visitor** (visitors.VisitorBase | None) - Optional - Runnable entities on each node after its setup.
- **kwargs** (typing.Any) - Optional - Dictionary of args to distribute to all behaviours in the (sub)tree.

### Raises
- **Exception** - Be ready to catch if any of the behaviours raise an exception.
- **RuntimeError** - In case setup() times out.
```

--------------------------------

### py_trees.behaviour.Behaviour.setup

Source: https://py-trees.readthedocs.io/en/devel/modules.html

Method to override for infrastructure setup and verification.

```APIDOC
## setup(**kwargs: Any) -> None

### Description
Set up and verify infrastructure (middleware connections, etc) is available. Users should override this method for any configuration and/or validation that is necessary prior to ticking the tree.
```

--------------------------------

### Initialize eternal guard demo script

Source: https://py-trees.readthedocs.io/en/devel/demos.html

Initial imports and documentation setup for the eternal guard demonstration script.

```python
  1#!/usr/bin/env python
  2#
  3# License: BSD
  4#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
  5#
  6##############################################################################
  7# Documentation
  8##############################################################################
  9
 10"""
 11A py_trees demo.
 12
 13.. argparse::
 14   :module: py_trees.demos.eternal_guard
 15   :func: command_line_argument_parser
 16   :prog: py-trees-demo-eternal-guard
 17
 18.. graphviz:: dot/demo-eternal-guard.dot
 19
 20.. image:: images/eternal_guard.gif
 21"""
 22
 23##############################################################################
 24# Imports
 25##############################################################################
 26
 27import argparse
 28import functools
 29import sys
 30import time
 31
 32import py_trees
 33import py_trees.console as console
 34
 35##############################################################################
 36# Classes
 37##############################################################################
 38
 39
 40def description(root: py_trees.behaviour.Behaviour) -> str:
 41    """
 42    Print description and usage information about the program.
 43
 44    Returns:
 45       the program description string
 46    """
 47    content = "A demonstration of the 'eternal guard' concept.\n\n"
 48    content += "Two binary (F|S) conditional checks will fire every\n"
```

--------------------------------

### Setup Ports and Blackboard Interface

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/ports.html

Initializes ports, applies remappings, and sets up the blackboard client. Must be called before accessing blackboard or logger properties.

```python
    def setup_ports(
        self,
        port_remappings: dict | None = None,
        subtree_namespace: str = "/",
        logger: PortsLogger | None = None,
    ) -> None:
        """
        Initialize the ports and prepare the blackboard interface.

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

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

        **Port remapping rules**

        1. If a port is *not* in ``port_remappings``, its blackboard key is automatically constructed as
           ``/{subtree_namespace}/{port_name}``.
        2. If a remapped key starts with ``/``, it is treated as an absolute/global key.
        3. If a remapped key does *not* start with ``/``, it is treated as a key relative to the given
           namespace, i.e. ``/{subtree_namespace}/{remapped_key}``.

        **General notes**

        1. The underlying data store is currently the ``py_trees.blackboard``, but this is abstracted.
        2. However, the API of ``PortsMixin`` abstracts from the concept of a blackboard, so the underlying
           implementation could change later.
        3. Think of a "data key" as a generic handle to some shared data storage (like a key in a map),
           which can be remapped to match external system requirements.

        Arguments:
            port_remappings (dict): Optional dictionary mapping port names to custom blackboard keys.
            subtree_namespace (str): Namespace to scope the blackboard client (default: ``"/"``).
            logger: Optional logger-like object with ``debug()``/``info()``/``warning()``/``error()`` methods.
                When ``None``, falls back to ``self.logger`` (the native py_trees logger).

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

        This function must be called before using ``get_input``, ``_set_output``, or accessing the
        ``blackboard`` property.
        """
        if port_remappings is None:
            port_remappings = {}

        name = self.name

        # Consistency check: all ports that are remapped must be present in the input or output ports
        for port in port_remappings:
            if port not in self.input_ports() and port not in self.output_ports():
                raise KeyError(f"Port '{port}' is not present in the input or output ports")

        # Use attach_blackboard_client() so the client is visible in self.blackboards
        # (upstream introspection / display).
        self._blackboard_client = self.attach_blackboard_client(name=name, namespace=subtree_namespace)
        self._ports_logger = logger if logger is not None else self.logger
        self._subtree_namespace = subtree_namespace

        # Register all keys for reading/writing that are remapped
        for port, key in port_remappings.items():
            if port in self.input_ports():
                if CONST_PREFIX in key:
                    local_key = self._constant_storage_key(port)
                    # Register write access temporarily to put constant value
                    self._blackboard_client.register_key(key=local_key, access=py_trees.common.Access.WRITE)

                    # Obtaining the initial direct value
                    raw_value = key.split(CONST_PREFIX, 1)[1]
                    # Replacing the DOT_REPLACEMENT with the actual dot (see comment in DOT_REPLACEMENT definition)
                    value = raw_value.replace(DOT_REPLACEMENT, ".")
```

--------------------------------

### Main Execution Loop

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/demos/eternal_guard.html

The entry point for the demo, handling tree setup, rendering, and the tick execution loop.

```python
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")
```

--------------------------------

### Context Switching Demo Implementation

Source: https://py-trees.readthedocs.io/en/devel/demos.html

The source code for the context switching demonstration script, including the description function and initial setup.

```python
  1#!/usr/bin/env python
  2#
  3# License: BSD
  4#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
  5#
  6##############################################################################
  7# Documentation
  8##############################################################################
  9
 10"""
 11A py_trees demo.
 12
 13.. argparse::
 14   :module: py_trees.demos.context_switching
 15   :func: command_line_argument_parser
 16   :prog: py-trees-demo-context-switching
 17
 18.. graphviz:: dot/demo-context_switching.dot
 19
 20.. image:: images/context_switching.gif
 21"""
 22
 23##############################################################################
 24# Imports
 25##############################################################################
 26
 27import argparse
 28import sys
 29import time
 30
 31import py_trees
 32import py_trees.console as console
 33
 34##############################################################################
 35# Classes
 36##############################################################################
 37
 38
 39def description() -> str:
 40    """
 41    Print description and usage information about the program.
 42
 43    Returns:
 44       the program description string
 45    """
 46    content = "Demonstrates context switching with parallels and sequences.\n"
 47    content += "\n"
 48    content += "A context switching behaviour is run in parallel with a work sequence.\n"
 49    content += "Switching the context occurs in the initialise() and terminate() methods\n"
 50    content += "of the context switching behaviour. Note that whether the sequence results\n"
 51    content += "in failure or success, the context switch behaviour will always call the\n"
 52    content += "terminate() method to restore the context. It will also call terminate()\n"
 53    content += "to restore the context in the event of a higher priority parent cancelling\n"
 54    content += "this parallel subtree.\n"
 55    if py_trees.console.has_colours:
 56        banner_line = console.green + "*" * 79 + "\n" + console.reset
 57        s = banner_line
```

--------------------------------

### Define Ports and Constructor Arguments

Source: https://py-trees.readthedocs.io/en/devel/_sources/ports.rst.txt

Example of a class using ports for remapping and constructor arguments for configuration.

```python
class Greeting(BehaviourWithPorts):

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

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

    def __init__(self, name: str, prefix: str = "Hello", **kwargs):
        super().__init__(name=name, **kwargs)
        self.prefix = prefix        # not a port; populated from XML attribute
```

--------------------------------

### Setup Parallel Composite

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/composites.html

Validates the policy configuration before the behaviour starts ticking.

```python
    def setup(self, **kwargs: typing.Any) -> None:
        """
        Detect before ticking whether the policy configuration is invalid.

        Args:
            **kwargs (:obj:`dict`): distribute arguments to this
               behaviour and in turn, all of its children

        Raises:
            RuntimeError: if the parallel's policy configuration is invalid
            Exception: be ready to catch if any of the children raise an exception
        """
        self.logger.debug(f"{self.__class__.__name__}.setup()")
        self.validate_policy_configuration()
```

--------------------------------

### setup_ports

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/ports.html

Initializes the ports and prepares the blackboard interface for a behavior. This must be called before accessing input/output ports or the blackboard client.

```APIDOC
## setup_ports(port_remappings=None, subtree_namespace='/', logger=None)

### Description
Registers declared input and output ports with the blackboard client, applies custom key remappings, and sets the namespace and logger for the behavior.

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

### Raises
- **KeyError**: If a port in port_remappings is not declared in the port definitions.
```

--------------------------------

### Initialize and run py_trees demo

Source: https://py-trees.readthedocs.io/en/devel/_sources/introduction.rst.txt

Use these commands to set up the environment and execute a demonstration of the behavior tree system.

```bash
uv sync
uv run py-trees-demo-blackboard  # or other demos
```

--------------------------------

### Skeleton Tree Example

Source: https://py-trees.readthedocs.io/en/devel/_sources/trees.rst.txt

Demonstrates the most basic feature of the behaviour tree: its automatic tick-tock mechanism. This example shows how to create a tree and let it run indefinitely.

```python
import py_trees

def main():
    # Create a simple behaviour tree
    root = py_trees.behaviours.Success("Always Succeed")
    tree = py_trees.trees.BehaviourTree(root)

    # Tick the tree indefinitely
    tree.tick_tock(1000)

if __name__ == '__main__':
    main()

```

--------------------------------

### Initialize Blackboard Clients

Source: https://py-trees.readthedocs.io/en/devel/blackboards.html

Demonstrates creating blackboard clients with custom or automatically generated names.

```python
provided = py_trees.blackboard.Client(name="Provided")
print(provided)
generated = py_trees.blackboard.Client()
print(generated)
```

--------------------------------

### Create a custom behaviour skeleton

Source: https://py-trees.readthedocs.io/en/devel/behaviours.html

Inherit from py_trees.behaviour.Behaviour to define custom logic. Use setup for delayed initialization, initialise for pre-tick setup, update for the main execution logic, and terminate for cleanup.

```python
  1#!/usr/bin/env python3
  2"""Example showing how to create a skeleton behaviour."""
  3
  4import random
  5import typing
  6
  7import py_trees
  8
  9
 10class Foo(py_trees.behaviour.Behaviour):
 11    """A skeleton behaviour that inherits from the PyTrees Behaviour class."""
 12
 13    def __init__(self, name: str) -> None:
 14        """
 15        Minimal one-time initialisation.
 16
 17        A good rule of thumb is to only include the initialisation relevant
 18        for being able to insert this behaviour in a tree for offline rendering to dot graphs.
 19
 20        Other one-time initialisation requirements should be met via
 21        the setup() method.
 22        """
 23        super().__init__(name)
 24
 25    def setup(self, **kwargs: typing.Any) -> None:
 26        """
 27        Minimal setup implementation.
 28
 29        When is this called?
 30          This function should be either manually called by your program
 31          to setup this behaviour alone, or more commonly, via
 32          :meth:`~py_trees.behaviour.Behaviour.setup_with_descendants`
 33          or :meth:`~py_trees.trees.BehaviourTree.setup`, both of which
 34          will iterate over this behaviour, its children (its children's
 35          children ...) calling :meth:`~py_trees.behaviour.Behaviour.setup`
 36          on each in turn.
 37
 38          If you have vital initialisation necessary to the success
 39          execution of your behaviour, put a guard in your
 40          :meth:`~py_trees.behaviour.Behaviour.initialise` method
 41          to protect against entry without having been setup.
 42
 43        What to do here?
 44          Delayed one-time initialisation that would otherwise interfere
 45          with offline rendering of this behaviour in a tree to dot graph
 46          or validation of the behaviour's configuration.
 47
 48          Good examples include:
 49
 50          - Hardware or driver initialisation
 51          - Middleware initialisation (e.g. ROS pubs/subs/services)
 52          - A parallel checking for a valid policy configuration after
 53            children have been added or removed
 54        """
 55        self.logger.debug(f"  {self.name} [Foo::setup()]")
 56
 57    def initialise(self) -> None:
 58        """
 59        Minimal initialisation implementation.
 60
 61        When is this called?
 62          The first time your behaviour is ticked and anytime the
 63          status is not RUNNING thereafter.
 64
 65        What to do here?
 66          Any initialisation you need before putting your behaviour
 67          to work.
 68        """
 69        self.logger.debug(f"  {self.name} [Foo::initialise()]")
 70
 71    def update(self) -> py_trees.common.Status:
 72        """
 73        Minimal update implementation.
 74
 75        When is this called?
 76          Every time your behaviour is ticked.
 77
 78        What to do here?
 79          - Triggering, checking, monitoring. Anything...but do not block!
 80          - Set a feedback message
 81          - return a py_trees.common.Status.[RUNNING, SUCCESS, FAILURE]
 82        """
 83        self.logger.debug(f"  {self.name} [Foo::update()]")
 84        ready_to_make_a_decision = random.choice([True, False])
 85        decision = random.choice([True, False])
 86        if not ready_to_make_a_decision:
 87            return py_trees.common.Status.RUNNING
 88        elif decision:
 89            self.feedback_message = "We are not bar!"
 90            return py_trees.common.Status.SUCCESS
 91        else:
 92            self.feedback_message = "Uh oh"
 93            return py_trees.common.Status.FAILURE
 94
 95    def terminate(self, new_status: py_trees.common.Status) -> None:
 96        """
 97        Minimal termination implementation.
 98
 99        When is this called?
100           Whenever your behaviour switches to a non-running state.
101            - SUCCESS || FAILURE : your behaviour's work cycle has finished
102            - INVALID : a higher priority branch has interrupted, or shutting down
103        """
104        self.logger.debug(f"  {self.name} [Foo::terminate().terminate()][{self.status}->{new_status}]")
```

--------------------------------

### BehaviourTree.tip

Source: https://py-trees.readthedocs.io/en/devel/modules.html

Get the tip of the tree.

```APIDOC
## tip()

### Description
Get the tip of the tree.

### Returns
- **py_trees.behaviour.Behaviour | None** - The deepest node (behaviour) that was running before subtree traversal reversed direction, or None if this behaviour’s status is INVALID.
```

--------------------------------

### Main entry point for the logging demo

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/demos/logging.html

Initializes the tree, configures visitors, and runs the tick loop.

```python
[docs]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")
```

--------------------------------

### Main entry point for the demo

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/demos/context_switching.html

Initializes the tree, handles command line arguments for rendering, and executes the tick loop.

```python
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")
```

--------------------------------

### get

Source: https://py-trees.readthedocs.io/en/devel/modules.html

Access a key on the blackboard programmatically.

```APIDOC
## get(name)

### Description
Access a key on the blackboard via method. This is useful when the key name is programmatically generated.

### Parameters
- **name** (str) - Required - Name of the variable to get, can be nested (e.g., battery.percentage).

### Returns
- **Any** - The value associated with the key.
```

--------------------------------

### Main Execution Entry Point

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/demos/blackboard.html

Configures the blackboard, initializes the tree, and handles rendering or execution.

```python
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())
```

--------------------------------

### Behaviour.setup(**kwargs: typing.Any) -> None

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/behaviour.html

A user-customizable callback used to set up and verify infrastructure, such as middleware connections, prior to ticking the tree.

```APIDOC
## Behaviour.setup(**kwargs: typing.Any) -> None

### Description
Set up and verify infrastructure (middleware connections, etc) is available. Users should override this method for any configuration and/or validation that is necessary prior to ticking the tree.

### Parameters
- **kwargs** (typing.Any) - Optional - Arbitrary keyword arguments for configuration.
```

--------------------------------

### Reset Counter Decorator

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/decorators.html

Resets all internal counters to zero during the setup phase.

```python
def setup(self, **kwargs: typing.Any) -> None:
    """Reset the counters."""
    self.total_tick_count = 0
    self.failure_count = 0
    self.running_count = 0
    self.success_count = 0
    self.interrupt_count = 0
```

--------------------------------

### Get class from registry

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/parsers/behaviour_tree_xml.html

Retrieves a class from the node registry, ensuring it is a subclass of PortsMixin.

```python
def get_class_from_registry(class_name: str, node_registry: dict) -> type["PortsMixin"]:
    """
    Get the class from the node_registry dictionary, ensuring it is a subclass of :class:`PortsMixin`.

    Args:
        class_name (str): The name of the class to look up.
        node_registry (dict): A dictionary mapping class names to class constructors or partial callables,
            e.g. ``{"Producer": Producer, "Consumer": partial(Consumer, name=name)}``.

    Returns:
        The class (subclass of :class:`PortsMixin`).

    Raises:
        KeyError: If the class name is not found in the node_registry.
        TypeError: If the entry is not a class or partial callable,
            or if the class is not a subclass of :class:`PortsMixin`.
    """
    if class_name not in node_registry:
        raise KeyError(f"Class name '{class_name}' not found in node_registry: {node_registry}")
    entry = node_registry[class_name]

    # Case 1: Direct class reference
    if inspect.isclass(entry):
        cls = entry
    elif isinstance(entry, functools.partial) and inspect.isclass(entry.func):
        cls = entry.func
    else:
        raise TypeError(f"Unsupported entry type for '{class_name}': {type(entry)}")

    # Validate subclass
    if not issubclass(cls, PortsMixin):
        raise TypeError(f"{cls.__name__} is not a subclass of PortsMixin")

    return cls
```

--------------------------------

### Demo Implementation

Source: https://py-trees.readthedocs.io/en/devel/demos.html

The full source code for the pick-up-where-you-left-off demonstration script.

```python
  1#!/usr/bin/env python
  2#
  3# License: BSD
  4#   https://raw.githubusercontent.com/splintered-reality/py_trees/devel/LICENSE
  5#
  6##############################################################################
  7# Documentation
  8##############################################################################
  9
 10"""
 11A py_trees demo.
 12
 13.. argparse::
 14   :module: py_trees.demos.pick_up_where_you_left_off
 15   :func: command_line_argument_parser
 16   :prog: py-trees-demo-pick-up-where-you-left-off
 17
 18.. graphviz:: dot/pick_up_where_you_left_off.dot
 19
 20.. image:: images/pick_up_where_you_left_off.gif
 21"""
 22
 23##############################################################################
 24# Imports
 25##############################################################################
 26
 27import argparse
 28import functools
 29import sys
 30import time
 31
 32import py_trees
 33import py_trees.console as console
 34
 35##############################################################################
 36# Classes
 37##############################################################################
 38
 39
 40def description(root: py_trees.behaviour.Behaviour) -> str:
 41    """
 42    Print description and usage information about the program.
 43
 44    Returns:
 45       the program description string
 46    """
 47    content = "A demonstration of the 'pick up where you left off' idiom.\n\n"
 48    content += "A common behaviour tree pattern that allows you to resume\n"
 49    content += "work after being interrupted by a high priority interrupt.\n"
 50    content += "\n"
 51    content += "EVENTS\n"
 52    content += "\n"
 53    content += " -  2 : task one done, task two running\n"
 54    content += " -  3 : high priority interrupt\n"
 55    content += " -  7 : task two restarts\n"
 56    content += " -  9 : task two done\n"
 57    content += "\n"
 58    if py_trees.console.has_colours:
 59        banner_line = console.green + "*" * 79 + "\n" + console.reset
 60        s = banner_line
 61        s += console.bold_white + "Pick Up Where you Left Off".center(79) + "\n" + console.reset
 62        s += banner_line
 63        s += "\n"
 64        s += content
 65        s += "\n"
 66        s += py_trees.display.unicode_tree(root)
 67        s += "\n"
 68        s += banner_line
 69    else:
 70        s = content
 71    return s
 72
 73
 74def epilog() -> str | None:
 75    """
 76    Print a noodly epilog for --help.
 77
 78    Returns:
 79       the noodly message
 80    """
 81    if py_trees.console.has_colours:
 82        return console.cyan + "And his noodly appendage reached forth to tickle the blessed...\n" + console.reset
 83    else:
```

--------------------------------

### Parallel.setup

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/composites.html

Prepares the behaviour and validates the policy configuration before ticking.

```APIDOC
## Parallel.setup(**kwargs)

### Description
Detect before ticking whether the policy configuration is invalid.

### Parameters
- **kwargs** (dict) - Optional - Distribute arguments to this behaviour and in turn, all of its children.

### Exceptions
- **RuntimeError** - Raised if the parallel's policy configuration is invalid.
- **Exception** - Raised if any of the children raise an exception.
```

--------------------------------

### py_trees.display.xhtml_tree

Source: https://py-trees.readthedocs.io/en/devel/modules.html

Generates an XHTML snippet representing the tree structure starting from the provided root.

```APIDOC
## py_trees.display.xhtml_tree(root, show_only_visited=False, show_status=False, visited=None, previously_visited=None, indent=0)

### Description
Paint your tree on an xhtml snippet.

### Parameters
- **root** (Behaviour) - Required - The root of the tree, or subtree you want to show.
- **show_only_visited** (bool) - Optional - Show only visited behaviours.
- **show_status** (bool) - Optional - Always show status and feedback message.
- **visited** (dict[uuid.UUID, py_trees.common.Status]) - Optional - Dictionary of (uuid.UUID) and status pairs for behaviours visited on the current tick.
- **previously_visited** (dict[uuid.UUID, py_trees.common.Status]) - Optional - Dictionary of behaviour id/status pairs from the previous tree tick.
- **indent** (int) - Optional - The number of characters to indent the tree.

### Returns
- **str** - An ascii tree as an xhtml snippet.
```

--------------------------------

### Combine auto-registration with explicit entries

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/parsers/behaviour_tree_xml.html

Example of how to extend the default auto-registry with custom partial callables.

```python
node_registry={**py_trees.ports.get_ports_registry(), "Wait": partial(Wait, factory=f)}
```

--------------------------------

### Get absolute reference

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/parsers/behaviour_tree_xml.html

Prepends a subtree namespace to a value to create an absolute path reference.

```python
def get_absolute_reference(value: str, subtree_namespace: str) -> str:
    """
    Get the absolute path of a value (e.g. a key) by prepending the namespace.

    Args:
        value (str): The value to make absolute.
        subtree_namespace (str): The current subtree namespace.

    Returns:
        str: The absolute reference to the value.
    """
    return subtree_namespace.rstrip("/") + "/" + value
```

--------------------------------

### Initialize Blackboard Clients

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/demos/blackboard.html

Sets up separate blackboard clients for parameters and state within a behavior class.

```python
    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)
```

--------------------------------

### Configure port remappings

Source: https://py-trees.readthedocs.io/en/devel/_sources/ports.rst.txt

Use setup_ports to wire node ports to specific blackboard keys after the tree topology is established.

```python
node = Multiply(name="mul")
node.setup_ports(
    port_remappings={
        "a":       "/numbers/a",
        "b":       "/numbers/b",
        "product": "/numbers/product",
    }
)
```

--------------------------------

### Generate Relative Blackboard Key Names

Source: https://py-trees.readthedocs.io/en/devel/modules.html

Examples of how to resolve a key name relative to a specified namespace.

```python
'/' + 'foo'  = 'foo'
'/' + '/foo' = 'foo'
'/foo' + 'bar' = 'bar'
'/foo/' + 'bar' = 'bar'
'/foo' + '/foo/bar' = 'bar'
'/foo/' + '/foo/bar' = 'bar'
'/foo' + 'foo/bar' = 'foo/bar'
'/foo' + '/food/bar' => KeyError('/food/bar' is prefixed with a namespace conflicting with '/foo/')
```

--------------------------------

### Compose behavior trees with XML includes

Source: https://py-trees.readthedocs.io/en/devel/_sources/ports.rst.txt

Examples of defining a library subtree and a main tree that includes it.

```xml
<!-- subtree_library.xml -->
<root>
  <BehaviorTree ID="LibraryTree">
    <Sequence>
      <Producer name="LibProducer" output="{lib_out}"/>
    </Sequence>
  </BehaviorTree>
</root>
```

```xml
<!-- main_tree.xml -->
<root main_tree_to_execute="MainTree">
  <Include src="subtree_library.xml"/>
  <BehaviorTree ID="MainTree">
    <Sequence>
      <SubTree ID="LibraryTree" name="Library" lib_out="{final}"/>
      <Consumer name="FinalConsumer" input="{final}"/>
    </Sequence>
  </BehaviorTree>
</root>
```

--------------------------------

### Main entry point for dot_graphs demo

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/demos/dot_graphs.html

Parses command line arguments, renders the tree to a dot file, and attempts to open it with xdot.

```python
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.demos.context_switching.main

Source: https://py-trees.readthedocs.io/en/devel/demos.html

The entry point for the demo script.

```APIDOC
## py_trees.demos.context_switching.main()

### Description
Entry point for the demo script.
```

--------------------------------

### Define a behavior node in XML

Source: https://py-trees.readthedocs.io/en/devel/_sources/ports.rst.txt

Example of declaring a behavior node with port remapping and constructor arguments in XML.

```xml
<Greeting name="hello_node" name_key="{target}" prefix="Howdy"/>
<!--       ^^^ behaviour name   ^^^ port remap    ^^^ ctor kwarg  -->
```

--------------------------------

### Get subtree tip

Source: https://py-trees.readthedocs.io/en/devel/_modules/py_trees/behaviour.html

Retrieves the deepest node that was running before the traversal reversed direction, or None if the behaviour is invalid.

```python
    def tip(self) -> Behaviour | None:
        """
        Get the *tip* of this behaviour's subtree (if it has one).

        This corresponds to the the deepest node that was running before the
        subtree traversal reversed direction and headed back to this node.

        Returns:
            The deepest node (behaviour) that was running before subtree traversal
            reversed direction, or None if this behaviour's status is
            :data:`~py_trees.common.Status.INVALID`.
        """
        return self if self.status != common.Status.INVALID else None
```
Tokens:
Raw