[Python-checkins] r54005 - sandbox/trunk/2to3/fixes/fix_apply.py sandbox/trunk/2to3/fixes/fix_except.py sandbox/trunk/2to3/fixes/fix_exec.py sandbox/trunk/2to3/fixes/fix_has_key.py sandbox/trunk/2to3/fixes/fix_intern.py sandbox/trunk/2to3/fixes/fix_raise.py sandbox/trunk/2to3/fixes/fix_throw.py

[collin.winter]

Author: collin.winter
Date: Wed Feb 28 00:02:12 2007
New Revision: 54005

Modified:
   sandbox/trunk/2to3/fixes/fix_apply.py
   sandbox/trunk/2to3/fixes/fix_except.py
   sandbox/trunk/2to3/fixes/fix_exec.py
   sandbox/trunk/2to3/fixes/fix_has_key.py
   sandbox/trunk/2to3/fixes/fix_intern.py
   sandbox/trunk/2to3/fixes/fix_raise.py
   sandbox/trunk/2to3/fixes/fix_throw.py
Log:
More comprehensive docstrings for fixer modules

Modified: sandbox/trunk/2to3/fixes/fix_apply.py
==============================================================================
--- sandbox/trunk/2to3/fixes/fix_apply.py	(original)
+++ sandbox/trunk/2to3/fixes/fix_apply.py	Wed Feb 28 00:02:12 2007
@@ -1,7 +1,9 @@
 # Copyright 2006 Google, Inc. All Rights Reserved.
 # Licensed to PSF under a Contributor Agreement.
 
-"""Fixer for apply()."""
+"""Fixer for apply().
+
+This converts apply(func, v, k) into (func)(*v, **k)."""
 
 # Local imports
 import pytree

Modified: sandbox/trunk/2to3/fixes/fix_except.py
==============================================================================
--- sandbox/trunk/2to3/fixes/fix_except.py	(original)
+++ sandbox/trunk/2to3/fixes/fix_except.py	Wed Feb 28 00:02:12 2007
@@ -1,4 +1,26 @@
-"""Fixer for except statements with named exceptions."""
+"""Fixer for except statements with named exceptions.
+
+The following cases will be converted:
+
+- "except E, T:" where T is a name:
+    
+    except E as T:
+    
+- "except E, T:" where T is not a name, tuple or list:
+    
+        except E as t:
+            T = t
+        
+    This is done because the target of an "except" clause must be a
+    name.
+    
+- "except E, T:" where T is a tuple or list literal:
+    
+        except E as t:
+            T = t.message
+    
+    This transformation is still under consideration.
+"""
 # Author: Collin Winter
 
 # Local imports
@@ -18,8 +40,6 @@
 as_leaf = pytree.Leaf(token.NAME, "as")
 as_leaf.set_prefix(" ")
 
-tuple_reason = "exception unpacking is going away"
-
 class FixExcept(basefix.BaseFix):
 
     PATTERN = """

Modified: sandbox/trunk/2to3/fixes/fix_exec.py
==============================================================================
--- sandbox/trunk/2to3/fixes/fix_exec.py	(original)
+++ sandbox/trunk/2to3/fixes/fix_exec.py	Wed Feb 28 00:02:12 2007
@@ -1,7 +1,13 @@
 # Copyright 2006 Google, Inc. All Rights Reserved.
 # Licensed to PSF under a Contributor Agreement.
 
-"""Fixer for exec."""
+"""Fixer for exec.
+
+This converts usages of the exec statement into calls to a built-in
+exec() function.
+
+exec code in ns1, ns2 -> exec(code, ns1, ns2)
+"""
 
 # Local imports
 import pytree

Modified: sandbox/trunk/2to3/fixes/fix_has_key.py
==============================================================================
--- sandbox/trunk/2to3/fixes/fix_has_key.py	(original)
+++ sandbox/trunk/2to3/fixes/fix_has_key.py	Wed Feb 28 00:02:12 2007
@@ -1,7 +1,33 @@
 # Copyright 2006 Google, Inc. All Rights Reserved.
 # Licensed to PSF under a Contributor Agreement.
 
-"""Fixer for has_key()."""
+"""Fixer for has_key().
+
+Calls to .has_key() methods are expressed in terms of the 'in'
+operator:
+
+    d.has_key(k) -> k in d
+
+CAVEATS:
+1) While the primary target of this fixer is dict.has_key(), the
+   fixer will change any has_key() method call, regardless of its
+   class.
+
+2) Cases like this will not be converted:
+
+    m = d.has_key
+    if m(k):
+        ...
+        
+   Only *calls* to has_key() are converted. While it is possible to
+   convert the above to something like
+   
+    m = d.__contains__
+    if m(k):
+        ...
+        
+   this is currently not done.
+"""
 
 # Local imports
 import pytree

Modified: sandbox/trunk/2to3/fixes/fix_intern.py
==============================================================================
--- sandbox/trunk/2to3/fixes/fix_intern.py	(original)
+++ sandbox/trunk/2to3/fixes/fix_intern.py	Wed Feb 28 00:02:12 2007
@@ -1,7 +1,9 @@
 # Copyright 2006 Georg Brandl.
 # Licensed to PSF under a Contributor Agreement.
 
-"""Fixer for intern()."""
+"""Fixer for intern().
+
+intern(s) -> sys.intern(s)"""
 
 # Local imports
 import pytree

Modified: sandbox/trunk/2to3/fixes/fix_raise.py
==============================================================================
--- sandbox/trunk/2to3/fixes/fix_raise.py	(original)
+++ sandbox/trunk/2to3/fixes/fix_raise.py	Wed Feb 28 00:02:12 2007
@@ -1,4 +1,24 @@
-"""Fixer for 'raise E, V, T'"""
+"""Fixer for 'raise E, V, T'
+
+raise         -> raise
+raise E       -> raise E
+raise E, V    -> raise E(V)
+raise E, V, T -> raise E(V).with_traceback(T)
+
+raise (((E, E'), E''), E'''), V -> raise E(V)
+raise "foo", V, T               -> warns about string exceptions
+
+
+CAVEATS:
+1) "raise E, V" will be incorrectly translated if V is an exception
+   instance. The correct Python 3 idiom is
+   
+        raise E from V
+        
+   but since we can't detect instance-hood by syntax alone and since
+   any client code would have to be changed as well, we don't automate
+   this.
+"""
 # Author: Collin Winter
 
 # Local imports

Modified: sandbox/trunk/2to3/fixes/fix_throw.py
==============================================================================
--- sandbox/trunk/2to3/fixes/fix_throw.py	(original)
+++ sandbox/trunk/2to3/fixes/fix_throw.py	Wed Feb 28 00:02:12 2007
@@ -1,4 +1,10 @@
-"""Fixer for generator.throw(E, V, T)"""
+"""Fixer for generator.throw(E, V, T).
+
+g.throw(E)       -> g.throw(E)
+g.throw(E, V)    -> g.throw(E(V))
+g.throw(E, V, T) -> g.throw(E(V).with_traceback(T))
+
+g.throw("foo"[, V[, T]]) will warn about string exceptions."""
 # Author: Collin Winter
 
 # Local imports