Contratos verificables y proyectos comprensibles.

Durante todo el curso has comprobado que Python es un lenguaje de tipado dinámico: una variable puede contener un número y, más tarde, una cadena. Esa flexibilidad es una de sus grandes ventajas para aprender y prototipar, pero en proyectos grandes puede convertirse en un arma de doble filo. Un cambio en una función puede romper otra parte del programa sin que el intérprete se queje hasta que esa línea se ejecuta. Las anotaciones de tipos y las herramientas de comprobación estática como mypy resuelven ese problema: permiten declarar qué tipos esperas y detectar incoherencias antes de ejecutar el código.

Pero el código no solo debe ser correcto: debe ser comprensible. Una función con una docstring clara, un proyecto con un README bien estructurado y una documentación generada automáticamente son la diferencia entre un programa que solo entiende su autor y uno que cualquier persona puede usar y mantener. Este módulo cubre las dos caras de la misma moneda: el contrato del código (los tipos) y su explicación (la documentación).

Título: Tipado y documentación: contratos verificables y proyectos comprensibles.

Alcance: Comprender qué son las anotaciones de tipos y qué no son; anotar funciones, variables y colecciones con la sintaxis moderna (list[int], dict[str, float], X | None); conocer las herramientas de typing (Optional, Union, Any, Callable, TypedDict, Protocol, Literal, Annotated); entender el nuevo TypeForm de Python 3.15 (PEP 747); distinguir entre anotaciones y validación en tiempo de ejecución; configurar y usar mypy para comprobación estática; escribir docstrings según PEP 257 con estilo Google o NumPy; estructurar un README de proyecto; y generar documentación con Sphinx y autodoc. Se presupone todo el curso hasta el Módulo 17, en particular funciones (Módulo 9), clases (Módulo 14) y documentación básica con docstrings (Módulo 16). No se introducen frameworks de validación en tiempo de ejecución como Pydantic (se mencionan conceptualmente).

Al terminar este módulo serás capaz de:

1. Explicar la diferencia entre tipado dinámico, tipado estático y anotaciones de tipos. 2. Anotar funciones, parámetros y valores de retorno con la sintaxis moderna (int, str, list[int], X | None). 3. Usar las herramientas de typing más habituales: Optional, Union, Any, Callable, TypedDict, Protocol, Literal y Annotated. 4. Comprender el propósito de TypeForm (PEP 747) y TYPE_CHECKING como constante incorporada (PEP 781) en Python 3.15. 5. Distinguir claramente entre anotaciones (metadatos para herramientas) y validación en ejecución (comprobaciones reales). 6. Instalar y configurar mypy, y ejecutarlo sobre un proyecto para detectar errores de tipo. 7. Escribir docstrings según PEP 257 con estilo Google o NumPy, documentando parámetros, retornos y excepciones. 8. Estructurar un README de proyecto claro y útil. 9. Generar documentación HTML/PDF con Sphinx y autodoc a partir de las docstrings. 10. Conocer las novedades de Python 3.15 relacionadas con el tipado y la documentación.

- Del Módulo 9: Funciones, return, parámetros y docstrings básicas. - Del Módulo 11: Excepciones y try/except (necesario para documentar Raises). - Del Módulo 14: Clases y métodos (necesario para Protocol y TypedDict). - Del Módulo 16: PEP 8, PEP 257 y buenas prácticas de documentación. - Ningún conocimiento de anotaciones de tipos, mypy ni Sphinx.

Imagina una función que calcula el precio final de un pedido. Recibe un diccionario con "precio" y "cantidad" y devuelve un número. Un compañero la llama pasando "precio": "10" (una cadena). El programa se ejecuta sin quejarse hasta que, en algún punto, intenta multiplicar "10" * 2 y obtiene "1010" en lugar de 20. El error lógico es silencioso y difícil de rastrear. Si la función hubiera tenido la anotación dict[str, float], mypy habría avisado antes de ejecutar: "10" no es un float.

