Empaquetar una biblioteca de Python

De una carpeta de scripts a una biblioteca instalable

El código que vive en una carpeta de scripts funciona en una máquina, para una persona, hasta el día en que otra persona lo necesita o lo necesitas en otro entorno. Empaquetar convierte tu código en una biblioteca con nombre, versión y dependencias declaradas que cualquiera puede instalar con pip install. Así un equipo comparte una biblioteca de valoración sin copiar archivos, un cuaderno de investigación y un trabajo de producción ejecutan exactamente el mismo código, y una corrección llega a todos con un nuevo número de versión.

# Versions are numbers, not text: compare them as tuples
def parse_version(text):
    parts = [int(part) for part in text.split(".")]
    return tuple(parts + [0] * (3 - len(parts)))

print("1.10" > "1.9")                                # False  as text, "1" < "9" decides it: wrong
print(parse_version("1.10") > parse_version("1.9"))  # True   as numbers (1, 10, 0) is newer than (1, 9, 0)
print(parse_version("2"))                            # (2, 0, 0)

Estructura, pyproject.toml y construcción

Una estructura habitual pone el código en src/yourlib/ (con un __init__.py), las pruebas en tests/ y un pyproject.toml en la raíz. Ese único archivo nombra la herramienta de construcción (la tabla [build-system]) y describe el proyecto: su name, su version, una descripción, las versiones de Python que admite y sus dependencies. pip install -e . instala la carpeta en modo editable mientras desarrollas, de modo que los cambios surten efecto al instante; python -m build produce una wheel (.whl, lista para instalar) y una sdist (archivo fuente) en dist/. Pon la versión en un solo lugar y expónla como yourlib.__version__ si los usuarios la necesitan.

# A minimal pyproject.toml, generated and then read back with tomllib to prove it is valid
import tomllib

def pyproject_toml(name, version, dependencies):
    lines = ["[build-system]", 'requires = ["setuptools>=68"]', 'build-backend = "setuptools.build_meta"', "",
             "[project]", f'name = "{name}"', f'version = "{version}"']
    if dependencies:
        lines += ["dependencies = ["] + [f'    "{d}",' for d in dependencies] + ["]"]
    else:
        lines.append("dependencies = []")
    return "\n".join(lines) + "\n"

text = pyproject_toml("qcpricing", "0.3.0", ["numpy>=1.26", "pandas>=2"])
data = tomllib.loads(text)
print(data["project"]["name"], data["project"]["version"])      # qcpricing 0.3.0
print(data["project"]["dependencies"])                          # ['numpy>=1.26', 'pandas>=2']

Versiones y especificadores de versión

La mayoría de las bibliotecas siguen el versionado semántico: MAYOR.MENOR.PARCHE. Una corrección de error sube el parche (1.4.2 a 1.4.3), una función compatible hacia atrás sube el menor y reinicia el parche (1.5.0) y un cambio incompatible sube el mayor (2.0.0). Las dependencias se declaran con especificadores: numpy>=1.26,<3 acepta cualquier NumPy desde la 1.26 hasta la 3 sin incluirla. Sé tan flexible como puedas serlo con honestidad: una cota inferior para la versión más antigua que probaste, una cota superior solo para una versión mayor que sabes que te rompe. Fijar versiones exactas (==) corresponde al archivo de bloqueo de una aplicación, no a una biblioteca que otros instalan.

# Bumping a version and checking a requirement, with versions compared as tuples
import operator

def parse_version(text):
    parts = [int(part) for part in text.split(".")]
    return tuple(parts + [0] * (3 - len(parts)))

def bump_version(version, part):
    major, minor, patch = parse_version(version)
    return {"major": f"{major + 1}.0.0", "minor": f"{major}.{minor + 1}.0", "patch": f"{major}.{minor}.{patch + 1}"}[part]

OPS = {">=": operator.ge, "<": operator.lt, "==": operator.eq}

def satisfies(version, specifier):
    for clause in specifier.split(","):
        symbol = next(op for op in (">=", "==", "<") if clause.startswith(op))
        if not OPS[symbol](parse_version(version), parse_version(clause[len(symbol):])):
            return False
    return True

print(bump_version("1.4.2", "minor"))                # 1.5.0
print(satisfies("1.26.4", ">=1.26,<3"), satisfies("3.0.0", ">=1.26,<3"))      # True False

# One place for the version: read it from the source instead of repeating it in several files
import re

init_py = """__version__ = "0.3.0"
from .pricing import price
"""
match = re.search(r'^__version__ = "([^"]+)"', init_py, re.MULTILINE)
version = match.group(1)
print(version)                                       # 0.3.0
print(tuple(int(part) for part in version.split(".")))      # (0, 3, 0)

• Empaquetar da al código un nombre, una versión y dependencias declaradas, instalable con pip install; desarrolla con pip install -e ., construye con python -m build.
• pyproject.toml contiene el sistema de construcción y los metadatos [project]; compara las versiones como tuplas de números, nunca como texto.
• Usa versionado semántico (MAYOR.MENOR.PARCHE) y especificadores flexibles (numpy>=1.26,<3); nunca cambies una versión publicada y deja los secretos fuera del paquete.

A continuación: CI/CD para código cuantitativo, ejecutar las comprobaciones automáticamente en cada cambio.

Lab: qué se califica

• Comparar versiones como números con parse_version25 pts
• Publicar la siguiente versión con bump_version25 pts
• Comprobar un requisito con satisfies25 pts
• Describir el paquete con pyproject_toml25 pts