Discuss the benefits of the src layout vs the flat layout

[bzah]

The goal here is to discuss and take a decision if this cookiecutter template should create a src/ layout instead of its current flat layout.

Context

A python project typically have one of the following layout:

• a src/ layout where a src directory is at the root of the project and a /src/project-name/ contains the python sources for the project
• a flat layour where /project-name is directly in the root.

Benefits of src/

The Python Packaging Authority now recommends to use the src layout, see https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/ The main benefits are:

• tests are not packaged when building dist/, so not publish on pypi/conda-forge.
• to run the tests, one needs to first install the project, this ensures that the tests are run in a environment that is closer to the real life scenario of users.

What others do

Across github we can find large projects following one or the other of these layout, many among the scientific software are following the flat layout, but some are migrating slowly. Notably, numpy, xarray, pandas, scipy are all flat, but all the pallets projects (flask, jinja, click...) as well as black and ansible (with lib instead of src) are following the src/ layout.

Further reading

I recommend this read from pyopensci to get an idea of the differences between these 2 layouts.

[Zeitsperre]

Upstream changes have adopted it, so we'll do the same, however:

• tests are not packaged when building dist/, so not publish on pypi/conda-forge.

The convention I employ is to package the tests as part of the source distribution, but not in the wheel. If it's alright with you, I'll keep that convention moving forward.