launch_xml

This package provides an abstraction of the XML tree.

XML front-end mapping rules

Accessing xml attributes

When having an xml tag like:

<tag value="2"/>

If the entity e is wrapping it, the following statements will be true:

e.get_attr('value') == '2'
e.get_attr('value', data_type=int) == 2
e.get_attr('value', data_type=float) == 2.0

By default, the value of the attribute is returned as a string.

Allowed types are: - scalar types: str, int, float, bool - An uniform list, e.g.: List[int]. - The list of entities type: List[Entity] (see below).

List is the usual object from the typing package. data_type can also be set to None, in which case yaml rules will be used.

For handling lists, the *-sep attribute is used. e.g.:

<tag value="2,3,4" value-sep=","/>
<tag2 value="2 3 4" value-sep=" "/>
<tag3 value="2, 3, 4" value-sep=", "/>

tag.get_attr('value', data_type=List[int]) == [2, 3, 4]
tag2.get_attr('value', data_type=List[float]) == [2.0, 3.0, 4.0]
tag3.get_attr('value', data_type=List[str]) == ['2', '3', '4']

In the case a value can be either an instance of a type or a substitution, the can_be_str argument of get_attr must be used, followed by a call to parser.parse_if_substitutions:

value = e.get_attr('value2', data_type=int, can_be_str=True)
normalized_value = parser.parse_if_substitutions(value)

For checking if an attribute exists, use an optional argument:

value = e.get_attr('value', optional=True)
if value is not None:
    do_something(value)

With optional=False (default), AttributeError is raised if the specified attribute is not found.

Accessing XML children as attributes:

In this xml:

<executable cmd="ls">
    <env name="a" value="100"/>
    <env name="b" value="stuff"/>
</executable>

The env children could be accessed like:

env = e.get_attr('env', data_type=List[Entity])
len(env) == 2
env[0].get_attr('name') == 'a'
env[0].get_attr('value') == '100'
env[1].get_attr('name') == 'b'
env[1].get_attr('value') == 'stuff'

In these cases, e.env is a list of entities, that can be accessed in the same abstract way.

Accessing all the XML children:

All the children can be directly accessed:

e.children

It returns a list of launch_xml.Entity wrapping each of the XML children.

Built-in substitutions

See this document.

Changelog for package launch_xml

3.7.0 (2024-11-20)

• Add test_xmllint to all of the ament_python packages. (#804)
• Contributors: Chris Lalancette

3.6.1 (2024-07-29)

3.6.0 (2024-06-25)

3.5.1 (2024-06-17)

3.5.0 (2024-04-26)

3.4.2 (2024-04-16)

3.4.1 (2024-03-28)

• launch_xml: fix xml syntax in README (#770)
• Contributors: Steve Peters

3.4.0 (2024-02-07)

3.3.0 (2024-01-24)

• Let XML executables/nodes be "required" (like in ROS 1) (#751) * Let XML nodes be "required" Essentially on_exit="shutdown" is equivalent to ROS 1 required="true". This feature is implemented using the python launchfile on_exit mechanism. Right now "shutdown" is the only action accepted by on_exit, but theoretically more "on_exit" actions could be added later. Example: <executable cmd="ls" on_exit="shutdown"/>
  • Added tests for yaml
• Contributors: Matthew Elwin

3.2.1 (2023-12-26)

3.2.0 (2023-10-04)

3.1.0 (2023-09-08)

3.0.1 (2023-09-07)

3.0.0 (2023-08-21)

2.2.1 (2023-07-11)

• Improve launch file parsing error messages (#626)
• Contributors: Timon Engelke

2.2.0 (2023-06-07)

2.1.0 (2023-04-27)

2.0.1 (2023-04-12)

2.0.0 (2023-04-11)

1.4.1 (2023-02-24)

• Fixed typos (#692)
• Contributors: Alejandro Hernández Cordero

1.4.0 (2023-02-14)

• Expose emulate_tty to xml and yaml launch (#669)
• Expose sigterm_timeout and sigkill_timeout to xml frontend (#667)
• [rolling] Update maintainers - 2022-11-07 (#671)
• Contributors: Aditya Pande, Audrow Nash

1.3.0 (2022-11-02)

1.2.0 (2022-09-13)

1.1.0 (2022-04-29)

1.0.1 (2022-04-13)

1.0.0 (2022-04-12)

0.23.1 (2022-04-08)

• Fix sphinx directive to cross-ref Launch method (#605)
• Contributors: Abrar Rahman Protyasha

0.23.0 (2022-03-30)

• Add boolean substitutions (#598)
• Contributors: Kenji Miyake

0.22.0 (2022-03-28)

• Support scoping environment variables (#601)
• Contributors: Jacob Perron

0.21.1 (2022-03-01)

• 'output' is expanded as a substitution in XML/YAML files (#577)
• Contributors: Khush Jain

0.21.0 (2022-01-14)

0.20.0 (2021-11-29)

• Declare frontend group dependency & use explicit dependencies in launch_testing (#520)
• Update maintainers to Aditya Pande and Michel Hidalgo (#559)
• Updated maintainers (#555)
• Add AppendEnvironmentVariable action (#543)
• Feature clear launch configs (#515)
• Fix [DeclareLaunchArgument]{.title-ref} xml parsing and constructor (#529)
• Add 'launch' to sets of launch file extensions (#518)
• Contributors: Aditya Pande, Audrow Nash, Christophe Bedard, Derek Chopp, Ivan Santiago Paunovic

0.19.0 (2021-07-15)

• Make each parser extension provide a set of file extensions (#516)
• Contributors: Christophe Bedard

0.18.0 (2021-06-18)

0.17.0 (2021-04-06)

0.16.0 (2021-03-19)

0.15.0 (2021-01-25)

0.14.0 (2020-12-08)

• Add frontend support for LogInfo action (#467)
• Contributors: Jacob Perron

0.13.0 (2020-11-04)

• Validate unparsed attributes and subentities in launch_xml and launch_yaml (#468)
• Add test for launch.actions.TimerAction (#470)
• Update package maintainers (#465)
• Contributors: Ivan Santiago Paunovic, Michel Hidalgo

0.12.0 (2020-08-18)

0.11.1 (2020-08-14)

0.11.0 (2020-08-04)

• Use new type_utils functions (#438)
• Add pytest.ini so local tests don't display warning (#428)
• Contributors: Chris Lalancette, Ivan Santiago Paunovic

0.10.2 (2020-05-26)

0.10.1 (2020-05-08)

0.10.0 (2020-04-24)

• more verbose test_flake8 error messages (same as ros2/launch_ros#135)
• Use imperative mood in docstrings. (#362)
• Contributors: Dirk Thomas, Steven! Ragnarök

0.9.5 (2019-11-13)

0.9.4 (2019-11-08)

0.9.3 (2019-10-23)

0.9.2 (2019-10-23)

• install resource marker file for packages (#341)
• Contributors: Dirk Thomas

0.9.1 (2019-09-25)

0.9.0 (2019-09-18)

• install package manifest (#330)
• Add deprecated argument to LaunchDescriptionn (#291)
• Add support for not optional environment variable substitution (#288)
• Add parsing methods for SetEnviromentVariable and UnsetEnviromentVariable (#272)
• Add parsing method for [DeclareLaunchArgument]{.title-ref} (#270)
• Add frontend module in launch, launch_xml and launch_yaml packages (#226)
• Contributors: Dirk Thomas, ivanpauno