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.9.1 (2025-06-19)

• Make sure to install py.typed files (#886)
• Add remaining [py.typed]{.title-ref} (#884)
• Fix [log_*]{.title-ref} warnings (#883)
• Allow Path in substitutions, instead of requiring cast to str (#873)
• Other Logging Implementations with [getLevelNamesMapping]{.title-ref} fix (#866)
• Revert "Add Other Logging Implementations (#858)" (#865) This reverts commit b7b31c45b0eb350deedd282b88398d1ca0d5faf4.
• Add Other Logging Implementations (#858)
• Contributors: Christophe Bedard, Emerson Knapp, Michael Carlstrom

3.9.0 (2025-04-24)

3.8.1 (2025-04-18)

3.8.0 (2025-02-27)

• Add ForEach action to repeat entities using iteration-specific values (#802)
• Stop loading extensions during launch_{xml,yaml} tests. (#820)
• Cleanup the launch dependencies. (#819)
• Contributors: Chris Lalancette, Christophe Bedard

3.7.1 (2024-12-20)

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)

File truncated at 100 lines see the full file