Ese es el valor del tipado estático opcional: no cambia cómo funciona Python en tiempo de ejecución, pero añade una capa de comprobación que atrapa errores antes de que lleguen a producción. Y la documentación hace el resto: explica a las personas qué espera la función, qué devuelve y qué excepciones puede lanzar, para que el contrato no sea una adivinanza.

En Python, el tipo de un valor se determina en tiempo de ejecución. Esto es el tipado dinámico. Las anotaciones de tipos (PEP 484) son una sintaxis opcional para declarar qué tipos esperas, pero Python no las hace cumplir en tiempo de ejecución: son metadatos para herramientas como mypy, IDEs y generadores de documentación.

def sumar(a: int, b: int) -> int:
    return a + b
 
sumar(2, 3)        # Correcto
sumar("2", "3")    # Python lo ejecuta: devuelve "23". mypy lo rechazaría.

[PYTHON] Las anotaciones no convierten a Python en un lenguaje de tipado estático. Siguen siendo opcionales y no afectan al rendimiento (salvo el coste mínimo de almacenarlas). Su valor está en el análisis estático que habilitan: detectar errores antes de ejecutar.

[ERROR HABITUAL] Creer que def f(x: int) -> int impide llamar a f("hola"). No lo impide: Python ejecutará la función y fallará o no según la operación. La anotación es una promesa que el programador hace a las herramientas, no una restricción del intérprete.

Desde Python 3.9 y 3.10, la sintaxis se ha simplificado:

def buscar(nombre: str, edades: dict[str, int]) -> int | None:
    """Devuelve la edad de una persona, o None si no está en el diccionario."""
    return edades.get(nombre)

[BUENA PRÁCTICA] Usa la sintaxis moderna siempre que sea posible. Es más legible y no requiere importar List, Dict u Optional. La documentación oficial de typing recomienda esta forma para código nuevo.

Ejemplo de TypedDict:

from typing import TypedDict
 
class Usuario(TypedDict):
    nombre: str
    edad: int
 
def procesar(u: Usuario) -> str:
    return f"{u['nombre']} tiene {u['edad']} años"

[PYTHON] TypedDict es especialmente útil para datos que provienen de JSON o de configuraciones, donde un dict genérico no expresa el contrato. mypy comprobará que las claves existen y tienen el tipo correcto.

[AMPLIACIÓN] Annotated permite añadir metadatos que otras herramientas pueden usar. Por ejemplo, Annotated[int, Gt(18)] (con la biblioteca annotated-types) indica que el entero debe ser mayor que 18. mypy por sí solo no hace cumplir esa restricción, pero frameworks como Pydantic o FastAPI la interpretan para validar en tiempo de ejecución.

Python 3.15 introduce varias mejoras en el sistema de tipos:

TYPE_CHECKING como constante incorporada (PEP 781): antes era necesario importarlo de typing (from typing import TYPE_CHECKING). Ahora es una constante global que vale True cuando el código está siendo analizado por un comprobador estático y False en tiempo de ejecución. Esto simplifica los bloques de importación condicional:

if TYPE_CHECKING:
    from mi_modulo_pesado import RecursoCostoso
 
def f(recurso: "RecursoCostoso") -> None:
    ...

TypeForm (PEP 747): un nuevo tipo especial que permite anotar funciones que aceptan tipos como argumentos (no instancias de tipos, sino las expresiones de tipo en sí). Antes solo se podía usar object, lo que perdía información. TypeForm[T] expresa que el argumento es una forma de tipo que representa un T.

from typing import TypeForm
 
def trycast[T](typx: TypeForm[T], value: object) -> T | None:
    """Comprueba si value es asignable a typx y lo devuelve, o None."""
    ...

[PYTHON] TypeForm está pensado para bibliotecas que hacen introspección de tipos (serializadores, validadores, frameworks de inyección de dependencias). Para el código de aplicación habitual, no lo necesitarás, pero conviene conocerlo porque aparece en la documentación de herramientas modernas.

