SubprocessCommand - libvcs._internal.subprocess¶
Invocable subprocess wrapper.
Defer running a subprocess, such as by handing to an executor.
Note
This is an internal API not covered by versioning policy.
Examples
SubprocessCommand: Wrapssubprocess.Popenandsubprocess.run()in adataclass().Before:
>>> import subprocess >>> subprocess.run( ... ['echo', 'hi'], ... capture_output=True, universal_newlines=True ... ).stdout 'hi\n'
With this:
>>> cmd = SubprocessCommand(['echo', 'hi']) >>> cmd.args ['echo', 'hi'] >>> cmd.run(capture_output=True, universal_newlines=True).stdout 'hi\n'
Tweak params before invocation:
>>> cmd = SubprocessCommand(['echo', 'hi']) >>> cmd.args[1] = 'hello' >>> cmd.args ['echo', 'hello'] >>> cmd.run(capture_output=True, universal_newlines=True).stdout 'hello\n'
Bases:
Exception
Command
Bases:
SkipDefaultFieldsReprMixinWraps a
subprocessrequest. Inspect, mutate, control before invocation.Fields mirror the parameters of
subprocess.Popen. Each is passed through as-is whenPopen(),run(),check_call(), orcheck_output()fires, and the defaults match the onessubprocessuses.Buffering policy for the pipe file objects:
-1forio.DEFAULT_BUFFER_SIZE,0for unbuffered,1for line buffered in text mode.
Program to execute in place of
args[0], or the shell to use whenshellis set.Nonerunsargs[0]itself.
Child’s standard input: a file descriptor, a file object,
subprocess.PIPE,subprocess.DEVNULL, orNoneto inherit the parent’s.
Child’s standard output, taking the same values as
stdin.
Child’s standard error, taking the same values as
stdin, plussubprocess.STDOUTto fold it intostdout.
POSIX-only callable run in the child between fork and exec, or
Noneto run nothing.
Close inherited file descriptors above stderr in the child before exec.
Run
argsthrough the system shell instead of exec’ing it directly.
Directory to change into before running, or
Noneto inherit the parent’s working directory.
Windows-only process creation flags, e.g.
subprocess.CREATE_NEW_CONSOLE.0applies none.
Windows-only
subprocess.STARTUPINFOcontrolling how the child’s window appears, orNonefor the defaults.
POSIX-only: reset signals Python set to
SIG_IGNback toSIG_DFLin the child before exec.
POSIX-only: run
os.setsid()in the child, detaching it from the parent’s process group and controlling terminal.
POSIX-only file descriptors to keep open in the child regardless of
close_fds. The empty()passes none.
POSIX-only umask to apply in the child before exec.
-1leaves the inherited umask alone.
Capacity of the pipes opened for
stdin,stdout, andstderr.-1keeps the operating system default.
POSIX-only user to switch the child to, or
Noneto stay as the calling user.
POSIX-only group to switch the child to, or
Noneto keep the calling group.
POSIX-only supplementary groups for the child, or
Noneto leave them untouched.
Alias of
text, kept for backwards compatibility.Noneleaves the mode to the other text options.
Open the pipe file objects in text mode.
Noneleaves them binary unlessencoding,errors, oruniversal_newlinesselects text.
Codec for the text-mode pipe file objects. Setting it turns text mode on;
Noneleaves the choice to the other text options.
Decoding error handler for the text-mode pipe file objects, e.g.
"replace". Setting it turns text mode on.
Examples
>>> cmd = SubprocessCommand("ls") >>> cmd.args 'ls'
With
shell=True:>>> cmd = SubprocessCommand("ls -l", shell=True) >>> cmd.shell True >>> cmd.args 'ls -l' >>> cmd.check_call() 0
-
__init__(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, creationflags=0, startupinfo=None, restore_signals=True, start_new_session=False, pass_fds=(), umask=-1, pipesize=-1, user=None, group=None, extra_groups=None, universal_newlines=None, text=None, encoding=None, errors=None)¶method[source]method[source]__init__(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, creationflags=0, startupinfo=None, restore_signals=True, start_new_session=False, pass_fds=(), umask=-1, pipesize=-1, user=None, group=None, extra_groups=None, universal_newlines=None, text=None, encoding=None, errors=None)¶
- Parameters:
- Return type:
-
method
-
method
-
method
-
method
Run commands
subprocess.Popen, optionally overrides via kwargs.- Parameters:
**kwargs (
dict,optional) – Overrides existing attributes forsubprocess.Popen
Examples
>>> cmd = SubprocessCommand(args=['echo', 'hello']) >>> proc = cmd.Popen(stdout=subprocess.PIPE) >>> proc.communicate() (b'hello\n', None)
Run command
subprocess.check_call(), optionally overrides via kwargs.- Parameters:
**kwargs (
dict,optional) – Overrides existing attributes forsubprocess.check_call()- Return type:
Examples
>>> cmd = SubprocessCommand(args=['echo', 'hello']) >>> cmd.check_call(stdout=subprocess.PIPE) 0
-
method
-
method
-
method
-
method
Run command
subprocess.check_output(), optionally override via kwargs.- Parameters:
input (
t.Union[bytes,str],optional) –pass string to subprocess’s stdin. Bytes by default, str in text mode.
Text mode is triggered by setting any of text, encoding, errors or universal_newlines.
**kwargs (
dict,optional) – Overrides existing attributes forsubprocess.check_output()
Examples
>>> cmd = SubprocessCommand(args=['echo', 'hello']) >>> proc = cmd.check_output(shell=True)
Examples from
subprocess:>>> import subprocess >>> cmd = SubprocessCommand( ... ["/bin/sh", "-c", "ls -l non_existent_file ; exit 0"]) >>> cmd.check_output(stderr=subprocess.STDOUT) b"ls: ...non_existent_file...: No such file or directory\n"
>>> cmd = SubprocessCommand(["sed", "-e", "s/foo/bar/"]) >>> cmd.check_output(input=b"when in the course of fooman events\n") b'when in the course of barman events\n'
-
method
-
method
-
method
-
method
Run command in
subprocess.run(), optionally overrides via kwargs.- Parameters:
input (
t.Union[bytes,str],optional) –pass string to subprocess’s stdin. Bytes by default, str in text mode.
Text mode is triggered by setting any of text, encoding, errors or universal_newlines.
check (
bool) – If True and the exit code was non-zero, it raises asubprocess.CalledProcessError. The CalledProcessError object will have the return code in the returncode attribute, and output & stderr attributes if those streams were captured.timeout (
int) – If given, and the process takes too long, asubprocess.TimeoutExpired**kwargs (
dict,optional) – Overrides existing attributes forsubprocess.run()
Examples
>>> import subprocess >>> cmd = SubprocessCommand( ... ["/bin/sh", "-c", "ls -l non_existent_file ; exit 0"]) >>> cmd.run() CompletedProcess(args=['/bin/sh', '-c', 'ls -l non_existent_file ; exit 0'], returncode=0)
>>> import subprocess >>> cmd = SubprocessCommand( ... ["/bin/sh", "-c", "ls -l non_existent_file ; exit 0"]) >>> cmd.run(check=True) CompletedProcess(args=['/bin/sh', '-c', 'ls -l non_existent_file ; exit 0'], returncode=0)
>>> cmd = SubprocessCommand(["sed", "-e", "s/foo/bar/"]) >>> completed = cmd.run(input=b"when in the course of fooman events\n") >>> completed CompletedProcess(args=['sed', '-e', 's/foo/bar/'], returncode=0) >>> completed.stderr
>>> cmd = SubprocessCommand(["sed", "-e", "s/foo/bar/"]) >>> completed = cmd.run(input=b"when in the course of fooman events\n", ... capture_output=True) >>> completed CompletedProcess(args=['sed', '-e', 's/foo/bar/'], returncode=0, stdout=b'when in the course of barman events\n', stderr=b'') >>> completed.stdout b'when in the course of barman events\n' >>> completed.stderr b''