basilisp.process

An API for starting subprocesses which wraps Python’s subprocess module.

The primary API function is start which starts a subprocess and returns the subprocess.Popen instance. You can wait for the process to terminate using exit-ref or you can manipulate it directly. You can fetch the streams attached to the process using stdin, stdout, and stderr. This namespace also includes an extension function communicate which wraps subprocess.Popen.communicate().

This namespace also includes exec for starting a subprocess, waiting for its completion, and returning the stdout as a string.

Note

There are some minor differences between the Basilisp implementation and the source Clojure implementation. Because Python does not have the concept of an unopened File object as Java does, standard streams can only be passed existing open file handles or paths. If a path is given, the Basilisp from-file and to-file functions allow specifying the options that the file at that path will be opened with (including encoding, binary mode, etc.).

In Clojure, as in the underlying java.lang.Process object, streams are always opened in binary mode and it is the responsibility of callers to encode and decode into strings as necessary. Python’s subprocesss offers some flexibility to callers to specify string encoding for pipes by default, saving them the effort of manually encoding and decoding and this namespace extends the same convenience.

fn (communicate process & kwargs)

Communicate with a subprocess, optionally sending data to the process stdin stream and reading any data in the process stderr and stdout streams, returning them as a string or bytes object (depending on whether the process was opened in text or binary mode).

This function is preferred over the use of stderr, stdin, and stdout to avoid potential deadlocks.

The following keyword/value arguments are optional:

keyword :input:

a string or bytes object (depending on whether the process was opened in text or binary mode); if omitted, do not send anything

keyword timeout:

an optional timeout

fn (exec & opts+args)

Execute a command as by start and, upon successful return, return the captured value of the process stdout as if by basilisp.core/slurp.

If opts are specified, they should be provided as a map in the first argument position. opts are exactly the same as those in start.

If the return code is non-zero, throw subprocess.CalledProcessError.

fn (exit-ref process)

Given a subprocess.Popen (such as the one returned by start), return a reference which can be used to wait (optionally with timeout) for the completion of the process.

fn (from-file f & {:as opts})

Return a file object suitable for use as the :in option for start.

Callers can specify additional opts. Anything supported by basilisp.io/writer and basilisp.io/output-stream is generally supported here. The values of individual opts are not validated until a call to start or exec.

Warning

opts may only be specified for path-like values. Providing options for existing file objects and file handles will raise an exception.

fn (map->FileWrapper m_4509)

Create a new instance of the record FileWrapper from a map whose keys correspond to the fields of FileWrapper.

fn (start & opts+args)

Start an external command as args.

If opts are specified, they should be provided as a map in the first argument position.

The following options are available:

keyword :in:

an existing file object or file handle, :pipe to generate a new stream, or :inherit to use the current process stdin; if not specified :pipe will be used

keyword :out:

an existing file object or file handle, :pipe to generate a new stream, :discard to ignore stdout, or :inherit to use the current process stdout; if not specified, :pipe will be used

keyword :err:

an existing file object or file handle, :pipe to generate a new stream, :discard to ignore stderr, :stdout to merge stdout and stderr, or :inherit to use the current process stderr; if not specified, :pipe will be used

keyword :dir:

current directory when the process runs; on POSIX systems, if executable is a relative path, it will be resolved relative to this value; if not specified, the current directory will be used

keyword :clear-env:

boolean which if true will prevent inheriting the environment variables from the current process

keyword :env:

a mapping of string values to string values which are added to the subprocess environment; if :clear-env, these are the only environment variables provided to the subprocess

The following options affect the pipe streams created by subprocess.Popen (if :pipe is selected), but do not apply to any files wrapped by from-file or to-file (in which case the options provided for those files take precedence) or if :inherit is specified (in which case the options for the corresponding stream in the current process is used). These options are specific to Basilisp.

keyword :encoding:

the string name of an encoding to use for input and output streams when :pipe is specified for any of the standard streams; this option does not apply to any files wrapped by from-file or to-file or if :inherit is specified; if not specified, streams are treated as bytes

Returns subprocess.Popen instance.

fn (stderr process)

Return the stderr stream from the external process.

Warning

Communication directly with the process streams introduces the possibility of deadlocks. Users may use communicate as a safe alternative.

fn (stdin process)

Return the stdin stream from the external process.

Warning

Communication directly with the process streams introduces the possibility of deadlocks. Users may use communicate as a safe alternative.

fn (stdout process)

Return the stdout stream from the external process.

Warning

Communication directly with the process streams introduces the possibility of deadlocks. Users may use communicate as a safe alternative.

fn (to-file f & {:as opts})

Return a file object suitable for use as the :err and :out options for start.

Callers can specify additional opts. Anything supported by basilisp.io/reader and basilisp.io/input-stream is generally supported here. The values of individual opts are not validated until a call to start or exec.

Warning

opts may only be specified for path-like values. Providing options for existing file objects and file handles will raise an exception.