Skip to content

Draft: switch to src layout

Leon Merten Lohse requested to merge src-structure into master

Python packaging allows for 2 different directory layouts, the so called flat layout and source layout. (see [1]). The central difference is that in the flat layout, the modules sit in the toplevel directory (here /hotopy) whereas in the src layout they sit in the /src directory (here /src/hotopy). This has the advantage of providing a clean separation between the library code and everything else (tests, CI definitions, examples, docs, ...)

Historically, we have been using the flat layout, which allows to use the code by adding the path of the cloned repository to the python path. In the past, we used sys.path.append('..') for notebooks in ./examples.

However, with python tooling rapidly maturing in the past 2 years and editable installs becoming usable (pip install -e), this is neither required nor recommended anymore. In particular, modern packaging tools such as uv [2]---which will quickly become the de-facto standard, I believe---clearly advocate the src layout.

[1] https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/ [2] https://github.com/astral-sh/uv

Advantages

  • clear separation between library code and installation scripts, docs, etc.
  • it is the recommended layout for libraries (not necessarily for CLI applications)
  • hotopy module not automatically available from python started in root directory (safer for CI scripts)
  • forces you to install the project if you want to use the module, possibly in editable mode

Disadvantages

  • forces you to install the project if you want to use the module
  • sys.path.append(<path-to-hotopy>) stops to work
Edited by Leon Merten Lohse

Merge request reports