Child processes (Effect's ChildProcess and ChildProcessSpawner).
A command describes a process; it is an Effect that starts it in the
current Scope and gives back a ChildProcessHandle::
from pyfect import process
@fx.fn
def program():
handle = yield from process.make("echo", ["hello"])
output = yield from handle.stdout.decode_text().run_string()
code = yield from handle.exit_code
return output, code
fx.run_blocking(fx.scoped(program()).pipe(fx.provide(platform.layer)))Standard output and error are byte streams and standard input a sink;
pipe_to feeds one command's output into the next. When the scope
closes, a running process is killed with its process group (unless it was
unref-ed). The ChildProcessSpawner service runs commands: its
string, lines, exit_code, ... helpers spawn, collect and clean
up in one call. command_line quotes and joins arguments into command
lines and splits templates into arguments. layer is the host's (on subprocess; it needs
FileSystem and Path, and platform.layer includes it).
Re-exports#
Values#
| Attribute | Type | Description |
|---|---|---|
ExitCode | type[ExitCode] | The status a child process exited with. |
ProcessId | type[ProcessId] | A child process's operating-system identifier. |
layer | Layer[ChildProcessSpawner, Never, FileSystem | Path] | The host's child processes; needs |
Types#
| Type | Definition | Description |
|---|---|---|
AdditionalFd | type AdditionalFd = InputFd | OutputFd | DuplexFd | |
Command | type Command = StandardCommand | PipedCommand | |
CommandInput | type CommandInput = StdioKind | Stream[bytes, PlatformError] | A child's standard input: a |
CommandOutput | type CommandOutput = StdioKind | Sink[bytes, bytes, Never, PlatformError] | A child's standard output or error: a |
Encoding | type Encoding = Literal['ascii', 'utf8', 'utf-8', 'utf16le', 'utf-16le', 'ucs2', 'ucs-2', 'base64', 'base64url', 'latin1', 'binary', 'hex'] | How text written to a child's standard input becomes bytes (Node's buffer encodings). |
PipeFrom | type PipeFrom = Literal['stdout', 'stderr', 'all'] | int | Which output of a command a pipe reads: an |
PipeTo | type PipeTo = Literal['stdin'] | int | Which input of a command a pipe writes: an |
StdioKind | type StdioKind = Literal['pipe', 'inherit', 'ignore'] | How the operating system sets up a standard stream: a pipe to the
parent, the parent's own stream, or nothing ( |
Reref | type Reref = Effect[None, PlatformError] | Given back by |
Spawn | type Spawn = Callable[[Command], Effect[ChildProcessHandle, PlatformError, Scope]] |
Classes#
Functions#
fd_name#
fd_name(fd) -> str"fd3" for 3.
| Parameter | Type | Description |
|---|---|---|
fd | int |
Returns str
def fd_name(fd: int) -> str:
"""``"fd3"`` for 3."""
return f"fd{fd}"flatten_command#
flatten_command(command) -> FlattenedPipelineThe commands of a pipeline in order, with the options of each pipe.
| Parameter | Type | Description |
|---|---|---|
command | Command |
Returns FlattenedPipeline
def flatten_command(command: Command) -> FlattenedPipeline:
"""The commands of a pipeline in order, with the options of each pipe."""
commands: list[StandardCommand] = []
pipes: list[PipeOptions] = []
_flatten_into(command, commands, pipes)
first, *rest = commands
return FlattenedPipeline((first, *rest), tuple(pipes))make#
make(command: str, args: Sequence[Word] = (), /, **options: Unpack[MakeOptions] = {}) -> StandardCommand
make(template: TemplateStrings | TemplateLike, /, *values: TemplateExpression = (), **options: Unpack[MakeOptions] = {}) -> StandardCommandA command running command with args (Effect's array form of
ChildProcess.make), or the command a template describes (Effect's
template form): its text parts and the values between them, or a
t-string on Python 3.14::
process.make("git", ["commit", "-m", message])
process.make(["git commit -m ", ' "two words"'], message)
process.make(t'git commit -m {message} "two words"') # Python 3.14A template is split with command_line.template: quotes group words,
each value is one literal argument, an argument containing a
Redacted value stays Redacted. Shell syntax (|, $HOME,
*, ~) raises CommandLineError here: quote it, or pass it as a
value. With shell, the template's text is the script, kept as
written, and it cannot have values. Arguments of either form can be
Redacted; the program name cannot.
cwd: the working directory, checked to exist when spawned.env: the environment; it replaces the parent's unlessextend_env, which adds it over the parent's. ANonevalue removes the variable.Redactedvalues reach the child as they are and never show in errors.shell: runcommandas a shell script with/bin/sh(cmd.exeon Windows) or the shell given. The command is the whole script (build it withcommand_line.joinorquotewhen it contains values); spawning it withargsfails withBadArgument.detached: start a process group of its own, so killing the command kills its descendants (the default except on Windows).windows_hide: hide the console window on Windows (the default unless detached).stdin,stdout,stderr: seeCommandInput,CommandOutput,StdinConfig,StdoutConfigandStderrConfig; each is a pipe by default.additional_fds: descriptors from 3 up, by number; lower ones are skipped.kill_signal,force_kill_after: how the scope ending the command kills it: the signal (SIGTERMby default), thenSIGKILLafter this long if the process group is still alive.
A NUL character in the command, an argument or an env value fails
with BadArgument when the command is spawned.
| Parameter | Type | Description |
|---|---|---|
command | ||
rest | = () | |
options | = {} |
@overload
def make(
command: str, args: Sequence[Word] = (), /, **options: Unpack[MakeOptions]
) -> StandardCommand: ...
@overload
def make(
template: TemplateStrings | TemplateLike,
/,
*values: TemplateExpression,
**options: Unpack[MakeOptions],
) -> StandardCommand: ...
def make(
command: str | TemplateStrings | TemplateLike, /, *rest: Any, **options: Unpack[MakeOptions]
) -> StandardCommand:
"""A command running ``command`` with ``args`` (Effect's array form of
``ChildProcess.make``), or the command a template describes (Effect's
template form): its text parts and the values between them, or a
t-string on Python 3.14::
process.make("git", ["commit", "-m", message])
process.make(["git commit -m ", ' "two words"'], message)
process.make(t'git commit -m {message} "two words"') # Python 3.14
A template is split with ``command_line.template``: quotes group words,
each value is one literal argument, an argument containing a
``Redacted`` value stays ``Redacted``. Shell syntax (``|``, ``$HOME``,
``*``, ``~``) raises ``CommandLineError`` here: quote it, or pass it as a
value. With ``shell``, the template's text is the script, kept as
written, and it cannot have values. Arguments of either form can be
``Redacted``; the program name cannot.
- ``cwd``: the working directory, checked to exist when spawned.
- ``env``: the environment; it replaces the parent's unless
``extend_env``, which adds it over the parent's. A ``None`` value
removes the variable. ``Redacted`` values reach the child as they are
and never show in errors.
- ``shell``: run ``command`` as a shell script with ``/bin/sh``
(``cmd.exe`` on Windows) or the shell given. The command is the whole
script (build it with ``command_line.join`` or ``quote`` when it
contains values); spawning it with ``args`` fails with
``BadArgument``.
- ``detached``: start a process group of its own, so killing the
command kills its descendants (the default except on Windows).
- ``windows_hide``: hide the console window on Windows (the default
unless detached).
- ``stdin``, ``stdout``, ``stderr``: see ``CommandInput``,
``CommandOutput``, ``StdinConfig``, ``StdoutConfig`` and
``StderrConfig``; each is a pipe by default.
- ``additional_fds``: descriptors from 3 up, by number; lower ones are skipped.
- ``kill_signal``, ``force_kill_after``: how the scope ending the
command kills it: the signal (``SIGTERM`` by default), then
``SIGKILL`` after this long if the process group is still alive.
A NUL character in the command, an argument or an ``env`` value fails
with ``BadArgument`` when the command is spawned.
"""
shell = options.get("shell", False)
if isinstance(command, str):
program, args = _words(command, rest)
return StandardCommand(program, args, _options(options))
if shell is not False:
return StandardCommand(_shell_script(command, rest), (), _options(options))
executable, args = _words(command, rest)
return StandardCommand(executable, args, _options(options))parse_fd_name#
parse_fd_name(name) -> int | NoneThe descriptor "fd3" names (3), or None unless the name is
fd and a number from 3 up.
| Parameter | Type | Description |
|---|---|---|
name | str |
Returns int | None
def parse_fd_name(name: str) -> int | None:
"""The descriptor ``"fd3"`` names (3), or ``None`` unless the name is
``fd`` and a number from 3 up."""
match = _FD_NAME.fullmatch(name)
if match is None:
return None
fd = int(match[1])
return fd if fd >= 3 else Nonebuild_spawn_options#
build_spawn_options(options, platform) -> SpawnOptionsDetached by default except on Windows ("win32"), and the window
hidden unless detached.
| Parameter | Type | Description |
|---|---|---|
options | CommandOptions | |
platform | str |
Returns SpawnOptions
def build_spawn_options(options: CommandOptions, platform: str) -> SpawnOptions:
"""Detached by default except on Windows (``"win32"``), and the window
hidden unless detached."""
detached = options.detached if options.detached is not None else platform != "win32"
windows_hide = options.windows_hide if options.windows_hide is not None else not detached
return SpawnOptions(detached=detached, shell=options.shell, windows_hide=windows_hide)