TypedDict cerrado: Python 3.15 permite declarar TypedDict con closed=True, lo que impide añadir claves no declaradas. Es útil para contratos estrictos de datos.

[AMPLIACIÓN] En Python 3.15, las anotaciones se evalúan de forma perezosa por defecto (PEP 649, implementado desde 3.14). Esto resuelve los problemas históricos de referencias hacia adelante (ForwardRef) y simplifica el uso de tipos definidos más adelante en el archivo. No tienes que hacer nada especial: es el comportamiento predeterminado.

Esta distinción es crucial y a menudo se malinterpreta:

- Anotaciones: metadatos estáticos. No validan nada en tiempo de ejecución. def f(x: int) acepta "hola" sin quejarse. - Validación en ejecución: comprobaciones explícitas dentro de la función, o mediante bibliotecas como Pydantic, que inspeccionan las anotaciones y lanzan errores si los datos no cumplen.

def f(x: int) -> int:
    if not isinstance(x, int):
        raise TypeError(f"Se esperaba int, se recibió {type(x).__name__}")
    return x * 2

[BUENA PRÁCTICA] No confíes en las anotaciones para validar datos de entrada (formularios, JSON, APIs). Usa anotaciones para documentar y para que mypy detecte errores en tu código, y añade validación explícita (o usa Pydantic) en las fronteras del sistema.

mypy es el comprobador de tipos estático de referencia para Python. Analiza el código sin ejecutarlo y reporta incoherencias entre los tipos declarados y los usados.

Instalación: pip install mypy

Uso:

mypy mi_proyecto/

Ejemplo de error detectado:

def duplicar(n: int) -> int:
    return n * 2
 
duplicar("hola")  # mypy: Argument 1 to "duplicar" has incompatible type "str"; expected "int"

Configuración en pyproject.toml:

[tool.mypy]
python_version = "3.15"
strict = true
warn_unused_ignores = true

[PYTHON] mypy 2.2 (julio de 2026) es la versión estable actual. Requiere Python 3.10 o superior para ejecutarse, pero puede analizar código destinado a versiones anteriores. El modo strict activa comprobaciones adicionales (por ejemplo, que todas las funciones estén anotadas) y es recomendable para proyectos nuevos.

[BUENA PRÁCTICA] No intentes anotar todo un proyecto heredado de golpe. mypy permite adoptar el tipado de forma incremental: empieza por los módulos nuevos, añade anotaciones a las funciones que modifiques y usa # type: ignore solo cuando sea inevitable (y documenta por qué).

En el Módulo 16 viste las reglas básicas de PEP 257. Aquí profundizamos en el formato de las docstrings para que sean útiles y procesables por herramientas.

Estilo Google:

def calcular_media(notas: list[float]) -> float:
    """Devuelve la media aritmética de una lista de notas.
 
    Args:
        notas: Una lista de números (int o float).
 
    Returns:
        La media como float. Si la lista está vacía, devuelve 0.
 
    Raises:
        ValueError: Si algún elemento de la lista no es numérico.
    """
    ...

Estilo NumPy:

def calcular_media(notas: list[float]) -> float:
    """Devuelve la media aritmética de una lista de notas.
 
    Parameters
    ----------
    notas : list[float]
        Una lista de números.
 
    Returns
    -------
    float
        La media, o 0 si la lista está vacía.
    """
    ...

[BUENA PRÁCTICA] Elige un estilo (Google o NumPy) y sé consistente en todo el proyecto. Sphinx puede parsear ambos con la extensión napoleon. La documentación oficial de Python recomienda documentar parámetros, retornos y excepciones, independientemente del estilo.

El README es el primer archivo que lee alguien que descubre tu proyecto. Debe responder, como mínimo, a estas preguntas:

- ¿Qué es este proyecto? Una descripción de una o dos frases. - ¿Cómo se instala? Comandos concretos (pip install ..., git clone ...). - ¿Cómo se usa? Un ejemplo mínimo funcional. - ¿Cómo se ejecutan las pruebas? El comando exacto. - ¿Dónde está la documentación completa? Enlace a docs/ o a Read the Docs.

