Shell commands¶
-
pshell.
call
(cmd: Union[str, List[str]], *, stdout: IO = None, stdin: IO = None, stderr: IO = None, obfuscate_pwd: str = None, shell: bool = True, timeout: Union[int, float] = None) → int¶ Run another program in a subprocess and wait for it to terminate.
Parameters: - cmd – Command to be executed (str or list). If shell=True, it must be a str.
- stdout – standard output file handle. Omit for sys.stdout.
Unlike the same parameter for
subprocess.call()
, which must be backed by a OS-level file descriptor, this can be a pseudo-stream like e.g.io.StringIO
. - stdin – standard input file handle. Omit for no input.
- stderr – standard error file handle. Omit for sys.stderr.
Unlike the same parameter for
subprocess.call()
, which must be backed by a OS-level file descriptor, this can be a pseudo-stream like e.g.io.StringIO
. - obfuscate_pwd (str) – if set, search for the target password and replace it with XXXX before logging it.
- shell (bool) –
Invoke inside the shell. This differes from the same parameter of
subprocess.call()
in several ways:- It is True by default instead of False
- In Linux and MacOSX, it sets some sane settings: errexit, nounset, pipefail
- In Linux and MacOSX, it is always guaranteed to be bash.
This differs from
subprocess.call()
, which on Ubuntu will invoke dash and RedHat will invoke bash. On Windows it is CMD.
- timeout (float) – kill command if doesn’t return within timeout limit
Returns: command exit code
Return type:
-
pshell.
check_call
(cmd: Union[str, List[str]], *, stdout: IO = None, stdin: IO = None, stderr: IO = None, obfuscate_pwd: str = None, shell: bool = True, timeout: Union[int, float] = None) → None¶ Run another program in a subprocess and wait for it to terminate; raise exception in case of non-zero exit code.
See
call()
for parameters documentation.Returns: None Raises: CalledProcessError – if the command returns a non-zero exit code
-
pshell.
check_output
(cmd: Union[str, List[str]], *, stdin: IO = None, stderr: IO = None, obfuscate_pwd: str = None, shell: bool = True, timeout: Union[int, float] = None, decode: bool = True, encoding: str = 'utf-8', errors: str = 'replace')¶ Run another program in a subprocess and wait for it to terminate; return its stdout. Raise exception in case of non-zero exit code.
See
call()
for parameters documentation.Parameters: - decode (bool) – If True, decode the raw output to UTF-8 and return a str object.
If False, return the raw bytes object.
The default is to decode to UTF-8. This differs
from
subprocess.check_output()
, which always returns the raw output. - encoding (str) – Encoding of the raw bytes output. Ignored if decode=False.
- errors (str) – ‘replace’, ‘ignore’, or ‘strict’. See
bytes.decode()
. Ignored if decode=False. Note that the default value isreplace
, whereas the default inbytes.decode()
isstrict
.
Returns: command stdout
Return type: str or bytes (see
decode
parameter)Raises: CalledProcessError – if the command returns a non-zero exit code
- decode (bool) – If True, decode the raw output to UTF-8 and return a str object.
If False, return the raw bytes object.
The default is to decode to UTF-8. This differs
from
-
pshell.
real_fh
(fh: Optional[IO])¶ The
io
module offers file-like objects which can be used to spoof a file handle. Among other things, they are extensively used by nosetests and py.test to capture stdout/stderr.In most cases, this is transparent; however there are exceptions, like the
subprocess
module, which require a file handle with a real file descriptor underlying it - that is, an object which defines thefileno()
method.This context manager transparently detects these cases and automatically converts pseudo file handlers from the
io
module into real POSIX-based file handles.Parameters: fh – Any of:
- A file handle opened for write and backed by a POSIX file descriptor,
e.g. as returned by
open()
or the default value of sys.stdout or sys.stderr. - A pseudo file handle such as
io.StringIO
,io.BytesIO
, or the stub used by nosetests to mock sys.stdout and sys.stderr. - None (default for most subprocess functions)
Usage:
buf = io.StringIO() with real_fh(buf) as real_buf: subprocess.check_call(cmd, stderr=real_buf)
All pshell functions that wrap around
subprocess
internally use this context manager. You don’t need to use it explicitly:buf = io.StringIO() pshell.check_call(cmd, stderr=buf)
- A file handle opened for write and backed by a POSIX file descriptor,
e.g. as returned by
-
exception
pshell.
CalledProcessError
(returncode, cmd, output=None, stderr=None)¶ Raised when run() is called with check=True and the process returns a non-zero exit status.
- Attributes:
- cmd, returncode, stdout, stderr, output
-
exception
pshell.
TimeoutExpired
(cmd, timeout, output=None, stderr=None)¶ This exception is raised when the timeout expires while waiting for a child process.
- Attributes:
- cmd, output, stdout, stderr, timeout