Python Project Management and Build Tools: CookieCutter, PyScaffold, PyBuilder, and Poetry

Python has long lacked a de‑facto standard for project layout and build automation, resulting in many different structures; this reflects Python's emphasis on flexibility.

Unlike Java, which converged on Maven (and later Gradle) with a fairly uniform directory layout, Python's ecosystem provides only package managers such as pip, pipenv, and conda, while project scaffolding and build tools remain diverse.

The article examines four tools that help create and manage Python projects: CookieCutter, PyScaffold, PyBuilder, and Poetry.

CookieCutter – a classic Python project template

Install and generate a project from the popular audreyr/cookiecutter-pypackage template:

$ pip install cookiecutter
$ cookiecutter gh:audreyr/cookiecutter-pypackage
# answer prompts, e.g. project_name [Python Boilerplate]: sample

The resulting layout includes documentation, source code, tests, and build configuration files:

$ tree sample
sample
├── AUTHORS.rst
├── CONTRIBUTING.rst
├── HISTORY.rst
├── LICENSE
├── MANIFEST.in
├── Makefile
├── README.rst
├── docs
│   └── ...
├── requirements_dev.txt
├── sample
│   ├── __init__.py
│   ├── cli.py
│   └── sample.py
├── setup.cfg
├── setup.py
├── tests
│   ├── __init__.py
│   └── test_sample.py
└── tox.ini

Typical build commands are invoked via make (clean, test, coverage, docs, dist, etc.) after installing helper packages such as tox, wheel, coverage, sphinx, and flake8 with pip.

PyScaffold – project scaffolding with a src layout

Install and create a project:

$ pip install pyscaffold
$ putup sample

The generated structure places source files under a src directory:

$ tree sample
sample
├── AUTHORS.rst
├── CHANGELOG.rst
├── CONTRIBUTING.rst
├── LICENSE.txt
├── README.rst
├── docs
│   └── ...
├── pyproject.toml
├── setup.cfg
├── setup.py
├── src
│   └── sample
│       ├── __init__.py
│       └── skeleton.py
├── tests
│   ├── conftest.py
│   └── test_skeleton.py
└── tox.ini

Building and testing are performed with tox, which creates isolated virtual environments for each task.

PyBuilder – Maven‑like build automation

Install and start a project:

$ pip install pybuilder
$ mkdir sample && cd sample
$ pyb --start-project

The generated layout resembles Maven’s:

$ tree sample
.
├── build.py
├── docs
├── pyproject.toml
├── setup.py
└── src
    ├── main
    │   ├── python
    │   └── scripts
    └── unittest
        └── python

Tasks are listed with pyb -t sample and include clean, compile_sources, test, package, publish, etc. Dependencies are declared in build.py.

Poetry – modern dependency and build manager

Install and create a new project:

$ pip install poetry
$ poetry new sample

Poetry generates a minimal layout:

$ tree sample
sample
├── README.rst
├── pyproject.toml
├── sample
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_sample.py

Adding dependencies is as simple as poetry add boto3; building, testing, and publishing are handled via commands like poetry build, poetry run pytest, and poetry publish. Poetry stores configuration in pyproject.toml, similar to Node’s package.json.

Overall, the complexity of the generated project structure decreases from CookieCutter to PyScaffold, PyBuilder, and finally Poetry, while the learning curve follows the same order.