Process reference¶

SubprocessRunner ¶

A class for managing the execution of external commands. This is available as the Application.subprocess property.

run ¶

run(
    command: list[str],
    *,
    check: bool = True,
    env: dict[str, str] | None = None,
    cwd: str | Path | None = None,
    encoding: str = "utf-8",
) -> int

Run a command and wait for it to complete.

Warning

Programs that require user interaction should use the attach method instead.

Parameters:

Name	Type	Description	Default
`command`	`list[str]`	The command to run.	required
`check`	`bool`	Whether to abort the application if the command exits with a non-zero exit code.	`True`
`env`	`dict[str, str] \| None`	The environment variables to include in the command's environment.	`None`
`cwd`	`str \| Path \| None`	The working directory in which to run the command.	`None`
`encoding`	`str`	The encoding used to decode the command's output.	`'utf-8'`

Returns:

Type	Description
`int`	The command's exit code.

capture ¶

capture(
    command: list[str],
    *,
    cross_streams: bool = True,
    show: bool = False,
    check: bool = True,
    env: dict[str, str] | None = None,
    cwd: str | Path | None = None,
    encoding: str = "utf-8",
    **kwargs: Any,
) -> str

Run a command and capture its output.

Parameters:

Name	Type	Description	Default
`command`	`list[str]`	The command to run.	required
`cross_streams`	`bool`	Whether to merge the command's standard error stream into its standard output stream.	`True`
`show`	`bool`	Whether to display the command's output while capturing it.	`False`
`check`	`bool`	Whether to abort the application if the command exits with a non-zero exit code.	`True`
`env`	`dict[str, str] \| None`	The environment variables to include in the command's environment.	`None`
`cwd`	`str \| Path \| None`	The working directory in which to run the command.	`None`
`encoding`	`str`	The encoding used to decode the command's output.	`'utf-8'`

Returns:

Type	Description
`str`	The command's standard output.

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `attach` method when `show` is `False`.

wait ¶

wait(
    command: list[str],
    *,
    message: str = "",
    check: bool = True,
    env: dict[str, str] | None = None,
    cwd: str | Path | None = None,
    encoding: str = "utf-8",
) -> None

Run a command and wait for it to complete. By default, the command output is hidden but will be displayed if the configured verbosity level is at least Verbosity.VERBOSE. Under that circumstance, this method is a mere pass-through to the run method.

Parameters:

Name	Type	Description	Default
`command`	`list[str]`	The command to run.	required
`message`	`str`	The message to display while the command is running. Has no effect if the verbosity level is less than `Verbosity.VERBOSE`.	`''`
`check`	`bool`	Whether to abort the application if the command exits with a non-zero exit code.	`True`
`env`	`dict[str, str] \| None`	The environment variables to include in the command's environment.	`None`
`cwd`	`str \| Path \| None`	The working directory in which to run the command.	`None`
`encoding`	`str`	The encoding used to decode the command's output.	`'utf-8'`

redirect ¶

redirect(
    command: list[str] | str,
    *,
    stream: BinaryIO,
    cross_streams: bool = True,
    **kwargs: Any,
) -> CompletedProcess

Redirect the output of a command to a binary writable file-like object. Example usage:

with open("latest.zip", "wb") as stream:
    app.subprocess.redirect(
        ["git", "archive", "--format=zip", "HEAD"],
        stream=stream,
    )

Parameters:

Name	Type	Description	Default
`command`	`list[str] \| str`	The command to run.	required
`stream`	`BinaryIO`	The binary stream with which to redirect the command's output.	required

Returns:

Type	Description
`CompletedProcess`	The completed process.

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `attach` method.

exit_with ¶

exit_with(
    command: list[str],
    *,
    env: dict[str, str] | None = None,
    cwd: str | Path | None = None,
    encoding: str = "utf-8",
) -> NoReturn

Run a command and abort with the command's exit code.

Parameters:

Name	Type	Description	Default
`command`	`list[str]`	The command to run.	required
`cwd`	`str \| Path \| None`	The working directory in which to run the command.	`None`
`env`	`dict[str, str] \| None`	The environment variables to include in the command's environment.	`None`
`encoding`	`str`	The encoding used to decode the command's output.	`'utf-8'`

attach ¶

attach(command: list[str] | str, **kwargs: Any) -> CompletedProcess

Run a command and wait for it to complete. By default, the command inherits the current process's standard input, output, and error streams.

The check keyword argument defaults to True. When set to True and the command exits with a non-zero exit code, the application will abort using the command's exit code rather than raising an exception.

Warning

This method does not support sending telemetry upon errors and should only be preferred over run when the command requires user interaction.

Parameters:

Name	Type	Description	Default
`command`	`list[str] \| str`	The command to run.	required

Returns:

Type	Description
`CompletedProcess`	The completed process.

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to `subprocess.run`.

spawn_daemon ¶

spawn_daemon(command: list[str] | str, **kwargs: Any) -> None

Spawn a daemon process that is detached from the current process.

Parameters:

Name	Type	Description	Default
`command`	`list[str] \| str`	The command to run.	required

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Popen` constructor.

EnvVars ¶

EnvVars(
    env_vars: dict[str, str] | None = None,
    *,
    include: list[str] | None = None,
    exclude: list[str] | None = None,
)

This class is a snapshot of the current process' environment variables at the time of instantiation.

Setting environment variables for subprocesses becomes easy, rather than having to manually make a copy of the current environment variables and updating it:

app.subprocess.run([...], env=EnvVars({"FOO": "bar"}))

Instances may also be used as a context manager to temporarily update os.environ for the current process:

with EnvVars({"FOO": "bar"}):
    ...

Warning

It's undesirable to persist instances for long periods of time because the environment variables may change during the lifetime of the instance.

Parameters:

Name	Type	Description	Default
`env_vars`	`dict[str, str] \| None`	Additional environment variables to include in the snapshot. These override existing environment variables and are unaffected by the `include` and `exclude` filtering parameters.	`None`
`include`	`list[str] \| None`	A list of glob patterns used to include environment variables in the snapshot.	`None`
`exclude`	`list[str] \| None`	A list of glob patterns used to exclude environment variables from the snapshot. This takes precedence over the `include` parameter.	`None`