[Python-Dev] PEP 8 updates/clarifications

[Barry Warsaw]

On Fri, 2005-12-09 at 15:38 -0600, Ian Bicking wrote:
> I was reading through PEP 8, and I think there's a few things that could 
> be clarified or updated:

BTW, I'm willing to make updates to PEP 8, if we agree on what to
change.

>      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.  

My own preference is away from "error" and toward CapWordsEndingInError.
This is especially true now that we're recommending exceptions be
classes.  So really, the exception naming scheme is just the class
naming scheme.

> The less obvious question I'm wondering about is if exceptions 
> should have names that are relatively unique, or simply unique within 
> their namespace.  

It depends.  If the exception class is intended to be imported with
other symbols via import-* it needs to be unique of course.  Otherwise I
think it's fine that it simply be unique in its own namespace (though I
tend to make them unique anyway).

> 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?

I think the latter are best, but "error" should definitely be out.
csv.Error is okay as a base exception, though I think I'd opt for
something longer.

> 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.

My own preference here is for HTTPRedirect -- IOW capitalize all letters
of the acronym.

>      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.

Yep, good point.

>      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.

Again, good point.

>        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.

Maybe the right thing to say is that non-public attributes should always
start with at least one, and usually only one, underscore.  If it is a
private attribute of a class that is intended to be inherited from, and
there is a likelihood that subclass attributes may conflict with this
attribute's name, use two leading and no trailing underscores.

> 
>        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.

It does seem like the more popular convention is to use "cls" than
"class_".  I'll admit the latter does look kind of ugly.  Maybe the
suggestion should be to use either a trailing single underscore or an
abbreviation instead of a spelling corruption.  We could then list some
common attribute names for common keywords, e.g. cls for class (what
else?).

>      - 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. 

Let's say something like "string-based exceptions are strongly
discouraged, and in fact may be deprecated or disappear in a future
Python version.  Use class-based exceptions."

> And this kind of implicitly indicates that longer names for exceptions 
> are better; how long?  Should they generally end in "Error"?

Again, I'd say something like: Since your exceptions will be classes,
use the CapWord naming convention for classes to name your exceptions.
It is recommended that your exception class end in the word "Error".

Also, I have some additional guidelines adapted from the Mailman coding
standards: http://barry.warsaw.us/software/STYLEGUIDE.txt

Other than the one about the inequality operator (which I know is sadly
doomed), what do you think about adding some of those suggestions to PEP
8?

-Barry

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 307 bytes
Desc: This is a digitally signed message part
Url : http://mail.python.org/pipermail/python-dev/attachments/20051209/0555927a/attachment.pgp