Some additional tweakage, hopefully non-controversial.

pep-0008.txt

@@ -162,19 +162,21 @@ Imports
 
     - Relative imports for intra-package imports are highly discouraged.
       Always use the absolute package path for all imports.
+      (However, once PEP 328 [7] is fully implemented, its style of
+      explicit relative imports will be recommended.)
 
     - When importing a class from a class-containing module, it's usually okay
       to spell this
 
-        from MyClass import MyClass
-        from foo.bar.YourClass import YourClass
+        from myclass import MyClass
+        from foo.bar.yourclass import YourClass
 
       If this spelling causes local name clashes, then spell them
 
-        import MyClass
-        import foo.bar.YourClass
+        import myclass
+        import foo.bar.yourclass
 
-      and use "MyClass.MyClass" and "foo.bar.YourClass.YourClass"
+      and use "myclass.MyClass" and "foo.bar.yourclass.YourClass"
 
 
 Whitespace in Expressions and Statements
@@ -224,8 +226,9 @@ Whitespace in Expressions and Statements
   Other Recommendations
 
     - Always surround these binary operators with a single space on
-      either side: assignment (=), comparisons (==, <, >, !=, <>, <=,
-      >=, in, not in, is, is not), Booleans (and, or, not).
+      either side: assignment (=), augmented assignment (+=, -= etc.),
+      comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not),
+      Booleans (and, or, not).
 
     - Use spaces around arithmetic operators:
 
@@ -269,11 +272,33 @@ Whitespace in Expressions and Statements
           do_two()
           do_three()
 
-      No:
+      Rather not:
 
           if foo == 'blah': do_blah_thing()
           do_one(); do_two(); do_three()
 
+    - While sometimes it's okay to put an if/for/while with a small
+      body on the same line, never do this for multi-clause
+      statements.  Also avoid folding such long lines!
+
+      Rather not:
+
+          if foo == 'blah': do_blah_thing()
+          for x in lst: total += x
+          while t < 10: t = delay()
+
+      Definitely not:
+
+          if foo == 'blah': do_blah_thing()
+          else: do_non_blah_thing()
+
+          try: something()
+          finally: cleanup()
+
+          do_one(); do_two(); do_three(long, argument,
+                                       list, like, this)
+
+          if foo == 'blah': one(); two(); three()
 
 Comments
 
@@ -339,11 +364,12 @@ Documentation Strings
 
     - PEP 257 describes good docstring conventions.  Note that most
       importantly, the """ that ends a multiline docstring should be on a line
-      by itself, e.g.:
+      by itself, and preferably preceded by a blank line, e.g.:
 
       """Return a foobang
 
       Optional plotz says to frobnicate the bizbaz first.
+
       """
 
     - For one liner docstrings, it's okay to keep the closing """ on the same
@@ -408,6 +434,9 @@ Naming Conventions
     names together.  This is not used much in Python, but it is mentioned for
     completeness.  For example, the os.stat() function returns a tuple whose
     items traditionally have names like st_mode, st_size, st_mtime and so on.
+    (This is done to emphasize the correspondence with the fields of the
+    POSIX system call struct, which helps programmers familiar with that.)
+
     The X11 library uses a leading X for all its public functions.  In Python,
     this style is generally deemed unnecessary because attribute and method
     names are prefixed with an object, and function names are prefixed with a
@@ -426,11 +455,12 @@ Naming Conventions
       Tkinter.Toplevel(master, class_='ClassName')
 
     - __double_leading_underscore: when naming a class attribute, invokes name
-      mangling as of Python 1.4.
+      mangling (inside class FooBar, __boo becomes _FooBar__boo; see below).
 
     - __double_leading_and_trailing_underscore__: "magic" objects or
       attributes that live in user-controlled namespaces.  E.g. __init__,
-      __import__ or __file__.
+      __import__ or __file__.  Never invent such names; only use then
+      as documented.
 
   Prescriptive: Naming Conventions
 
@@ -441,7 +471,7 @@ Naming Conventions
       names.
 
       In some fonts, these characters are indistinguishable from the numerals
-      one and zero.  When tempted to use `l' use `L' instead.
+      one and zero.  When tempted to use `l', use `L' instead.
 
     Module Names
 
@@ -450,14 +480,15 @@ Naming Conventions
       Since module names are mapped to file names, and some file systems are
       case insensitive and truncate long names, it is important that module
       names be chosen to be fairly short -- this won't be a problem on Unix,
-      but it may be a problem when the code is transported to Mac or Windows.
+      but it may be a problem when the code is transported to older Mac or
+      Windows versions, or DOS.
 
       When an extension module written in C or C++ has an accompanying Python
       module that provides a higher level (e.g. more object oriented)
       interface, the C/C++ module has a leading underscore (e.g. _socket).
 
-      Python packages should have short, all-lowercase names, without
-      underscores.
+      Like module, Python packages should have short, all-lowercase names,
+      without underscores.
 
     Class Names
 
@@ -497,7 +528,7 @@ Naming Conventions
       If a function argument's name clashes with a reserved keyword, it is
       generally better to append a single trailing underscore rather than use
       an abbreviation or spelling corruption.  Thus "print_" is better than
-      "prnt".
+      "prnt".  (Perhaps better is to avoid such clashes by using a synonym.)
 
     Method Names and Instance Variables
 
@@ -565,6 +596,10 @@ Naming Conventions
         Note 2: Try to keep the functional behavior side-effect free, although
         side-effects such as caching are generally fine.
 
+        Note 3: Avoid using properties for computationally expensive
+        operations; the attribute notation makes the caller believe
+        that access is (relatively) cheap.
+
       - If your class is intended to be subclassed, and you have attributes
         that you do not want subclasses to use, consider naming them with
         double leading underscores and no trailing underscores.  This invokes
@@ -581,6 +616,10 @@ Naming Conventions
         __getattr__(), less convenient.  However the name mangling algorithm
         is well documented and easy to perform manually.
 
+        Note 3: Not everyone likes name mangling.  Try to balance the
+        need to avoid accidental name clashes with potential use by
+        advanced callers.
+
 
 Programming Recommendations
 
@@ -600,13 +639,14 @@ Programming Recommendations
 
       Also, beware of writing "if x" when you really mean "if x is not None"
       -- e.g. when testing whether a variable or argument that defaults to
-      None was set to some other value.  The other value might be a value
-      that's false in a boolean context!
+      None was set to some other value.  The other value might have a type
+      (such as a container) that could be false in a boolean context!
 
     - Use class-based exceptions.
 
       String exceptions in new code are strongly discouraged, as they will
-      eventually be deprecated and then removed.
+      eventually (in Python 2.5) be deprecated and then (in Python 3000 or
+      perhaps sooner) removed.
 
       Modules or packages should define their own domain-specific base
       exception class, which should be subclassed from the built-in Exception
@@ -686,8 +726,9 @@ Programming Recommendations
 
     - Don't compare boolean values to True or False using ==
 
-        Yes: if greeting:
-        No:  if greeting == True:
+        Yes:   if greeting:
+        No:    if greeting == True:
+        Worse: if greeting is True:
 
 
 References
@@ -705,6 +746,8 @@ References
 
     [6] PEP 20, The Zen of Python
 
+    [7] PEP 328, Imports: Multi-Line and Absolute/Relative    
+
 
 Copyright