launch.actions.execute_local module

Module for the ExecuteLocal action.

class launch.actions.execute_local.ExecuteLocal

Bases: Action

Action that begins executing a process on the local system and sets up event handlers.

__init__(*, process_description: ~launch.descriptions.executable.Executable, shell: bool = False, sigterm_timeout: str | ~launch.substitution.Substitution | ~typing.Iterable[str | ~launch.substitution.Substitution] = <launch.substitutions.launch_configuration.LaunchConfiguration object>, sigkill_timeout: str | ~launch.substitution.Substitution | ~typing.Iterable[str | ~launch.substitution.Substitution] = <launch.substitutions.launch_configuration.LaunchConfiguration object>, emulate_tty: bool = False, output: str | ~launch.substitution.Substitution | ~typing.Iterable[str | ~launch.substitution.Substitution] = 'log', output_format: str = '[{this.process_description.final_name}] {line}', cached_output: bool = False, log_cmd: bool = False, on_exit: ~launch.launch_description_entity.LaunchDescriptionEntity | ~typing.Iterable[~launch.launch_description_entity.LaunchDescriptionEntity] | ~typing.Callable[[~launch.events.process.process_exited.ProcessExited, ~launch.launch_context.LaunchContext], ~launch.launch_description_entity.LaunchDescriptionEntity | ~typing.Iterable[~launch.launch_description_entity.LaunchDescriptionEntity] | None] | None = None, respawn: bool | str | ~launch.substitution.Substitution | ~typing.Iterable[str | ~launch.substitution.Substitution] = False, respawn_delay: float | None = None, respawn_max_retries: int = -1, **kwargs) → None

Construct an ExecuteLocal action.

Many arguments are passed eventually to subprocess.Popen, so see the documentation for the class for additional details.

This action, once executed, registers several event handlers for various process related events and will also emit events asynchronously when certain events related to the process occur.

Handled events include:

• launch.events.process.ShutdownProcess:

  • begins standard shutdown procedure for a running executable

• launch.events.process.SignalProcess:

  • passes the signal provided by the event to the running process

• launch.events.process.ProcessStdin:

  • passes the text provided by the event to the stdin of the process

• launch.events.Shutdown:

  • same as ShutdownProcess

Emitted events include:

• launch.events.process.ProcessStarted:

  • emitted when the process starts

• launch.events.process.ProcessExited:

  • emitted when the process exits

  • event contains return code

• launch.events.process.ProcessStdout and launch.events.process.ProcessStderr:

  • emitted when the process produces data on either the stdout or stderr pipes

  • event contains the data from the pipe

Note that output is just stored in this class and has to be properly implemented by the event handlers for the process’s ProcessIO events.

Param:

process_description the launch.descriptions.Executable to execute as a local process

Param:

shell if True, a shell is used to execute the cmd

Param:

sigterm_timeout time until shutdown should escalate to SIGTERM, as a string or a list of strings and Substitutions to be resolved at runtime, defaults to the LaunchConfiguration called ‘sigterm_timeout’

Param:

sigkill_timeout time until escalating to SIGKILL after SIGTERM, as a string or a list of strings and Substitutions to be resolved at runtime, defaults to the LaunchConfiguration called ‘sigkill_timeout’

Param:

emulate_tty emulate a tty (terminal), defaults to False, but can be overridden with the LaunchConfiguration called ‘emulate_tty’, the value of which is evaluated as true or false according to evaluate_condition_expression(). Throws InvalidConditionExpressionError if the ‘emulate_tty’ configuration does not represent a boolean.

Param:

output configuration for process output logging. Defaults to ‘log’ i.e. log both stdout and stderr to launch main log file and stderr to the screen. Overridden externally by the OVERRIDE_LAUNCH_PROCESS_OUTPUT envvar value. See launch.logging.get_output_loggers() documentation for further reference on all available options.

Param:

output_format for logging each output line, supporting str.format() substitutions with the following keys in scope: line to reference the raw output line and this to reference this action instance.

Param:

log_cmd if True, prints the final cmd before executing the process, which is useful for debugging when substitutions are involved.

Param:

cached_output if True, both stdout and stderr will be cached. Use get_stdout() and get_stderr() to read the buffered output.

Param:

on_exit list of actions to execute upon process exit.

Param:

respawn if ‘True’, relaunch the process that abnormally died. Either a boolean or a Substitution to be resolved at runtime. Defaults to ‘False’.

Param:

respawn_delay a delay time to relaunch the died process if respawn is ‘True’.

Param:

respawn_max_retries number of times to respawn the process if respawn is ‘True’. A negative value will respawn an infinite number of times (default behavior).

property emulate_tty

Getter for emulate_tty.

execute(context: LaunchContext) → List[LaunchDescriptionEntity] | None

Execute the action.

This does the following: - register an event handler for the shutdown process event - register an event handler for the signal process event - register an event handler for the stdin event - configures logging for the IO process event - create a task for the coroutine that monitors the process

get_asyncio_future() → Future | None

Return an asyncio Future, used to let the launch system know when we’re done.

get_stderr()

Get cached stdout.

Raises:

RuntimeError – if cached_output is false.

get_stdout()

Get cached stdout.

Raises:

RuntimeError – if cached_output is false.

get_sub_entities()

Return subentities.

property output

Getter for output.

prepare(context: LaunchContext)

Prepare the action for execution.

property process_description

Getter for process_description.

property process_details

Getter for the process details, e.g. name, pid, cmd, etc., or None if not started.

property return_code

Get the process return code, None if it hasn’t finished.

property shell

Getter for shell.

property sigkill_timeout

Getter for sigkill timeout.

property sigterm_timeout

Getter for sigterm timeout.