Python Package Structure & Layout

There are two different layouts that you will commonly see within the Python packaging ecosystem: src and flat layouts. Both layouts have advantages for different groups of maintainers.

We strongly suggest, but do not require, that you use the src/ layout (discussed below) for creating your Python package. This layout is also recommended in the PyPA packaging guide tutorial.

pyOpenSci nunca requerirá una estructura de paquete específica para la revisión por pares

We understand that it would take significant effort for existing maintainers to move to a new layout.

La descripción general en esta página presenta recomendaciones que creemos que son las mejores para alguien que está comenzando con el empaquetado de Python o para alguien cuyo paquete tiene una construcción simple y podría estar abierto a moverse a un enfoque a prueba de fallos.

Other resources you can check out:

• PyPA’s overview of src vs flat layouts

You can use tools like Hatch to quickly create a modern Python package structure. Check out our quickstart tutorial:

Want to learn how to create the structure to build your package? Click here.

What is the Python package source layout?

An example of the src/package layout structure is below.

myPackageRepoName
├── CHANGELOG.md               ┐
├── CODE_OF_CONDUCT.md         │
├── CONTRIBUTING.md            │
├── docs                       │ Package documentation
│   └── index.md
│   └── ...                    │
├── LICENSE                    │
├── README.md                  ┘
├── pyproject.toml             ] Package metadata and build configuration
├── src                        ┐
│   └── myPackage              │
│       ├── __init__.py        │ Package source code
│       ├── moduleA.py         │
│       └── moduleB.py         ┘
└── tests                      ┐
   └── ...                     ┘ Package tests

Nótese la ubicación de los siguientes directorios en el ejemplo anterior:

• docs/: Discussed in our docs chapter, this directory contains your user-facing documentation website. In a src/ layout docs/ are normally included at the same directory level as the src/ folder.

• tests/ This directory contains the tests for your project code. In a src/ layout, tests are normally included at the same directory level as the src/ folder.

• src/package/: este es el directorio que contiene el código de su proyecto de Python. «Package» es normalmente el nombre de su proyecto.

También en el ejemplo anterior, observe que todos los archivos de documentación básicos que pyOpenSci requiere se encuentran en la raíz del directorio de su proyecto. Estos archivos incluyen:

• CHANGELOG.md

• CODE_OF_CONDUCT.md

• CONTRIBUTING.md

• LICENSE.txt

• README.md

Haga clic aquí para leer sobre nuestros requisitos de documentación de empaquetado.

Ejemplos de paquetes científicos que utilizan el diseño src/package

• Sourmash

• bokeh

• openscm

• awkward

• poliastro

The src layout and testing

The benefit of using the src/package layout is that it ensures tests are run against the installed version of your package rather than the files in your package working directory. If you run your tests on your files rather than the installed version of your package, you may be missing issues that users encounter when your package is installed.

If tests/ are outside the src/package directory, they aren’t included in the package’s wheel. This makes your package size slightly smaller, which places a smaller storage burden on PyPI, and makes them faster to fetch.

• Lea más sobre las razones para usar el diseño src/package

¿Cómo descubre y prioriza Python la importación de módulos?

De forma predeterminada, Python agrega un módulo en su directorio de trabajo actual al principio de la ruta de búsqueda de módulos de Python.

Esto significa que si ejecuta sus pruebas en el directorio de trabajo de su paquete, utilizando un diseño plano, /package/module.py, Python descubrirá el archivo package/module.py antes de que descubra el paquete instalado.

However, if your package lives in a src/ directory structure src/package, then it won’t be added to the Python path by default. This means that when you import your package, Python will be forced to search the active environment (which has your package installed).

Note: Python versions 3.11 and above have a path setting that can be adjusted to ensure the priority is to use installed packages first (e.g., PYTHONSAFEPATH).

Don’t include tests in your package wheel

Writing tests for your package is important; however, we do not recommend including tests as part of your package wheel by default. However, not including tests in your package distribution will make it harder for people other than yourself to test whether your package runs properly on their system. If you have a small test suite (Python files + data), and think your users may want to run tests locally on their systems, you can include tests by moving the tests/ directory into the src/package directory (see example below).

