Image for post Mejora la Calidad de tu Código Python: Una Guía Práctica de Type Hinting y Mypy

Mejora la Calidad de tu Código Python: Una Guía Práctica de Type Hinting y Mypy

Escrito por Sergio Márquez

Contexto del Problema

Python es conocido por su flexibilidad y facilidad de uso, en gran parte debido a su naturaleza de tipado dinámico. Esto significa que no necesitas declarar explícitamente el tipo de una variable cuando la creas; Python lo infiere en tiempo de ejecución. Si bien esto acelera el desarrollo inicial, puede convertirse en una fuente de problemas a medida que tus proyectos crecen en tamaño y complejidad, o cuando trabajas en equipo.

Imagina que estás trabajando en una función que espera una lista de números, pero accidentalmente le pasas una cadena de texto. Python no te avisará de este error hasta que la función intente realizar una operación numérica con la cadena, resultando en un error en tiempo de ejecución. Esto puede ser especialmente problemático en código que no se ejecuta con frecuencia o en partes críticas de una aplicación que solo fallan bajo ciertas condiciones.

Además, la falta de información de tipos explícita dificulta la lectura y comprensión del código. ¿Qué tipo de datos espera esta función? ¿Qué tipo de datos devuelve? Sin type hints, a menudo tienes que recurrir a la documentación (si existe y está actualizada), o peor aún, a leer la implementación de la función para entender sus expectativas. Esto ralentiza el desarrollo, hace que la refactorización sea más arriesgada y reduce la eficacia del autocompletado y la verificación de errores de tu IDE.

Aquí es donde el type hinting y herramientas como Mypy entran en juego, ofreciendo una solución elegante para añadir una capa de robustez y claridad a tu código Python sin sacrificar la flexibilidad del lenguaje.

Conceptos Clave

Tipado Dinámico vs. Estático

  • Tipado Dinámico: En Python, el tipo de una variable se determina en tiempo de ejecución. Esto permite una gran flexibilidad, pero los errores de tipo solo se descubren cuando el código se ejecuta.
  • Tipado Estático: En lenguajes como Java o C++, los tipos de las variables se declaran explícitamente y se verifican en tiempo de compilación. Esto ayuda a detectar errores antes de que el programa se ejecute, pero puede ser más verboso.

Python, con el type hinting, busca un equilibrio, permitiéndote añadir información de tipo opcional que puede ser verificada estáticamente por herramientas externas.

Type Hinting (PEP 484)

El type hinting es una característica introducida en Python 3.5 (a través de la PEP 484) que permite a los desarrolladores especificar los tipos esperados de argumentos de función, valores de retorno, variables y atributos de clase. Es importante entender que estos hints son solo eso: sugerencias. Python los ignora en tiempo de ejecución, lo que significa que no afectan el comportamiento del programa. Su propósito principal es ser utilizados por herramientas de análisis estático de código, IDEs y otros desarrolladores.

Algunos tipos comunes que usarás:

  • Tipos básicos: int, str, float, bool.
  • Colecciones: List[int], Dict[str, float], Tuple[str, int, bool], Set[str]. Necesitas importarlos desde el módulo typing.
  • Tipos especiales del módulo typing:
    • Optional[T]: Indica que un valor puede ser de tipo T o None. Es equivalente a Union[T, None].
    • Union[T1, T2]: Indica que un valor puede ser de tipo T1 o T2.
    • Any: Indica que el tipo es desconocido o puede ser cualquier cosa. Úsalo con precaución, ya que anula la verificación de tipos.
    • Callable[[Arg1Type, Arg2Type], ReturnType]: Para funciones o cualquier objeto invocable.
    • TypeVar: Para definir tipos genéricos.
    • TypedDict: Para definir la estructura de diccionarios con claves y tipos específicos.

Mypy

Mypy es un verificador de tipos estático opcional para Python. Su función es leer tu código Python, interpretar los type hints que has añadido y verificar si hay inconsistencias de tipo. Si Mypy encuentra un lugar donde un tipo no coincide con lo que se esperaba (por ejemplo, pasas una cadena a una función que espera un entero), te lo notificará antes de que ejecutes tu código. Piensa en Mypy como un 'linter' para tipos.

