better_launch.utils.substitutions module

exception better_launch.utils.substitutions.SubstitutionError

Bases: ValueError

Exception type that will be thrown by substitution handlers.

better_launch.utils.substitutions.default_substitution_handlers(eval_type: Literal['full', 'literal', 'none']) → dict[str, Callable]

Returns the default substitution handlers.

Right now the following substitution handlers will be returned: * $(find <filename> <package> <subdir>): return the result of find(). Note that substitution arguments are always sequential (not kwargs). * $(arg <name> <default>): return the value of an argument passed to the launch function or <default> if it doesn’t exist. Raises KeyError if no default is provided and no default was provided. * $(param <full-node-name> <param>): retrieves the value of the ROS parameter <param> from the <full-node-name> (i.e. namespace + node name). Raises KeyError if the node does not exist or ValueError if the node does not have the specified parameter. * $(env <key> <default>): return the value of the environment variable <key> or <default> if it doesn’t exist. Raises KeyError if no default is provided and no default was provided. * $(eval <python-snippet>): returns the result from evaluating the provided <python-snippet>. Typical use cases include simple math and assembling strings. Note that this indeed uses python’s eval().

NOTE this function will most likely be deprecated in the future.

Parameters

eval_typeLiteral[“full”, “literal”, “none”]: How eval substitutions should be handled: eval, ast.literal_eval or not at all.

Returns

dict[str, Callable]: A dict mapping substitution keys to handler functions. Note that handler functions are allowed to throw instances of SubstitutionError when invalid parameters are passed.

better_launch.utils.substitutions.substitute_tokens(text: str, substitutions: dict[str, Callable[[...], str]]) → str

Parses a string and replaces all substitution strings according to the provided handler functions.

Substitution strings are expected to follow the “ROS1 pattern”: $(key *args), where key is a substitution type and *args are additional arguments passed to the substitution handler.

Parameters

textstr: A string that may contain substitution tokens.
substitutionsdict[str, Callable[…, str]]: A dict mapping substitution tokens to handler functions.

Returns

str: The input string with all substitution tokens handled.

Raises

ValueError: If the input string contains unbalanced parentheses or quotes.