Merge pull request twisted#1640 from twisted/10238-runwithwarnings-docs

Author: twm Reviewer: adiroiban Fixes: ticket:10238 Document runWithWarningsSuppressed deferred behavior
dctikan · Aug 7, 2021 · c0429b9 · c0429b9
2 parents 5568fa2 + b4bd6b3
commit c0429b9
Show file tree

Hide file tree

Showing 3 changed files with 35 additions and 15 deletions.
diff --git a/src/twisted/internet/utils.py b/src/twisted/internet/utils.py
@@ -7,15 +7,14 @@
 """
 
 
-import warnings
 import sys
+import warnings
 from functools import wraps
+from io import BytesIO
 
-from twisted.internet import protocol, defer
+from twisted.internet import defer, protocol
 from twisted.python import failure
 
-from io import BytesIO
-
 
 def _callProtocolWithDeferred(
     protocol, executable, args, env, path, reactor=None, protoArgs=()
@@ -192,11 +191,30 @@ def _resetWarningFilters(passthrough, addedFilters):
 
 
 def runWithWarningsSuppressed(suppressedWarnings, f, *a, **kw):
-    """Run the function C{f}, but with some warnings suppressed.
+    """
+    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)}
 
-    @param suppressedWarnings: A list of arguments to pass to filterwarnings.
-                               Must be a sequence of 2-tuples (args, kwargs).
-    @param f: A callable, followed by its arguments and keyword arguments
+    @seealso: L{twisted.python.util.runWithWarningsSuppressed}
+        functions similarly, but doesn't handled L{Deferred}s.
     """
     for args, kwargs in suppressedWarnings:
         warnings.filterwarnings(*args, **kwargs)

diff --git a/src/twisted/newsfragments/10238.doc b/src/twisted/newsfragments/10238.doc
@@ -0,0 +1 @@
+twisted.internet.utils.runWithWarningsSupressed behavior of waiting on deferreds has been documented.
diff --git a/src/twisted/python/util.py b/src/twisted/python/util.py
@@ -19,30 +19,30 @@
     pwd = _pwd
 
 try:
-    from os import setgroups as _setgroups, getgroups as _getgroups
+    from os import getgroups as _getgroups, setgroups as _setgroups
 except ImportError:
     setgroups = None
     getgroups = None
 else:
     setgroups = _setgroups
     getgroups = _getgroups
 
+# For backwards compatibility, some things import this, so just link it
+from collections import OrderedDict
 from typing import (
     Callable,
     ClassVar,
     Mapping,
     MutableMapping,
     Sequence,
-    Union,
     Tuple,
+    Union,
     cast,
 )
 
 from incremental import Version
-from twisted.python.deprecate import deprecatedModuleAttribute
 
-# For backwards compatibility, some things import this, so just link it
-from collections import OrderedDict
+from twisted.python.deprecate import deprecatedModuleAttribute
 
 deprecatedModuleAttribute(
     Version("Twisted", 15, 5, 0),
@@ -935,8 +935,9 @@ def runWithWarningsSuppressed(suppressedWarnings, f, *args, **kwargs):
     Unlike L{twisted.internet.utils.runWithWarningsSuppressed}, it has no
     special support for L{twisted.internet.defer.Deferred}.
 
-    @param suppressedWarnings: A list of arguments to pass to filterwarnings.
-        Must be a sequence of 2-tuples (args, kwargs).
+    @param suppressedWarnings: A list of arguments to pass to
+        L{warnings.filterwarnings}.  Must be a sequence of 2-tuples (args,
+        kwargs).
 
     @param f: A callable.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		twisted.internet.utils.runWithWarningsSupressed behavior of waiting on deferreds has been documented.