257 lines
8.5 KiB
Python
257 lines
8.5 KiB
Python
|
# -*- test-case-name: twisted.test.test_iutils -*-
|
||
|
|
# Copyright (c) Twisted Matrix Laboratories.
|
||
|
|
# See LICENSE for details.
|
||
|
|
|
||
|
|
"""
|
||
|
|
Utility methods.
|
||
|
|
"""
|
||
|
|
|
||
|
|
|
||
|
|
import sys
|
||
|
|
import warnings
|
||
|
|
from functools import wraps
|
||
|
|
from io import BytesIO
|
||
|
|
|
||
|
|
from twisted.internet import defer, protocol
|
||
|
|
from twisted.python import failure
|
||
|
|
|
||
|
|
|
||
|
|
def _callProtocolWithDeferred(
|
||
|
|
protocol, executable, args, env, path, reactor=None, protoArgs=()
|
||
|
|
):
|
||
|
|
if reactor is None:
|
||
|
|
from twisted.internet import reactor
|
||
|
|
|
||
|
|
d = defer.Deferred()
|
||
|
|
p = protocol(d, *protoArgs)
|
||
|
|
reactor.spawnProcess(p, executable, (executable,) + tuple(args), env, path)
|
||
|
|
return d
|
||
|
|
|
||
|
|
|
||
|
|
class _UnexpectedErrorOutput(IOError):
|
||
|
|
"""
|
||
|
|
Standard error data was received where it was not expected. This is a
|
||
|
|
subclass of L{IOError} to preserve backward compatibility with the previous
|
||
|
|
error behavior of L{getProcessOutput}.
|
||
|
|
|
||
|
|
@ivar processEnded: A L{Deferred} which will fire when the process which
|
||
|
|
produced the data on stderr has ended (exited and all file descriptors
|
||
|
|
closed).
|
||
|
|
"""
|
||
|
|
|
||
|
|
def __init__(self, text, processEnded):
|
||
|
|
IOError.__init__(self, f"got stderr: {text!r}")
|
||
|
|
self.processEnded = processEnded
|
||
|
|
|
||
|
|
|
||
|
|
class _BackRelay(protocol.ProcessProtocol):
|
||
|
|
"""
|
||
|
|
Trivial protocol for communicating with a process and turning its output
|
||
|
|
into the result of a L{Deferred}.
|
||
|
|
|
||
|
|
@ivar deferred: A L{Deferred} which will be called back with all of stdout
|
||
|
|
and, if C{errortoo} is true, all of stderr as well (mixed together in
|
||
|
|
one string). If C{errortoo} is false and any bytes are received over
|
||
|
|
stderr, this will fire with an L{_UnexpectedErrorOutput} instance and
|
||
|
|
the attribute will be set to L{None}.
|
||
|
|
|
||
|
|
@ivar onProcessEnded: If C{errortoo} is false and bytes are received over
|
||
|
|
stderr, this attribute will refer to a L{Deferred} which will be called
|
||
|
|
back when the process ends. This C{Deferred} is also associated with
|
||
|
|
the L{_UnexpectedErrorOutput} which C{deferred} fires with earlier in
|
||
|
|
this case so that users can determine when the process has actually
|
||
|
|
ended, in addition to knowing when bytes have been received via stderr.
|
||
|
|
"""
|
||
|
|
|
||
|
|
def __init__(self, deferred, errortoo=0):
|
||
|
|
self.deferred = deferred
|
||
|
|
self.s = BytesIO()
|
||
|
|
if errortoo:
|
||
|
|
self.errReceived = self.errReceivedIsGood
|
||
|
|
else:
|
||
|
|
self.errReceived = self.errReceivedIsBad
|
||
|
|
|
||
|
|
def errReceivedIsBad(self, text):
|
||
|
|
if self.deferred is not None:
|
||
|
|
self.onProcessEnded = defer.Deferred()
|
||
|
|
err = _UnexpectedErrorOutput(text, self.onProcessEnded)
|
||
|
|
self.deferred.errback(failure.Failure(err))
|
||
|
|
self.deferred = None
|
||
|
|
self.transport.loseConnection()
|
||
|
|
|
||
|
|
def errReceivedIsGood(self, text):
|
||
|
|
self.s.write(text)
|
||
|
|
|
||
|
|
def outReceived(self, text):
|
||
|
|
self.s.write(text)
|
||
|
|
|
||
|
|
def processEnded(self, reason):
|
||
|
|
if self.deferred is not None:
|
||
|
|
self.deferred.callback(self.s.getvalue())
|
||
|
|
elif self.onProcessEnded is not None:
|
||
|
|
self.onProcessEnded.errback(reason)
|
||
|
|
|
||
|
|
|
||
|
|
def getProcessOutput(executable, args=(), env={}, path=None, reactor=None, errortoo=0):
|
||
|
|
"""
|
||
|
|
Spawn a process and return its output as a deferred returning a L{bytes}.
|
||
|
|
|
||
|
|
@param executable: The file name to run and get the output of - the
|
||
|
|
full path should be used.
|
||
|
|
|
||
|
|
@param args: the command line arguments to pass to the process; a
|
||
|
|
sequence of strings. The first string should B{NOT} be the
|
||
|
|
executable's name.
|
||
|
|
|
||
|
|
@param env: the environment variables to pass to the process; a
|
||
|
|
dictionary of strings.
|
||
|
|
|
||
|
|
@param path: the path to run the subprocess in - defaults to the
|
||
|
|
current directory.
|
||
|
|
|
||
|
|
@param reactor: the reactor to use - defaults to the default reactor
|
||
|
|
|
||
|
|
@param errortoo: If true, include stderr in the result. If false, if
|
||
|
|
stderr is received the returned L{Deferred} will errback with an
|
||
|
|
L{IOError} instance with a C{processEnded} attribute. The
|
||
|
|
C{processEnded} attribute refers to a L{Deferred} which fires when the
|
||
|
|
executed process ends.
|
||
|
|
"""
|
||
|
|
return _callProtocolWithDeferred(
|
||
|
|
lambda d: _BackRelay(d, errortoo=errortoo), executable, args, env, path, reactor
|
||
|
|
)
|
||
|
|
|
||
|
|
|
||
|
|
class _ValueGetter(protocol.ProcessProtocol):
|
||
|
|
def __init__(self, deferred):
|
||
|
|
self.deferred = deferred
|
||
|
|
|
||
|
|
def processEnded(self, reason):
|
||
|
|
self.deferred.callback(reason.value.exitCode)
|
||
|
|
|
||
|
|
|
||
|
|
def getProcessValue(executable, args=(), env={}, path=None, reactor=None):
|
||
|
|
"""Spawn a process and return its exit code as a Deferred."""
|
||
|
|
return _callProtocolWithDeferred(_ValueGetter, executable, args, env, path, reactor)
|
||
|
|
|
||
|
|
|
||
|
|
class _EverythingGetter(protocol.ProcessProtocol):
|
||
|
|
def __init__(self, deferred, stdinBytes=None):
|
||
|
|
self.deferred = deferred
|
||
|
|
self.outBuf = BytesIO()
|
||
|
|
self.errBuf = BytesIO()
|
||
|
|
self.outReceived = self.outBuf.write
|
||
|
|
self.errReceived = self.errBuf.write
|
||
|
|
self.stdinBytes = stdinBytes
|
||
|
|
|
||
|
|
def connectionMade(self):
|
||
|
|
if self.stdinBytes is not None:
|
||
|
|
self.transport.writeToChild(0, self.stdinBytes)
|
||
|
|
# The only compelling reason not to _always_ close stdin here is
|
||
|
|
# backwards compatibility.
|
||
|
|
self.transport.closeStdin()
|
||
|
|
|
||
|
|
def processEnded(self, reason):
|
||
|
|
out = self.outBuf.getvalue()
|
||
|
|
err = self.errBuf.getvalue()
|
||
|
|
e = reason.value
|
||
|
|
code = e.exitCode
|
||
|
|
if e.signal:
|
||
|
|
self.deferred.errback((out, err, e.signal))
|
||
|
|
else:
|
||
|
|
self.deferred.callback((out, err, code))
|
||
|
|
|
||
|
|
|
||
|
|
def getProcessOutputAndValue(
|
||
|
|
executable, args=(), env={}, path=None, reactor=None, stdinBytes=None
|
||
|
|
):
|
||
|
|
"""Spawn a process and returns a Deferred that will be called back with
|
||
|
|
its output (from stdout and stderr) and it's exit code as (out, err, code)
|
||
|
|
If a signal is raised, the Deferred will errback with the stdout and
|
||
|
|
stderr up to that point, along with the signal, as (out, err, signalNum)
|
||
|
|
"""
|
||
|
|
return _callProtocolWithDeferred(
|
||
|
|
_EverythingGetter,
|
||
|
|
executable,
|
||
|
|
args,
|
||
|
|
env,
|
||
|
|
path,
|
||
|
|
reactor,
|
||
|
|
protoArgs=(stdinBytes,),
|
||
|
|
)
|
||
|
|
|
||
|
|
|
||
|
|
def _resetWarningFilters(passthrough, addedFilters):
|
||
|
|
for f in addedFilters:
|
||
|
|
try:
|
||
|
|
warnings.filters.remove(f)
|
||
|
|
except ValueError:
|
||
|
|
pass
|
||
|
|
return passthrough
|
||
|
|
|
||
|
|
|
||
|
|
def runWithWarningsSuppressed(suppressedWarnings, f, *a, **kw):
|
||
|
|
"""
|
||
|
|
Run the function I{f}, but with some warnings suppressed.
|
||
|
|
|
||
|
|
This calls L{warnings.filterwarnings} to add warning filters before
|
||
|
|
invoking I{f}. If I{f} returns a L{Deferred} then the added filters are
|
||
|
|
removed once the deferred fires. Otherwise they are removed immediately.
|
||
|
|
|
||
|
|
Note that the list of warning filters is a process-wide resource, so
|
||
|
|
calling this function will affect all threads.
|
||
|
|
|
||
|
|
@param suppressedWarnings:
|
||
|
|
A list of arguments to pass to L{warnings.filterwarnings}, a sequence
|
||
|
|
of (args, kwargs) 2-tuples.
|
||
|
|
|
||
|
|
@param f: A callable, which may return a L{Deferred}.
|
||
|
|
|
||
|
|
@param a: Positional arguments passed to I{f}
|
||
|
|
|
||
|
|
@param kw: Keyword arguments passed to I{f}
|
||
|
|
|
||
|
|
@return: The result of C{f(*a, **kw)}
|
||
|
|
|
||
|
|
@seealso: L{twisted.python.util.runWithWarningsSuppressed}
|
||
|
|
functions similarly, but doesn't handled L{Deferred}s.
|
||
|
|
"""
|
||
|
|
for args, kwargs in suppressedWarnings:
|
||
|
|
warnings.filterwarnings(*args, **kwargs)
|
||
|
|
addedFilters = warnings.filters[: len(suppressedWarnings)]
|
||
|
|
try:
|
||
|
|
result = f(*a, **kw)
|
||
|
|
except BaseException:
|
||
|
|
exc_info = sys.exc_info()
|
||
|
|
_resetWarningFilters(None, addedFilters)
|
||
|
|
raise exc_info[1].with_traceback(exc_info[2])
|
||
|
|
else:
|
||
|
|
if isinstance(result, defer.Deferred):
|
||
|
|
result.addBoth(_resetWarningFilters, addedFilters)
|
||
|
|
else:
|
||
|
|
_resetWarningFilters(None, addedFilters)
|
||
|
|
return result
|
||
|
|
|
||
|
|
|
||
|
|
def suppressWarnings(f, *suppressedWarnings):
|
||
|
|
"""
|
||
|
|
Wrap C{f} in a callable which suppresses the indicated warnings before
|
||
|
|
invoking C{f} and unsuppresses them afterwards. If f returns a Deferred,
|
||
|
|
warnings will remain suppressed until the Deferred fires.
|
||
|
|
"""
|
||
|
|
|
||
|
|
@wraps(f)
|
||
|
|
def warningSuppressingWrapper(*a, **kw):
|
||
|
|
return runWithWarningsSuppressed(suppressedWarnings, f, *a, **kw)
|
||
|
|
|
||
|
|
return warningSuppressingWrapper
|
||
|
|
|
||
|
|
|
||
|
|
__all__ = [
|
||
|
|
"runWithWarningsSuppressed",
|
||
|
|
"suppressWarnings",
|
||
|
|
"getProcessOutput",
|
||
|
|
"getProcessValue",
|
||
|
|
"getProcessOutputAndValue",
|
||
|
|
]
|