[Python-Dev] PEP 8 updates/clarifications

[Ian Bicking]

I was reading through PEP 8, and I think there's a few things that could 
be clarified or updated:

     Exception Names

       If a module defines a single exception raised for all sorts of
       conditions, it is generally called "error" or "Error".  It seems
       that built-in (extension) modules use "error" (e.g. os.error),
       while Python modules generally use "Error" (e.g. xdrlib.Error).
       The trend seems to be toward CapWords exception names.

To my knowledge, except for some outlying cases like os.error or 
socket.error (which are themselves old modules), CapWords are always 
used.  The less obvious question I'm wondering about is if exceptions 
should have names that are relatively unique, or simply unique within 
their namespace.  Built-in exceptions use fairly long names, but then 
they have no namespace.  Looking at some newer stdlib modules: email and 
optparse use longer-named exceptions; csv uses csv.Error.  Should 
"error" exceptions be discouraged?  Would http.ServerError or 
http.HTTPServerError be considered better?

Also, perhaps somewhere in the description of CapWords, how should they 
deal with acronyms?  It seems like the convention is, to give an 
example, HTTPRedirect over HttpRedirect.  I would appreciate an explicit 
preferred style.

     Global Variable Names

       (Let's hope that these variables are meant for use inside one
       module only.)  The conventions are about the same as those for
       functions.  Modules that are designed for use via "from M import *"
       should prefix their globals (and internal functions and classes)
       with an underscore to prevent exporting them.

It seems like __all__ is a better technique than leading underscores.

     Designing for inheritance

       Always decide whether a class's methods and instance variables
       should be public or non-public.  In general, never make data
       variables public unless you're implementing essentially a
       record.  It's almost always preferrable to give a functional
       interface to your class instead (and some Python 2.2
       developments will make this much nicer).

Yes, Python 2.2 developments have made this better.  Use of property() 
should be suggested.

       Also decide whether your attributes should be private or not.
       The difference between private and non-public is that the former
       will never be useful for a derived class, while the latter might
       be.  Yes, you should design your classes with inheritence in
       mind!

       Private attributes should have two leading underscores, no
       trailing underscores.

This conflicts with a previous suggestion "Generally, double leading 
underscores should be used only to avoid name conflicts with attributes 
in classes designed to be subclassed."  Or perhaps "private attributes" 
needs to be better explained.

       Non-public attributes should have a single leading underscore,
       no trailing underscores.

       Public attributes should have no leading or trailing
       underscores, unless they conflict with reserved words, in which
       case, a single trailing underscore is preferrable to a leading
       one, or a corrupted spelling, e.g. class_ rather than klass.
       (This last point is a bit controversial; if you prefer klass
       over class_ then just be consistent. :).

With class methods, this has become a more important.  Can PEP 8 include 
a preferred name for the class argument to classmethods?  I personally 
prefer cls, there are some who use klass, and I haven't see class_ used.

     - Class-based exceptions are always preferred over string-based
       exceptions.  Modules or packages should define their own
       domain-specific base exception class, which should be subclassed
       from the built-in Exception class.  Always include a class
       docstring.  E.g.:

         class MessageError(Exception):
             """Base class for errors in the email package."""

I think the language against string-based exceptions can be stronger. 
And this kind of implicitly indicates that longer names for exceptions 
are better; how long?  Should they generally end in "Error"?



-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org