Conceptos básicos de las sugerencias de tipo

9 ejemplos para empezar con las sugerencias de tipo de Python: 6 básicos y 3 intermedios.

Prerrequisitos

• Python 3.14.0 con mypy o pyright disponibles (uv add --dev mypy).

Ejemplos básicos

1. Anotaciones de variables y funciones

Documenta los tipos esperados en nombres y firmas.

name: str = "Ada"
count: int = 0
 
def greet(user: str) -> str:
    return f"Hello, {user}"

• Las anotaciones se almacenan en __annotations__ pero no se aplican en tiempo de ejecución.
• El retorno -> None documenta que no hay un valor de retorno útil.
• Añade gradualmente sugerencias primero a los módulos estables.

Relacionado: Genéricos integrados y de colección - list[int], dict[str, int]

2. Tipos de colección

Usa genéricos integrados para contenedores (3.9+).

users: list[str] = []
index: dict[str, int] = {}
unique: set[int] = set()

• list sin parámetros significa una lista sin tipo para verificadores estrictos.
• Prefiere tipos de contenedores concretos sobre los abstractos, a menos que la API requiera flexibilidad.
• La longitud de la tupla puede ser fija: tuple[int, str].

Relacionado: Genéricos integrados y de colección - Sequence, Mapping

3. Opcional y None

Los valores nulos usan la unión con None.

def find_user(user_id: int) -> dict | None:
    return None
 
email: str | None = None

• Optional[str] es equivalente a str | None (estilo antiguo).
• Estrecha con if x is not None antes de usar; los verificadores refinan los tipos.
• No uses Optional cuando None no está permitido.

Relacionado: Opcional, Unión y el operador | - estrechamiento

4. Ejecutando mypy

Verifica tipos estáticamente en CI.

uv run mypy src/

# fragmento de pyproject.toml
[tool.mypy]
python_version = "3.14"
strict = false
warn_return_any = true

• Empieza de forma permisiva; ciérrala por módulo con anulaciones strict = true.
• mypy lee la sección [tool.mypy] de pyproject.toml.
• Corrige primero los errores en los límites: manejadores HTTP, adaptadores de base de datos.

Relacionado: Configuración de mypy y pyright - configuración completa

5. Estrechamiento con isinstance

Combina comprobaciones en tiempo de ejecución con estrechamiento estático.

def handle(value: str | int) -> str:
    if isinstance(value, str):
        return value.upper()
    return str(value * 2)

• isinstance ayuda a mypy/pyright a estrechar uniones.
• match/case también estrecha cuando los patrones son específicos del tipo.
• Todavía se necesita validación en tiempo de ejecución en límites no confiables (usa Pydantic 2).

Relacionado: Opcional, Unión y el operador | - type guards

6. Definición tipada con vía de escape Any

Any se excluye de la verificación; úsala con moderación.

from typing import Any
 
def legacy_bridge(payload: Any) -> dict[str, Any]:
    assert isinstance(payload, dict)
    return payload

• Any es contagioso: los retornos infectan a los llamadores.
• Prefiere object cuando se permite cualquier valor pero no operaciones arbitrarias.
• Refina Any en los bordes del sistema con el tiempo.

Ejemplos intermedios

7. Tipos Callable

Tipa funciones de orden superior.

from collections.abc import Callable
 
def apply(fn: Callable[[int, int], int], a: int, b: int) -> int:
    return fn(a, b)

• Callable[[ArgTypes], ReturnType] documenta la forma de la función.
• ParamSpec preserva las firmas de los decoradores (avanzado).
• Prefiere Callable sobre funciones sin tipo en API públicas.

Relacionado: Sobrecargas y tipos Callable - ParamSpec

8. Atributos de clase

Anota variables de instancia y de clase.

class Counter:
    total: int = 0
 
    def __init__(self) -> None:
        self.value: int = 0

• Las variables de clase se anotan en el cuerpo de la clase; las variables de instancia a menudo en __init__.
• ClassVar marca los atributos que no se anulan en las instancias.
• Los dataclasses generan anotaciones a partir de las definiciones de campo.

Relacionado: dataclasses - campos tipados

9. Estrategia de tipado gradual

Añade tipos módulo por módulo.

# mypackage/service.py  (tipado)
def compute(x: int) -> int:
    return x + 1
 
# mypackage/legacy.py  (sin tipo por ahora)
def legacy(): ...

• Habilita check_untyped_defs después de la cobertura base.
• Usa # type: ignore[code] con moderación, comentando el porqué.
• Rastrea el progreso con informes de cobertura de mypy por paquete.

Relacionado: Estrategia de tipado gradual - plan de implementación

Versiones de la pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.