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.collect_type_hints(constructor: Callable) → dict[str, Any]

Collect parameter type hints from a constructor.

When constructor is a class, the method resolution order (MRO) is walked so that a type hint declared on a parent’s __init__ is still found when the subclass forwards **kwargs to super().__init__(), and therefore does not declare the parameter itself, or declares it without an annotation.

The most-derived annotation for a given parameter name wins: walking the MRO from subclass to base and only recording the first hint seen per parameter.

Args:

constructor: A class (whose __init__ chain is inspected) or a callable.

Returns:

dict[str, Any]: Mapping of parameter name to its type annotation. Parameters

without an annotation anywhere in the hierarchy are omitted, as are self and any *args/**kwargs catch-alls.

py_trees.ports_utils.convert_str_to_type(value: str, target_type: type | UnionType, 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.