Mailman 3 May 2012 - Python-checkins

cpython (2.7): Issue #14962: Update text coloring in IDLE shell window after changing
by ned.deily May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/1a4e99460438 changeset: 77265:1a4e99460438 branch: 2.7 parent: 77253:8817c295a8ee user: Ned Deily <nad(a)acm.org> date: Thu May 31 09:17:29 2012 -0700 summary: Issue #14962: Update text coloring in IDLE shell window after changing options. Patch by Roger Serwy. files: Lib/idlelib/PyShell.py | 5 +++++ Misc/NEWS | 3 +++ 2 files changed, 8 insertions(+), 0 deletions(-) diff --git a/Lib/idlelib/PyShell.py b/Lib/idlelib/PyShell.py --- a/Lib/idlelib/PyShell.py +++ b/Lib/idlelib/PyShell.py @@ -313,6 +313,11 @@ "console": idleConf.GetHighlight(theme, "console"), }) + def removecolors(self): + # Don't remove shell color tags before "iomark" + for tag in self.tagdefs: + self.tag_remove(tag, "iomark", "end") + class ModifiedUndoDelegator(UndoDelegator): "Extend base class: forbid insert/delete before the I/O mark" diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -67,6 +67,9 @@ Library ------- +- Issue #14962: Update text coloring in IDLE shell window after changing + options. Patch by Roger Serwy. + - Issue #10997: Prevent a duplicate entry in IDLE's "Recent Files" menu. - Issue12510: Attempting to get invalid tooltip no longer closes Idle. -- Repository URL: http://hg.python.org/cpython

1 0

cpython: Issue #14952: Fix incorrect output dll names for win64/debug builds, causing
by kristjan.jonsson May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/c7b16e2be71a changeset: 77264:c7b16e2be71a user: Kristjan Valur Jonsson <sweskman(a)gmail.com> date: Thu May 31 15:09:21 2012 +0000 summary: Issue #14952: Fix incorrect output dll names for win64/debug builds, causing the dll importer on windows to fail. files: PCbuild/pythoncore.vcxproj | 4 ---- 1 files changed, 0 insertions(+), 4 deletions(-) diff --git a/PCbuild/pythoncore.vcxproj b/PCbuild/pythoncore.vcxproj --- a/PCbuild/pythoncore.vcxproj +++ b/PCbuild/pythoncore.vcxproj @@ -203,7 +203,6 @@ </PreLinkEvent> <Link> <AdditionalDependencies>$(IntDir)getbuildinfo.o;%(AdditionalDependencies)</AdditionalDependencies> - <OutputFile>$(OutDir)$(PyDllName).dll</OutputFile> <IgnoreSpecificDefaultLibraries>libc;%(IgnoreSpecificDefaultLibraries)</IgnoreSpecificDefaultLibraries> <BaseAddress>0x1e000000</BaseAddress> </Link> @@ -257,7 +256,6 @@ </PreLinkEvent> <Link> <AdditionalDependencies>$(IntDir)getbuildinfo.o;%(AdditionalDependencies)</AdditionalDependencies> - <OutputFile>$(OutDir)$(PyDllName)_d.dll</OutputFile> <IgnoreSpecificDefaultLibraries>libc;%(IgnoreSpecificDefaultLibraries)</IgnoreSpecificDefaultLibraries> <BaseAddress>0x1e000000</BaseAddress> </Link> @@ -306,7 +304,6 @@ </PreLinkEvent> <Link> <AdditionalDependencies>$(IntDir)getbuildinfo.o;%(AdditionalDependencies)</AdditionalDependencies> - <OutputFile>$(OutDir)$(PyDllName).dll</OutputFile> <IgnoreSpecificDefaultLibraries>libc;%(IgnoreSpecificDefaultLibraries)</IgnoreSpecificDefaultLibraries> <BaseAddress>0x1e000000</BaseAddress> <TargetMachine>MachineX64</TargetMachine> @@ -356,7 +353,6 @@ </PreLinkEvent> <Link> <AdditionalDependencies>$(IntDir)getbuildinfo.o;%(AdditionalDependencies)</AdditionalDependencies> - <OutputFile>$(OutDir)$(PyDllName).dll</OutputFile> <IgnoreSpecificDefaultLibraries>libc;%(IgnoreSpecificDefaultLibraries)</IgnoreSpecificDefaultLibraries> <BaseAddress>0x1e000000</BaseAddress> <TargetMachine>MachineX64</TargetMachine> -- Repository URL: http://hg.python.org/cpython

