py_trees.behaviours module

A library of fundamental behaviours for use.

class py_trees.behaviours.BlackboardToStatus(name: str, variable_name: str)

Bases: Behaviour

Reflects a Status stored in a blackboard variable.

This behaviour reverse engineers the StatusToBlackboard decorator. Used in conjuction with that decorator, this behaviour can be used to reflect the status of a decision elsewhere in the tree.

Note

A word of caution. The consequences of a behaviour’s status should be discernable upon inspection of the tree graph. If using StatusToBlackboard and BlackboardToStatus to reflect a behaviour’s status across a tree, this is no longer true. The graph of the tree communicates the local consequences, but not the reflected consequences at the point BlackboardToStatus is used. A recommendation, use this class only where other options are infeasible or impractical.

Args:

variable_name: name of the variable look for, may be nested, e.g. battery.percentage name: name of the behaviour

Raises:

KeyError: if the variable doesn’t exist TypeError: if the variable isn’t of type Status

update() → Status

Check for existence.

Returns:

SUCCESS if key found, FAILURE otherwise.

class py_trees.behaviours.CheckBlackboardVariableExists(name: str, variable_name: str)

Bases: Behaviour

A non-blocking check for the existence of a blackboard variable.

Check the blackboard to verify if a specific variable (key-value pair) exists. This is non-blocking, so will always tick with status FAILURE SUCCESS.

See also

WaitForBlackboardVariable for the blocking counterpart to this behaviour.

Args:

variable_name: name of the variable look for, may be nested, e.g. battery.percentage name: name of the behaviour

update() → Status

Check for existence.

Returns:

SUCCESS if key found, FAILURE otherwise.

class py_trees.behaviours.CheckBlackboardVariableValue(name: str, check: ComparisonExpression)

Bases: Behaviour

Non-blocking check to determine if a blackboard variable matches a given value/expression.

Inspect a blackboard variable and if it exists, check that it meets the specified criteria (given by operation type and expected value). This is non-blocking, so it will always tick with SUCCESS or FAILURE.

Args:

name: name of the behaviour check: a comparison expression to check against

Note

If the variable does not yet exist on the blackboard, the behaviour will return with status FAILURE.

Tip

The python `operator module`_ includes many useful comparison operations.

update() → Status

Check for existence, or the appropriate match on the expected value.

Returns:

Status: FAILURE

if not matched, SUCCESS otherwise.

class py_trees.behaviours.CheckBlackboardVariableValues(name: str, checks: List[ComparisonExpression], operator: Callable[[bool, bool], bool], namespace: str | None = None)

Bases: Behaviour

Apply a logical operation across a set of blackboard variable checks.

This is non-blocking, so will always tick with status FAILURE or SUCCESS.

Args:

checks: a list of comparison checks to apply to blackboard variables logical_operator: a logical check to apply across the results of the blackboard variable checks name: name of the behaviour namespace: optionally store results of the checks (boolean) under this namespace

Tip

The python `operator module`_ includes many useful logical operators, e.g. operator.xor.

Raises:

ValueError if less than two variable checks are specified (insufficient for logical operations)

update() → Status

Apply comparison checks on each and a logical check across all variables.

Returns:

FAILURE if key retrieval or logical

checks failed, SUCCESS otherwise.

class py_trees.behaviours.Dummy(name: str = 'Dummy')

Bases: Behaviour

Crash test dummy used for anything dangerous.

terminate(new_status: Status) → None

Execute user specified instructions when the behaviour is stopped.

Users should override this method to clean up. It will be triggered when a behaviour either finishes execution (switching from RUNNING to FAILURE || SUCCESS) or it got interrupted by a higher priority branch (switching to INVALID). Remember that the initialise() method will handle resetting of variables before re-entry, so this method is about disabling resources until this behaviour’s next tick. This could be a indeterminably long time. e.g.

• cancel an external action that got started

• shut down any temporary communication handles

Args:

new_status (Status): the behaviour is transitioning to this new status

Warning