# Analizador de Gastos
 
Herramienta para procesar listas de gastos y generar informes.
 
## Instalación
 
```bash
pip install -e .

from gastos import generar_informe
informe = generar_informe([{"concepto": "comida", "importe": 20}])

pytest

Consulta docs/ o ejecuta sphinx-build -b html docs/ docs/_build/html.

> **[BUENA PRÁCTICA]** El `README` debe estar en formato Markdown (`README.md`) y en la raíz del proyecto. PyPI y GitHub lo renderizan automáticamente. Incluye badges de estado de CI y cobertura si el proyecto es público.

#### 5.9. Sphinx: documentación generada a partir de docstrings

**Sphinx** es el generador de documentación de referencia en Python. Convierte archivos reStructuredText (o Markdown con MyST) y docstrings en HTML, PDF y otros formatos.

**Flujo básico:**

1.  **Instalar:** `pip install sphinx sphinx-autodoc-typehints`
2.  **Inicializar:** `sphinx-quickstart docs`
3.  **Configurar `docs/conf.py`:**

    ```python
    extensions = [
        "sphinx.ext.autodoc",      # Extrae docstrings
        "sphinx.ext.napoleon",     # Parsea estilo Google/NumPy
        "sphinx.ext.intersphinx",  # Enlaces a docs externas
        "sphinx_autodoc_typehints", # Muestra las anotaciones de tipo
    ]
    ```

4.  **Documentar un módulo** en `docs/api.rst`:

    ```rst
    .. automodule:: gastos
       :members:
       :undoc-members:
    ```

5.  **Construir:** `sphinx-build -b html docs/ docs/_build/html`

> **[PYTHON]** Sphinx es el estándar de facto para la documentación de proyectos Python (lo usa la propia documentación oficial de Python). `autodoc` extrae las docstrings; `napoleon` convierte los estilos Google/NumPy a reStructuredText; `sphinx-autodoc-typehints` muestra las anotaciones de tipo en la documentación generada.

---

### 6. Ejemplo completo comentado: módulo con tipado y documentación

```python
"""Módulo para el cálculo de estadísticas básicas de una lista de números."""

from typing import TypedDict


class Estadisticas(TypedDict):
    """Resultado del análisis estadístico de una lista de números."""
    media: float
    maximo: float
    minimo: float
    total: int


def calcular_estadisticas(numeros: list[float]) -> Estadisticas:
    """Calcula la media, el máximo, el mínimo y el total de una lista.

    Args:
        numeros: Una lista de números (int o float). No puede estar vacía.

    Returns:
        Un diccionario con las claves ``media``, ``maximo``, ``minimo`` y ``total``.

    Raises:
        ValueError: Si la lista está vacía.

    Examples:
        >>> calcular_estadisticas([10, 20, 30])
        {'media': 20.0, 'maximo': 30, 'minimo': 10, 'total': 3}
    """
    if not numeros:
        raise ValueError("La lista no puede estar vacía.")

    return {
        "media": sum(numeros) / len(numeros),
        "maximo": max(numeros),
        "minimo": min(numeros),
        "total": len(numeros),
    }

Seguimiento: La anotación list[float] indica que se espera una lista de números. Estadisticas es un TypedDict que documenta las claves y tipos del retorno. La docstring sigue el estilo Google y documenta parámetros, retorno, excepciones y un ejemplo. mypy comprobará que la función devuelve el tipo declarado y que las claves del diccionario coinciden con Estadisticas.

Cuando ejecutas mypy mi_modulo.py:

1. Parsea el archivo y construye un árbol de sintaxis. 2. Infiere los tipos de las expresiones cuando no están anotadas. 3. Comprueba que las operaciones son válidas para los tipos declarados. 4. Reporta los errores con el archivo, la línea y una descripción. 5. Si no hay errores, termina con código de salida 0. Si los hay, con código 1.

mypy no ejecuta el código: solo lo analiza. Por eso puede detectar errores en funciones que nunca se llaman.