1 0

cpython: Improve comments.
by stefan.krah May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/8c7bfd7ab995 changeset: 77263:8c7bfd7ab995 user: Stefan Krah <skrah(a)bytereef.org> date: Thu May 31 16:21:34 2012 +0200 summary: Improve comments. files: Modules/_decimal/libmpdec/mpdecimal.c | 18 +++++++++++--- 1 files changed, 14 insertions(+), 4 deletions(-) diff --git a/Modules/_decimal/libmpdec/mpdecimal.c b/Modules/_decimal/libmpdec/mpdecimal.c --- a/Modules/_decimal/libmpdec/mpdecimal.c +++ b/Modules/_decimal/libmpdec/mpdecimal.c @@ -3953,8 +3953,18 @@ } /* - * Internal function, specials have been dealt with. The result has a - * relative error of less than 0.5 * 10**(-ctx->prec). + * Internal function, specials have been dealt with. Apart from Overflow + * and Underflow, two cases must be considered for the error of the result: + * + * 1) abs(a) <= 9 * 10**(-prec-1) ==> result == 1 + * + * Absolute error: abs(1 - e**x) < 10**(-prec) + * ------------------------------------------- + * + * 2) abs(a) > 9 * 10**(-prec-1) + * + * Relative error: abs(result - e**x) < 0.5 * 10**(-prec) * e**x + * ------------------------------------------------------------- * * The algorithm is from Hull&Abrham, Variable Precision Exponential Function, * ACM Transactions on Mathematical Software, Vol. 12, No. 2, June 1986. @@ -3998,9 +4008,9 @@ * * MAX-EMAX+1 < log10(e^(0.1*10*t)) <= log10(e^(r*10^t)) < adjexp(e^(r*10^t))+1 * - * (2) -1 < r <= -0.1, so e^r <= e^-0.1. It t > MAX_T, underflow occurs: + * (2) -1 < r <= -0.1, so e^r <= e^-0.1. If t > MAX_T, underflow occurs: * - * adjexp(e^(r*10^t)) <= log10(e^(r*10^t)) <= log10(e^(-0.1*10^t) < MIN-ETINY + * adjexp(e^(r*10^t)) <= log10(e^(r*10^t)) <= log10(e^(-0.1*10^t)) < MIN-ETINY */ #if defined(CONFIG_64) #define MPD_EXP_MAX_T 19 -- Repository URL: http://hg.python.org/cpython

1 0

cpython (merge default -> default): Merge.
by stefan.krah May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/c623f681ad1a changeset: 77262:c623f681ad1a parent: 77261:dff6dd248059 parent: 77260:c0c7618762e5 user: Stefan Krah <skrah(a)bytereef.org> date: Thu May 31 16:03:49 2012 +0200 summary: Merge. files: Lib/contextlib.py | 41 +++++++++--------------- Lib/test/test_contextlib.py | 6 +++ Misc/NEWS | 8 ++++- 3 files changed, 28 insertions(+), 27 deletions(-) diff --git a/Lib/contextlib.py b/Lib/contextlib.py --- a/Lib/contextlib.py +++ b/Lib/contextlib.py @@ -225,32 +225,21 @@ return self def __exit__(self, *exc_details): - if not self._exit_callbacks: - return - # This looks complicated, but it is really just - # setting up a chain of try-expect statements to ensure - # that outer callbacks still get invoked even if an - # inner one throws an exception - def _invoke_next_callback(exc_details): - # Callbacks are removed from the list in FIFO order - # but the recursion means they're invoked in LIFO order - cb = self._exit_callbacks.popleft() - if not self._exit_callbacks: - # Innermost callback is invoked directly - return cb(*exc_details) - # More callbacks left, so descend another level in the stack + # Callbacks are invoked in LIFO order to match the behaviour of + # nested context managers + suppressed_exc = False + while self._exit_callbacks: + cb = self._exit_callbacks.pop() try: - suppress_exc = _invoke_next_callback(exc_details) + if cb(*exc_details): + suppressed_exc = True + exc_details = (None, None, None) except: - suppress_exc = cb(*sys.exc_info()) - # Check if this cb suppressed the inner exception - if not suppress_exc: + new_exc_details = sys.exc_info() + if exc_details != (None, None, None): + # simulate the stack of exceptions by setting the context + new_exc_details[1].__context__ = exc_details[1] + if not self._exit_callbacks: raise - else: - # Check if inner cb suppressed the original exception - if suppress_exc: - exc_details = (None, None, None) - suppress_exc = cb(*exc_details) or suppress_exc - return suppress_exc - # Kick off the recursive chain - return _invoke_next_callback(exc_details) + exc_details = new_exc_details + return suppressed_exc diff --git a/Lib/test/test_contextlib.py b/Lib/test/test_contextlib.py --- a/Lib/test/test_contextlib.py +++ b/Lib/test/test_contextlib.py @@ -572,6 +572,12 @@ stack.push(lambda *exc: 1/0) stack.push(lambda *exc: {}[1]) + def test_excessive_nesting(self): + # The original implementation would die with RecursionError here + with ExitStack() as stack: + for i in range(10000): + stack.callback(int) + def test_instance_bypass(self): class Example(object): pass cm = Example() diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -7,11 +7,17 @@ *Release date: TBD* +Library +------- + +- Issue #14963: Convert contextlib.ExitStack.__exit__ to use an iterative + algorithm (Patch by Alon Horev) + Tests ----- - Issue #14963 (partial): Add test cases for exception handling behaviour - in contextlib.ContextStack (Initial patch by Alon Horev) + in contextlib.ExitStack (Initial patch by Alon Horev) What's New in Python 3.3.0 Alpha 4? =================================== -- Repository URL: http://hg.python.org/cpython

