Twisted Coding Standard

Naming

Try to choose names which are both easy to remember and meaningful. Some silliness is OK at the module naming level (see twisted.spread...) but when choosing class names, be as precise as possible. Write code with a dictionary and thesaurus open on the table next to you.

Try to avoid overloaded terms. This rule is often broken, since it is incredibly difficult, as most normal words have already been taken by some other software. More importantly, try to avoid meaningless words. In particular, words like "handler", "processor", "engine", "manager", and "component" don't really indicate what something does, only that it does something.

Testing

Unit tests are written using the PyUnit framework. Many examples are in the twisted.test package, and all tests should be integrated through the main test suite builder in twisted.test.test_all.

Acceptance tests are all automated by the bin/accepttests script currently. (TODO: real acceptance tests strategy!)

Whitespace

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

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.

Note that this rule is a change from previous versions of Twisted, so a lot of code does not yet adhere to it.

By default, objects from modules in Twisted ought to be imported directly into the namespace of the module that uses them, like this: from twisted.python.defer import Deferred

In some cases, however, Twisted takes advantage of the dynamic binding of Python in order to provide an interface through a module that may be imported -- we call these "volatile" modules, because their internals are subject to change without warning. In these cases, it is desireable to import the module itself into the user's namespace, so that things bound to it will be looked up on each call. For obvious reasons, classes in volatile modules should never be subclassed.

Volatile modules will have a __volatile__ attribute set to 1, and should always have a docstring snippet like the one that follows:

"""
NOTE: this is a __volatile__ module.  This means that if you are using it
externally, you should know that its contents may change at any time.  In
general, all this means is that you must not use it like this::

    from twisted.package.module import Class
    Class()

but instead like this::

    from twisted.package import module
    module.Class()
"""

Packages

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.

If you wish to promote code from a module to a package, for example, to break a large module out into several smaller files, the accepted way to do this is to promote from within the module. For example,

# parent/
# --- __init__.py ---
import child

# --- child.py ---
import parent
class Foo:
    pass
parent.Foo = Foo

Docstrings

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:

Single quotes of the type of the docstring's triple-quote should be escaped. This will prevent font-lock from accidentally fontifying large portions of the file as a string.
Code examples in docstrings should be prefixed by the | character. This will prevent IM-Python from regarding sample code as real functions, methods, and classes.

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.