- Tipado opcional: en Java o C#, el tipado es obligatorio. En Python, las anotaciones son opcionales y no afectan al tiempo de ejecución. Esto permite adoptarlas de forma incremental. - mypy separado del intérprete: en lenguajes compilados, el compilador hace la comprobación de tipos. En Python, es una herramienta externa que se ejecuta aparte. - Protocol en lugar de interfaces: Python no tiene interfaces explícitas como Java. Protocol permite definir contratos estructurales que mypy verifica, alineados con el duck typing. - TypeForm (3.15): no tiene equivalente directo en la mayoría de lenguajes; está pensado para bibliotecas que manipulan tipos en tiempo de ejecución. - Sphinx y docstrings: la documentación integrada en el código (__doc__, help()) es una característica cultural de Python. En otros lenguajes, la documentación suele vivir en archivos separados.

Incorrecto (anotaciones ausentes y docstring vaga):

def f(x):
    """Hace algo."""
    return x * 2

Mejor (anotaciones precisas y docstring útil):

def duplicar(valor: int) -> int:
    """Devuelve el doble de un número entero.
 
    Args:
        valor: El número a duplicar.
 
    Returns:
        El doble de ``valor``.
    """
    return valor * 2

[BUENA PRÁCTICA] Anota las funciones públicas y los módulos nuevos. Usa mypy --strict en proyectos nuevos. Documenta parámetros, retornos y excepciones con un estilo consistente. Mantén el README actualizado y genera la documentación con Sphinx para que las docstrings sean accesibles sin leer el código fuente.

- mypy funciona igual en ambos sistemas. Se instala con pip y se ejecuta desde la terminal. - Sphinx: los comandos sphinx-quickstart y sphinx-build son idénticos. Las rutas de salida (docs/_build/html) funcionan en ambos sistemas. - Rutas en conf.py: usa pathlib o rutas relativas con /, que Sphinx interpreta correctamente en Windows y Linux. - Codificación: con Python 3.15 y UTF-8 por defecto, las docstrings con tildes y caracteres especiales se procesan sin problemas en ambos sistemas.

[WINDOWS / LINUX] Si mypy no se encuentra en el PATH después de instalarlo, usa py -m mypy en Windows o python3 -m mypy en Linux.

Ejercicio guiado 1: Anotar una función.

Toma esta función y añade anotaciones de tipos para parámetros y retorno:

def contar_palabras(texto):
    return len(texto.split())

Añade también una docstring de una línea. Ejecuta mypy sobre el archivo y comprueba que no hay errores.

Ejercicio guiado 2: TypedDict para datos estructurados.

Define un TypedDict llamado Producto con nombre: str, precio: float y stock: int. Escribe una función valor_total(producto: Producto) -> float que devuelva precio * stock. Crea un diccionario que cumpla el contrato y pásalo a la función.

Ejercicio guiado 3: Docstring estilo Google.

Escribe una función dividir(a: float, b: float) -> float que lance ZeroDivisionError si b es 0. Documenta parámetros, retorno y excepción con estilo Google. Ejecuta help(dividir) en el intérprete y observa la salida.

1. Predicción: ¿Qué reporta mypy para este código?

  ```python
  def suma(a: int, b: int) -> int:
      return a + b

  resultado = suma(2, "3")
  ```
  Ejecútalo y comprueba tu predicción.

2. Protocol: Define un Protocol llamado Saludador con un método saludar() -> str. Escribe dos clases que lo implementen y una función que acepte cualquier Saludador. Verifica con mypy que ambas clases son válidas.

3. README: Crea un README.md para uno de los proyectos que hayas hecho en módulos anteriores. Incluye descripción, instalación, uso y pruebas.

4. Sphinx: Inicializa un proyecto Sphinx en una carpeta docs/, configura autodoc y napoleon, y genera la documentación HTML de un módulo con docstrings.

5. Reto opcional: Investiga el nuevo TypeForm de Python 3.15 y escribe una función que acepte un tipo como argumento y compruebe si un valor es de ese tipo usando isinstance. Anota el parámetro con TypeForm[T] y comprueba con mypy que el uso es correcto.

