launch.substitutions package

Submodules

• launch.substitutions.anon_name module
  • AnonName
    • AnonName.__init__()
    • AnonName.compute_name()
    • AnonName.describe()
    • AnonName.name
    • AnonName.parse()
    • AnonName.perform()
• launch.substitutions.boolean_substitution module
  • AllSubstitution
    • AllSubstitution.__init__()
    • AllSubstitution.args
    • AllSubstitution.describe()
    • AllSubstitution.parse()
    • AllSubstitution.perform()
  • AndSubstitution
    • AndSubstitution.__init__()
    • AndSubstitution.describe()
    • AndSubstitution.left
    • AndSubstitution.parse()
    • AndSubstitution.perform()
    • AndSubstitution.right
  • AnySubstitution
    • AnySubstitution.__init__()
    • AnySubstitution.args
    • AnySubstitution.describe()
    • AnySubstitution.parse()
    • AnySubstitution.perform()
  • NotSubstitution
    • NotSubstitution.__init__()
    • NotSubstitution.describe()
    • NotSubstitution.parse()
    • NotSubstitution.perform()
    • NotSubstitution.value
  • OrSubstitution
    • OrSubstitution.__init__()
    • OrSubstitution.describe()
    • OrSubstitution.left
    • OrSubstitution.parse()
    • OrSubstitution.perform()
    • OrSubstitution.right
• launch.substitutions.command module
  • Command
    • Command.__init__()
    • Command.command
    • Command.describe()
    • Command.on_stderr
    • Command.parse()
    • Command.perform()
• launch.substitutions.environment_variable module
  • EnvironmentVariable
    • EnvironmentVariable.__init__()
    • EnvironmentVariable.default_value
    • EnvironmentVariable.describe()
    • EnvironmentVariable.name
    • EnvironmentVariable.parse()
    • EnvironmentVariable.perform()
• launch.substitutions.equals_substitution module
  • EqualsSubstitution
    • EqualsSubstitution.__init__()
    • EqualsSubstitution.describe()
    • EqualsSubstitution.left
    • EqualsSubstitution.parse()
    • EqualsSubstitution.perform()
    • EqualsSubstitution.right
• launch.substitutions.file_content module
  • FileContent
    • FileContent.__init__()
    • FileContent.describe()
    • FileContent.parse()
    • FileContent.path
    • FileContent.perform()
• launch.substitutions.find_executable module
  • FindExecutable
    • FindExecutable.__init__()
    • FindExecutable.describe()
    • FindExecutable.name
    • FindExecutable.parse()
    • FindExecutable.perform()
• launch.substitutions.if_else_substitution module
  • IfElseSubstitution
    • IfElseSubstitution.__init__()
    • IfElseSubstitution.condition
    • IfElseSubstitution.describe()
    • IfElseSubstitution.else_value
    • IfElseSubstitution.if_value
    • IfElseSubstitution.parse()
    • IfElseSubstitution.perform()
• launch.substitutions.launch_configuration module
  • LaunchConfiguration
    • LaunchConfiguration.__init__()
    • LaunchConfiguration.describe()
    • LaunchConfiguration.parse()
    • LaunchConfiguration.perform()
    • LaunchConfiguration.variable_name
• launch.substitutions.launch_log_dir module
  • LaunchLogDir
    • LaunchLogDir.__init__()
    • LaunchLogDir.describe()
    • LaunchLogDir.parse()
    • LaunchLogDir.perform()
• launch.substitutions.local_substitution module
  • LocalSubstitution
    • LocalSubstitution.__init__()
    • LocalSubstitution.describe()
    • LocalSubstitution.description
    • LocalSubstitution.expression
    • LocalSubstitution.perform()
• launch.substitutions.not_equals_substitution module
  • NotEqualsSubstitution
    • NotEqualsSubstitution.__init__()
    • NotEqualsSubstitution.describe()
    • NotEqualsSubstitution.perform()
• launch.substitutions.path_join_substitution module
  • PathJoinSubstitution
    • PathJoinSubstitution.__init__()
    • PathJoinSubstitution.describe()
    • PathJoinSubstitution.perform()
    • PathJoinSubstitution.substitutions