Las ventajas de usar Mypy son significativas:

  • Detección temprana de errores: Atrapa errores de tipo antes de que lleguen a producción.
  • Mejora la legibilidad: El código con type hints es más fácil de entender para otros desarrolladores y para tu yo futuro.
  • Facilita la refactorización: Puedes cambiar el tipo de un argumento o retorno y Mypy te ayudará a encontrar todos los lugares afectados.
  • Mejor soporte de IDE: Los IDEs modernos utilizan los type hints para ofrecer un autocompletado más preciso y una mejor verificación de errores en tiempo real.

Implementación Paso a Paso

1. Instalación de Mypy

Lo primero es instalar Mypy en tu entorno virtual. Es una herramienta de desarrollo, por lo que no es una dependencia de tu aplicación en producción.


pip install mypy

2. Sintaxis Básica de Type Hints

Veamos cómo aplicar los type hints en diferentes escenarios.

Variables

Puedes anotar variables para indicar su tipo esperado. Esto es útil para la claridad, aunque Mypy a menudo puede inferir el tipo de asignaciones simples.


nombre: str = "Alice"
edad: int = 30
salario: float = 50000.50
es_activo: bool = True

Parámetros de Función y Valores de Retorno

Esta es la aplicación más común y beneficiosa de los type hints.


def saludar(nombre: str) -> str:
    return f"Hola, {nombre}!"

def sumar(a: int, b: int) -> int:
    return a + b

def dividir(dividendo: float, divisor: float) -> float:
    if divisor == 0:
        raise ValueError("No se puede dividir por cero")
    return dividendo / divisor

Colecciones (Listas, Diccionarios, Tuplas, Sets)

Para colecciones, necesitas especificar el tipo de los elementos que contienen. Para esto, importamos los tipos genéricos del módulo typing.


from typing import List, Dict, Tuple, Set

productos: List[str] = ["manzana", "pera", "uva"]
precios: Dict[str, float] = {"manzana": 1.2, "pera": 0.8}
coordenadas: Tuple[float, float] = (10.5, 20.3)
usuarios_activos: Set[int] = {101, 105, 203}

Optional y Union

Optional[T] se usa cuando un valor puede ser de tipo T o None. Union[T1, T2] se usa cuando un valor puede ser de tipo T1 o T2.


from typing import Optional, Union

def obtener_usuario(id_usuario: int) -> Optional[str]:
    if id_usuario == 1:
        return "Alice"
    return None

def procesar_entrada(valor: Union[str, int]) -> str:
    if isinstance(valor, int):
        return f"Número recibido: {valor}"
    return f"Cadena recibida: {valor.upper()}"

Clases Personalizadas

Puedes usar tus propias clases como tipos.


class Producto:
    def __init__(self, nombre: str, precio: float):
        self.nombre = nombre
        self.precio = precio

def mostrar_producto(p: Producto) -> str:
    return f"Producto: {p.nombre}, Precio: {p.precio:.2f}"

mi_producto = Producto("Laptop", 1200.50)
print(mostrar_producto(mi_producto))

3. Ejecutando Mypy

Una vez que has añadido los type hints a tu código, puedes ejecutar Mypy desde la línea de comandos para verificarlo.

Crea un archivo llamado ejemplo_tipos.py con el siguiente contenido:


from typing import List, Dict, Optional

def calcular_total_compra(precios_productos: Dict[str, float], cantidades: Dict[str, int]) -> float:
    total = 0.0
    for producto, precio in precios_productos.items():
        cantidad = cantidades.get(producto, 0)
        total += precio * cantidad
    return total

def obtener_nombre_cliente(id_cliente: int) -> Optional[str]:
    if id_cliente == 101:
        return "Juan Pérez"
    elif id_cliente == 102:
        return "María García"
    return None

def procesar_pedidos(pedidos: List[Dict[str, Union[str, int, float]]]) -> List[str]:
    resultados = []
    for pedido in pedidos:
        nombre_producto = pedido.get("producto", "Desconocido")
        cantidad = pedido.get("cantidad", 0)
        precio_unitario = pedido.get("precio", 0.0)
        
        # Mypy nos ayudará a asegurar que estas operaciones son válidas
        if isinstance(nombre_producto, str) and isinstance(cantidad, int) and isinstance(precio_unitario, float):
            resultados.append(f"Pedido: {nombre_producto} x {cantidad} a {precio_unitario:.2f} cada uno.")
        else:
            resultados.append(f"Error en el formato del pedido: {pedido}")
    return resultados

# Ejemplo de uso correcto
precios = {"manzana": 1.5, "pan": 2.0, "leche": 1.0}
cantidades_compra = {"manzana": 2, "pan": 1}
print(f"Total de la compra: {calcular_total_compra(precios, cantidades_compra):.2f}")