1 0

cpython: Pad the result with zeros just before the final rounding.
by stefan.krah May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/dff6dd248059 changeset: 77261:dff6dd248059 parent: 77259:fc73e6ea9e73 user: Stefan Krah <skrah(a)bytereef.org> date: Thu May 31 16:00:21 2012 +0200 summary: Pad the result with zeros just before the final rounding. files: Modules/_decimal/libmpdec/mpdecimal.c | 4 +--- 1 files changed, 1 insertions(+), 3 deletions(-) diff --git a/Modules/_decimal/libmpdec/mpdecimal.c b/Modules/_decimal/libmpdec/mpdecimal.c --- a/Modules/_decimal/libmpdec/mpdecimal.c +++ b/Modules/_decimal/libmpdec/mpdecimal.c @@ -3903,7 +3903,6 @@ /* abs(a) <= 9 * 10**(-prec-1) */ if (_mpd_cmp(&aa, &lim) <= 0) { _settriple(result, 0, 1, 0); - _mpd_zeropad(result, ctx, status); *status |= MPD_Rounded|MPD_Inexact; return 1; } @@ -4074,8 +4073,6 @@ } #endif - _mpd_zeropad(result, ctx, status); - mpd_del(&tmp); mpd_del(&sum); *status |= (workctx.status&MPD_Errors); @@ -4148,6 +4145,7 @@ if (mpd_isspecial(result) || mpd_iszerocoeff(result) || mpd_qcmp(&t1, &t2, status) == 0) { workctx.clamp = ctx->clamp; + _mpd_zeropad(result, ctx, status); mpd_check_underflow(result, &workctx, status); mpd_qfinalize(result, &workctx, status); break; -- Repository URL: http://hg.python.org/cpython

1 0

