Ouranosinc / cookiecutter-pypackage

Cookiecutter template for a Python package.
BSD 3-Clause "New" or "Revised" License
6 stars 1 forks source link

Discuss the benefits of the src layout vs the flat layout #39

Closed bzah closed 5 months ago

bzah commented 6 months ago

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:

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:

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 commented 5 months ago

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.