py_trees.common module

Common definitions, methods and variables used by the py_trees library.

class py_trees.common.Access(*values)

Bases: Enum

Use to distinguish types of access to, e.g. variables on a blackboard.

EXCLUSIVE_WRITE = 'EXCLUSIVE_WRITE': Exclusive lock for writing, i.e. no other writer permitted.

READ = 'READ': Read access.

WRITE = 'WRITE': Write access, implicitly also grants read access.

class py_trees.common.BlackBoxLevel(*values)

Bases: IntEnum

A hint used for visualisation.

Whether a behaviour is a blackbox entity that may be considered collapsible (i.e. everything in its subtree will not be visualised) by visualisation tools. DETAIL.

BIG_PICTURE = 3: A blackbox that represents a big picture part of the entire tree view.

COMPONENT = 2: A blackbox that encapsulates a subgroup of functionalities as a single group.

DETAIL = 1: A blackbox that encapsulates detailed activity.

NOT_A_BLACKBOX = 4: Not a blackbox, do not ever collapse.

class py_trees.common.ClearingPolicy(*values)

Bases: IntEnum

Policy rules for behaviours to dictate when data should be cleared/reset.

NEVER = 3: Never clear the data

ON_INITIALISE = 1: Clear when entering the initialise() method.

ON_SUCCESS = 2: Clear when returning SUCCESS.

class py_trees.common.ComparisonExpression(variable: str, value: ComparisonV | Callable[[], ComparisonV], operator: Callable[[ComparisonV, ComparisonV], bool])

Bases: object

Store the parameters for a univariate comparison operation.

A univariate comparison operation compares the relationship between a variable and a value (e.g. x > 3).

Args:: variable: name of the variable to compare value: value or callable to compare against operator: a callable comparison operator

Tip

The python `operator module`_ includes many useful comparison operations, e.g. operator.ne

class py_trees.common.Duration(*values)

Bases: Enum

Naming conventions.

INFINITE = 1.7976931348623157e+308: INFINITE oft used for perpetually blocking operations.

UNTIL_THE_BATTLE_OF_ALFREDO = 1.7976931348623157e+308: UNTIL_THE_BATTLE_OF_ALFREDO is an alias for INFINITE.

class py_trees.common.Name(*values)

Bases: Enum

Naming conventions.

AUTO_GENERATED = 'AUTO_GENERATED': Automagically generate (hopefully) something sensible..

class py_trees.common.OneShotPolicy(*values)

Bases: Enum

Policy rules for oneshots.

These are used to configure both OneShot (decorator) and py:meth:`~py_trees.idioms.oneshot (idiom) approaches.

ON_COMPLETION = [Status.SUCCESS, Status.FAILURE]: Reflect the child/subtree’s status as soon as it ticks to completion (success or failure).

ON_SUCCESSFUL_COMPLETION = [Status.SUCCESS]: Reflect the child/subtree’s status only when it succeeds (failures are rerun).

class py_trees.common.ParallelPolicy

Bases: object

Configurable policies for Parallel behaviours.

class Base(synchronise: bool = False)

Bases: object

Base class for parallel policies. Should never be used directly.

class SuccessOnAll(synchronise: bool = True)

Bases: Base

Success depends on all children succeeding.

Return SUCCESS only when each and every child returns SUCCESS. If synchronisation is requested, any children that tick with SUCCESS will be skipped on subsequent ticks until the policy criteria is met, or one of the children returns status FAILURE.

class SuccessOnOne

Bases: Base

Success depends on just one child (can be any child).

Return SUCCESS so long as at least one child has SUCCESS and the remainder are RUNNING

class SuccessOnSelected(children: List[Any], synchronise: bool = True)

Bases: Base

Success depends on an explicitly selected set of children behaviours.

Return SUCCESS so long as each child in a specified list returns SUCCESS. If synchronisation is requested, any children that tick with SUCCESS will be skipped on subsequent ticks until the policy criteria is met, or one of the children returns status FAILURE.

class py_trees.common.Status(*values)

Bases: Enum

An enumerator representing the status of a behaviour.

FAILURE = 'FAILURE': Behaviour check has failed, or execution of its action finished with a failed result.

INVALID = 'INVALID': Behaviour is uninitialised and/or in an inactive state, i.e. not currently being ticked.

RUNNING = 'RUNNING': Behaviour is in the middle of executing some action, result still pending.

SUCCESS = 'SUCCESS': Behaviour check has passed, or execution of its action has finished with a successful result.

class py_trees.common.VisibilityLevel(*values)

Bases: IntEnum

Flag used by visualisation tools to configure visibility..

Closely associated with the BlackBoxLevel for a behaviour.

This sets the visibility level to be used for visualisations. Visibility levels correspond to reducing levels of visibility in a visualisation.

ALL = 0: Do not collapse any behaviour.

BIG_PICTURE = 3: Collapse any blackbox that isn’t marked with BIG_PICTURE.

COMPONENT = 2: Collapse blackboxes marked with COMPONENT or lower.

DETAIL = 1: Collapse blackboxes marked with DETAIL or lower.

py_trees.common.string_to_visibility_level(level: str) → VisibilityLevel

Will convert a string to a visibility level.

Note that it will quietly return ALL if the string is not matched to any visibility level string identifier.

Args:: level: visibility level as a string
Returns:: VisibilityLevel: visibility level enum

py_trees.common.visibility_level_strings = ['all', 'detail', 'component', 'big_picture']: Convenient string representations to use for command line input (amongst other things).