GitHub

ChildProcessSpawnerService

API reference for ChildProcessSpawnerService.

Starts commands; the constructor is Effect's ChildProcessSpawner.make: given spawn, the rest is built on it.

The helpers own the handles they spawn, so they read and drop the output they do not return, keeping a full pipe from stopping the child.

Functions

__init__

__init__(spawn) -> None
ParameterTypeDescription
spawnSpawn
def __init__(self, spawn: Spawn) -> None:
    self._spawn = spawn

spawn

spawn(command) -> Effect[ChildProcessHandle, PlatformError, Scope]

Starts command (a single command or a pipeline) and gives its handle; closing the scope kills the process if it is still running. Fails with a PlatformError when it cannot start (a missing program or working directory, an invalid argument).

ParameterTypeDescription
commandCommand

Returns Effect[ChildProcessHandle, PlatformError, Scope]

def spawn(self, command: Command) -> Effect[ChildProcessHandle, PlatformError, Scope]:
    """Starts ``command`` (a single command or a pipeline) and gives its
    handle; closing the scope kills the process if it is still
    running. Fails with a ``PlatformError`` when it cannot start (a
    missing program or working directory, an invalid argument)."""
    return self._spawn(command)

exit_code

exit_code(command) -> Effect[ExitCode, PlatformError]

Run command and give back its exit code, reading and dropping its output meanwhile. Returns once the process exits, even if descendants keep its pipes open.

ParameterTypeDescription
commandCommand

Returns Effect[ExitCode, PlatformError]

def exit_code(self, command: Command) -> Effect[ExitCode, PlatformError]:
    """Run ``command`` and give back its exit code, reading and dropping
    its output meanwhile. Returns once the process exits, even if
    descendants keep its pipes open."""

    def wait(handle: ChildProcessHandle) -> Effect[ExitCode, PlatformError]:
        return handle.exit_code.race_first(handle.all.run_drain().flat_map(lambda _: never))

    return scoped(self.spawn(command).flat_map(wait))

stream_string

stream_string(command, *, include_stderr=False) -> Stream[str, PlatformError]

The standard output of command as text; with include_stderr, interleaved with its standard error, else that is read and dropped until standard output ends.

ParameterTypeDescription
commandCommand
include_stderrbool = False

Returns Stream[str, PlatformError]

def stream_string(
    self, command: Command, *, include_stderr: bool = False
) -> Stream[str, PlatformError]:
    """The standard output of ``command`` as text; with
    ``include_stderr``, interleaved with its standard error, else that
    is read and dropped until standard output ends."""

    def text(handle: ChildProcessHandle) -> Stream[str, PlatformError]:
        output = handle.all if include_stderr else handle.stdout.drain_fork(handle.stderr)
        return output.decode_text()

    return unwrap_stream(self.spawn(command).map(text))

stream_lines

stream_lines(command, *, include_stderr=False) -> Stream[str, PlatformError]

stream_string split into lines.

ParameterTypeDescription
commandCommand
include_stderrbool = False

Returns Stream[str, PlatformError]

def stream_lines(
    self, command: Command, *, include_stderr: bool = False
) -> Stream[str, PlatformError]:
    """``stream_string`` split into lines."""
    return self.stream_string(command, include_stderr=include_stderr).split_lines()

lines

lines(command, *, include_stderr=False) -> Effect[list[str], PlatformError]

Run command and collect the lines of its output.

ParameterTypeDescription
commandCommand
include_stderrbool = False

Returns Effect[list[str], PlatformError]

def lines(
    self, command: Command, *, include_stderr: bool = False
) -> Effect[list[str], PlatformError]:
    """Run ``command`` and collect the lines of its output."""
    return self.stream_lines(command, include_stderr=include_stderr).run_collect()

string

string(command, *, include_stderr=False) -> Effect[str, PlatformError]

Run command and give back its output.

ParameterTypeDescription
commandCommand
include_stderrbool = False

Returns Effect[str, PlatformError]

def string(
    self, command: Command, *, include_stderr: bool = False
) -> Effect[str, PlatformError]:
    """Run ``command`` and give back its output."""
    return self.stream_string(command, include_stderr=include_stderr).run_string()