launch.actions.declare_launch_argument module

Module for the DeclareLaunchArgument action.

class launch.actions.declare_launch_argument.DeclareLaunchArgument

Bases: Action

Action that declares a new launch argument.

A launch argument is stored in a “launch configuration” of the same name. See launch.actions.SetLaunchConfiguration and launch.substitutions.LaunchConfiguration.

Any launch arguments declared within a launch.LaunchDescription will be exposed as arguments when that launch description is included, e.g. as additional parameters in the launch.actions.IncludeLaunchDescription action or as command-line arguments when launched with ros2 launch ....

In addition to the name, which is also where the argument result is stored, launch arguments may have a default value, a list of valid value choices, and a description. If a default value is given, then the argument becomes optional and the default value is placed in the launch configuration instead. If no default value is given and no value is given when including the launch description, then an error occurs. If a choice list is given, and the given value is not in it, an error occurs.

The default value may use Substitutions, but the name and description can only be Text, since they need a meaningful value before launching, e.g. when listing the command-line arguments.

Note that declaring a launch argument needs to be in a part of the launch description that is describable without launching. For example, if you declare a launch argument with this action from within a condition group or as a callback to an event handler, then it may not be possible for a tool like ros2 launch to know about the argument before launching the launch description. In such cases, the argument will not be visible on the command line but may raise an exception if that argument is not satisfied once visited (and has no default value).

Put another way, the post-condition of this action being visited is either that a launch configuration of the same name is set with a value or an exception is raised because none is set and there is no default value. However, the pre-condition does not guarantee that the argument was visible if behind condition or situational inclusions.

>>> ld = LaunchDescription([
...     DeclareLaunchArgument('simple_argument'),
...     DeclareLaunchArgument('with_default_value', default_value='default'),
...     DeclareLaunchArgument(
...         'with_default_and_description',
...         default_value='some_default',
...         description='this argument is used to configure ...'),
...     DeclareLaunchArgument(
...         'mode',
...         default_value='A',
...         description='Choose between mode A and mode B',
...         choices=['A', 'B']),
...     # other actions here, ...
... ])

<launch>
    <arg name="simple_argument"/>
    <arg name="with_default_value" default_value="default"/>
    <arg name="with_default_and_description" default_value="some_default"
        description="this argument is used to configure ..."/>
</launch>

__init__(name: str, *, default_value: str | Path | Substitution | Iterable[str | Path | Substitution] | None = None, description: str | None = None, choices: List[str] | None = None, **kwargs) → None

Create a DeclareLaunchArgument action.

property choices: List[str] | None

Getter for self.__choices.

property default_value: List[Substitution] | None

Getter for self.__default_value.

property description: str

Getter for self.__description.

execute(context: LaunchContext)

Execute the action.

property name: str

Getter for self.__name.

classmethod parse(entity: Entity, parser: Parser)

Parse arg tag.