layout src vs layout plano

O “layout plano” (em inglês, flat layout) refere-se à organização dos arquivos de um projeto em uma pasta ou repositório, de forma que os vários arquivos de configuração e pacotes de importação estejam todos no diretório de nível superior.

.
├── README.md
├── noxfile.py
├── pyproject.toml
├── setup.py
├── awesome_package/
│   ├── __init__.py
│   └── module.py
└── tools/
    ├── generate_awesomeness.py
    └── decrease_world_suck.py

O “layout src” (em inglês, layout src)se desvia do layout plano movendo o código que se destina a ser importável (ou seja, import awesome_package, também conhecido como pacotes de importação) para um subdiretório. Este subdiretório é normalmente chamado de src/, daí “layout src”.

.
├── README.md
├── noxfile.py
├── pyproject.toml
├── setup.py
├── src/
│    └── awesome_package/
│       ├── __init__.py
│       └── module.py
└── tools/
    ├── generate_awesomeness.py
    └── decrease_world_suck.py

Aqui está uma análise das diferenças de comportamento importantes entre o layout src e o layout plano:

• O layout src requer a instalação do projeto para poder executar seu código, e o layout plano não.

  Isso significa que o layout src envolve uma etapa adicional no fluxo de trabalho de desenvolvimento de um projeto (normalmente, uma instalação editável é usada para desenvolvimento e uma instalação regular é usada para teste) .

• O layout src ajuda a evitar o uso acidental da cópia em desenvolvimento do código.

  Isso é relevante, pois o interpretador Python inclui o diretório de trabalho atual como o primeiro item no caminho de importação. Isso significa que se existir um pacote de importação no diretório de trabalho atual com o mesmo nome de um pacote de importação instalado, a variante do diretório de trabalho atual será usada. Isso pode levar a uma configuração incorreta sutil das ferramentas de empacotamento do projeto, o que pode resultar na não inclusão de arquivos em uma distribuição.

  O layout src ajuda a evitar isso mantendo os pacotes de importação em um diretório separado do diretório raiz do projeto, garantindo que a cópia instalada seja usada.

• O layout src ajuda a reforçar que uma instalação editável só é capaz de importar arquivos que deveriam ser importados.

  Isso é especialmente relevante quando a instalação editável é implementada usando um arquivo de configuração de caminho que adiciona o diretório ao caminho de importação.

  O layout plano adicionaria os outros arquivos de projeto (por exemplo: README.md, tox.ini) e arquivos de configuração de pacotes/ferramentas (por exemplo: setup.py, noxfile.py) no caminho de importação. Isso faria com que certas importações funcionassem em instalações editáveis, mas não em instalações regulares.

Executando uma interface de linha de comando da fonte com src-layout

Due to the firstly mentioned specialty of the src layout, a command-line interface can not be run directly from the source tree, but requires installation of the package in Development Mode for testing purposes. Since this can be unpractical in some situations, a workaround could be to prepend the package folder to Python’s sys.path when called via its __main__.py file:

import os
import sys

if not __package__:
    # Make CLI runnable from source tree with
    #    python src/package
    package_source_path = os.path.dirname(os.path.dirname(__file__))
    sys.path.insert(0, package_source_path)