cpython: Close #14963: Use an iterative algorithm in contextlib.ExitStack.__exit__
by nick.coghlan May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/c0c7618762e5 changeset: 77260:c0c7618762e5 user: Nick Coghlan <ncoghlan(a)gmail.com> date: Fri Jun 01 00:00:38 2012 +1000 summary: Close #14963: Use an iterative algorithm in contextlib.ExitStack.__exit__ (Patch by Alon Horev) files: Lib/contextlib.py | 41 +++++++++--------------- Lib/test/test_contextlib.py | 6 +++ Misc/NEWS | 8 ++++- 3 files changed, 28 insertions(+), 27 deletions(-) diff --git a/Lib/contextlib.py b/Lib/contextlib.py --- a/Lib/contextlib.py +++ b/Lib/contextlib.py @@ -225,32 +225,21 @@ return self def __exit__(self, *exc_details): - if not self._exit_callbacks: - return - # This looks complicated, but it is really just - # setting up a chain of try-expect statements to ensure - # that outer callbacks still get invoked even if an - # inner one throws an exception - def _invoke_next_callback(exc_details): - # Callbacks are removed from the list in FIFO order - # but the recursion means they're invoked in LIFO order - cb = self._exit_callbacks.popleft() - if not self._exit_callbacks: - # Innermost callback is invoked directly - return cb(*exc_details) - # More callbacks left, so descend another level in the stack + # Callbacks are invoked in LIFO order to match the behaviour of + # nested context managers + suppressed_exc = False + while self._exit_callbacks: + cb = self._exit_callbacks.pop() try: - suppress_exc = _invoke_next_callback(exc_details) + if cb(*exc_details): + suppressed_exc = True + exc_details = (None, None, None) except: - suppress_exc = cb(*sys.exc_info()) - # Check if this cb suppressed the inner exception - if not suppress_exc: + new_exc_details = sys.exc_info() + if exc_details != (None, None, None): + # simulate the stack of exceptions by setting the context + new_exc_details[1].__context__ = exc_details[1] + if not self._exit_callbacks: raise - else: - # Check if inner cb suppressed the original exception - if suppress_exc: - exc_details = (None, None, None) - suppress_exc = cb(*exc_details) or suppress_exc - return suppress_exc - # Kick off the recursive chain - return _invoke_next_callback(exc_details) + exc_details = new_exc_details + return suppressed_exc diff --git a/Lib/test/test_contextlib.py b/Lib/test/test_contextlib.py --- a/Lib/test/test_contextlib.py +++ b/Lib/test/test_contextlib.py @@ -572,6 +572,12 @@ stack.push(lambda *exc: 1/0) stack.push(lambda *exc: {}[1]) + def test_excessive_nesting(self): + # The original implementation would die with RecursionError here + with ExitStack() as stack: + for i in range(10000): + stack.callback(int) + def test_instance_bypass(self): class Example(object): pass cm = Example() diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -7,11 +7,17 @@ *Release date: TBD* +Library +------- + +- Issue #14963: Convert contextlib.ExitStack.__exit__ to use an iterative + algorithm (Patch by Alon Horev) + Tests ----- - Issue #14963 (partial): Add test cases for exception handling behaviour - in contextlib.ContextStack (Initial patch by Alon Horev) + in contextlib.ExitStack (Initial patch by Alon Horev) What's New in Python 3.3.0 Alpha 4? =================================== -- Repository URL: http://hg.python.org/cpython

1 0

