launch.substitutions package

Submodules

Module contents

Package for substitutions.

class launch.substitutions.AllSubstitution[source]

Bases: Substitution

Substitutes to the string ‘true’ if all of the input arguments evaluate to true.

If any of the arguments evaluates to false, then this substitution returns the string ‘false’.

__init__(*args: str | Path | Substitution | Iterable[str | Path | Substitution], container: Iterable[str | Path | Substitution | Iterable[str | Path | Substitution]] | None = None) → None[source]

Create an AllSubstitution substitution.

The following string arguments evaluate to true: ‘1’, ‘true’, ‘True’, ‘on’ The following string arguments evaluate to false: ‘0’, ‘false’, ‘False’, ‘off’

property args: List[List[Substitution]]

Getter for args.

describe() → str[source]

Return a description of this substitution as a string.

classmethod parse(data: Iterable[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse AllSubstitution substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution.

class launch.substitutions.AndSubstitution[source]

Bases: Substitution

Substitution that returns ‘and’ of the input boolean values.

__init__(left: str | Path | Substitution | Iterable[str | Path | Substitution], right: str | Path | Substitution | Iterable[str | Path | Substitution]) → None[source]

Create an AndSubstitution substitution.

describe() → str[source]

Return a description of this substitution as a string.

property left: List[Substitution]

Getter for left.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse AndSubstitution substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution.

property right: List[Substitution]

Getter for right.

class launch.substitutions.AnonName[source]

Bases: Substitution

Generates an anonymous id based on name.

Name itself is a unique identifier: multiple uses of anon with the same parameter name will create the same “anonymized” name

__init__(name: str | Path | Substitution | Iterable[str | Path | Substitution]) → None[source]

Construct an AnonName substitution.

compute_name(id_value: str) → str[source]

Get anonymous name based on id value.

describe() → str[source]

Return a description of this substitution as a string.

property name: List[Substitution]

Getter for name.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse AnonName substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by creating/getting the anonymous name.

class launch.substitutions.AnySubstitution[source]

Bases: Substitution

Substitutes to the string ‘true’ if at least one of the input arguments evaluates to true.

If none of the arguments evaluate to true, then this substitution returns the string ‘false’.

__init__(*args: str | Path | Substitution | Iterable[str | Path | Substitution], container: Iterable[str | Path | Substitution | Iterable[str | Path | Substitution]] | None = None) → None[source]

Create an AnySubstitution substitution.

The following string arguments evaluate to true: ‘1’, ‘true’, ‘True’, ‘on’

property args: List[List[Substitution]]

Getter for args.

describe() → str[source]

Return a description of this substitution as a string.

classmethod parse(data: Iterable[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse AnySubstitution substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution.

class launch.substitutions.Command[source]

Bases: Substitution

Substitution that gets the output of a command as a string.

If the command is not found or fails a SubstitutionFailure error is raised. Behavior on stderr output is configurable, see constructor.

__init__(command: str | Path | Substitution | Iterable[str | Path | Substitution], *, on_stderr: str | Path | Substitution | Iterable[str | Path | Substitution] = 'fail') → None[source]

Construct a command substitution.

Parameters:

  • command – command to be executed. The substitutions will be performed, and shlex.split will be used on the result.

  • on_stderr – specifies what to do when there is stderr output. Can be one of: - ‘fail’: raises SubstitutionFailere when stderr output is detected. - ‘ignore’: stderr output is ignored. - ‘warn’: The stderr output is ignored, but a warning is logged if detected. - ‘capture’: The stderr output will be captured, together with stdout. It can also be a substitution, that results in one of those four options.

property command: List[Substitution]

Getter for command.

describe() → str[source]

Return a description of this substitution as a string.

property on_stderr: List[Substitution]

Getter for on_stderr.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse Command substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by running the command and capturing its output.

class launch.substitutions.EnvironmentVariable[source]

Bases: Substitution

Substitution that gets an environment variable value as a string.

If the environment variable is not found, it returns empty string.

Note that the environment variable is resolved based on the launch context’s environment (i.e., context.environment) even though the substitution may be associated with an entity that might have a different set of environment variables.

__init__(name: str | Path | Substitution | Iterable[str | Path | Substitution], *, default_value: str | Path | Substitution | Iterable[str | Path | Substitution] | None = None) → None[source]

Construct an environment variable substitution.

Parameters:

  • name – name of the environment variable.

  • default_value – used when the environment variable doesn’t exist. If None, the substitution is not optional.

Raises:

launch.substitutions.substitution_failure.SubstitutionFailure – If the environment variable doesn’t exist and default_value is None.

property default_value: List[Substitution] | None

Getter for default_value.

describe() → str[source]

Return a description of this substitution as a string.

property name: List[Substitution]

Getter for name.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse EnviromentVariable substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by looking up the environment variable.

class launch.substitutions.EqualsSubstitution[source]

Bases: Substitution

Substitution that checks if two inputs are equal.

Returns ‘true’ or ‘false’ strings depending on the result.

__init__(left: Any | Iterable[Any] | None, right: Any | Iterable[Any] | None) → None[source]

Create an EqualsSubstitution substitution.

describe() → str[source]

Return a description of this substitution as a string.

property left: List[Substitution]

Getter for left.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse EqualsSubstitution substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution.

property right: List[Substitution]

Getter for right.

class launch.substitutions.FileContent[source]

Bases: Substitution

Substitution that reads the contents of a file.

If the file is not found a SubstitutionFailure error is raised.

__init__(path: str | Path | Substitution | Iterable[str | Path | Substitution]) → None[source]

Create a FileContent substitution.

describe() → str[source]

Return a description of this substitution as a string.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse FileContent substitution.

property path: List[Substitution]

Getter for path.

perform(context: LaunchContext) → str[source]

Perform the substitution by evaluating the expression.

class launch.substitutions.FindExecutable[source]

Bases: Substitution

Substitution that tries to locate an executable on the PATH.

Raise:

SubstitutionFailure when executable not found

__init__(*, name: str | Path | Substitution | Iterable[str | Path | Substitution]) → None[source]

Create a FindExecutable substitution.

describe() → str[source]

Return a description of this substitution as a string.

property name: List[Substitution]

Getter for name.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse FindExecutable substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by locating the executable on the PATH.

class launch.substitutions.ForEachVar[source]

Bases: Substitution

Substitution for a launch.actions.ForEach iteration variable value.

__init__(name: str | Path | Substitution | Iterable[str | Path | Substitution], *, default_value: str | Path | Substitution | Iterable[str | Path | Substitution] | None = None) → None[source]

Create a ForEachVar.

Parameters:

  • name – the name of the launch.actions.ForEach iteration variable

  • default_value – a default value for the variable if a value is not available for a given iteration

property default_value: List[Substitution] | None
describe() → str[source]

Return a description of this substitution as a string.

When inherited from, calling this base class’s default method is not required.

classmethod get_local_arg_name(name: str) → str[source]
property name: List[Substitution]
classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]
perform(context: LaunchContext) → str[source]

Perform the substitution, given the launch context, and return it as a string.

This should be overridden by the derived classes, and the default raises NotImplementedError.

Raises:

NotImplementedError

class launch.substitutions.ForLoopIndex[source]

Bases: ForEachVar

Substitution for a launch.actions.ForLoop iteration index value.

__init__(name: str | Path | Substitution | Iterable[str | Path | Substitution], **kwargs) → None[source]

Create a ForLoopIndex.

Parameters:

name – the name of the launch.actions.ForLoop index which this substitution is part of

class launch.substitutions.IfElseSubstitution[source]

Bases: Substitution

Substitution that conditionally returns one of two substitutions.

Depending on whether the condition substitution evaluates to true, either it returns the if_value substitution or the else_value substitution.

Example with a boolean launch configuration:

>>> from launch.substitutions import LaunchConfiguration
>>> subst = IfElseSubstitution(
...     LaunchConfiguration("arg"),
...     if_value="arg_evaluated_to_true",
...     else_value="arg_evaluated_to_false")

Combine with boolean substitutions to create more complex conditions. Example with multiple boolean launch configurations:

>>> from launch.substitutions import AllSubstitution
>>> from launch.substitutions import EqualsSubstitution
>>> from launch.substitutions import LaunchConfiguration
>>> from launch.substitutions import NotSubstitution
>>> subst = IfElseSubstitution(
...     AllSubstitution(EqualsSubstitution(LaunchConfiguration("arg1"),
...                                        LaunchConfiguration("arg2")),
...                     NotSubstitution(LaunchConfiguration("arg3"))),
...     if_value="all_args_evaluated_to_true",
...     else_value="at_least_one_arg_evaluated_to_false")
__init__(condition: str | Path | Substitution | Iterable[str | Path | Substitution], if_value: str | Path | Substitution | Iterable[str | Path | Substitution] = '', else_value: str | Path | Substitution | Iterable[str | Path | Substitution] = '') → None[source]

Create a IfElseSubstitution substitution.

property condition: List[Substitution]

Getter for condition.

describe() → str[source]

Return a description of this substitution as a string.

property else_value: List[Substitution]

Getter for else value.

property if_value: List[Substitution]

Getter for if value.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse IfElseSubstitution substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by evaluating the condition.

class launch.substitutions.LaunchConfiguration[source]

Bases: Substitution

Substitution that can access launch configuration variables.

__init__(variable_name: str | Path | Substitution | Iterable[str | Path | Substitution], *, default: Any | Iterable[Any] | None = None) → None[source]

Create a LaunchConfiguration substitution.

describe() → str[source]

Return a description of this substitution as a string.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse FindExecutable substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by retrieving the launch configuration, as a string.

If the launch configuration is not found and a default has been set, the default will be returned, as a string.

property variable_name: List[Substitution]

Getter for variable_name.

class launch.substitutions.LaunchLogDir[source]

Bases: PathSubstitution

Substitution that returns the absolute path to the current launch log directory.

__init__() → None[source]

Create a LaunchLogDir substitution.

describe() → str[source]

Return a description of this substitution as a string.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse LaunchLogDir substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by returning the path to the current launch log directory.

class launch.substitutions.LocalSubstitution[source]

Bases: Substitution

Substitution that can access contextual local variables.

__init__(expression: str, description: str | None = None) → None[source]

Create a LocalSubstitution.

describe() → str[source]

Return a description of this substitution as a string.

property description: str | None

Getter for description.

property expression: str

Getter for expression.

perform(context: LaunchContext) → str[source]

Perform the substitution by retrieving the local variable.

class launch.substitutions.NotEqualsSubstitution[source]

Bases: EqualsSubstitution

Substitution that checks if two inputs are not equal.

Returns ‘true’ or ‘false’ strings depending on the result.

__init__(left: Any | Iterable[Any] | None, right: Any | Iterable[Any] | None) → None[source]

Create a NotEqualsSubstitution substitution.

describe() → str[source]

Return a description of this substitution as a string.

perform(context: LaunchContext) → str[source]

Perform the substitution.

class launch.substitutions.NotSubstitution[source]

Bases: Substitution

Substitution that returns ‘not’ of the input boolean value.

__init__(value: str | Path | Substitution | Iterable[str | Path | Substitution]) → None[source]

Create a NotSubstitution substitution.

describe() → str[source]

Return a description of this substitution as a string.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse NotSubstitution substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution.

property value: List[Substitution]

Getter for value.

class launch.substitutions.OrSubstitution[source]

Bases: Substitution

Substitution that returns ‘or’ of the input boolean values.

__init__(left: str | Path | Substitution | Iterable[str | Path | Substitution], right: str | Path | Substitution | Iterable[str | Path | Substitution]) → None[source]

Create an OrSubstitution substitution.

describe() → str[source]

Return a description of this substitution as a string.

property left: List[Substitution]

Getter for left.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse OrSubstitution substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution.

property right: List[Substitution]

Getter for right.

class launch.substitutions.PathJoinSubstitution[source]

Bases: Substitution

Substitution that join paths, in a platform independent way.

This takes in a list of path components as substitutions. The substitutions for each path component are performed and concatenated, and then all path components are joined.

For example:

PathJoinSubstitution([
    EnvironmentVariable('SOME_DIR'),
    'cfg',
    ['config_', LaunchConfiguration('map'), '.yml']
])

Or:

cfg_dir = PathJoinSubstitution([EnvironmentVariable('SOME_DIR'), 'cfg'])
cfg_file = cfg_dir / ['config_', LaunchConfiguration('map'), '.yml']

If the SOME_DIR environment variable was set to /home/user/dir and the map launch configuration was set to my_map, this would result in a path equal equivalent to (depending on the platform):

'/home/user/dir/cfg/config_my_map.yml'
__init__(substitutions: Iterable[str | Path | Substitution | Iterable[str | Path | Substitution]]) → None[source]

Create a PathJoinSubstitution.

Parameters:

substitutions – the list of path component substitutions to join

perform(context: LaunchContext) → str[source]

Perform the substitutions and join into a path.

property substitutions: List[List[Substitution]]

Getter for substitutions.

class launch.substitutions.PathSubstitution[source]

Bases: PathJoinSubstitution

Thin wrapper on PathJoinSubstitution for more pathlib.Path-like construction.

PathSubstitution(LaunchConfiguration('base_dir')) / 'sub_dir' / 'file_name'

Which, for base_dir:=/my_dir, results in (depending on the platform):

/my_dir/sub_dir/file_name
__init__(path: str | Path | Substitution | Iterable[str | Path | Substitution])[source]

Create a PathSubstitution.

Parameters:

path – May be a single text or Substitution element,

or an Iterable of them which are then joined

class launch.substitutions.PythonExpression[source]

Bases: Substitution

Substitution that can access contextual local variables.

The expression may contain Substitutions, but must return something that can be converted to a string with str(). It also may contain math symbols and functions.

__init__(expression: str | Path | Substitution | Iterable[str | Path | Substitution], python_modules: str | Path | Substitution | Iterable[str | Path | Substitution] = ['math']) → None[source]

Create a PythonExpression substitution.

describe() → str[source]

Return a description of this substitution as a string.

property expression: List[Substitution]

Getter for expression.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse PythonExpression substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by evaluating the expression.

property python_modules: List[Substitution]

Getter for python modules.

class launch.substitutions.StringJoinSubstitution[source]

Bases: Substitution

Substitution that joins strings and/or other substitutions.

This takes in a list of string components as substitutions. The substitutions for each string component are performed and concatenated, and then all string components are joined with a specified delimiter as seperation.

For example:

StringJoinSubstitution(
    [['https', '://'], LaunchConfiguration('subdomain')], 'ros', 'org'],
    delimiter='.'
)

If the subdomain launch configuration was set to docs and the delimiter to ., this would result in a string equal to

'https://docs.ros.org'
__init__(substitutions: Iterable[str | Path | Substitution | Iterable[str | Path | Substitution]], delimiter: str | Path | Substitution | Iterable[str | Path | Substitution] = '') → None[source]

Create a StringJoinSubstitution.

Parameters:

  • substitutions – the list of string component substitutions to join

  • delimiter – the text inbetween two consecutive components (default no text)

property delimiter: List[Substitution]

Getter for delimiter.

perform(context: LaunchContext) → str[source]

Perform the substitution by retrieving the local variable.

property substitutions: List[List[Substitution]]

Getter for substitutions.

exception launch.substitutions.SubstitutionFailure[source]

Bases: RuntimeError

Raised when a Substitution fails.

__init__(msg)[source]

Create a SubstitutionFailure error.

class launch.substitutions.TextSubstitution[source]

Bases: Substitution

Substitution that wraps a single string text.

__init__(*, text: str) → None[source]

Create a TextSubstitution.

describe() → str[source]

Return a description of this substitution as a string.

perform(context: LaunchContext) → str[source]

Perform the substitution by returning the string itself.

property text: str

Getter for text.

class launch.substitutions.ThisLaunchFile[source]

Bases: Substitution

Substitution that returns the absolute path to the current launch file.

__init__() → None[source]

Create a ThisLaunchFile substitution.

describe() → str[source]

Return a description of this substitution as a string.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse ThisLaunchFile substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by returning the path to the current launch file.

If there is no current launch file, i.e. if run from a script, then an error is raised.

Raises:

SubstitutionFailure if not in a launch file

class launch.substitutions.ThisLaunchFileDir[source]

Bases: PathSubstitution

Substitution that returns the absolute path to the current launch file.

__init__() → None[source]

Create a ThisLaunchFileDir substitution.

describe() → str[source]

Return a description of this substitution as a string.

classmethod parse(data: Sequence[str | Path | Substitution | Iterable[str | Path | Substitution]])[source]

Parse ThisLaunchFileDir substitution.

perform(context: LaunchContext) → str[source]

Perform the substitution by returning the path to the current launch file.

If there is no current launch file, i.e. if run from a script, then an error is raised.

Raises:

launch.substitutions.substitution_failure.SubstitutionFailure – if not in a launch file