pysys.process

Process execution and monitoring implementations.

pysys.process.monitor

Contains the process monitoring API used by pysys.basetest.BaseTest.startProcessMonitor.

pysys.process.monitorimpl

Contains implementations of the pysys.process.monitor.BaseProcessMonitor interface.

pysys.process.user

Contains pysys.process.user.ProcessUser which supports using processes from PySys, and provides the shared functionality of subclasses pysys.basetest.BaseTest and pysys.baserunner.BaseRunner.

Process

class pysys.process.Process(command, arguments, environs, workingDir, state, timeout, stdout=None, stderr=None, displayName=None, expectedExitStatus=None, info={}, owner=None)[source]

Bases: object

Represents a process that PySys has started (or can start).

A platform-specific implementation subclass of this interface is returned by pysys.process.user.ProcessUser.startProcess.

Variables

  • ~.command (str) – The full path to the executable.

  • ~.arguments (list[str]) – A list of arguments to the command.

  • ~.environs (dict(str,str)) – A dictionary of environment variables (key, value) for the process context execution.

  • ~.workingDir (str) – The working directory for the process

  • ~.state – The state of the process.

  • ~.timeout (int) – The time in seconds for a foreground process to complete.

  • ~.stdout (str) – The full path to the filename to write the stdout of the process, or None for no stderr stream.

  • ~.stderr (str) – The full path to the filename to write the stderr of the process, or None for no stderr stream.

  • ~.displayName (str) – Display name for this process (defaults to the basename if not explicitly specified). The display name is returned by calling str() on this instance. The display name and pid are returned by repr().

  • expectedExitStatus (str) – The condition string used to determine whether the exit status/code returned by the process is correct, for example ‘==0’.

  • ~.pid (int) – The process id for a running or complete process (as set by the OS), or None if it is not yet started.

  • ~.owner (ProcessUser) – The owner object that is running this process.

  • ~.exitStatus (int) – The process exit status for a completed process (for many processes 0 represents success), or None if it has not yet completed.

  • ~.info (dict[str,obj]) – A mutable dictionary of user-supplied information that was passed into startProcess, for example port numbers, log file paths etc.

stop(timeout=30, hard=False)[source]

Stop a running process and wait until it has finished.

Does nothing if the process is not running.

On Windows, this uses TerminateProcess, on Linux this sends a SIGTERM signal (which allows the process a chance to exit gracefully including possibly dumping code coverage output) unless the hard=True parameter is specified.

Parameters

  • hard (bool) – Set to True to use a hard termination (e.g. SIGKILL).

  • timeout (float) – The time to wait for the process to complete before raising an exception.

Raises

pysys.exceptions.ProcessError – Raised if an error occurred whilst trying to stop the process.

signal(signal)[source]

Send a signal to a running process.

Typically this uses os.kill to send the signal.

Parameters

signal (int) – The integer signal to send to the process, e.g. process.signal(signal.SIGTERM).

Raises

pysys.exceptions.ProcessError – Raised if an error occurred whilst trying to signal the process

write(data, addNewLine=True, closeStdinAfterWrite=False)[source]

Write binary data to the stdin of the process.

Note that when the addNewLine argument is set to true, if a new line does not terminate the input data string, a newline character will be added. If one already exists a new line character will not be added. Should you explicitly require to add data without the method appending a new line charater set addNewLine to false.

Parameters

  • data (bytes|str) – The data to write to the process stdin. As only binary data can be written to a process stdin, if a character string rather than a byte object is passed as the data, it will be automatically converted to a bytes object using the encoding given by PREFERRED_ENCODING.

  • addNewLine (bool) – True if a new line character is to be added to the end of the data string

  • closeStdinAfterWrite (bool) – If True, the stdin file handle will be closed after this write. Added in v2.1.

running()[source]

Check to see if a process is running.

Returns

True if the process is currently running, False if not.

wait(timeout)[source]

Wait for a process to complete execution, raising an exception on timeout.

Logs and info message if the process takes more than a few seconds to complete.

This method provides basic functionality but does not check the exit status or log any messages; see pysys.basetest.BaseTest.waitProcess for a wrapper that adds additional functionality.

Note that this method will not terminate the process if the timeout is exceeded.

Parameters

timeout – The timeout to wait in seconds, for example timeout=TIMEOUTS['WaitForProcess'].

Raises

pysys.exceptions.ProcessTimeout – Raised if the timeout is exceeded.

start()[source]

Start a process using the runtime parameters set at instantiation.

Raises