GitHub

API reference for process.

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

AttributeTypeDescription
ExitCodetype[ExitCode]

The status a child process exited with.

ProcessIdtype[ProcessId]

A child process's operating-system identifier.

layerLayer[ChildProcessSpawner, Never, FileSystem | Path]

The host's child processes; needs FileSystem and Path (platform.layer provides all three).

Types

TypeDefinitionDescription
AdditionalFdtype AdditionalFd = InputFd | OutputFd | DuplexFd
Commandtype Command = StandardCommand | PipedCommand
CommandInputtype CommandInput = StdioKind | Stream[bytes, PlatformError]

A child's standard input: a StdioKind, or a stream written into it.

CommandOutputtype CommandOutput = StdioKind | Sink[bytes, bytes, Never, PlatformError]

A child's standard output or error: a StdioKind, or a sink its bytes are transduced through as the handle's stream is read.

Encodingtype 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).

PipeFromtype PipeFrom = Literal['stdout', 'stderr', 'all'] | int

Which output of a command a pipe reads: an int is an additional output descriptor (3 or more).

PipeTotype PipeTo = Literal['stdin'] | int

Which input of a command a pipe writes: an int is an additional input descriptor (3 or more).

StdioKindtype 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 (/dev/null).

Rereftype Reref = Effect[None, PlatformError]

Given back by ChildProcessHandle.unref: running it makes the scope own the process again.

Spawntype Spawn = Callable[[Command], Effect[ChildProcessHandle, PlatformError, Scope]]

Classes

Functions

fd_name

fd_name(fd) -> str

"fd3" for 3.

ParameterTypeDescription
fdint

Returns str

def fd_name(fd: int) -> str:
    """``"fd3"`` for 3."""
    return f"fd{fd}"

flatten_command

flatten_command(command) -> FlattenedPipeline

The commands of a pipeline in order, with the options of each pipe.

ParameterTypeDescription
commandCommand

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] = {}) -> 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.

ParameterTypeDescription
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 | None

The descriptor "fd3" names (3), or None unless the name is fd and a number from 3 up.

ParameterTypeDescription
namestr

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 None

build_spawn_options

build_spawn_options(options, platform) -> SpawnOptions

Detached by default except on Windows ("win32"), and the window hidden unless detached.

ParameterTypeDescription
optionsCommandOptions
platformstr

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)

Modules