Indentation is 4 spaces per indent. Tabs are not allowed. It is preferred that every block appear on a new line, so that control structure indentation is always visible.
Modules must be named in all lower-case, preferably short, single words. If a module name contains multiple words, they may be separated by underscores or not separated at all.
In most cases, modules should contain more than one class, function, or method; if a module contains only one object, consider refactoring to include more related functionality in that module.
I realize that different ways to import a module have different semantics, so this rule is flexible, but: it is preferred that modules be imported directly into the namespace of the referencing module, and references to functionality in that module be prefixed with the module name.
For example, from twisted import reality; reality.Thing(),
not import twisted.reality; twisted.reality.Thing() or
from twisted.reality import Thing; Thing().
Unfortunately, sibling imports within a package may be required when circular module imports exist. Only use them in that case, and make sure module names are not ambiguous with other modules.
Package names should follow the same conventions as module names. All modules must be encapsulated in some package. Nested packages may be used to further organize related modules.
__init__.py must never contain anything other than a docstring and (optionally) an __all__ attribute. Packages are not modules and should be treated differently. This rule may be broken to preserve backwards compatibility if a module is made into a nested package as part of a refactoring.
Wherever possible, docstrings should be used to describe the purpose of methods, functions, classes, and modules. In cases where it's desirable to avoid documenting thoroughly -- for example, and evolving interface -- insert a placeholder docstring ("UNDOCUMENTED" is preferred), so that the auto-generated API documentation will not pick up an extraneous comment as the documentation for that module/class/function.
Docstrings are never to be used to provide semantic information about an object; this rule may be violated if the code in question is to be used in a system where this is a requirement (such as Zope).
Docstrings should be indented to the level of the code they are documenting.
Docstrings should be triple-quoted.
Docstrings should be written in StructuredText format; more documentation is available on the HappyDoc website.
Additionally, to accommodate emacs users:
For example,
def foo2bar(f):
"""I am a function to convert foos to bars.
I should be used when you have a foo but you want a bar; note that this is a
non-destructive operation. If I can\'t convert the foo to a bar I will raise a
FooException().
For example::
| import wombat
| def sample(something):
| f = something.getFoo()
| f.doFooThing()
| b = wombat.foo2bar(f)
| b.doBarThing()
| return b
"""
# Optionally, actual code can go here.
Classes are to be named in mixed case, with the first letter capitalized; each word separated by having its first letter capitalized. Acronyms should be capitalized in their entirety. Class names should not include the name of the module they are a part of. Examples:
Methods should be in mixed case, with the first letter lower case, each word separated by having its first letter capitalized. For example, "someMethodName", "method".
Sometimes, a class will dispatch to a specialized sort of method using its name; for example, twisted.reflect.Accessor. In those cases, the type of method should be a prefix in all lower-case with a trailing underscore, so method names will have an underscore in them. For example, "get_someAttribute". Underscores in method names in twisted code are therefore expected to have some semantic associated with them.
Functions should be named similiarly to methods.