Backport of decimal module context management updates from rev 51694 to 2.5 release branch
diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex
index a0c7bde..127eb1d 100644
--- a/Doc/lib/libdecimal.tex
+++ b/Doc/lib/libdecimal.tex
@@ -435,36 +435,37 @@
the \function{getcontext()} and \function{setcontext()} functions:
\begin{funcdesc}{getcontext}{}
- Return the current context for the active thread.
+ Return the current context for the active thread.
\end{funcdesc}
\begin{funcdesc}{setcontext}{c}
- Set the current context for the active thread to \var{c}.
+ Set the current context for the active thread to \var{c}.
\end{funcdesc}
Beginning with Python 2.5, you can also use the \keyword{with} statement
-to temporarily change the active context. For example the following code
-increases the current decimal precision by 2 places, performs a
-calculation, and then automatically restores the previous context:
+and the \function{localcontext()} function to temporarily change the
+active context.
+\begin{funcdesc}{localcontext}{\optional{c}}
+ Return a context manager that will set the current context for
+ the active thread to a copy of \var{c} on entry to the with-statement
+ and restore the previous context when exiting the with-statement. If
+ no context is specified, a copy of the current context is used.
+ \versionadded{2.5}
+
+ For example, the following code sets the current decimal precision
+ to 42 places, performs a calculation, and then automatically restores
+ the previous context:
\begin{verbatim}
-from __future__ import with_statement
-import decimal
+ from __future__ import with_statement
+ from decimal import localcontext
-with decimal.getcontext() as ctx:
- ctx.prec += 2 # add 2 more digits of precision
- calculate_something()
+ with localcontext() as ctx:
+ ctx.prec = 42 # Perform a high precision calculation
+ s = calculate_something()
+ s = +s # Round the final result back to the default precision
\end{verbatim}
-
-The context that's active in the body of the \keyword{with} statement is
-a \emph{copy} of the context you provided to the \keyword{with}
-statement, so modifying its attributes doesn't affect anything except
-that temporary copy.
-
-You can use any decimal context in a \keyword{with} statement, but if
-you just want to make a temporary change to some aspect of the current
-context, it's easiest to just use \function{getcontext()} as shown
-above.
+\end{funcdesc}
New contexts can also be created using the \class{Context} constructor
described below. In addition, the module provides three pre-made
diff --git a/Doc/whatsnew/whatsnew25.tex b/Doc/whatsnew/whatsnew25.tex
index bf939c0..4272ce3 100644
--- a/Doc/whatsnew/whatsnew25.tex
+++ b/Doc/whatsnew/whatsnew25.tex
@@ -683,22 +683,22 @@
The lock is acquired before the block is executed and always released once
the block is complete.
-The \module{decimal} module's contexts, which encapsulate the desired
-precision and rounding characteristics for computations, provide a
-\method{context_manager()} method for getting a context manager:
+The new \function{localcontext()} function in the \module{decimal} module
+makes it easy to save and restore the current decimal context, which
+encapsulates the desired precision and rounding characteristics for
+computations:
\begin{verbatim}
-import decimal
+from decimal import Decimal, Context, localcontext
# Displays with default precision of 28 digits
-v1 = decimal.Decimal('578')
-print v1.sqrt()
+v = Decimal('578')
+print v.sqrt()
-ctx = decimal.Context(prec=16)
-with ctx.context_manager():
+with localcontext(Context(prec=16)):
# All code in this block uses a precision of 16 digits.
# The original context is restored on exiting the block.
- print v1.sqrt()
+ print v.sqrt()
\end{verbatim}
\subsection{Writing Context Managers\label{context-managers}}