cliente = obtener_nombre_cliente(101)
if cliente:
    print(f"Cliente encontrado: {cliente}")

pedidos_ejemplo = [
    {"producto": "Camisa", "cantidad": 2, "precio": 25.50},
    {"producto": "Pantalón", "cantidad": 1, "precio": 40.00},
    {"producto": "Zapatos", "cantidad": "uno", "precio": 60.00} # Error intencional
]

print("\nProcesando pedidos:")
for res in procesar_pedidos(pedidos_ejemplo):
    print(res)

Ahora, ejecuta Mypy en tu terminal:


mypy ejemplo_tipos.py

Mypy debería reportar un error similar a este (la línea exacta puede variar):


ejemplo_tipos.py:40: error: Argument "cantidad" to "procesar_pedidos" has incompatible type "List[Dict[str, Union[str, int, float]]]"; expected "List[Dict[str, Union[str, int, float]]]"  [arg-type]
ejemplo_tipos.py:40: note: "Dict[str, Union[str, int, float]]" is incompatible with "Dict[str, Union[str, int, float]]"
ejemplo_tipos.py:40: note: At item "cantidad": Expected "Union[str, int, float]", got "str"
Found 1 error in 1 file (checked 1 source file)

Mypy detectó que en el tercer pedido, el valor de "cantidad" es una cadena ("uno") cuando la anotación de tipo Union[str, int, float] para los valores del diccionario de pedidos esperaba un tipo compatible con int o float para la operación posterior. Aunque str es parte de la unión, el problema real es que la lógica interna de procesar_pedidos espera un int o float para la cantidad para poder usarla en operaciones numéricas, y Mypy te está avisando de una posible inconsistencia entre el tipo declarado y el uso real. Si cambiamos "uno" a 1, Mypy pasaría la verificación.

4. Configuración de Mypy (mypy.ini)

Para proyectos más grandes, querrás configurar Mypy para que se adapte a tus necesidades. Puedes hacerlo creando un archivo mypy.ini en la raíz de tu proyecto.


[mypy]
python_version = 3.9
warn_unused_ignores = True
warn_redundant_casts = True
# Disallow untyped definitions (funciones sin type hints)
disallow_untyped_defs = True
# Disallow calls to untyped definitions
disallow_incomplete_defs = True
# Report errors for missing imports
ignore_missing_imports = False
# Show error codes
show_error_codes = True

[mypy-mi_modulo_externo.*]
# Ignorar un módulo específico que no tiene type hints
ignore_missing_imports = True

Ejecuta Mypy de nuevo, y automáticamente buscará este archivo de configuración.


mypy .

Esto verificará todos los archivos Python en el directorio actual y sus subdirectorios.

Mini Proyecto / Aplicación Sencilla: Gestor de Tareas con Type Hints

Vamos a construir un pequeño gestor de tareas para ilustrar cómo los type hints mejoran la claridad y la robustez.

Crea un archivo task_manager.py:


from typing import List, Dict, Optional, Union, TypedDict
from datetime import datetime

# Definimos un TypedDict para la estructura de una tarea
class Task(TypedDict):
    id: int
    titulo: str
    descripcion: Optional[str]
    fecha_creacion: datetime
    completada: bool

class TaskManager:
    def __init__(self) -> None:
        self.tasks: List[Task] = []
        self._next_id: int = 1

    def add_task(self, titulo: str, descripcion: Optional[str] = None) -> Task:
        new_task: Task = {
            "id": self._next_id,
            "titulo": titulo,
            "descripcion": descripcion,
            "fecha_creacion": datetime.now(),
            "completada": False
        }
        self.tasks.append(new_task)
        self._next_id += 1
        return new_task

    def get_task(self, task_id: int) -> Optional[Task]:
        for task in self.tasks:
            if task["id"] == task_id:
                return task
        return None

    def update_task_status(self, task_id: int, completada: bool) -> bool:
        task = self.get_task(task_id)
        if task:
            task["completada"] = completada
            return True
        return False

    def list_tasks(self, solo_pendientes: bool = False) -> List[Task]:
        if solo_pendientes:
            return [task for task in self.tasks if not task["completada"]]
        return self.tasks

    def delete_task(self, task_id: int) -> bool:
        initial_len = len(self.tasks)
        self.tasks = [task for task in self.tasks if task["id"] != task_id]
        return len(self.tasks) < initial_len