src/
  package/
    tests/
docs/

Including the tests/ directory in your src/package directory ensures that tests will be included in your package’s wheel.

Asegúrese de leer la documentación de pytest para obtener más información sobre cómo incluir pruebas en su distribución de paquete.

Desafíos al incluir pruebas y datos en una rueda de paquete

Tests, especially when accompanied by test data, can create a few small challenges, including:

• Take up space in your distribution, which will build up over time as storage space on PyPI

• Large file sizes can also slow down package installation.

However, in some cases, particularly in the scientific Python ecosystem, you may need to include tests.

No incluya conjuntos de datos de pruebas en su paquete

If you include your tests in your package distribution, we strongly discourage you from including data in your test suite directory. Rather, host your test data in a repository such as Figshare or Zenodo. Use a tool such as Pooch to access the data when you (or a user) runs tests.

For more information about Python package tests, see the tests section of our guide.

• El diseño src/package es semánticamente más claro. El código siempre se encuentra en el directorio src/package, tests/ y docs/ están en el directorio raíz.

Importante

If your package tests require data, do NOT include that data within your package structure. Including data in your package structure increases the size of your distribution files. This places a maintenance toll on repositories like PyPI and Anaconda.org that have to deal with thousands of package uploads.

Click here for a quickstart tutorial on creating your Python package.

What is the flat Python package layout?

Many scientific packages use the flat-layout given:

• This layout is used by many core scientific Python packages such as NumPy, SciPy, and Matplotlib.

• Many Python tools depend upon tools in other languages and/or complex builds with compilation steps. Many maintainers prefer features of the flat layout for more complex builds.

While we suggest that you use the src/package layout discussed above, it’s important to also understand the flat layout, especially if you plan to contribute to a package that uses this layout.

Why most scientific Python packages do not use src/ layout

Migrating larger scientific packages that already use a flat layout would consume significant time and resources.

However, the advantages of using the src/package layout for a beginner are significant. As such, we recommend that you use the src/package layout if you are creating a new package.

Numerous packages in the ecosystem have had to move to a src/package layout.

¿Cómo es la estructura del diseño plano?

Las características principales del diseño plano son:

• El código fuente de su paquete se encuentra en un directorio con el nombre de su paquete en la raíz de su directorio

• A menudo, el directorio tests/ también se encuentra dentro de ese mismo directorio package.

A continuación, puede ver la estructura recomendada de un paquete científico de Python que utiliza el diseño plano.

myPackage/
├── CHANGELOG.md             ┐
├── CODE_OF_CONDUCT.md       │
├── CONTRIBUTING.md          │
├── docs/                    │ Package documentation
│   └── ...                  │
├── LICENSE                  │
├── README.md                ┘
├── pyproject.toml           ] Package metadata and build configuration
|   myPackage/               ┐
│     ├── __init__.py        │ Package source code
│     ├── moduleA.py         │
│     └── moduleB.py         ┘
      tests/                 ┐
        └── test-file1.py    | Package tests
        └── ....             ┘

Beneficios de usar el diseño plano en su paquete de Python

Existen algunos beneficios para la comunidad científica al utilizar el diseño plano.

• Esta estructura se ha utilizado históricamente en todo el ecosistema y es poco probable que los paquetes que la utilizan cambien.

• Puede importar el paquete directamente desde el directorio raíz. Para algunos, esto está arraigado en sus respectivos flujos de trabajo. Sin embargo, para un principiante, el peligro de hacer esto es que no está desarrollando y probando contra la versión instalada de su paquete. En cambio, está trabajando directamente con los archivos planos.

Paquetes científicos de Python que utilizan el diseño plano

• numpy

• scipy

• pandas

• xarray

• Jupyter-core

• Jupyter notebook

• scikit-learn

It would be a significant maintenance cost and burden to move all of these packages to a different layout. The potential benefits of the source layout for these tools are not worth the maintenance investment.

Multiple packages in a src/ folder

In some more advanced cases, you may have more than one package in your src/ directory. See Black’s GitHub repo for an example of this. However, for most beginners you will likely only have one sub-directory in your src/ folder.