How python source code in large projects are organized?

Christopher Arndt chris.arndt at
Sat Sep 26 18:30:09 CEST 2009

On 20 Sep., 22:10, exar... at wrote:
> On 07:10 pm, pengyu... at wrote:
> >On Sun, Sep 20, 2009 at 11:31 AM, Daniel Fetchinson
> ><fetchin... at> wrote:
> >>>I am wondering what is the best way of organizing python source code
> >>>in a large projects. There are package code, testing code. I'm
> >>>wondering if there has been any summary on previous practices.
> >>I suggest looking at the source code of large projects like twisted,
> >>PIL, django, turbogears, etc. These have different styles, pick the
> >>one you like best.

Start by having a standard for structuring the single Python files. I
like to have mine organized like this:

- (shebang)
- encoding declaration
- module docstring
- __all__ symbol export list
- imports
  - standard library
  - third-party
  - project specific
- author, version, date and copyright information
- globals (logging setup, constants, etc.)
- utility functions
- classes
- "main" function (some like to have this at the top)
- if __name__ ==  '__main__': clause

For sub-packages, like to have the following layout:


If a package is not too big, the test may also go into a "test" sub-
directory of the main package.

I have an __all__ symbol export list in all module file, so then in in I can do:

    from base import *
    from exception import *
    from module1 import this, that
    from module2 import foo, bar

without worrying about import too much and in my main package I can

    from package import this, bar

And in e.g. package.module1 I can do

    from package.exceptions import SomeError

without having to worry about circular imports.

If my package has any code to be called directly from the command
line, I create a script in the root of the distribution or in a "bin"


and in that script:

    #!/usr/bin/env python

    from mainpackage import run
    # or
    # from mainpackage.command.mycommand import run

you can also add a command line script entry point to your setup
script to let this script be automatically created on installation by
setuptools/easy_install. Look at the TurboGears 1.1 branch for

HTH, Chris

More information about the Python-list mailing list