Comments on the diff.

> -Two good reasons to break a particular rule:
> +Some especially good reasons to ignore a particular guideline:

It's probably enough to just s/Two/Some/ - not sure the 'especially' emphasis
is really needed.

> +3. Because the code in question predates the introduction of the rule and
> +   there is no other reason to be modifying that code (especially if
> +   conforming to the updated style guide risks breaking backwards
> +   compatibility)

I'd rather s/rules/recommendation/.

Also, I'm not sure the parenthetical comment is necessary, but if you
disagree, perhaps remove the parentheses and rephrase more assertively:
"...that code.  Don't break backward compatibility just to conform to the
recommendations in this PEP."

> -second-most popular way is with tabs only.  Code indented with a
> -mixture of tabs and spaces should be converted to using spaces
> -exclusively.  When invoking the Python command line interpreter with
> +second-most popular way is with tabs only. In Python 3, these are the
> +only two permitted options (mixing tabs and spaces in the same file will
> +raise an error).

I don't think the parenthetical comment adds much.  They'll find this out soon
enough.

> +
> +Code indented with a mixture of tabs and spaces should be converted to
> +using spaces exclusively.

Perhaps more assertively (but perhaps controversial): "Spaces-only indentation
is recommended."

> -There are still many devices around that are limited to 80 character
> -lines; plus, limiting windows to 80 characters makes it possible to
> -have several windows side-by-side.  The default wrapping on such
> -devices disrupts the visual structure of the code, making it more
> -difficult to understand.  Therefore, please limit all lines to a
> -maximum of 79 characters.  For flowing long blocks of text (docstrings
> -or comments), limiting the length to 72 characters is recommended.
> +Limiting the required editor window width to 80 characters makes it possible
> +to have several files open side-by-side, and works well when using code
> +review tools that present the two versions in adjacent columns.
> +
> +The default wrapping in most tools disrupts the visual structure of the
> +code, making it more difficult to understand. Some web based tools may not
> +offer line wrapping at all. Therefore, please limit all lines to a maximum
> +of 79 characters.  For flowing long blocks of text (docstrings or comments),
> +limiting the length to 72 characters is recommended.

Because I've fielded some questions about this over the years, perhaps add a
footnote explaining why 79 characters is recommended instead of 80.  Even
though the window might be 80 characters wide, some editors (e.g. Emacs) place
a glyph in column 80 instead of the 80th character, so the text actually wraps
after the 79th character.

> -- Relative imports for intra-package imports are highly discouraged.
> -  Always use the absolute package path for all imports.  Even now that
> -  PEP 328 is fully implemented in Python 2.5, its style of explicit
> -  relative imports is actively discouraged; absolute imports are more
> -  portable and usually more readable.
> +- Absolute imports are recommended, as they are usually more readable and
> +  tend to be better behaved (or at least give better error messages) if the
> +  mport system is incorrectly configured (such as when a directory inside a

s/mport/import/

> +- Wildcard imports (``from <module> import *``) should be avoided, as they
> +  make it unclear which names are present in the namespace, confusing both
> +  readers and many automated tools. There is one defensible use case for
> +  a wildcard import, which is to republish an internal interface as part
> +  of a public API (for example, overwriting a pure Python implementation of
> +  an interface with the definitions from an optional accelerator module).

Although I'll note that even in this case, it can be preferable to explicitly
name the symbols being republished.  import-* is useful if that list is too
difficult to manage, e.g. it changes often, is dynamically created, or is just
huge.  Perhaps this should also reiterate the recommendation that
intentionally republished symbols should be named in the masked module's
__all__.

[section on public and internal interfaces]

Nicely written!

> -  or ``a = a + b``.  Those statements run more slowly in Jython.  In
> -  performance sensitive parts of the library, the ``''.join()`` form
> -  should be used instead.  This will ensure that concatenation occurs
> -  in linear time across various implementations.
> +  or ``a = a + b``.  This optimisation is fragile even in CPython (it only

s/optimisation/optimization/ but I guess we don't need to argue about that
particular bikeshed colour :).

> +  The first form means that the name of the resulting function object is
> +  specifically 'f' instead of the generic '<lambda>'. This is more useful
> +  for tracebacks and string representations in general. The use of the
> +  assignment statement eliminates the sole benefit a lambda expression can
> +  offer over an explicit def statement (i.e. that it can be embedded inside
> +  a larger expression)

I'm concerned that the PEP is getting too verbose with all the Talmudic
detours.  The more verbose the PEP gets, the less useful it is as a reference
document.  OTOH, explaining why the recommendations exist helps people to
understand that it's not just a collection of arbitrary rules.  Two thoughts
come to mind as a possible solution:

* Keep PEP 8 lean and mean, but publish a companion PEP, say 108, that is an
  "annotated PEP 8".  It would contain all the explanatory material.  The
  downside is that it's always harder to keep two documents in sync.  Perhaps
  there are docutils hacks that we can use to delineate "explanation" from
  "recommendation" and let PEP 108 be auto-generated.

* Use footnotes for further discussion.  This would keep the main body of the
  PEP lean and mean, but provide further explanation for those who want to dig
  into the reasons.

> +  Design exception hierarchies based on the distinctions that code
> +  *catching* the exceptions is likely to need, rather than the locations
> +  where the exceptions are raised. Aim to answer the question
> +  "What went wrong?" programmatically, rather than only stating that
> +  "A problem occurred" (see PEP 3151 for an example of this lesson being
> +  learned for the builtin exception hierarchy)

While I agree, this recommendation feels a little squishy to me.  This is a
perfect example of discussion I'd like to see removed from the main body of
the PEP, but could be appropriate for an annotation or footnote.

> +  It is highly recommended that third party experimants with annotations
> +  use an associated decorator to indicate how the annotation should be
> +  intepreted.

s/experimants/experiments
s/intepreted/interpreted