• launch.substitutions.python_expression module
  • PythonExpression
    • PythonExpression.__init__()
    • PythonExpression.describe()
    • PythonExpression.expression
    • PythonExpression.parse()
    • PythonExpression.perform()
    • PythonExpression.python_modules
• launch.substitutions.substitution_failure module
  • SubstitutionFailure
    • SubstitutionFailure.__init__()
• launch.substitutions.text_substitution module
  • TextSubstitution
    • TextSubstitution.__init__()
    • TextSubstitution.describe()
    • TextSubstitution.perform()
    • TextSubstitution.text
• launch.substitutions.this_launch_file module
  • ThisLaunchFile
    • ThisLaunchFile.__init__()
    • ThisLaunchFile.describe()
    • ThisLaunchFile.parse()
    • ThisLaunchFile.perform()
• launch.substitutions.this_launch_file_dir module
  • ThisLaunchFileDir
    • ThisLaunchFileDir.__init__()
    • ThisLaunchFileDir.describe()
    • ThisLaunchFileDir.parse()
    • ThisLaunchFileDir.perform()

Module contents

Package for substitutions.

class launch.substitutions.AllSubstitution

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 | Substitution | Iterable[str | Substitution]) → None

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

Return a description of this substitution as a string.

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

Parse AllSubstitution substitution.

perform(context: LaunchContext) → str

Perform the substitution.

class launch.substitutions.AndSubstitution

Bases: Substitution

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

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

Create an AndSubstitution substitution.

describe() → str

Return a description of this substitution as a string.

property left: List[Substitution]

Getter for left.

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

Parse AndSubstitution substitution.

perform(context: LaunchContext) → str

Perform the substitution.

property right: List[Substitution]

Getter for right.

class launch.substitutions.AnonName

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 | Substitution | Iterable[str | Substitution]) → None

Construct an AnonName substitution.

compute_name(id_value: str) → str

Get anonymous name based on id value.

describe() → str

Return a description of this substitution as a string.

property name: List[Substitution]

Getter for name.

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

Parse AnonName substitution.

perform(context: LaunchContext) → str

Perform the substitution by creating/getting the anonymous name.

class launch.substitutions.AnySubstitution

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 | Substitution | Iterable[str | Substitution]) → None

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

Return a description of this substitution as a string.

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

Parse AnySubstitution substitution.

perform(context: LaunchContext) → str

Perform the substitution.

class launch.substitutions.Command

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 | Substitution | Iterable[str | Substitution], *, on_stderr: str | Substitution | Iterable[str | Substitution] = 'fail') → None

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

Return a description of this substitution as a string.

property on_stderr: List[Substitution]

Getter for on_stderr.

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

Parse Command substitution.

perform(context: LaunchContext) → str

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

class launch.substitutions.EnvironmentVariable

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 | Substitution | Iterable[str | Substitution], *, default_value: str | Substitution | Iterable[str | Substitution] | None = None) → None

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

Return a description of this substitution as a string.

property name: List[Substitution]

Getter for name.

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

Parse EnviromentVariable substitution.

perform(context: LaunchContext) → str

Perform the substitution by looking up the environment variable.

class launch.substitutions.EqualsSubstitution

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

Create an EqualsSubstitution substitution.

describe() → str

Return a description of this substitution as a string.

property left: List[Substitution]

Getter for left.

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

Parse EqualsSubstitution substitution.

perform(context: LaunchContext) → str

Perform the substitution.

property right: List[Substitution]

Getter for right.

class launch.substitutions.FileContent

Bases: Substitution

Substitution that reads the contents of a file.

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

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

Create a FileContent substitution.

describe() → str

Return a description of this substitution as a string.

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

Parse FileContent substitution.

property path: List[Substitution]

Getter for path.

perform(context: LaunchContext) → str

Perform the substitution by evaluating the expression.

class launch.substitutions.FindExecutable

Bases: Substitution

Substitution that tries to locate an executable on the PATH.

Raise:

SubstitutionFailure when executable not found

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

Create a FindExecutable substitution.

describe() → str

Return a description of this substitution as a string.

property name: List[Substitution]

Getter for name.

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

