[Python-checkins] r45884 - peps/trunk/pep-0343.txt

[nick.coghlan]

Author: nick.coghlan
Date: Wed May  3 11:41:53 2006
New Revision: 45884

Modified:
   peps/trunk/pep-0343.txt
Log:
Address some comments from Guido by cutting back on the overengineering in the terminology section. Also a few minor grammar cleanups and fixes I missed last night.

Modified: peps/trunk/pep-0343.txt
==============================================================================
--- peps/trunk/pep-0343.txt	(original)
+++ peps/trunk/pep-0343.txt	Wed May  3 11:41:53 2006
@@ -15,8 +15,8 @@
     it possible to factor out standard uses of try/finally statements.
 
     In this PEP, context managers provide __enter__() and __exit__()
-    methods that are invoked on entry to and exit from the managed
-    context that forms the body of the with statement.
+    methods that are invoked on entry to and exit from the body of the
+    with statement.
 
 Author's Note
 
@@ -50,8 +50,8 @@
     [2] and universally approved of.  I'm also changing the keyword to
     'with'.
 
-    Following acceptance of this PEP, the following PEPs have been
-    rejected due to overlap:
+    After acceptance of this PEP, the following PEPs were rejected due
+    to overlap:
 
     - PEP 310, Reliable Acquisition/Release Pairs.  This is the
       original with-statement proposal.
@@ -469,37 +469,29 @@
     and that objects that implement that protocol be known as "context
     managers". [4]
 
-    The code in the body of the with statement is a "managed context".
-    This term refers primarily to the code location, rather than to the
-    runtime environment established by the context manager.
-
     The expression immediately following the with keyword in the
     statement is a "context expression" as that expression provides the
     main clue as to the runtime environment the context manager
-    establishes for the duration of the managed context.
+    establishes for the duration of the statement body.
 
-    The value assigned to the target list after the as keyword is the
-    "context entry value", as that value is returned as the result of
-    entering the context.
-
-    These terms are based on the idea that the context expression
-    provides a context manager to appropriately handle entry into the
-    managed context. The context manager may also provide a meaningful
-    context entry value and perform clean up operations on exit from
-    the managed context.
-
-    The general term "context" is unfortunately ambiguous. If necessary,
-    it can be made more explicit by using the terms "context manager"
-    for the concrete object created by the context expression,
-    "managed context" for the code in the body of the with statement,
-    and "runtime context" or (preferebly) "runtime environment" for the
-    actual state modifications made by the context manager. When solely
-    discussing use of the with statement, the distinction between these
-    shouldn't matter too much as the context manager fully defines the
-    changes made to the runtime environment, and those changes apply for
-    the duration of the managed context. The distinction is more
-    important when discussing the process of implementing context
-    managers and the mechanics of the with statement itself.
+    The code in the body of the with statement and the variable name
+    (or names) after the as keyword don't really have special terms at
+    this point in time. The general terms "statement body" and "target
+    list" can be used, prefixing with "with" or "with statement" if the
+    terms would otherwise be unclear.
+
+    Given the existence of objects such as the decimal module's
+    arithmetic context, a term "context" is unfortunately ambiguous.
+    If necessary, it can be made more specific by using the terms
+    "context manager" for the concrete object created by the context
+    expression and "runtime context" or (preferably) "runtime
+    environment" for the actual state modifications made by the context
+    manager. When simply discussing use of the with statement, the
+    ambiguity shouldn't matter too much as the context expression fully
+    defines the changes made to the runtime environment.
+    The distinction is more important when discussing the mechanics of
+    the with statement itself and how to go about actually implementing
+    context managers.
 
 Caching Context Managers
 
@@ -531,7 +523,7 @@
 
     1. Greg Ewing raised the question of whether or not the term
        "context manager" was too generic and suggested "context guard"
-       as an alternative name.
+       as an alternative name. [16]
 
     2. In Python 2.5a2, the decorator in contextlib to create a
        context manager from a generator function is called
@@ -594,9 +586,9 @@
 Examples
 
     The generator based examples rely on PEP 342. Also, some of the
-    examples are likely to be unnecessary in practice, as the
-    appropriate objects, such as threading.RLock, will be able to be
-    used directly in with statements.
+    examples are unnecessary in practice, as the appropriate objects,
+    such as threading.RLock, are able to be used directly in with
+    statements.
 
     The tense used in the names of the example contexts is not
     arbitrary. Past tense ("-ed") is used when the name refers to an
@@ -755,9 +747,8 @@
             # so this must be outside the with-statement:
             return +s
 
-     9. Here's a proposed context manager for the decimal module:
+     9. Here's a simple context manager for the decimal module:
 
-         # This would be a new decimal.Context method
          @contextmanager
          def localcontext(ctx=None):
              """Set a new local decimal context for the block"""
@@ -906,7 +897,7 @@
     This PEP was first accepted by Guido at his EuroPython
     keynote, 27 June 2005.
     It was accepted again later, with the __context__ method added.
-    The PEP was implemented in subversion for Python 2.5a1
+    The PEP was implemented in Subversion for Python 2.5a1
     The __context__() method will be removed in Python 2.5a3
 
 
@@ -970,7 +961,7 @@
     [15] Guido kills the __context__() method
     http://mail.python.org/pipermail/python-dev/2006-April/064632.html
 
-    [16] Greg propose 'context guard' instead of 'context manager'
+    [16] Proposal to use 'context guard' instead of 'context manager'
     http://mail.python.org/pipermail/python-dev/2006-May/064676.html
 
 Copyright