hydra.system module

A model for a program’s interface to the host operating system: running other programs, the environment, the working directory, and process exit status. Names and semantics follow the POSIX System Interfaces (XSH) volume; see https://pubs.opengroup.org/onlinepubs/9799919799. Only the portable, cross-platform subset is modeled.

class hydra.system.Command(program: Annotated[FilePath, 'The executable to run; a POSIX pathname, resolved against PATH by the host when it contains no slash (as for the execvp/execlp family). POSIX argv[0] (the program name) is supplied by the host from this field'], arguments: Annotated[Sequence[str], 'The arguments following the program name, becoming argv[1..] for the child. The program name (argv[0]) is not included here'], working_directory: Annotated[object, "The directory in which to run the child, as if chdir() (XSH, https://pubs.opengroup.org/onlinepubs/9799919799/functions/chdir.html) were called before exec. None inherits the parent's working directory"], environment: Annotated[object, "The complete environment for the child (POSIX environ). None inherits the parent's environment; given(m) replaces it entirely, as execve's envp argument does. There is no partial-merge form; merge in pure code before calling"])

Bases: object

A description of a program to run, supplying the inputs the POSIX posix_spawn / execve family takes: the executable, its argument vector, and optionally a working directory and a replacement environment. Only the portable subset is modeled; POSIX file actions, spawn attributes, and signal masks are omitted. See https://pubs.opengroup.org/onlinepubs/9799919799/functions/posix_spawn.html and https://pubs.opengroup.org/onlinepubs/9799919799/functions/execve.html.

ARGUMENTS = Name(value='arguments')

class Builder(_program: 'hydra.file.FilePath' = None, _arguments: 'Sequence[str]' = None, _working_directory: 'Optional[hydra.file.FilePath]' = None, _environment: 'Optional[Mapping[EnvironmentVariable, str]]' = None)

Bases: object

arguments(arguments)

build()

environment(environment)

program(program)

working_directory(working_directory)

ENVIRONMENT = Name(value='environment')

PROGRAM = Name(value='program')

TYPE_ = Name(value='hydra.system.Command')

WORKING_DIRECTORY = Name(value='workingDirectory')

arguments: Annotated[Sequence[str], 'The arguments following the program name, becoming argv[1..] for the child. The program name (argv[0]) is not included here']

static builder()

environment: Annotated[object, "The complete environment for the child (POSIX environ). None inherits the parent's environment; given(m) replaces it entirely, as execve's envp argument does. There is no partial-merge form; merge in pure code before calling"]

program: Annotated[FilePath, 'The executable to run; a POSIX pathname, resolved against PATH by the host when it contains no slash (as for the execvp/execlp family). POSIX argv[0] (the program name) is supplied by the host from this field']

with_arguments(arguments)

with_environment(environment)

with_program(program)

with_working_directory(working_directory)

working_directory: Annotated[object, "The directory in which to run the child, as if chdir() (XSH, https://pubs.opengroup.org/onlinepubs/9799919799/functions/chdir.html) were called before exec. None inherits the parent's working directory"]

class hydra.system.EnvironmentVariable(value: T)

Bases: Node[str]

The name of an environment variable: its identity within the POSIX environment list environ (XBD section 8, Environment Variables, https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html). POSIX models each entry as a “name=value” string; this type wraps the name, which is the constrained, identifying part: XBD section 8 requires names to consist of characters from the portable character set and to contain no ‘=’ (the name/value separator). A variable’s value is an arbitrary string and is left unwrapped.

TYPE_ = Name(value='hydra.system.EnvironmentVariable')

class hydra.system.ProcessResult(exit_code: Annotated[StatusCode, "The child's exit status (POSIX WEXITSTATUS); 0 denotes success by convention"], stdout: Annotated[bytes, 'The bytes the child wrote to file descriptor 1, standard output (XBD STDOUT_FILENO)'], stderr: Annotated[bytes, 'The bytes the child wrote to file descriptor 2, standard error (XBD STDERR_FILENO)'])

Bases: object

The outcome of a child process that ran to completion, as obtained by wait() / waitpid() (XSH, https://pubs.opengroup.org/onlinepubs/9799919799/functions/wait.html) together with its captured output. Only normal termination is modeled directly; abnormal termination (POSIX WIFSIGNALED) is surfaced through exitCode using the host’s convention rather than as a separate field.

class Builder(_exit_code: 'StatusCode' = None, _stdout: 'bytes' = None, _stderr: 'bytes' = None)

Bases: object

build()

exit_code(exit_code)

stderr(stderr)

stdout(stdout)

EXIT_CODE = Name(value='exitCode')

STDERR = Name(value='stderr')

STDOUT = Name(value='stdout')

TYPE_ = Name(value='hydra.system.ProcessResult')

static builder()

exit_code: Annotated[StatusCode, "The child's exit status (POSIX WEXITSTATUS); 0 denotes success by convention"]

stderr: Annotated[bytes, 'The bytes the child wrote to file descriptor 2, standard error (XBD STDERR_FILENO)']

stdout: Annotated[bytes, 'The bytes the child wrote to file descriptor 1, standard output (XBD STDOUT_FILENO)']

with_exit_code(exit_code)

with_stderr(stderr)

with_stdout(stdout)

class hydra.system.StatusCode(value: T)

Bases: Node[int]

A process exit status: the value passed to the POSIX exit() function and reported by wait() / waitpid() for a normally-terminated child (XSH; see https://pubs.opengroup.org/onlinepubs/9799919799/functions/exit.html and https://pubs.opengroup.org/onlinepubs/9799919799/functions/wait.html). By the convention of XCU section 2.8.2, Exit Status for Commands (https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#tag_19_08_02), 0 denotes success and non-zero denotes failure. POSIX passes only the low 8 bits of the status through wait(); Hydra widens this to a signed int32 so that host runtimes which expose a fuller code (e.g. Windows process exit codes, or the negative “killed by signal N” convention) can be represented without loss.

TYPE_ = Name(value='hydra.system.StatusCode')