Parse FindExecutable substitution.

perform(context: LaunchContext) → str

Perform the substitution by locating the executable on the PATH.

class launch.substitutions.IfElseSubstitution

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 | Substitution | Iterable[str | Substitution], if_value: str | Substitution | Iterable[str | Substitution] = '', else_value: str | Substitution | Iterable[str | Substitution] = '') → None

Create a IfElseSubstitution substitution.

property condition: List[Substitution]

Getter for condition.

describe() → str

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 | Substitution | Iterable[str | Substitution]])

Parse IfElseSubstitution substitution.

perform(context: LaunchContext) → str

Perform the substitution by evaluating the condition.

class launch.substitutions.LaunchConfiguration

Bases: Substitution

Substitution that can access launch configuration variables.

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

Create a LaunchConfiguration substitution.

describe() → str

Return a description of this substitution as a string.

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

Parse FindExecutable substitution.

perform(context: LaunchContext) → str

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

Bases: Substitution

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

__init__() → None

Create a LaunchLogDir substitution.

describe() → str

Return a description of this substitution as a string.

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

Parse LaunchLogDir substitution.

perform(context: LaunchContext) → str

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

class launch.substitutions.LocalSubstitution

Bases: Substitution

Substitution that can access contextual local variables.

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

Create a LocalSubstitution.

describe() → str

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

Perform the substitution by retrieving the local variable.

class launch.substitutions.NotEqualsSubstitution

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

Create a NotEqualsSubstitution substitution.

describe() → str

Return a description of this substitution as a string.

perform(context: LaunchContext) → str

Perform the substitution.

class launch.substitutions.NotSubstitution

Bases: Substitution

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

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

Create a NotSubstitution substitution.

describe() → str

Return a description of this substitution as a string.

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

Parse NotSubstitution substitution.

perform(context: LaunchContext) → str

Perform the substitution.

property value: List[Substitution]

Getter for value.

class launch.substitutions.OrSubstitution

Bases: Substitution

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

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

Create an OrSubstitution substitution.

describe() → str

Return a description of this substitution as a string.

property left: List[Substitution]

Getter for left.

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

Parse OrSubstitution substitution.

perform(context: LaunchContext) → str

Perform the substitution.

property right: List[Substitution]

Getter for right.

class launch.substitutions.PathJoinSubstitution

Bases: Substitution

Substitution that join paths, in a platform independent way.

__init__(substitutions: Iterable[str | Substitution]) → None

Create a PathJoinSubstitution.

describe() → str

Return a description of this substitution as a string.

perform(context: LaunchContext) → str

Perform the substitution by retrieving the local variable.

property substitutions: Iterable[Substitution]

Getter for variable_name.

class launch.substitutions.PythonExpression

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 | Substitution | Iterable[str | Substitution], python_modules: str | Substitution | Iterable[str | Substitution] = ['math']) → None

Create a PythonExpression substitution.

describe() → str

Return a description of this substitution as a string.

property expression: List[Substitution]

Getter for expression.

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

Parse PythonExpression substitution.

perform(context: LaunchContext) → str

Perform the substitution by evaluating the expression.

property python_modules: List[Substitution]

Getter for python modules.

exception launch.substitutions.SubstitutionFailure

Bases: RuntimeError

Raised when a Substitution fails.

__init__(msg)

Create a SubstitutionFailure error.

class launch.substitutions.TextSubstitution

Bases: Substitution

Substitution that wraps a single string text.

__init__(*, text: str) → None

Create a TextSubstitution.

describe() → str

Return a description of this substitution as a string.

perform(context: LaunchContext) → str

Perform the substitution by returning the string itself.

property text: str

Getter for text.

class launch.substitutions.ThisLaunchFile

Bases: Substitution

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

__init__() → None

Create a ThisLaunchFile substitution.

describe() → str

Return a description of this substitution as a string.

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

Parse ThisLaunchFile substitution.

perform(context: LaunchContext) → str

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

Bases: Substitution

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

__init__() → None

Create a ThisLaunchFileDir substitution.

describe() → str

Return a description of this substitution as a string.

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

Parse ThisLaunchFileDir substitution.

perform(context: LaunchContext) → str

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