The Drcom-Client Open Source Project

Coding Style for Python Code

Code lay-out

  1. Indentation 
    Use 4 spaces per indentation level.

For really old code that you don't want to mess up, you can 
continue to use 8-space tabs.
  2. Tabs or Spaces? 
    Never mix tabs and spaces.

The most popular way of indenting Python is with spaces only.
The second-most popular way is with tabs only. Code indented 
with a mixture of tabs and spaces should be converted to using
spaces exclusively. When invoking the Python command line 
interpreter with the -t option, it issues warnings about code
that illegally mixes tabs and spaces. When using -tt these
warnings become errors. These options are highly recommended!

For new projects, spaces-only are strongly recommended over
tabs. Most editors have features that make this easy to do.
  3. Maximum Line Length 
    Limit all lines to a maximum of 79 characters.

There are still many devices around that are limited to 80 
character lines; plus, limiting windows to 80 characters makes 
it possible to have several windows side-by-side. The default 
wrapping on such devices disrupts the visual structure of the 
code, making it more difficult to understand. Therefore, please
limit all lines to a maximum of 79 characters. For flowing long
blocks of text (docstrings or comments), limiting the length to 
72 characters is recommended.

The preferred way of wrapping long lines is by using Python's 
implied line continuation inside parentheses, brackets and braces.  
If necessary, you can add an extra pair of parentheses around an 
expression, but sometimes using a backslash looks better. Make 
sure to indent the continued line appropriately. The preferred
place to break around a binary operator is *after* the operator, 
not before it.  Some examples:

    class Rectangle(Blob):
    
    def __init__(self, width, height,
                 color='black', emphasis=None, highlight=0):
        if width == 0 and height == 0 and \
           color == 'red' and emphasis == 'strong' or \
           highlight > 100:
            raise ValueError("sorry, you lose")
        if width == 0 and height == 0 and (color == 'red' or
                                           emphasis is None):
           raise ValueError("I don't think so -- values are %s, %s" %
                            (width, height))
        Blob.__init__(self, width, height,
                      color, emphasis, highlight)
  4. Blank Lines 
    Separate top-level function and class definitions with two blank
lines. Method definitions inside a class are separated by a 
single blank line.

Extra blank lines may be used (sparingly) to separate groups of
related functions. Blank lines may be omitted between a bunch 
of related one-liners (e.g. a set of dummy implementations).

Use blank lines in functions, sparingly, to indicate logical 
sections.

Python accepts the control-L (i.e. ^L) form feed character as 
whitespace; Many tools treat these characters as page separators,
so you may use them to separate pages of related sections of 
your file.
  5. Encodings 
    Code in the core Python distribution should aways use the ASCII 
or Latin-1 encoding (a.k.a. ISO-8859-1).  For Python 3.0 and 
beyond, UTF-8 is preferred over Latin-1, see PEP 3120.

Files using ASCII (or UTF-8, for Python 3.0) should not have a
coding cookie.  Latin-1 (or UTF-8) should only be used when a
comment or docstring needs to mention an author name that requires
Latin-1; otherwise, using \x, \u or \U escapes is the preferred
way to include non-ASCII data in string literals.

For Python 3.0 and beyond, the following policy is prescribed for
the standard library (see PEP 3131): 
All identifiers in the Python standard library MUST use ASCII-only 
identifiers, and SHOULD use English words wherever feasible (in
many cases, abbreviations and technical terms are used which 
aren't English). In addition, string literals and comments must 
also be in ASCII. The only exceptions are 
(a)test cases testing the non-ASCII features,
(b)names of authors.

Authors whose names are not based on the latin alphabet MUST
provide a latin transliteration of their names.

Open source projects with a global audience are encouraged to
adopt a similar policy.

Imports

  1. Imports should usually be on separate lines 
    e.g.:

        Yes: import os
         import sys

    No:  import sys, os

    it's okay to say this though:

        from subprocess import Popen, PIPE
  2. 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 in the following order:

1. standard library imports
2. related third party imports
3. local application/library specific imports

You should put a blank line between each group of imports.

Put any relevant __all__ specification after the imports.
  3. Relative imports for intra-package imports are highly discouraged. 
    Always use the absolute package path for all imports.
Even now that PEP 328 is fully implemented in Python 2.5, 
its style of explicit relative imports is actively discouraged; 
absolute imports are more portable and usually more readable.
  4. 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 local name clashes, then spell them

        import myclass
    import foo.bar.yourclass

    and use "myclass.MyClass" and "foo.bar.yourclass.YourClass"

(to be continued...)