# --- Mini Aplicación de Prueba ---
if __name__ == "__main__":
    manager = TaskManager()

    print("Añadiendo tareas...")
    manager.add_task("Comprar víveres", "Leche, pan, huevos")
    manager.add_task("Estudiar Mypy", "Revisar la documentación oficial")
    manager.add_task("Preparar presentación")

    print("\nTodas las tareas:")
    for task in manager.list_tasks():
        print(f"- [{'X' if task['completada'] else ' '}] {task['id']}: {task['titulo']} (Creada: {task['fecha_creacion'].strftime('%Y-%m-%d')})")

    print("\nCompletando tarea 1...")
    manager.update_task_status(1, True)

    print("\nTareas pendientes:")
    for task in manager.list_tasks(solo_pendientes=True):
        print(f"- [{'X' if task['completada'] else ' '}] {task['id']}: {task['titulo']}")

    print("\nIntentando obtener tarea inexistente (ID 99):")
    tarea_inexistente = manager.get_task(99)
    if tarea_inexistente is None:
        print("Tarea no encontrada, como se esperaba.")

    print("\nEliminando tarea 2...")
    if manager.delete_task(2):
        print("Tarea 2 eliminada.")

    print("\nTareas restantes:")
    for task in manager.list_tasks():
        print(f"- [{'X' if task['completada'] else ' '}] {task['id']}: {task['titulo']}")

    # Ejemplo de un error que Mypy detectaría si no fuera por el TypedDict
    # manager.add_task(123, "Esto es un error de tipo si 'titulo' no fuera str")
    # Si intentaras pasar un int como título, Mypy te avisaría.

Para ejecutar este mini-proyecto y verificarlo con Mypy:


python task_manager.py
mypy task_manager.py

Mypy debería pasar sin errores, demostrando que la estructura de tipos es consistente. Si intentaras, por ejemplo, pasar un entero como título a add_task, Mypy te lo señalaría.

Errores Comunes y Depuración

Aunque el type hinting es una herramienta poderosa, hay algunas trampas comunes que los desarrolladores suelen encontrar:

1. Olvidar importar tipos del módulo typing

Es un error muy común. Si usas List, Dict, Optional, etc., debes importarlos explícitamente.


# Incorrecto
def procesar_items(items: List[str]) -> None:
    pass

# Correcto
from typing import List
def procesar_items(items: List[str]) -> None:
    pass

2. Uso excesivo o incorrecto de Any

Any es el comodín del type hinting. Le dice a Mypy que "confíe en mí, sé lo que estoy haciendo" y desactiva la verificación de tipos para esa parte del código. Si bien es útil para interactuar con código sin anotaciones o para prototipos rápidos, su uso excesivo anula los beneficios del type hinting.


from typing import Any

# Evitar esto si es posible
def procesar_datos_genericos(data: Any) -> Any:
    # ... lógica que podría fallar si 'data' no es del tipo esperado
    return data

Intenta ser lo más específico posible con tus tipos. Si no estás seguro, Union o Optional suelen ser mejores alternativas que Any.

3. Ignorar los errores de Mypy

Mypy está ahí para ayudarte. Si reporta un error, tómate el tiempo para entender por qué. A menudo, revela un problema real en tu lógica o una ambigüedad en tus tipos.

Si estás seguro de que Mypy está equivocado o si estás lidiando con una limitación conocida, puedes usar # type: ignore en la línea donde Mypy reporta el error. Úsalo con moderación y con un comentario que explique por qué lo estás ignorando.


def sumar_numeros(a: int, b: int) -> int:
    return a + b

resultado = sumar_numeros("1", 2) # Mypy reportará un error aquí
resultado_ignorado = sumar_numeros("1", 2) # type: ignore # ¡No hagas esto a menos que sea realmente necesario!

4. Problemas con librerías de terceros sin stubs

Algunas librerías antiguas o menos mantenidas pueden no tener type hints o archivos .pyi (archivos de stubs que contienen solo las anotaciones de tipo). Mypy puede quejarse de "missing imports" o de no poder inferir tipos.

Puedes configurar Mypy para ignorar los módulos que no tienen type hints en tu archivo mypy.ini:


[mypy]
ignore_missing_imports = True

[mypy-nombre_de_la_libreria_sin_tipos.*]
ignore_missing_imports = True

O puedes instalar stubs de terceros si están disponibles (ej: pip install types-requests para la librería requests).