Solución al ejercicio guiado 1:

def contar_palabras(texto: str) -> int:
    """Devuelve el número de palabras de un texto."""
    return len(texto.split())

mypy no reporta errores: texto es str y .split() devuelve list[str], cuya longitud es int.

Solución al ejercicio guiado 2:

from typing import TypedDict
 
class Producto(TypedDict):
    nombre: str
    precio: float
    stock: int
 
def valor_total(producto: Producto) -> float:
    """Devuelve el valor total del stock de un producto."""
    return producto["precio"] * producto["stock"]
 
p: Producto = {"nombre": "Teclado", "precio": 25.0, "stock": 10}
print(valor_total(p))  # 250.0

Solución al ejercicio guiado 3:

def dividir(a: float, b: float) -> float:
    """Divide dos números.
 
    Args:
        a: El dividendo.
        b: El divisor.
 
    Returns:
        El resultado de la división.
 
    Raises:
        ZeroDivisionError: Si ``b`` es cero.
    """
    if b == 0:
        raise ZeroDivisionError("El divisor no puede ser cero.")
    return a / b

Solución al ejercicio 1 (predicción): mypy reporta Argument 2 to "suma" has incompatible type "str"; expected "int". Python, en tiempo de ejecución, lanzaría TypeError al intentar 2 + "3".

- Las anotaciones de tipos son metadatos opcionales que no afectan a la ejecución pero permiten detectar errores con herramientas estáticas. - La sintaxis moderna (list[int], dict[str, float], X | None) es preferible a List, Dict y Optional. - typing ofrece Any, Callable, TypedDict, Protocol, Literal y Annotated para expresar contratos complejos. - Python 3.15 incorpora TYPE_CHECKING como constante global y TypeForm (PEP 747) para anotar funciones que aceptan tipos. - Las anotaciones no validan en ejecución; para eso se usa isinstance o bibliotecas como Pydantic. - mypy es el comprobador estático de referencia; se adopta de forma incremental y con strict en proyectos nuevos. - Las docstrings (PEP 257) documentan el contrato de funciones y clases; el estilo Google o NumPy facilita su procesamiento. - El README es la puerta de entrada al proyecto; debe incluir descripción, instalación, uso y pruebas. - Sphinx genera documentación HTML/PDF a partir de docstrings y archivos reStructuredText.

1. ¿Qué diferencia hay entre una anotación de tipo y una comprobación en tiempo de ejecución? Pon un ejemplo en el que la anotación no impida un error. 2. ¿Por qué mypy es útil si Python sigue ejecutando el código aunque los tipos no coincidan? 3. ¿Qué aporta TypedDict frente a un dict genérico? 4. ¿Qué hace TYPE_CHECKING y por qué es útil para evitar importaciones circulares? 5. Reto: Sin ejecutar, predice qué reporta mypy para x: int = "hola". Luego compruébalo y explica el mensaje.

- Documentación oficial de typing: https://docs.python.org/3.15/library/typing.html - PEP 484 – Type Hints: https://peps.python.org/pep-0484/ - PEP 747 – Annotating Type Forms (novedad 3.15): https://peps.python.org/pep-0747/ - PEP 781 – Make TYPE_CHECKING a built-in constant (novedad 3.15): https://peps.python.org/pep-0781/ - PEP 649 – Deferred Evaluation Of Annotations (base de la evaluación perezosa en 3.15): https://peps.python.org/pep-0649/ - Documentación oficial de mypy: https://mypy.readthedocs.io/ - Mypy 2.2 (julio 2026): https://mypy-lang.blogspot.com/2026/07/mypy-22-released.html - PEP 257 – Docstring Conventions: https://peps.python.org/pep-0257/ - Documentación oficial de Sphinx: https://www.sphinx-doc.org/ - Guía de sphinx.ext.autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html - Guía oficial de empaquetado: README para PyPI: https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/