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.