Creación de módulos¶

En esta sección se describen los pasos básicos para la creación de un módulo de Python.

Estructura básica del proyecto¶

La estructura básica de un proyecto para poder crear un módulo es la siguiente:

proyecto_acme/
│
├── README.md                 #(1)! 
├── requirements.txt          #(2)!
├── setup.py                  #(3)!
├── pyproject.toml            #(4)!
├── app.py                    #(5)!
├── mkdocs.yml                #(6)!
├── .pypirc                   #(7)!
├── .readthedocs.yaml         #(8)!
│
├── src/                      #(9)!
│   ├── __init__.py           #(10)!
│   └── proyecto_acme         #(11)!
│       ├── __init__.py       
│     ├── modulo1.py        #(12)!
│     └── modulo2.py        #(13)!
│
├── tests/                    #(14)!
│   ├── __init__.py           
│   └── test_modulo1.py       #(15)!
│
└── docs/                     #(16)!
    ├── requirements.txt      #(17)!
    └── index.md              #(18)!

Documentación del proyecto
Lista de dependencias del proyecto
Archivo de configuración para instalar el proyecto
Archivo adicional para la compilación del proyecto
Archivo de ejecución
Archivo de la configuración en mkdocs (Opcional)
Configuración para subir el módulo a pypip (Opcional)
Configuración para documentar en readthedocks (Opcional)
Directorio base para el módulo
Directorio principal del código fuente
Archivo de inicialización del paquete
Módulo 1 del proyecto
Módulo 2 del proyecto
Directorio para pruebas
Pruebas para el módulo 1
Directorio para la documentación adicional
Archivo de configuración para la documentación en readthedocs (Opcional)
Archivo principal de la documentación

Archivos básicos¶

setup.py¶

import os

import setuptools

try:
    if os.environ.get("CI_COMMIT_TAG"):
        version = os.environ["CI_COMMIT_TAG"]
    else:
        version = os.environ["CI_JOB_ID"]
except KeyError:
    version = "0.0.1"

with open("requirements.txt", 'r') as f:
    requirements = f.read()

setuptools.setup(
    version=version,
    package_dir={"": "src"},
    packages=setuptools.find_packages("src"),
    install_requires=requirements,
)

pyproject.toml¶

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
dynamic = ["version", "dependencies"]
name = "proyecto-acme"
authors = [
    { name = "John Doe", email = "john@doe.com" },
]
description = "Proyecto ACME"
readme = "README.md"
requires-python = ">=3.10"

.pypirc (sólo necesario para subir el módulo a un repositorio)¶

NOTA: Para los repositorios oficiales de pypi, el usuario debe ser __token__

[distutils]
Index-servers =
  pypi
  testpypi
  CustomRepo

[pypi]
Repository = https://upload.pypi.org/legacy/
username = __token__
password = MY_TOKEN

[testpypi]
Repository = https://test.pypi.org/legacy/
username = __token__
password = MY_TOKEN

[CustomRepo]
Repository = https://custom.repository.example.com
username = username
password = MY_TOKEN

.readthedocs (sólo necesario para usar readthedocs como documentación)¶

# Read the Docs configuration file for MkDocs projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

mkdocs:
  configuration: mkdocs.yml
# Optionally declare the Python requirements required to build your docs
python:
  install:
    - requirements: docs/requirements.txt

Desarrollo y compilación del módulo¶

Para desarrollar el módulo, debemos instalarlo en modo edición, de la siguiente manera

pip install -e .

Esto permite que los cambios se vean reflejados directamente sin necesidad de tener que reinstalarlo cada vez.

Subida a un registry (pypip) - Opcional¶

Instalar y ejecutar el módulo de build

python -m pip install --upgrade build
python -m build

Instalar el módulo de twine
python -m pip install --upgrade twine

Subir el módulo

python -m twine upload [--repository reponame] dist/* [--config-file path/to/.pypirc]

NOTA: el flag --repository espera algun nombre de los definidos en el fichero .pypirc

Uso del módulo¶

Una vez instalado, ya sea localmente con pip install . o a través de un repositorio como pypi, se debe importar el módulo cualquier otro módulo desde el código principal de ejecución, usando el nombre del módulo definido en el fichero pyproject.toml:

import proyecto-acme

...