Python style conventions are described in PEPs.
 * [[http://www.python.org/peps/pep-0008.html|PEP 8]] -- Style Guide for Python Code
 * [[http://www.python.org/peps/pep-0257.html|PEP 257]] -- Docstring Conventions

<<TableOfContents>>

== Learning Python Style ==

There are a lot of rules in PEP 8 and 257! Learn and document in steps.

The key is to use formatters and validators to ensure PEP 8 compliance. As your code is put through validators, you slowly learn all the intricate details of styling.

== Examples ==
=== Example Module ===

{{{
#!python
"""Short description of module.

Blah blah blah. This is the long description of the module. More brief
explanations.

ClassNameA --  short description
function_a --  short description
function_b --  short description
"""

import sys  # standard library imports
import os

import optparse  # related major package imports

import eggs  # application specific imports
import spam


class ClassNameA:
    """What it is.

    Notes on what it is and how it does it.

    Lots to say, lots to say.  I'm unclear on whether we need two spaces
    between sentences or not.  72 characters wide.  Blah blah blah.

    Document methods in here, with a short explanation.

    eat_eggs --  does X
    eat_spam --  does Y
    """

    def __init__(self, green_eggs, green_spam):
        """Init ClassNameA with some eggs and spam."""
        foo()
        bar()
        baz()

    def eat_eggs(self):
        """One line documentation is like this."""
        foo()
        bar()

    def eat_spam(self):
        """Short explanation.

        Multi-line spam has a one line description at top, seperated by
        a space, and then more multi-line spam afterwards.  Note that
        the final triple-quote appears beneath.
        """
        baz()

    def _internal_use(self):
        # Eat eggs and spam.
        #
        # Docstrings are not necessary for non-public methods, but you
        # should have a comment that describes what the method does.
        # This comment should appear after the "def" line.

        self.eat_eggs()
        self.eat_spam()


def function_a(eggs, ham):
    """A function_a is a foobar.

    Again, multi-line rules apply in here as well, the same way.  Note
    that we have two spaces between module-level class and function
    definitions.  That's PEP-8 at work.
    """
    foo()
    bar()
    baz()


def function_b(eggs, ham):
    """A function_b is a foobar.

    Another one.  Still two spaces separating functions and classes.
    """
    foo()
    bar()
    baz()

}}}