Suggested directory structure for a web API project, written in Python

STRUCTURE.md

api/

Handlers, etc. Everything needed to translate a web request into data that can be passed into a regular Python function and vice versa.

api/exports.py

Typically this would be imported into an app like this.

import api.exports as api

This submodule contains the core functions and other objects that are used to interact with the api module.

app/

Core operations, that either returns data as expected or raises errors that would be returned by the web server. Think of this as a library that does exactly what the API does, but a library that can be imported into another Python app and be called directly from Python.

app/async.py

This file just contains asynchronous wrappers, such as functions decorated with @tornado.gen.coroutine. These are otherwise equivalent to what's in app.exports.

app/core.py

This file contains auxiliary functions and other classes that don't fit neatly into either exc.py or exports.py.

app/exc.py

Custom, user-defined exceptions.

app/exports.py

Typically this would be imported into an app like this.

import app.exports as app

This submodule contains the core functions and other objects that are used to interact with the app module. Note that these functions should be synchronous, with asynchronous wrapper functions defined in app.async.

scripts/

Files in this directory should be runnable from the project root directory.

scripts/web.py

This is what make start should run.

python scripts/web.py

All configuration variables should have default values and be configurable via envvars only, no command line args.

test/

Unit tests for all other modules. This should lend itself to test discovery for make test, defined as follows.

python -m unittest discover -s test -p "*_spec.py"

Use of command line args will cause test discovery to fail, which is why customizable configuration should be set up to use only envvars.