# -*- 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", ]