cpython: Issue #14963: Added test cases for contextlib.ExitStack exception handling
by nick.coghlan May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/fc73e6ea9e73 changeset: 77259:fc73e6ea9e73 user: Nick Coghlan <ncoghlan(a)gmail.com> date: Thu May 31 23:49:26 2012 +1000 summary: Issue #14963: Added test cases for contextlib.ExitStack exception handling behaviour (Initial patch by Alon Horev) files: Lib/test/test_contextlib.py | 89 +++++++++++++++++++++++++ Misc/ACKS | 1 + Misc/NEWS | 11 +++ 3 files changed, 101 insertions(+), 0 deletions(-) diff --git a/Lib/test/test_contextlib.py b/Lib/test/test_contextlib.py --- a/Lib/test/test_contextlib.py +++ b/Lib/test/test_contextlib.py @@ -483,6 +483,95 @@ new_stack.close() self.assertEqual(result, [1, 2, 3]) + def test_exit_raise(self): + with self.assertRaises(ZeroDivisionError): + with ExitStack() as stack: + stack.push(lambda *exc: False) + 1/0 + + def test_exit_suppress(self): + with ExitStack() as stack: + stack.push(lambda *exc: True) + 1/0 + + def test_exit_exception_chaining_reference(self): + # Sanity check to make sure that ExitStack chaining matches + # actual nested with statements + class RaiseExc: + def __init__(self, exc): + self.exc = exc + def __enter__(self): + return self + def __exit__(self, *exc_details): + raise self.exc + + class SuppressExc: + def __enter__(self): + return self + def __exit__(self, *exc_details): + type(self).saved_details = exc_details + return True + + try: + with RaiseExc(IndexError): + with RaiseExc(KeyError): + with RaiseExc(AttributeError): + with SuppressExc(): + with RaiseExc(ValueError): + 1 / 0 + except IndexError as exc: + self.assertIsInstance(exc.__context__, KeyError) + self.assertIsInstance(exc.__context__.__context__, AttributeError) + # Inner exceptions were suppressed + self.assertIsNone(exc.__context__.__context__.__context__) + else: + self.fail("Expected IndexError, but no exception was raised") + # Check the inner exceptions + inner_exc = SuppressExc.saved_details[1] + self.assertIsInstance(inner_exc, ValueError) + self.assertIsInstance(inner_exc.__context__, ZeroDivisionError) + + def test_exit_exception_chaining(self): + # Ensure exception chaining matches the reference behaviour + def raise_exc(exc): + raise exc + + saved_details = None + def suppress_exc(*exc_details): + nonlocal saved_details + saved_details = exc_details + return True + + try: + with ExitStack() as stack: + stack.callback(raise_exc, IndexError) + stack.callback(raise_exc, KeyError) + stack.callback(raise_exc, AttributeError) + stack.push(suppress_exc) + stack.callback(raise_exc, ValueError) + 1 / 0 + except IndexError as exc: + self.assertIsInstance(exc.__context__, KeyError) + self.assertIsInstance(exc.__context__.__context__, AttributeError) + # Inner exceptions were suppressed, but the with statement + # cleanup code adds the one from the body back in as the + # context of the exception raised by the outer callbacks + # See http://bugs.python.org/issue14969 + suite_exc = exc.__context__.__context__.__context__ + self.assertIsInstance(suite_exc, ZeroDivisionError) + else: + self.fail("Expected IndexError, but no exception was raised") + # Check the inner exceptions + inner_exc = saved_details[1] + self.assertIsInstance(inner_exc, ValueError) + self.assertIsInstance(inner_exc.__context__, ZeroDivisionError) + + def test_exit_exception_chaining_suppress(self): + with ExitStack() as stack: + stack.push(lambda *exc: True) + stack.push(lambda *exc: 1/0) + stack.push(lambda *exc: {}[1]) + def test_instance_bypass(self): class Example(object): pass cm = Example() diff --git a/Misc/ACKS b/Misc/ACKS --- a/Misc/ACKS +++ b/Misc/ACKS @@ -460,6 +460,7 @@ Brian Hooper Randall Hopper Nadav Horesh +Alon Horev Jan Hosang Ken Howard Brad Howes diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -2,6 +2,17 @@ Python News +++++++++++ +What's New in Python 3.3.0 Beta 1? +=================================== + +*Release date: TBD* + +Tests +----- + +- Issue #14963 (partial): Add test cases for exception handling behaviour + in contextlib.ContextStack (Initial patch by Alon Horev) + What's New in Python 3.3.0 Alpha 4? =================================== -- Repository URL: http://hg.python.org/cpython

1 0

cpython: Do not clobber existing flags.
by stefan.krah May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/05097240ffb0 changeset: 77258:05097240ffb0 user: Stefan Krah <skrah(a)bytereef.org> date: Thu May 31 15:09:27 2012 +0200 summary: Do not clobber existing flags. files: Modules/_decimal/libmpdec/mpdecimal.c | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) diff --git a/Modules/_decimal/libmpdec/mpdecimal.c b/Modules/_decimal/libmpdec/mpdecimal.c --- a/Modules/_decimal/libmpdec/mpdecimal.c +++ b/Modules/_decimal/libmpdec/mpdecimal.c @@ -3904,7 +3904,7 @@ if (_mpd_cmp(&aa, &lim) <= 0) { _settriple(result, 0, 1, 0); _mpd_zeropad(result, ctx, status); - *status = MPD_Rounded|MPD_Inexact; + *status |= MPD_Rounded|MPD_Inexact; return 1; } -- Repository URL: http://hg.python.org/cpython

1 0

cpython: Typo fix
by nick.coghlan May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/e2998e66fab6 changeset: 77257:e2998e66fab6 user: Nick Coghlan <ncoghlan(a)gmail.com> date: Thu May 31 22:34:59 2012 +1000 summary: Typo fix files: Doc/library/contextlib.rst | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -308,7 +308,7 @@ In the specific case of a single optional context manager, :class:`ExitStack` instances can be used as a "do nothing" context manager, allowing a context -managers to easily be omitted without affecting the overall structure of +manager to easily be omitted without affecting the overall structure of the source code:: def debug_trace(details): -- Repository URL: http://hg.python.org/cpython

1 0

cpython: Additional ExitStack examples, and a few other cleanups for the ExitStack docs
by nick.coghlan May 31, 2012

May 31, 2012

