launch_yaml

This package provides an abstraction of the YAML tree.

YAML front-end mapping rules

Accessing yaml attributes

When having an YAML file like:

tag:
    value1: '2'
    value2: 2
    value3: 2.0

If the entity e is wrapping tag, the following statement will be true:

e.get_attr('value1') == '2'
e.get_attr('value2', data_type=int) == 2
e.get_attr('value3', data_type=float) == 2.0

By default, get_attr returns an string and it does type checking. The following code will raise a TypeError:

e.get_attr('value1', data_type=int)
e.get_attr('value2', data_type=float)
e.get_attr('value3')

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 any of the following scalar types or uniform lists of them are allowed:

int, float, bool, str

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 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 it is not found.

Accessing attributes that are also an Entity:

In this yaml:

executable:
    cmd: ls
    env:
        - name: a
        - value: '100'
        - name: b
        - value: 'stuff'

The env children could be accessed doing:

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 children:

All the children can be directly accessed. e.g.:

group:
    - executable:
        cmd: ls
    - executable:
        cmd: ps

e.children

or:

group:
    scoped: False
    children:
        - executable:
            cmd: ls
        - executable:
            cmd: ps

e.children

It returns a list of launch_xml.Entity wrapping each of the xml children. In the example, the list has two Entity objects wrapping each of the executable tags.

Built-in substitutions

See this document.

Changelog for package launch_yaml

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)

3.4.0 (2024-02-07)

• Fix flake8 warnings in launch_yaml. (#756)
• Contributors: Chris Lalancette

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)

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)
• Add 'launch' to sets of launch file extensions (#518)
• Contributors: Aditya Pande, Audrow Nash, Christophe Bedard, Derek Chopp

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)
• 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)
• Close YAML file when we're done. (#415)
• Add pytest.ini so local tests don't display warning (#428)
• Contributors: Chris Lalancette, Dan Rose, 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 frontend module in launch, launch_xml and launch_yaml packages (#226)
• Contributors: Dirk Thomas, ivanpauno