py_trees.ports_utils module

Helpers shared between py_trees.ports and py_trees.parsers.

class py_trees.ports_utils.LogLevel(*values)

Bases: Enum

Severity levels accepted by PortsLogger-compatible loggers.

DEBUG = 'debug'

ERROR = 'error'

INFO = 'info'

WARNING = 'warning'

class py_trees.ports_utils.PortsLogger(*args, **kwargs)

Bases: Protocol

Minimal logger interface used by the ports subsystem.

Any object that provides these four methods is accepted wherever the ports code takes an optional logger parameter. This is satisfied by Python’s logging.Logger, py_trees’ py_trees.logging.Logger, and typical ROS 2 loggers.

debug(msg: str) → None

error(msg: str) → None

info(msg: str) → None

warning(msg: str) → None

py_trees.ports_utils.apply_type_hints(constructor: Callable, kwargs: dict[str, Any], logger: PortsLogger | None = None, ignore: set[str] | None = None) → tuple[dict[str, Any], bool]

Convert XML string kwargs into hinted types from the constructor signature.

Keys that are in the ignore set will be kept as-is.

• If constructor is a class, its __init__ is inspected (excluding self).

• Only parameters that have type annotations are converted.

• On conversion failure, the original string is preserved and a warning is printed. The function return indicates that there was a failure in one of the values.

Returns:

tuple[dict[str, Any], bool]: The converted dictionary and a flag set to False if one of

the values was attempted bo convert but it failed (a warning was also printed then).

py_trees.ports_utils.convert_str_to_type(value: str, target_type: type | Union, logger: PortsLogger | None = None) → Any

Convert a string value to target_type (handles unions, list, tuple, enum).

py_trees.ports_utils.find_node_by_class(node: Behaviour, class_: type) → Any

Recursively search a tree for the first node instance of a class.

py_trees.ports_utils.find_node_by_name(node: Behaviour, name: str, strip_prefix: bool = False, strip_uuid: bool = False, find_all: bool = False) → Behaviour | list[Behaviour] | None

Find a node (or nodes) by name in a behavior tree.

py_trees.ports_utils.generate_node_name(explicit_name: str | None, general_name: str = '', prefix: str = '', no_uuid: bool = False) → str

Generate a node name.

Args:

explicit_name: Optional explicit name set by user. general_name: Fallback node category name. prefix: Optional dot-separated parent prefix. no_uuid: If True, do not append UUID when using general_name fallback.

py_trees.ports_utils.get_base_name(name: str, strip_uuid: bool = False) → str

Extract the base name from a fully-qualified name.

Args:

name: The fully-qualified name (e.g., “namespace1.namespace2.NodeName”). strip_uuid: Strip UUID suffix generated by generate_node_name().

py_trees.ports_utils.reset_blackboard_key(blackboard_client: Client, key_name: str, node_name: str = 'unknown') → None

Clear the stored value for key_name via its registered client.

py_trees.ports_utils.sanitize_name_for_blackboard_use(component: str, extra_allowed_chars: str = '') → str

Replace characters py_trees treats as separators with underscores.

py_trees.ports_utils.set_feedback_and_log(behaviour: Behaviour, *, name: str, message: str, level: LogLevel = LogLevel.INFO, logger: PortsLogger | None = None, return_only: bool = False) → str

Format message, update behaviour.feedback_message, and log at level.

py_trees.ports_utils.strip_trailing_uuid4(name: str) → str

Remove a trailing UUID4 suffix from name.

py_trees.ports_utils.uuid4_regex(at_end: bool = False) → str

Return a regex fragment matching a UUID4 string.