Pipettor Library

Function Interface

pipettor.run(cmds, stdin=None, stdout=None, stderr=<class 'pipettor.devices.DataReader'>, logger=None, logLevel=None)

Construct and run an process pipeline. If any of the processes fail, a ProcessException is throw.

cmds is either a list of arguments for a single process, or a list of such lists for a pipeline. If the stdin, stdout, or stderr arguments are none, the open files are are inherited. Otherwise they can be string file names, file-like objects, file number, or pipettor.Dev object. stdin is input to the first process, stdout is output to the last process and stderr is attached to all processed. pipettor.DataReader and pipettor.DataWriter objects can be specified for stdin, stdout, or stderr asynchronously I/O with the pipeline without the danger of deadlock.

If stderr is the class DataReader, a new instance is created for each process in the pipeline. The contents of stderr will include an exception if an occurs in that process. If an instance of pipettor.DataReader is provided, the contents of stderr from all process will be included in the exception.

pipettor.runout(cmds, stdin=None, stderr=<class 'pipettor.devices.DataReader'>, logger=None, logLevel=None, buffering=-1, encoding=None, errors=None)

Construct and run an process pipeline, returning the output. If any of the processes fail, a ProcessException is throw.

See the pipettor.run() function for more details. Use str.splitlines() to split result into lines.

The logger argument can be the name of a logger or a logger object. If none, default is user.

Specifying binary access results in data of type bytes, otherwise str type is return. The buffering, encoding, and errors arguments are as used in the open() function.

pipettor.runlex(cmds, stdin=None, stdout=None, stderr=<class 'pipettor.devices.DataReader'>, logger=None, logLevel=None)

Call pipettor.run(), first splitting commands specified as strings are split into arguments using shlex.split.

If cmds is a string, it is split into arguments and run as as a single process. If cmds is a list, a multi-process pipeline is created. Elements that are strings are split into arguments to form commands. Elements that are lists are treated as commands without splitting.

pipettor.runlexout(cmds, stdin=None, stderr=<class 'pipettor.devices.DataReader'>, logger=None, logLevel=None, buffering=-1, encoding=None, errors=None)

Call pipettor.runout(), first splitting commands specified as strings are split into arguments using shlex.split.

If cmds is a string, it is split into arguments and run as as a single process. If cmds is a list, a multi-process pipeline is created. Elements that are strings are split into arguments to form commands. Elements that are lists are treated as commands without splitting.

The logger argument can be the name of a logger or a logger object. If none, default is user.

Specifying binary access results in data of type bytes, otherwise str type is returned. The buffering, encoding, and errors arguments are as used in the open() function.

Pipeline Classes

class pipettor.Pipeline(cmds, *, stdin=None, stdout=None, stderr=<class 'pipettor.devices.DataReader'>, logger=None, logLevel=None)

A process pipeline. Once constructed, the pipeline is started with start(), poll(), or wait() functions.

The cmds argument is either a list of arguments for a single process, or a list of such lists for a pipeline. If the stdin/out/err arguments are none, the open files are are inherited. Otherwise they can be string file names, file-like objects, file number, or Dev object. Stdin is input to the first process, stdout is output to the last process and stderr is attached to all processed. DataReader and DataWriter objects can be specified for stdin/out/err asynchronously I/O with the pipeline without the danger of deadlock.

If stderr is the class DataReader, a new instance is created for each process in the pipeline. The contents of stderr will include an exception if an occurs in that process. If an instance of DataReader is provided, the contents of stderr from all process will be included in the exception.

Command arguments will be converted to strings.

The logger argument can be the name of a logger or a logger object. If none, default is user.

class pipettor.Popen(cmds, mode='r', *, stdin=None, stdout=None, logger=None, logLevel=None, buffering=-1, encoding=None, errors=None)

File-like object of processes to read from or write to a Pipeline.

The cmds argument is either a list of arguments for a single process, or a list of such lists for a pipeline. Mode is ‘r’ for a pipeline who’s output will be read, or ‘w’ for a pipeline to that is to have data written to it. If stdin or stdout is specified, and is a string, it is a file to open as other file at the other end of the pipeline. If it’s not a string, it is assumed to be a file object to use for input or output. For a read pipe, only stdin can be specified, for a write pipe, only stdout can be used.

read pipeline (‘r’):

stdin –> cmd[0] –> … –> cmd[n] –> Popen

write pipeline (‘w’)

Popen –> cmd[0] –> … –> cmd[n] –> stdout

Command arguments will be converted to strings.

The logger argument can be the name of a logger or a logger object. If none, default is user.

Specifying binary access results in data of type bytes, otherwise str type is returned. The buffering, encoding, and errors arguments are as used in the open() function.

Process I/O Classes

class pipettor.DataReader(*, binary=False, buffering=-1, encoding=None, errors=None)

Object to asynchronously read data from process into memory via a pipe. A thread is use to prevent deadlock when both reading and writing to a child pipeline.

Specifying binary access results in data of type bytes, otherwise str type is returned. The buffering, encoding, and errors arguments are as used in the open() function.

class pipettor.DataWriter(data, *, buffering=-1, encoding=None, errors=None)

Object to asynchronously write data to process from memory via a pipe. A thread is use to prevent deadlock when both reading and writing to a child pipeline. Text or binary output is determined by the type of data.

The buffering, encoding, and errors arguments are as used in the open() function.

class pipettor.File(path, mode='r')

A file path for input or output, used for specifying stdio associated with files. Mode is invalued on of standard r, w, or a

Logging Control

pipettor.setDefaultLogger(logger)

Set the default pipettor logger used in logging command and errors. If None, there is no default logging. The logger can be the name of a logger or the logger itself. Standard value is None

pipettor.getDefaultLogger()

return the current value of the pipettor default logger

Exceptions

class pipettor.PipettorException

Base class for Pipettor exceptions.

class pipettor.ProcessException(procDesc, returncode=None, stderr=None)

Exception associated with running a process. A None returncode indicates a exec failure.