Working with Processes

gruvi.PIPE = ...

gruvi.DEVNULL = ...

class Process(encoding=None, timeout=None)

A child process.

This class allows you to start up a child process, communicate with it and control it. The API is modeled after the subprocess.Popen class.

The encoding argument specifies the encoding to use for communications with the child. If an encoding is specified, the standard input and output handles provide text-based IO, otherwise they provide bytes-based IO.

stdin

The child’s standard input, or None.

stdout

The child’s standard output, or None.

stderr

The child’s standard error, or None.

returncode

The child’s exit status, or None if it has not exited yet.

On Unix, if the child was terminated by a signal, return -SIGNUM.

pid

The child’s process ID, or None if there is no child.

spawn(args, executable=None, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, env=None, flags=0, extra_handles=None)

Spawn a new child process.

The executable to spawn and its arguments are determined by args, executable and shell.

When shell is set to False (the default), args is normally a sequence and it contains both the program to execute (at index 0), and its arguments.

When shell is set to True, then args is normally a string and it indicates the command to execute through the shell.

The executable argument can be used to override the executable to execute. If shell is False, it overrides args[0]. This is sometimes used on Unix to implement “fat” executables that behave differently based on argv[0]. If shell is True, it overrides the shell to use. The default shell is '/bin/sh' on Unix, and the value of $COMSPEC (or 'cmd.exe' if it is unset) on Windows.

The stdin, stdout and stderr arguments specify how to handle standard input, output, and error, respectively. If set to None, then the child will inherit our respective stdio handle. If set to the special constant PIPE then a pipe is created. The pipe will be connected to a gruvi.StreamProtocol which you can use to read or write from it. The stream protocol instance is available under either stdin, stdout or stderr. All 3 stdio arguments can also be a file descriptor, a file-like object, or a pyuv Stream instance.

The extra_handles specifies any extra handles to pass to the client. It must be a sequence where each element is either a file descriptor, a file-like objects, or a pyuv.Stream instance. The position in the sequence determines the file descriptor in the client. The first position corresponds to FD 3, the second to 4, etc. This places these file descriptors directly after the stdio handles.

The cwd argument specifies the directory to change to before executing the child. If not provided, the current directory is used.

The env argument specifies the environment to use when executing the child. If provided, it must be a dictionary. By default, the current environment is used.

The flags argument can be used to specify optional libuv uv_process_flags. The only relevant flags are pyuv.UV_PROCESS_DETACHED and pyuv.UV_PROCESS_WINDOWS_HIDE. Both are Windows specific and are silently ignored on Unix.

child_exited(exit_status, term_signal)

Callback that is called when the child has exited.

switchpoint close()

Close the process and frees its associated resources.

This method waits for the resources to be freed by the event loop.

send_signal(signum)

Send the signal signum to the child.

On Windows, SIGTERM, SIGKILL and SIGINT are emulated using TerminateProcess(). This will cause the child to exit unconditionally with status 1. No other signals can be sent on Windows.

terminate()

Terminate the child process.

It is not an error to call this method when the child has already exited.

switchpoint wait(timeout=-1)

Wait for the child to exit.

Wait for at most timeout seconds, or indefinitely if timeout is None. Return the value of the returncode attribute.

switchpoint communicate(input=None, timeout=-1)

Communicate with the child and return its output.

If input is provided, it is sent to the client. Concurrent with sending the input, the child’s standard output and standard error are read, until the child exits.

The return value is a tuple (stdout_data, stderr_data) containing the data read from standard output and standard error.