Do not set self.status = new_status here, that is automatically handled by the stop() method. Use the argument purely for introspection purposes (e.g. comparing the current state in self.status with the state it will transition to in new_status.

See also

py_trees.behaviour.Behaviour.stop()

update() → Status

Define a functor for a crash test dummy behaviour.

Args:

self: behaviour for this function to substitute update() in.

Returns:

behaviour status

class py_trees.behaviours.Failure(name: str = 'Failure')

Bases: Behaviour

Do nothing but tick over with FAILURE.

terminate(new_status: Status) → None

Execute user specified instructions when the behaviour is stopped.

Users should override this method to clean up. It will be triggered when a behaviour either finishes execution (switching from RUNNING to FAILURE || SUCCESS) or it got interrupted by a higher priority branch (switching to INVALID). Remember that the initialise() method will handle resetting of variables before re-entry, so this method is about disabling resources until this behaviour’s next tick. This could be a indeterminably long time. e.g.

• cancel an external action that got started

• shut down any temporary communication handles

Args:

new_status (Status): the behaviour is transitioning to this new status

Warning

Do not set self.status = new_status here, that is automatically handled by the stop() method. Use the argument purely for introspection purposes (e.g. comparing the current state in self.status with the state it will transition to in new_status.

See also

py_trees.behaviour.Behaviour.stop()

update() → Status

Define a functor for an always failing behaviour.

Args:

self: behaviour for this function to substitute update() in.

Returns:

behaviour status

class py_trees.behaviours.Periodic(name: str, n: int)

Bases: Behaviour

Simply periodically rotates it’s status over all each status.

That is, RUNNING for N ticks, SUCCESS for N ticks, FAILURE for N ticks…

Args:

name: name of the behaviour n: period value (in ticks)

Note

It does not reset the count when initialising.

update() → Status

Increment counter and use to decide the current status.

Returns:

the behaviour’s new status Status

class py_trees.behaviours.ProbabilisticBehaviour(name: str, weights: List[float] | None = None)

Bases: Behaviour

Return a status based on a probability distribution. If unspecified - a uniform distribution will be used.

Args:

name: name of the behaviour weights: 3 probabilities that correspond to returning SUCCESS,

FAILURE and RUNNING respectively.

Note

Probability distribution does not need to be normalised, it will be normalised internally.

Raises:

ValueError if only some probabilities are specified

update() → Status

Return a status based on a probability distribution.

Returns:

SUCCESS with probability weights[0], FAILURE with probability weights[1] and RUNNING with probability weights[2].

class py_trees.behaviours.Running(name: str = 'Running')

Bases: Behaviour

Do nothing but tick over with RUNNING.

terminate(new_status: Status) → None

Execute user specified instructions when the behaviour is stopped.

Users should override this method to clean up. It will be triggered when a behaviour either finishes execution (switching from RUNNING to FAILURE || SUCCESS) or it got interrupted by a higher priority branch (switching to INVALID). Remember that the initialise() method will handle resetting of variables before re-entry, so this method is about disabling resources until this behaviour’s next tick. This could be a indeterminably long time. e.g.

• cancel an external action that got started

• shut down any temporary communication handles

Args:

new_status (Status): the behaviour is transitioning to this new status

Warning

Do not set self.status = new_status here, that is automatically handled by the stop() method. Use the argument purely for introspection purposes (e.g. comparing the current state in self.status with the state it will transition to in new_status.

See also

py_trees.behaviour.Behaviour.stop()

update() → Status

Define a functor for an always running behaviour.

Args:

self: behaviour for this function to substitute update() in.

Returns:

behaviour status

class py_trees.behaviours.SetBlackboardVariable(name: str, variable_name: str, variable_value: Any | Callable[[], Any], overwrite: bool)

Bases: Behaviour

Set the specified variable on the blackboard.

Args:

variable_name: name of the variable to set, may be nested, e.g. battery.percentage variable_value: value of the variable to set overwrite: when False, do not set the variable if it already exists name: name of the behaviour

update() → Status

Attempt to set the stored value in the requested blackboard variable.

Returns:

FAILURE if no overwrite requested

and the variable exists, SUCCESS otherwise

class py_trees.behaviours.StatusQueue(name: str, queue: List[Status], eventually: Status | None)

Bases: Behaviour

Cycle through a specified queue of states.

Note

This does not reset when the behaviour initialises.

Args:

name: name of the behaviour sequence: list of status values to cycle through eventually: status to use eventually, None to re-cycle the sequence

terminate(new_status: Status) → None

Log debug information.

Args:

new_status: the behaviour is transitioning to this new status

update() → Status

Pop from the queue or rotate / switch to eventual if the end has been reached.

Returns:

the Status from the popped queue / eventual element

class py_trees.behaviours.Success(name: str = 'Success')

Bases: Behaviour

Do nothing but tick over with SUCCESS.

terminate(new_status: Status) → None

Execute user specified instructions when the behaviour is stopped.

Users should override this method to clean up. It will be triggered when a behaviour either finishes execution (switching from RUNNING to FAILURE || SUCCESS) or it got interrupted by a higher priority branch (switching to INVALID). Remember that the initialise() method will handle resetting of variables before re-entry, so this method is about disabling resources until this behaviour’s next tick. This could be a indeterminably long time. e.g.

• cancel an external action that got started

• shut down any temporary communication handles

Args:

new_status (Status): the behaviour is transitioning to this new status

Warning

Do not set self.status = new_status here, that is automatically handled by the stop() method. Use the argument purely for introspection purposes (e.g. comparing the current state in self.status with the state it will transition to in new_status.

See also

py_trees.behaviour.Behaviour.stop()

update() → Status

Define a functor for an always succeeding behaviour.

Args:

self: behaviour for this function to substitute update() in.

Returns:

behaviour status

class py_trees.behaviours.SuccessEveryN(name: str, n: int)

Bases: Behaviour

Non-blocking, periodic success.

This behaviour updates it’s status with SUCCESS once every N ticks, FAILURE otherwise.

Args:

name: name of the behaviour n: trigger success on every n’th tick

Tip

Use with decorators to change the status value as desired, e.g. py_trees.decorators.FailureIsRunning()

update() → Status

Increment the counter and decide on success/failure from that.

Returns:

SUCCESS if the nth tick, FAILURE otherwise.

class py_trees.behaviours.TickCounter(name: str, duration: int, completion_status: Status)

Bases: Behaviour

Block for a specified tick count.

A useful utility behaviour for demos and tests. Simply ticks with RUNNING for the specified number of ticks before returning the requested completion status (SUCCESS or FAILURE).

This behaviour will reset the tick counter when initialising.

Args:

name: name of the behaviour duration: number of ticks to run completion_status: status to switch to once the counter has expired

initialise() → None

Reset the tick counter.

update() → Status

Increment the tick counter and check to see if it should complete.

Returns

RUNNING while not expired, the given completion status otherwise

class py_trees.behaviours.UnsetBlackboardVariable(name: str, key: str)

Bases: Behaviour

Unset the specified variable (key-value pair) from the blackboard.

This always returns SUCCESS regardless of whether the variable was already present or not.

Args:

key: unset this key-value pair name: name of the behaviour

update() → Status

Unset and always return success.

Returns:

SUCCESS

class py_trees.behaviours.WaitForBlackboardVariable(name: str, variable_name: str)

Bases: CheckBlackboardVariableExists

Block until a blackboard variable comes into existence.

This is blocking, so it will tick with status SUCCESS if the variable is found, and RUNNING otherwise.

See also

CheckBlackboardVariableExists for the non-blocking counterpart to this behaviour.

Args:

variable_name: name of the variable to wait for, may be nested, e.g. battery.percentage name: name of the behaviour

update() → Status

Check for existence, wait otherwise.

Returns:

SUCCESS if key found, RUNNING otherwise.

class py_trees.behaviours.WaitForBlackboardVariableValue(name: str, check: ComparisonExpression)

Bases: CheckBlackboardVariableValue

Block until a blackboard variable matches a given value/expression.

Inspect a blackboard variable and if it exists, check that it meets the specified criteria (given by operation type and expected value). This is blocking, so it will always tick with SUCCESS or RUNNING.

See also

CheckBlackboardVariableValue for the non-blocking counterpart to this behaviour.

Note

If the variable does not yet exist on the blackboard, the behaviour will return with status RUNNING.

Args:

check: a comparison expression to check against name: name of the behaviour

update() → Status

Check for existence, or the appropriate match on the expected value.

Returns:

Status: FAILURE

if not matched, SUCCESS otherwise.

py_trees.behaviours.dummy(self: Behaviour) → Status

Define a functor for a crash test dummy behaviour.

Args:

self: behaviour for this function to substitute update() in.

Returns:

behaviour status

py_trees.behaviours.failure(self: Behaviour) → Status

Define a functor for an always failing behaviour.

Args:

self: behaviour for this function to substitute update() in.

Returns:

behaviour status

py_trees.behaviours.running(self: Behaviour) → Status

Define a functor for an always running behaviour.

Args:

self: behaviour for this function to substitute update() in.

Returns:

behaviour status

py_trees.behaviours.success(self: Behaviour) → Status

Define a functor for an always succeeding behaviour.

Args:

self: behaviour for this function to substitute update() in.

Returns:

behaviour status