Official Python coding style guide for the mimelib/email package
Copyright (C) 2002 Python Software Foundation

This document contains a style guide of sorts for Python programming,
as used in the mimelib/email package, as well as in GNU Mailman.  In
general, Guido van Rossum's style guide should be taken as a basis.
This is 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..." which means, 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 this
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 my preference departures
from Guido's:

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

- Right hanging comments are usually 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 two blank lines between any module level function.  Put
  only one blank line between methods in a class.

- 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

	     While the lines above are indented, it's only because
	     they are in a bulleted list.  In general lines inside a
	     TQS should be indented under the first quote.  The
	     closing triple-quote should be on a separate line.
	     """

- <> is prefered over != (I know Guido strongly disagrees with this
  one; it must be a Dutch thing).

- Block comments typically don't need surrounding blank lines.

- No blank line between the class statement and the first method def.

- <> is always preferred over !=

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

- fill-column for docstrings should be 78 (but 72 is okay).