http://hg.python.org/cpython/rev/5d91d87b5969 changeset: 77256:5d91d87b5969 user: Nick Coghlan <ncoghlan(a)gmail.com> date: Thu May 31 22:17:08 2012 +1000 summary: Additional ExitStack examples, and a few other cleanups for the ExitStack docs files: Doc/library/contextlib.rst | 82 +++++++++++++++++++++++-- 1 files changed, 75 insertions(+), 7 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -188,15 +188,15 @@ Each instance maintains a stack of registered callbacks that are called in reverse order when the instance is closed (either explicitly or implicitly - at the end of a ``with`` statement). Note that callbacks are *not* invoked - implicitly when the context stack instance is garbage collected. + at the end of a :keyword:`with` statement). Note that callbacks are *not* + invoked implicitly when the context stack instance is garbage collected. This stack model is used so that context managers that acquire their resources in their ``__init__`` method (such as file objects) can be handled correctly. Since registered callbacks are invoked in the reverse order of - registration, this ends up behaving as if multiple nested ``with`` + registration, this ends up behaving as if multiple nested :keyword:`with` statements had been used with the registered set of callbacks. This even extends to exception handling - if an inner callback suppresses or replaces an exception, then outer callbacks will be passed arguments based on that @@ -216,7 +216,7 @@ manager's own :meth:`__enter__` method. These context managers may suppress exceptions just as they normally - would if used directly as part of a ``with`` statement. + would if used directly as part of a :keyword:`with` statement. .. method:: push(exit) @@ -234,7 +234,7 @@ same way context manager :meth:`__exit__` methods can. The passed in object is returned from the function, allowing this - method to be used is a function decorator. + method to be used as a function decorator. .. method:: callback(callback, *args, **kwds) @@ -245,14 +245,14 @@ exceptions (as they are never passed the exception details). The passed in callback is returned from the function, allowing this - method to be used is a function decorator. + method to be used as a function decorator. .. method:: pop_all() Transfers the callback stack to a fresh :class:`ExitStack` instance and returns it. No callbacks are invoked by this operation - instead, they will now be invoked when the new stack is closed (either - explicitly or implicitly). + explicitly or implicitly at the end of a :keyword:`with` statement). For example, a group of files can be opened as an "all or nothing" operation as follows:: @@ -280,6 +280,74 @@ the tools provided by :mod:`contextlib`. +Supporting a variable number of context managers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The primary use case for :class:`ExitStack` is the one given in the class +documentation: supporting a variable number of context managers and other +cleanup operations in a single :keyword:`with` statement. The variability +may come from the number of context managers needed being driven by user +input (such as opening a user specified collection of files), or from +some of the context managers being optional:: + + with ExitStack() as stack: + for resource in resources: + stack.enter_context(resource) + if need_special resource: + special = acquire_special_resource() + stack.callback(release_special_resource, special) + # Perform operations that use the acquired resources + +As shown, :class:`ExitStack` also makes it quite easy to use :keyword:`with` +statements to manage arbitrary resources that don't natively support the +context management protocol. + + +Simplifying support for single optional context managers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the specific case of a single optional context manager, :class:`ExitStack` +instances can be used as a "do nothing" context manager, allowing a context +managers to easily be omitted without affecting the overall structure of +the source code:: + + def debug_trace(details): + if __debug__: + return TraceContext(details) + # Don't do anything special with the context in release mode + return ExitStack() + + with debug_trace(): + # Suite is traced in debug mode, but runs normally otherwise + + +Catching exceptions from ``__enter__`` methods +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is occasionally desirable to catch exceptions from an ``__enter__`` +method implementation, *without* inadvertently catching exceptions from +the :keyword:`with` statement body or the context manager's ``__exit__`` +method. By using :class:`ExitStack` the steps in the context management +protocol can be separated slightly in order to allow this:: + + stack = ExitStack() + try: + x = stack.enter_context(cm) + except Exception: + # handle __enter__ exception + else: + with stack: + # Handle normal case + +Actually needing to do this is likely to indicate that the underlying API +should be providing a direct resource management interface for use with +:keyword:`try`/:keyword:`except`/:keyword:`finally` statements, but not +all APIs are well designed in that regard. When a context manager is the +only resource management API provided, then :class:`ExitStack` can make it +easier to handle various situations that can't be handled directly in a +:keyword:`with` statement. + + Cleaning up in an ``__enter__`` implementation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- Repository URL: http://hg.python.org/cpython

1 0