Directory layout#

A first step of a new project is to define its directory layout.


Applications should follow the layout of the framework used, like Django or Scrapy, and should use its command for generating the layout, like django-admin startproject and django-admin startapp.


Commit generated files before making changes, so that the changes appear in the history.

If no framework is used, prefer a smaller number of directories, like in Kingfisher Summarize or Pelican backend. For example:

│   ├── migrations
│   └── static
├── docs
└── tests
    └── fixtures

Components should be logically distinct units, like apps in Django.


Packages should follow this layout, where PACKAGENAME is the name of the package:

│   ├──
│   ├──
│   ├── commands
│   └── static
├── docs
└── tests
    └── fixtures

Note is executed when the package is invoked directly from the command line using the -m flag. For example:

python -m ocdskit


We don’t use the src/ layout. Although a single blog post and a few passionate developers have popularized the idea, in practice, we rarely encounter the problems it solves, and our use of check-manifest and guard against those problems.

Test files#

  • Put tests outside application code. Do not add tests directories inside application code.

  • Prefix filenames with test_. Do not suffix basenames with _test.

Static files#

  • Don’t mix static files with Python files in the same directory.

Filename conventions#

  • util for a generic module of helper functions, not utils, tools or helper.

  • exceptions for a generic module of exception classes, not errors.

  • Use verbs for commands (like

  • Use nouns for workers (like


    Verbs may be used for workers if they aren’t mixed with commands.