Python coding style guide for GNU Mailman
Copyright (C) 2002-2003 Python Software Foundation, Barry A. Warsaw

This document contains a style guide for Python programming, as used
in GNU Mailman.  In general, Guido van Rossum's style guide should be
taken as a basis, as embodied in PEP 8:

    http://python.sourceforge.net/peps/pep-0008.html

however, my (Barry Warsaw's) personal preferences differ from Guido's
in a few places.  "When in Rome..." should apply meaning, when coding
stuff for Python, Guido's style should rule, however when coding for
Mailman, I'd like to see my preferences used instead.  For software
like the email package, which is both standalone and distributed in
Python's standard library, please adhere to the established style,
which means please use my style.

Remember rule #1, A Foolish Consistency is the Hobgoblin of Little
Minds.  That said, here's a quick outline of where my preferences
depart from Guido's:

- Imports usually should be on separate lines.  While it's sometimes
  okay to say

    from types import StringType, ListType

  it's never okay to say

    import os, sys

  Put these on separate lines.

- Imports are always put at the top of the file, just after any module
  comments and docstrings, and before module globals and constants.
  Imports should be grouped, with the order being

  1. standard library imports
  2. related major package imports (i.e. all email package imports next)
  3. application specific imports

  Dotted imports should follow non-dotted imports.  Non-dotted imports
  should be grouped by increasing length, while dotted imports should
  be grouped roughly alphabetically.

- In general, there should be at most one class per module, if the
  module contains class definitions.  If it's a module of functions,
  that's fine, group them as common sense dictates.  A
  class-containing module can also contain some helper functions, but
  it's best to keep these non-public (i.e. use a single leading
  underscore).

  Always give the class and the module the same name.

  Note though that Zope3's module naming style has a lot of merit.
  Here, package and module names are all lower cased.  I'm
  experimenting with this approach for Mailman3.

- 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

  If this spelling causes name clashes, then spell them

    import MyClass
    import foo.bar.YourClass

  and use "MyClass.MyClass"

- Right hanging comments are discouraged, in favor of preceding
  comments.  E.g.

    foo = blarzigop(bar)  # if you don't blarzigop it, it'll shlorp

  should be written as

    # if you don't blarzigop it, it'll shlorp
    foo = blarzigop(bar)

- Major sections of code in a module should be separated by line feed
  characters (e.g. ^L -- that's a single character control-L not two
  characters).  This helps with Emacs navigation.

  Always put a ^L before module-level functions, before class
  definitions, before big blocks of constants which follow imports,
  and any place else that would be convenient to jump to.  Always put
  two blank lines before a ^L.

- Also put to blank lines between any module level function.  Put only
  one blank line between methods in a class.  No blank lines between
  the class definition and the first method in the class (although
  class docstrings often go in this space).

- Try to minimize the vertical whitespace in a class.  If you're
  inclined to separate stanzas of code for readability, consider
  putting a comment in describing what the next stanza's purpose is.
  Don't put stupid or obvious comments in just to avoid vertical
  whitespace though.

- Unless internal quote characters would mess things up, the general
  rule is that single quotes should be used for short strings, double
  quotes for triple-quoted multi-line strings and docstrings.  E.g.

    foo = 'a foo thing'
    warn = "Don't mess things up"
    notice = """Our three chief weapons are:
                - surprise
		- deception
		- an almost fanatical devotion to the pope
	     """

- Write docstrings for all public modules, functions, classes, and
  methods.  Docstrings are not necessary and usually discouraged for
  non-public methods, but you should have a comment that describes
  what the method does.  This comment should appear after the "def"
  line.

- PEP 257 describes good docstrings conventions.  Note that most
  importantly, the """ that ends a multiline docstring should be on a
  line by itself, e.g.:

  """Return a foobang

  Optional plotz says to frobnicate the bizbaz first.
  """

- For one liner docstrings, keep the closing """ on the same line --
  except for module docstrings!

- <> is strongly preferred over !=

- fill-column for docstrings should be 78.

- Always use string methods instead of string module functions, unless
  your code must work with Python 1.5.2 (but let's hope not).

- For sequences, (strings, lists, tuples), use the fact that empty
  sequences are false, so "if not seq" or "if seq" is preferable to
  "if len(seq)" or "if not len(seq)".  Unless you must be compatible
  with Pythons before 2.2.1, always use True and False instead of 1
  and 0 for boolean values.

- 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 preferable to give a functional interface to
  your class instead (Python 2.2's descriptors and properties make
  this much nicer).

  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 inheritance in mind!

  Private attributes should have two leading underscores, 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 preferable to a leading one, or a corrupted
  spelling, e.g. class_ rather than klass).