5. Tipos genéricos y TypeVar

Cuando trabajas con funciones o clases que operan sobre diferentes tipos pero mantienen la relación de tipo, TypeVar es esencial. Por ejemplo, una función identity que devuelve exactamente el mismo tipo que recibe.


from typing import TypeVar

T = TypeVar('T')

def identity(arg: T) -> T:
    return arg

valor_str: str = identity("hola")
valor_int: int = identity(123)

# Mypy detectaría un error aquí:
# valor_str_error: str = identity(123) # type: ignore

Si no usaras TypeVar y solo pusieras Any, perderías la verificación de que el tipo de retorno es el mismo que el de entrada.

Aprendizaje Futuro / Próximos Pasos

El type hinting y Mypy son solo el comienzo de un camino hacia un código Python más robusto y mantenible. Aquí hay algunas áreas para explorar a medida que te sientas más cómodo:

1. Integración con CI/CD

Automatiza la ejecución de Mypy en tu pipeline de Integración Continua/Despliegue Continuo (CI/CD). Esto asegura que todo el código nuevo o modificado cumpla con los estándares de tipo antes de ser fusionado o desplegado. Herramientas como GitHub Actions, GitLab CI o Jenkins pueden configurarse fácilmente para ejecutar mypy . como parte de tus pruebas.

2. Explorar otras herramientas de verificación de tipos

Mypy es el verificador de tipos más popular, pero no es el único. Otras herramientas como pyright (desarrollado por Microsoft, usado en VS Code) o pyre (desarrollado por Meta) ofrecen enfoques ligeramente diferentes y pueden tener ventajas en ciertos escenarios o con bases de código muy grandes. Experimenta con ellas para ver cuál se adapta mejor a tu flujo de trabajo.

3. TypedDict para estructuras de diccionario complejas

Ya lo usamos en el mini-proyecto, pero profundiza en TypedDict. Es increíblemente útil para definir la forma de diccionarios que se usan como estructuras de datos, proporcionando verificación de tipos para claves y valores, lo cual es un gran paso adelante de los diccionarios de Python sin tipado.

4. Protocol para tipado estructural

Python es un lenguaje de "duck typing" (si camina como un pato y grazna como un pato, es un pato). Protocol (introducido en PEP 544) te permite definir interfaces basadas en el comportamiento (métodos y atributos) en lugar de la herencia explícita. Esto es muy poderoso para escribir código flexible que aún se beneficia de la verificación de tipos.


from typing import Protocol

class Printable(Protocol):
    def print_info(self) -> None:
        ...

class Book:
    def __init__(self, title: str):
        self.title = title
    def print_info(self) -> None:
        print(f"Libro: {self.title}")

class Article:
    def __init__(self, heading: str):
        self.heading = heading
    def print_info(self) -> None:
        print(f"Artículo: {self.heading}")

def process_printable(item: Printable) -> None:
    item.print_info()

process_printable(Book("El Quijote"))
process_printable(Article("La importancia del Type Hinting"))

5. Escribir archivos de stubs (.pyi)

Si trabajas con una librería de terceros que carece de type hints, puedes contribuir a la comunidad escribiendo archivos .pyi. Estos archivos contienen solo las anotaciones de tipo para una librería, permitiendo que Mypy y los IDEs la entiendan mejor sin modificar el código fuente original.

6. Uso de NewType

NewType te permite crear tipos distintos basados en tipos existentes, lo que puede mejorar la claridad y prevenir errores lógicos donde se mezclan valores que, aunque tienen el mismo tipo base (ej. int), representan conceptos diferentes (ej. UserID vs ProductID).


from typing import NewType

UserID = NewType('UserID', int)
ProductID = NewType('ProductID', int)

def get_user_name(user_id: UserID) -> str:
    # ... lógica para obtener el nombre del usuario
    return f"Usuario {user_id}"

def get_product_price(product_id: ProductID) -> float:
    # ... lógica para obtener el precio del producto
    return float(product_id * 10)

user_id_val = UserID(123)
product_id_val = ProductID(456)

print(get_user_name(user_id_val))
# Mypy detectaría un error aquí si intentaras:
# print(get_user_name(ProductID(789))) # type: ignore

Adoptar el type hinting y Mypy en tus proyectos es una inversión que rinde frutos en forma de código más limpio, menos errores y una experiencia de desarrollo más agradable. ¡Empieza hoy mismo a tipar tu código y observa la diferencia!

Volver al blog