diff options
| -rw-r--r-- | Lib/contextlib.py | 80 | ||||
| -rw-r--r-- | Lib/test/test_contextlib.py | 63 | ||||
| -rw-r--r-- | Misc/NEWS | 5 |
3 files changed, 102 insertions, 46 deletions
diff --git a/Lib/contextlib.py b/Lib/contextlib.py index a564943..fb89118 100644 --- a/Lib/contextlib.py +++ b/Lib/contextlib.py @@ -37,6 +37,16 @@ class _GeneratorContextManager(ContextDecorator): def __init__(self, func, *args, **kwds): self.gen = func(*args, **kwds) self.func, self.args, self.kwds = func, args, kwds + # Issue 19330: ensure context manager instances have good docstrings + doc = getattr(func, "__doc__", None) + if doc is None: + doc = type(self).__doc__ + self.__doc__ = doc + # Unfortunately, this still doesn't provide good help output when + # inspecting the created context manager instances, since pydoc + # currently bypasses the instance docstring and shows the docstring + # for the class instead. + # See http://bugs.python.org/issue19404 for more details. def _recreate_cm(self): # _GCM instances are one-shot context managers, so the @@ -117,9 +127,6 @@ def contextmanager(func): return helper -# Unfortunately, this was originally published as a class, so -# backwards compatibility prevents the use of the wrapper function -# approach used for the other classes class closing(object): """Context to automatically close something at the end of a block. @@ -144,8 +151,18 @@ class closing(object): def __exit__(self, *exc_info): self.thing.close() -class _RedirectStdout: - """Helper for redirect_stdout.""" +class redirect_stdout: + """Context manager for temporarily redirecting stdout to another file + + # How to send help() to stderr + with redirect_stdout(sys.stderr): + help(dir) + + # How to write help() to a file + with open('help.txt', 'w') as f: + with redirect_stdout(f): + help(pow) + """ def __init__(self, new_target): self._new_target = new_target @@ -163,25 +180,19 @@ class _RedirectStdout: self._old_target = self._sentinel sys.stdout = restore_stdout -# Use a wrapper function since we don't care about supporting inheritance -# and a function gives much cleaner output in help() -def redirect_stdout(target): - """Context manager for temporarily redirecting stdout to another file - # How to send help() to stderr - with redirect_stdout(sys.stderr): - help(dir) - # How to write help() to a file - with open('help.txt', 'w') as f: - with redirect_stdout(f): - help(pow) - """ - return _RedirectStdout(target) +class suppress: + """Context manager to suppress specified exceptions + + After the exception is suppressed, execution proceeds with the next + statement following the with statement. + with suppress(FileNotFoundError): + os.remove(somefile) + # Execution still resumes here if the file was already removed + """ -class _SuppressExceptions: - """Helper for suppress.""" def __init__(self, *exceptions): self._exceptions = exceptions @@ -189,30 +200,17 @@ class _SuppressExceptions: pass def __exit__(self, exctype, excinst, exctb): - # Unlike isinstance and issubclass, exception handling only - # looks at the concrete type heirarchy (ignoring the instance - # and subclass checking hooks). However, all exceptions are - # also required to be concrete subclasses of BaseException, so - # if there's a discrepancy in behaviour, we currently consider it - # the fault of the strange way the exception has been defined rather - # than the fact that issubclass can be customised while the - # exception checks can't. + # Unlike isinstance and issubclass, CPython exception handling + # currently only looks at the concrete type hierarchy (ignoring + # the instance and subclass checking hooks). While Guido considers + # that a bug rather than a feature, it's a fairly hard one to fix + # due to various internal implementation details. suppress provides + # the simpler issubclass based semantics, rather than trying to + # exactly reproduce the limitations of the CPython interpreter. + # # See http://bugs.python.org/issue12029 for more details return exctype is not None and issubclass(exctype, self._exceptions) -# Use a wrapper function since we don't care about supporting inheritance -# and a function gives much cleaner output in help() -def suppress(*exceptions): - """Context manager to suppress specified exceptions - - After the exception is suppressed, execution proceeds with the next - statement following the with statement. - - with suppress(FileNotFoundError): - os.remove(somefile) - # Execution still resumes here if the file was already removed - """ - return _SuppressExceptions(*exceptions) # Inspired by discussions on http://bugs.python.org/issue13585 class ExitStack(object): diff --git a/Lib/test/test_contextlib.py b/Lib/test/test_contextlib.py index 419104d..6362a97 100644 --- a/Lib/test/test_contextlib.py +++ b/Lib/test/test_contextlib.py @@ -14,6 +14,20 @@ except ImportError: class ContextManagerTestCase(unittest.TestCase): + def test_instance_docstring_given_function_docstring(self): + # Issue 19330: ensure context manager instances have good docstrings + # See http://bugs.python.org/issue19404 for why this doesn't currently + # affect help() output :( + def gen_with_docstring(): + """This has a docstring""" + yield + gen_docstring = gen_with_docstring.__doc__ + cm_with_docstring = contextmanager(gen_with_docstring) + self.assertEqual(cm_with_docstring.__doc__, gen_docstring) + obj = cm_with_docstring() + self.assertEqual(obj.__doc__, gen_docstring) + self.assertNotEqual(obj.__doc__, type(obj).__doc__) + def test_contextmanager_plain(self): state = [] @contextmanager @@ -109,7 +123,11 @@ class ContextManagerTestCase(unittest.TestCase): class ClosingTestCase(unittest.TestCase): - # XXX This needs more work + def test_instance_docs(self): + # Issue 19330: ensure context manager instances have good docstrings + cm_docstring = closing.__doc__ + obj = closing(None) + self.assertEqual(obj.__doc__, cm_docstring) def test_closing(self): state = [] @@ -205,6 +223,7 @@ class LockContextTestCase(unittest.TestCase): class mycontext(ContextDecorator): + """Example decoration-compatible context manager for testing""" started = False exc = None catch = False @@ -220,6 +239,12 @@ class mycontext(ContextDecorator): class TestContextDecorator(unittest.TestCase): + def test_instance_docs(self): + # Issue 19330: ensure context manager instances have good docstrings + cm_docstring = mycontext.__doc__ + obj = mycontext() + self.assertEqual(obj.__doc__, cm_docstring) + def test_contextdecorator(self): context = mycontext() with context as result: @@ -373,6 +398,12 @@ class TestContextDecorator(unittest.TestCase): class TestExitStack(unittest.TestCase): + def test_instance_docs(self): + # Issue 19330: ensure context manager instances have good docstrings + cm_docstring = ExitStack.__doc__ + obj = ExitStack() + self.assertEqual(obj.__doc__, cm_docstring) + def test_no_resources(self): with ExitStack(): pass @@ -634,6 +665,12 @@ class TestExitStack(unittest.TestCase): class TestRedirectStdout(unittest.TestCase): + def test_instance_docs(self): + # Issue 19330: ensure context manager instances have good docstrings + cm_docstring = redirect_stdout.__doc__ + obj = redirect_stdout(None) + self.assertEqual(obj.__doc__, cm_docstring) + def test_redirect_to_string_io(self): f = io.StringIO() msg = "Consider an API like help(), which prints directly to stdout" @@ -671,6 +708,12 @@ class TestRedirectStdout(unittest.TestCase): class TestSuppress(unittest.TestCase): + def test_instance_docs(self): + # Issue 19330: ensure context manager instances have good docstrings + cm_docstring = suppress.__doc__ + obj = suppress() + self.assertEqual(obj.__doc__, cm_docstring) + def test_no_result_from_enter(self): with suppress(ValueError) as enter_result: self.assertIsNone(enter_result) @@ -683,16 +726,26 @@ class TestSuppress(unittest.TestCase): with suppress(TypeError): len(5) + def test_exception_hierarchy(self): + with suppress(LookupError): + 'Hello'[50] + + def test_other_exception(self): + with self.assertRaises(ZeroDivisionError): + with suppress(TypeError): + 1/0 + + def test_no_args(self): + with self.assertRaises(ZeroDivisionError): + with suppress(): + 1/0 + def test_multiple_exception_args(self): with suppress(ZeroDivisionError, TypeError): 1/0 with suppress(ZeroDivisionError, TypeError): len(5) - def test_exception_hierarchy(self): - with suppress(LookupError): - 'Hello'[50] - def test_cm_is_reentrant(self): ignore_exceptions = suppress(Exception) with ignore_exceptions: @@ -21,6 +21,11 @@ Core and Builtins Library ------- +- Issue #19330: the unnecessary wrapper functions have been removed from the + implementations of the new contextlib.redirect_stdout and + contextlib.suppress context managers, which also ensures they provide + reasonable help() output on instances + - Issue #18685: Restore re performance to pre-PEP 393 levels. - Issue #19339: telnetlib module is now using time.monotonic() when available |