/usr/lib/python3/dist-packages/twisted/internet
Edit: /usr/lib/python3/dist-packages/twisted/internet/utils.py (8682B)
# -*- 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",
]