Pythons · DacaCode

aiohttp: Peticiones HTTP Concurrentes con asyncio

Dacadev — Wed, 24 Jun 2026 00:00:00 -0500

Tabla de Contenido

En el artículo anterior cerramos con una regla clave: nunca uses APIs bloqueantes como requests dentro de una coroutine, porque bloquean el event loop. La alternativa asíncrona por excelencia para clientes HTTP es aiohttp. En este artículo la pondremos en práctica y, más importante aún, veremos cómo coordinar cientos de peticiones concurrentes con las tres APIs que asyncio ofrece para esto: gather, as_completed y wait.

Note

Aprenderás a usar aiohttp con sesiones y connection pooling, a entender el patrón async with, y a elegir entre gather, as_completed y wait según necesites resultados ordenados, procesamiento incremental o control fino sobre la cancelación.

El Patrón `async with`: Context Managers Asíncronos

Antes de tocar aiohttp debemos entender el patrón sobre el que se construye. Un context manager síncrono se define con __enter__ y __exit__ y nos permite adquirir y liberar recursos de forma segura con with. Su equivalente asíncrono usa los métodos __aenter__ y __aexit__, y se consume con async with.

La diferencia es que estos métodos son coroutines: pueden usar await internamente para adquirir o liberar el recurso sin bloquear el event loop.

class ConnectedSocket:
 def __init__(self, server_socket):
 self._connection = None
 self._server_socket = server_socket

 async def __aenter__(self): # 1
 loop = asyncio.get_event_loop()
 connection, address = await loop.sock_accept(self._server_socket)
 self._connection = connection
 return self._connection

 async def __aexit__(self, exc_type, exc_val, exc_tb): # 2
 self._connection.close()

__aenter__ se ejecuta al entrar al bloque async with y retorna el recurso (la conexión).
__aexit__ se ejecuta al salir del bloque —incluso si hay una excepción— y libera el recurso.

Esto es relevante porque, como veremos enseguida, tanto la sesión de aiohttp como cada petición que hacemos son context managers asíncronos.

sequenceDiagram
 participant C as Código (async with)
 participant CM as Context Manager
 C->>CM: await __aenter__()
 Note over CM: adquiere el recurso (sin bloquear)
 CM-->>C: retorna el recurso
 Note over C: ejecuta el bloque async with
 C->>CM: await __aexit__()
 Note over CM: libera el recurso

aiohttp: Sesiones y Connection Pooling

aiohttp, y los clientes HTTP en general, se basan en el concepto de sesión. Una ClientSession mantiene abiertas varias conexiones que luego se reutilizan entre peticiones. Esto se conoce como connection pooling y es fundamental para el rendimiento: crear una conexión TCP es costoso, así que reutilizar un pool reduce drásticamente esa sobrecarga.

import asyncio
import aiohttp
from aiohttp import ClientSession


async def fetch_status(session: ClientSession, url: str) -> int:
 async with session.get(url) as result: # 1
 return result.status


async def main():
 async with aiohttp.ClientSession() as session: # 2
 url = 'https://example.com'
 status = await fetch_status(session, url)
 print(f'Status para {url}: {status}')


asyncio.run(main())

session.get(url) es un context manager asíncrono: dentro del bloque tenemos la respuesta; al salir, la conexión vuelve al pool.
La sesión también se gestiona con async with, garantizando que todas las conexiones se cierren correctamente al terminar.

Tip

Crea una sola ClientSession y reutilízala para todas tus peticiones. Crear una sesión por petición desperdicia el connection pooling y degrada el rendimiento.

Configurando Timeouts

Por defecto aiohttp aplica un timeout de cinco minutos a cada operación. Para la mayoría de aplicaciones ese valor es demasiado alto. Podemos ajustarlo con ClientTimeout, tanto a nivel de sesión (aplica a todas las peticiones) como a nivel de petición individual.

async def fetch_status(session: ClientSession, url: str) -> int:
 diez_millis = aiohttp.ClientTimeout(total=.01) # por petición
 async with session.get(url, timeout=diez_millis) as result:
 return result.status


async def main():
 session_timeout = aiohttp.ClientTimeout(total=1, connect=.1) # por sesión
 async with aiohttp.ClientSession(timeout=session_timeout) as session:
 await fetch_status(session, 'https://example.com')

El parámetro total limita la duración completa de la operación; connect limita solo el tiempo de establecer la conexión. El timeout de la petición tiene prioridad sobre el de la sesión.

La Trampa del `await` Secuencial

Antes de lanzar muchas peticiones, hay un error sutil que conviene evitar. Supongamos que queremos ejecutar varias coroutines y recolectar resultados con una list comprehension:

❌ Secuencial
✅ Concurrente

async def main() -> None:
 delay_times = [3, 3, 3]
 # await dentro del comprehension → espera cada task antes de crear el siguiente
 [await asyncio.create_task(delay(seconds)) for seconds in delay_times]

Tarda ~9 segundos. El await fuerza a esperar cada task antes de crear el siguiente.

async def main() -> None:
 delay_times = [3, 3, 3]
 tasks = [asyncio.create_task(delay(seconds)) for seconds in delay_times] # 1
 [await task for task in tasks] # 2

Tarda ~3 segundos. Primero se crean todos los tasks, luego se esperan.

La clave está en separar la creación de los tasks (que los pone a correr en el event loop) de la espera de sus resultados. Si haces await mientras los creas, los serializas. Esta separación es precisamente lo que las siguientes APIs resuelven por nosotros.

`gather`: Recolectar Todos los Resultados

asyncio.gather recibe una secuencia de awaitables, los ejecuta concurrentemente y, cuando hacemos await sobre él, espera a que todos terminen y retorna una lista con sus resultados. Si le pasamos coroutines, las envuelve en tasks automáticamente, así que no necesitamos llamar a create_task manualmente.

async def main():
 async with aiohttp.ClientSession() as session:
 urls = ['https://example.com' for _ in range(1000)]
 requests = [fetch_status(session, url) for url in urls]
 status_codes = await asyncio.gather(*requests) # 1
 print(status_codes)

gather ejecuta las 1000 peticiones de forma concurrente y retorna sus códigos de estado.

Una garantía importante: aunque las peticiones terminen en cualquier orden, los resultados se devuelven en el mismo orden en que pasamos los awaitables. Esto hace que gather sea ideal cuando necesitas correlacionar cada resultado con su entrada.

Manejo de Excepciones en `gather`

El comportamiento ante errores se controla con el parámetro return_exceptions:

return_exceptions=False (por defecto): si cualquier awaitable lanza una excepción, esa excepción se propaga al hacer await gather. El resto de coroutines siguen ejecutándose, pero perdemos sus resultados a menos que manejemos la excepción.
return_exceptions=True: las excepciones se devuelven como parte de la lista de resultados, junto a los valores exitosos. gather nunca lanza, y nosotros decidimos cómo tratar cada error.

results = await asyncio.gather(*requests, return_exceptions=True)

exitos = [r for r in results if not isinstance(r, Exception)]
errores = [r for r in results if isinstance(r, Exception)]

Warning

gather tiene dos limitaciones: no es fácil cancelar las peticiones restantes cuando una falla, y debemos esperar a que todas terminen antes de procesar cualquier resultado. Si una petición tarda 20 s y otra 100 ms, nos bloqueamos 20 s antes de poder usar la rápida.

`as_completed`: Procesar a Medida que Terminan

Cuando queremos reaccionar a cada resultado en cuanto está disponible, asyncio.as_completed es la herramienta. Recibe una lista de awaitables y retorna un iterador de futures. Al iterar y hacer await sobre cada uno, obtenemos los resultados en el orden en que van completándose, no en el que los pasamos.

async def main():
 async with aiohttp.ClientSession() as session:
 fetchers = [
 fetch_status(session, 'https://example.com', delay=1),
 fetch_status(session, 'https://example.com', delay=1),
 fetch_status(session, 'https://example.com', delay=10),
 ]

 for finished_task in asyncio.as_completed(fetchers):
 print(await finished_task) # se imprime apenas cada uno termina

Las dos primeras peticiones se imprimen alrededor del segundo 1, sin esperar a la de 10 segundos. Esto mejora la responsividad de la aplicación. También nos da mejor control de errores: la excepción de un task se lanza justo cuando hacemos await sobre él, permitiéndonos manejarla en el momento.

as_completed admite un timeout global. Si se excede, el await sobre los futures pendientes lanza asyncio.TimeoutError, que podemos capturar:

for done_task in asyncio.as_completed(fetchers, timeout=2):
 try:
 print(await done_task)
 except asyncio.TimeoutError:
 print('¡Timeout!')

flowchart LR
 subgraph gather["gather → espera TODO"]
 G1[req 1s] --> GW[⏳ bloquea hasta el más lento]
 G2[req 1s] --> GW
 G3[req 10s] --> GW
 GW --> GR[procesa los 3 resultados]
 end
 subgraph asc["as_completed → procesa al terminar"]
 A1[req 1s] --> AR1[procesa ~1s]
 A2[req 1s] --> AR2[procesa ~1s]
 A3[req 10s] --> AR3[procesa ~10s]
 end

La desventaja de as_completed es que no es fácil saber qué tasks ya terminaron y cuáles siguen pendientes: los recibimos uno a uno por el iterador.

`wait`: Control Fino sobre la Espera

asyncio.wait es la opción más flexible. Recibe una colección de tasks y retorna dos conjuntos: done (los que terminaron, con resultado o excepción) y pending (los que siguen corriendo). A diferencia de las otras APIs, wait no lanza excepciones automáticamente ni cancela tasks por timeout; nos da el control y la responsabilidad.

Info

Es buena práctica envolver las coroutines en create_task antes de pasarlas a wait. En versiones recientes de Python, wait espera objetos Task, no coroutines crudas.

Su comportamiento se ajusta con el parámetro return_when, que acepta tres valores:

`return_when`	`wait` retorna cuando…	Uso típico
`ALL_COMPLETED` (def.)	todos los tasks terminan	equivalente a `gather`, pero con `done`/`pending`
`FIRST_EXCEPTION`	el primero falla (o todos terminan si no hay errores)	cancelar el resto al primer error
`FIRST_COMPLETED`	el primero termina (con éxito o error)	reaccionar al más rápido y cancelar el resto

Como wait nos entrega el conjunto pending, podemos cancelar explícitamente los tasks que ya no necesitamos:

async def main():
 async with aiohttp.ClientSession() as session:
 fetchers = [
 asyncio.create_task(fetch_status(session, 'https://example.com')),
 asyncio.create_task(fetch_status(session, 'https://example.com')),
 ]

 done, pending = await asyncio.wait(
 fetchers, return_when=asyncio.FIRST_COMPLETED
 )

 print(f'Terminados: {len(done)} | Pendientes: {len(pending)}')

 for task in done:
 if task.exception() is None: # 1
 print(task.result())
 else:
 print(f'Error: {task.exception()}')

 for task in pending:
 task.cancel() # 2

Como los tasks en done ya terminaron, es seguro consultar exception() y result(). Esto evita usar await con try/except.
Cancelamos manualmente lo que quedó pendiente —algo que gather no permite hacer con facilidad.

Sobre los timeouts en wait: si pasas el parámetro timeout y se agota, wait simplemente retorna done y pending hasta ese momento, sin lanzar excepción y sin cancelar los tasks pendientes. Tú decides qué hacer con ellos.

¿Cuál Debo Usar?

Las tres APIs ejecutan awaitables concurrentemente; la elección depende de cómo necesites consumir los resultados.

flowchart TD
 Start{¿Cómo necesito
los resultados?} --> A[Todos juntos
y ordenados]
 Start --> B[Cada uno apenas
termina]
 Start --> C[Control fino:
done/pending,
cancelar el resto]

 A --> AG["asyncio.gather"]
 B --> AC["asyncio.as_completed"]
 C --> AW["asyncio.wait"]

 style AG fill:#3b82f6,stroke:#1e40af,color:#fff
 style AC fill:#f59e0b,stroke:#b45309,color:#fff
 style AW fill:#10b981,stroke:#065f46,color:#fff

gather → la opción más simple cuando quieres todos los resultados, en orden, y un único punto donde manejar el éxito o el error.
as_completed → cuando quieres procesar cada resultado en cuanto llega y mejorar la responsividad.
wait → cuando necesitas control fino: saber qué terminó y qué sigue pendiente, manejar errores sin excepciones implícitas y cancelar tasks manualmente.

En conclusión

aiohttp es el reemplazo asíncrono de requests; usa una ClientSession con connection pooling y reutilízala entre peticiones.
Tanto la sesión como cada petición son context managers asíncronos (async with), construidos sobre __aenter__/__aexit__.
Separa la creación de tasks de su espera: hacer await mientras los creas los serializa.
gather espera todo y devuelve resultados ordenados; controla errores con return_exceptions.
as_completed entrega resultados a medida que terminan, ideal para responsividad.
wait ofrece control fino con los conjuntos done/pending y los modos ALL_COMPLETED, FIRST_EXCEPTION y FIRST_COMPLETED.

Referencias

aiohttp — Documentación Oficial
Python asyncio.gather — Documentación Oficial
Python asyncio.as_completed — Documentación Oficial
Python asyncio.wait — Documentación Oficial
PEP 492 — Coroutines with async and await syntax
Matthew Fowler, Python Concurrency with asyncio (Manning, 2022)

Futures, Awaitables y Errores Comunes en asyncio

Dacadev — Wed, 13 May 2026 00:00:00 -0500

Tabla de Contenido

En los artículos anteriores aprendimos a crear coroutines con async/await y ejecutar tasks concurrentes. En este artículo vamos a cerrar el modelo mental: entenderemos qué son los futures, cómo se relacionan con tasks y coroutines a través de los awaitables, y veremos cómo medir el rendimiento de nuestro código asíncrono. Para cerrar, hablaremos de los dos errores más comunes al trabajar con asyncio.

Futures: Un Valor que Aún No Existe

Un future es un objeto de Python que representa un valor que esperamos obtener en algún momento, pero que todavía no tenemos. Cuando se crea, un future está en estado incompleto. Una vez que el valor llega, se establece con set_result y el future pasa a estar completado.

from asyncio import Future

my_future = Future()

print(f'¿Está completo? {my_future.done()}') # False

my_future.set_result(42)

print(f'¿Está completo? {my_future.done()}') # True
print(f'Resultado: {my_future.result()}') # 42

stateDiagram-v2
 [*] --> Incompleto: Future()
 Incompleto --> Completado: set_result(valor)
 Completado --> [*]: result() → valor

 note right of Incompleto
 done() → False
 result() → InvalidStateError
 end note

 note right of Completado
 done() → True
 result() → valor
 end note

Futures en la práctica

En la mayoría de los casos no crearás futures directamente — asyncio los gestiona internamente. Pero entender su mecánica es clave para comprender cómo funciona todo por dentro. Veamos un ejemplo donde un task establece el valor de un future después de un segundo:

from asyncio import Future
import asyncio


def hacer_peticion() -> Future:
 future = Future()
 asyncio.create_task(establecer_valor(future)) # 1
 return future


async def establecer_valor(future) -> None:
 await asyncio.sleep(1) # 2
 future.set_result(42)


async def main():
 future = hacer_peticion()
 print(f'¿Está completo? {future.done()}') # False
 valor = await future # 3
 print(f'¿Está completo? {future.done()}') # True
 print(valor) # 42


asyncio.run(main())

Crea un task que configurará el valor del future.
Espera 1 segundo antes de establecer el resultado.
await pausa main() hasta que el future reciba su valor.

sequenceDiagram
 participant M as main()
 participant F as Future
 participant T as task: establecer_valor()

 M->>F: hacer_peticion() → Future incompleto
 M->>T: create_task(establecer_valor(future))
 M->>F: await future
 Note over M: ⏸ PAUSE main()
 T->>T: await asyncio.sleep(1)
 Note over T: ⏳ 1 segundo...
 T->>F: set_result(42)
 Note over F: ✅ Completado
 F-->>M: ▶ RESUME main()
 Note over M: valor = 42

La Jerarquía de los Awaitables

Tanto las coroutines como los tasks pueden usarse con await. ¿Qué tienen en común? Ambos son awaitables — objetos que implementan el método __await__, que es lo que Python necesita para poder usar la palabra clave await sobre ellos.

La relación entre estos conceptos forma una jerarquía clara:

flowchart TD
 A["Awaitable\n(__await__)"] --> B["Coroutine"]
 A --> C["Future"]
 C --> D["Task"]

 style A fill:#8b5cf6,stroke:#5b21b6,color:#fff
 style B fill:#3b82f6,stroke:#1e40af,color:#fff
 style C fill:#f59e0b,stroke:#b45309,color:#fff
 style D fill:#10b981,stroke:#065f46,color:#fff

Awaitable es la clase base que define el protocolo __await__. Todo lo que se pueda usar con await es un awaitable.
Coroutine es una función definida con async def. Hereda de Awaitable.
Future representa un valor pendiente. También hereda de Awaitable.
Task hereda de Future. Es la combinación de un future y una coroutine: encapsula una coroutine y la ejecuta en el event loop, mientras que el future subyacente almacena el resultado cuando la coroutine termina.

Note

Un Future es qué esperamos obtener. Un Task es cómo lo obtenemos (ejecutando una coroutine). Y Awaitable es el contrato que ambos cumplen para que await funcione.

Midiendo el Tiempo de Ejecución

Cuando trabajamos con código asíncrono, medir cuánto tarda cada operación es esencial para verificar que la concurrencia realmente funciona. La mejor forma de hacerlo es con un decorador que registre el tiempo de inicio y fin de cada coroutine:

import functools
import time
from typing import Callable, Any


def async_timed():
 def wrapper(func: Callable) -> Callable:
 @functools.wraps(func)
 async def wrapped(*args, **kwargs) -> Any:
 print(f'starting {func} with args {args} {kwargs}')
 start = time.time()
 try:
 return await func(*args, **kwargs)
 finally:
 end = time.time()
 total = end - start
 print(f'finished {func} in {total:.4f} second(s)')

 return wrapped

 return wrapper

Uso en la práctica

import asyncio


@async_timed()
async def delay(delay_seconds: int) -> int:
 print(f'sleeping for {delay_seconds} second(s)')
 await asyncio.sleep(delay_seconds)
 print(f'finished sleeping for {delay_seconds} second(s)')
 return delay_seconds


@async_timed()
async def main():
 task_one = asyncio.create_task(delay(2))
 task_two = asyncio.create_task(delay(3))

 await task_one
 await task_two


asyncio.run(main())

starting <function main ...> with args () {}
starting <function delay ...> with args (2,) {}
starting <function delay ...> with args (3,) {}
finished <function delay ...> in 2.0032 second(s)
finished <function delay ...> in 3.0003 second(s)
finished <function main ...> in 3.0004 second(s)

El output confirma lo que esperamos: ambos tasks corren concurrentemente. delay(2) termina a los ~2 segundos, delay(3) a los ~3, y main() tarda ~3 segundos en total (no 5).

gantt
 title Ejecución concurrente verificada con @async_timed
 dateFormat X
 axisFormat %s

 section delay(2)
 sleep(2) :a1, 0, 2

 section delay(3)
 sleep(3) :b1, 0, 3

 section main()
 Tiempo total :c1, 0, 3

Errores Comunes en `asyncio`

Hay dos trampas frecuentes que pueden arruinar el rendimiento de una aplicación async. Ambas tienen la misma causa: bloquear el event loop.

1. Ejecutar código CPU-bound en coroutines

Cuando tenemos funciones computacionalmente costosas (cálculos matemáticos, procesamiento de datos grandes), puede parecer buena idea envolverlas en tasks para ejecutarlas concurrentemente. Pero recuerda: asyncio usa un solo hilo. El GIL garantiza que solo una instrucción de bytecode se ejecute a la vez, así que el código CPU-bound bloqueará el event loop sin importar cuántos tasks crees.

flowchart LR
 A["Código CPU-bound\nen una coroutine"] -->|"Bloquea el\nevent loop 🛑"| B["Otras tareas\nno pueden ejecutarse"]
 C["Solución"] --> D["multiprocessing\no run_in_executor()"]

 style A fill:#ef4444,stroke:#991b1b,color:#fff
 style B fill:#ef4444,stroke:#991b1b,color:#fff
 style D fill:#10b981,stroke:#065f46,color:#fff

2. Usar APIs bloqueantes

El mismo problema ocurre al usar librerías de I/O que no son asíncronas. Librerías como requests o funciones como time.sleep bloquean el hilo principal. Cuando las llamas dentro de una coroutine, bloqueas el event loop completo y ninguna otra coroutine puede ejecutarse.

❌ Bloqueante
✅ No bloqueante

No uses estas funciones dentro de coroutines

requests.get() → bloquea el event loop
time.sleep() → bloquea el event loop
Cualquier función de I/O síncrona

Usa las alternativas asíncronas

aiohttp → reemplazo async de requests
asyncio.sleep() → cede control al event loop
asyncpg → cliente async de PostgreSQL
aiofiles → lectura/escritura async de archivos

Warning

Regla general: cualquier función que realice I/O y no sea una coroutine, o que ejecute operaciones CPU costosas, debe considerarse bloqueante. Para CPU-bound, usa loop.run_in_executor() con un ProcessPoolExecutor.

En conclusión

Un Future representa un valor que aún no existe — se completa con set_result.
Un Task es un future + una coroutine: ejecuta la coroutine y almacena su resultado en el future subyacente.
Todo lo que se pueda usar con await es un Awaitable — el contrato que unifica coroutines, futures y tasks.
El decorador @async_timed permite verificar que la concurrencia funciona midiendo tiempos reales.
Los dos errores más comunes son ejecutar código CPU-bound y usar APIs bloqueantes dentro de coroutines — ambos bloquean el event loop.

Referencias

Coroutines y async/await: Tu Primer Código Asíncrono en Python

Dacadev — Tue, 12 May 2026 00:00:00 -0500

Tabla de Contenido

En los artículos anteriores construimos la base teórica: concurrencia vs paralelismo, procesos, hilos, el GIL y el event loop. Ahora es momento de escribir código. En este artículo vamos a aprender a crear coroutines, usar las palabras clave async y await, y entender exactamente qué pasa cuando pausamos y reanudamos la ejecución.

¿Qué es una Coroutine?

Una coroutine es como una función normal de Python, pero con un superpoder: puede pausar su ejecución cuando encuentra una operación que podría tardar (una petición de red, una lectura de disco, una espera). Mientras la coroutine está pausada, el event loop puede ejecutar otras tareas. Cuando la operación termina, la coroutine se “despierta” y continúa desde donde se detuvo.

Esta capacidad de pausar y reanudar es lo que le da concurrencia a nuestra aplicación.

Para trabajar con coroutines necesitamos dos palabras clave:

async def → define una coroutine.
await → pausa la coroutine hasta que la operación esperada termine.

Creando Coroutines

Crear una coroutine es casi idéntico a crear una función normal. La única diferencia es usar async def en lugar de def:

async def mi_coroutine() -> None:
 print('¡Hola mundo!')

Info

Llamar a una coroutine no la ejecuta. Solo produce un objeto coroutine. Para ejecutarla, necesitas un event loop.

# ❌ Esto NO ejecuta la coroutine
mi_coroutine() # Retorna un objeto coroutine, no imprime nada

# ✅ Esto SÍ la ejecuta
import asyncio
asyncio.run(mi_coroutine()) # Imprime: ¡Hola mundo!

Ejecutando Coroutines con `asyncio.run`

asyncio.run es el punto de entrada principal de cualquier aplicación asyncio. Veamos un ejemplo concreto:

import asyncio


async def sumar_uno(numero: int) -> int:
 return numero + 1


resultado = asyncio.run(sumar_uno(1))
print(resultado) # 2

asyncio.run hace varias cosas por nosotros:

Crea un event loop nuevo.
Ejecuta la coroutine que le pasamos hasta que se completa.
Retorna el resultado de la coroutine.
Limpia cualquier tarea pendiente y cierra el event loop.

flowchart LR
 A["asyncio.run(coroutine)"] --> B["Crea el\nEvent Loop"]
 B --> C["Ejecuta la\ncoroutine"]
 C --> D["Retorna\nel resultado"]
 D --> E["Cierra el\nEvent Loop"]

 style A fill:#3b82f6,stroke:#1e40af,color:#fff
 style C fill:#10b981,stroke:#065f46,color:#fff
 style E fill:#64748b,stroke:#334155,color:#fff

Info

asyncio.run está diseñado para ejecutarse una sola vez como entrada principal de tu aplicación. Esa única coroutine debería encargarse de lanzar todas las demás tareas.

Pausando la Ejecución con `await`

El verdadero poder de asyncio está en await. Esta palabra clave hace dos cosas:

Ejecuta la coroutine que le sigue (a diferencia de llamarla directamente, que solo crea el objeto).
Pausa la coroutine contenedora hasta que la coroutine esperada retorne un resultado.

Cuando la coroutine esperada termina, la coroutine contenedora se “despierta” y puede usar el resultado.

import asyncio


async def obtener_saludo() -> str:
 return '¡Hola desde una coroutine!'


async def main() -> None:
 saludo = await obtener_saludo() # Pausa main() hasta obtener el resultado
 print(saludo)


asyncio.run(main())

Simulando Operaciones Largas con `asyncio.sleep`

Para simular una operación de I/O de larga duración (como una petición HTTP o una consulta a base de datos), podemos usar asyncio.sleep. Esta función pausa la coroutine por el número de segundos indicado, cediendo el control al event loop.

Veamos un ejemplo más completo con una función auxiliar delay:

import asyncio


async def delay(seconds: int) -> str:
 print(f'Esperando {seconds} segundo(s)...')
 await asyncio.sleep(seconds)
 print(f'¡Espera de {seconds} segundo(s) completada!')
 return f'Esperé {seconds} segundo(s)'

La Trampa del `await` Secuencial

Ahora veamos un error muy común al empezar con asyncio. Considera este código:

import asyncio


async def sumar_uno(numero: int) -> int:
 return numero + 1


async def mensaje_hola_mundo() -> str:
 await asyncio.sleep(1)
 return '¡Hola Mundo!'


async def main() -> None:
 mensaje = await mensaje_hola_mundo() # Pausa 1 segundo
 uno_mas_uno = await sumar_uno(1) # Ejecuta después de la pausa
 print(uno_mas_uno)
 print(mensaje)


asyncio.run(main())

Cuando ejecutamos este código, pasa 1 segundo antes de que se impriman ambos resultados. Pero sumar_uno(1) es instantánea — ¿por qué espera?

Warning

await pausa toda la coroutine contenedora. No se ejecuta ningún otro código dentro de main() hasta que la expresión await retorne un valor. Como mensaje_hola_mundo() tarda 1 segundo, main() queda pausada ese segundo completo antes de siquiera llegar a sumar_uno(1).

El siguiente diagrama muestra exactamente qué pasa en cada momento:

sequenceDiagram
 participant EL as Event Loop
 participant M as main()
 participant HW as mensaje_hola_mundo()
 participant AO as sumar_uno(1)

 EL->>M: ▶ RUN main()
 Note over M: await mensaje_hola_mundo()
 M->>HW: ▶ RUN mensaje_hola_mundo()
 HW->>HW: await sleep(1)
 Note over M: ⏸ PAUSE main()
 Note over HW: ⏸ PAUSE mensaje_hola_mundo()
 Note over EL: ⏳ Pasa 1 segundo...
 EL->>HW: ▶ RESUME mensaje_hola_mundo()
 Note over HW: return '¡Hola Mundo!'
 HW-->>M: ▶ RESUME main()
 Note over M: mensaje = '¡Hola Mundo!'
 Note over M: await sumar_uno(1)
 M->>AO: ▶ RUN sumar_uno(1)
 Note over AO: return 1 + 1
 AO-->>M: ▶ RESUME main()
 Note over M: uno_mas_uno = 2
 Note over M: print() resultados

El problema visualizado

El flujo de ejecución es completamente secuencial, a pesar de usar async/await:

gantt
 title Ejecución secuencial — Sin concurrencia real
 dateFormat X
 axisFormat %s

 section main()
 await mensaje_hola_mundo() :a1, 0, 10
 await sumar_uno(1) :a2, 10, 11
 print() resultados :a3, 11, 12

Lo que queremos es que sumar_uno(1) se ejecute mientras mensaje_hola_mundo() espera su segundo de delay. Pero con await secuencial eso no es posible — cada await bloquea la coroutine hasta completarse.

¿Cómo logramos concurrencia real?

Para ejecutar múltiples coroutines de forma concurrente necesitamos herramientas como asyncio.gather o asyncio.create_task. Un adelanto rápido:

async def main() -> None:
 # ✅ Ambas coroutines corren concurrentemente
 mensaje, uno_mas_uno = await asyncio.gather(
 mensaje_hola_mundo(),
 sumar_uno(1)
 )
 print(uno_mas_uno)
 print(mensaje)

Con gather, el event loop puede ejecutar sumar_uno(1) mientras mensaje_hola_mundo() está pausada esperando su sleep. El tiempo total se mantiene en ~1 segundo en lugar de sumar ambos tiempos.

gantt
 title Ejecución concurrente — Con asyncio.gather
 dateFormat X
 axisFormat %s

 section mensaje_hola_mundo()
 await sleep(1) :a1, 0, 10

 section sumar_uno(1)
 return 1 + 1 :a2, 0, 1

 section main()
 print() resultados :a3, 10, 11

En conclusión

flowchart TD
 A["async def"] -->|"Define"| B["Coroutine"]
 B -->|"Se ejecuta con"| C["asyncio.run()"]
 B -->|"Se pausa con"| D["await"]
 D -->|"Cede control al"| E["Event Loop"]
 E -->|"Cuando I/O completa"| F["Reanuda la coroutine"]
 C -->|"Crea y gestiona"| E

 style A fill:#8b5cf6,stroke:#5b21b6,color:#fff
 style B fill:#3b82f6,stroke:#1e40af,color:#fff
 style D fill:#f59e0b,stroke:#b45309,color:#fff
 style E fill:#10b981,stroke:#065f46,color:#fff

async def define una coroutine — una función que puede pausarse.
await pausa la coroutine actual hasta que la operación esperada termine.
asyncio.run crea el event loop y ejecuta la coroutine principal.
asyncio.sleep simula operaciones de I/O de larga duración.
Usar await de forma secuencial no da concurrencia — para eso necesitamos asyncio.gather o asyncio.create_task.

Referencias

asyncio: Cómo Funcionan los Procesos, Hilos y el Event Loop

Dacadev — Mon, 11 May 2026 00:00:00 -0500

Tabla de Contenido

En el artículo anterior construimos un modelo mental sobre concurrencia, paralelismo y los tipos de multitarea. Ahora vamos a bajar un nivel: entender qué son los procesos y los hilos, por qué el GIL de Python cambia las reglas del juego, y cómo asyncio logra concurrencia con un solo hilo gracias al event loop.

Procesos e Hilos

¿Qué es un proceso?

Un proceso es una instancia de una aplicación en ejecución. Cada proceso tiene su propio espacio de memoria aislado — ningún otro proceso puede acceder a él directamente — y se ejecuta en un CPU o núcleo del sistema.

¿Qué es un hilo (thread)?

Un hilo es una unidad de ejecución más ligera que vive dentro de un proceso. A diferencia de los procesos, los hilos no tienen su propia memoria: comparten el espacio de memoria del proceso que los creó.

Todo proceso tiene al menos un hilo asociado, conocido como el hilo principal (main thread). Además, un proceso puede crear hilos adicionales, comúnmente llamados hilos de trabajo (worker threads) o hilos en segundo plano (background threads).

flowchart TB
 subgraph P1["Proceso (PID: 1234)"]
 direction TB
 M1["Memoria del proceso"]
 MT["Hilo principal\n(main thread)"]
 W1["Worker thread 1"]
 W2["Worker thread 2"]
 M1 <--> MT
 M1 <--> W1
 M1 <--> W2
 end

 style P1 fill:transparent,stroke:#64748b
 style M1 fill:#3b82f6,stroke:#1e40af,color:#fff
 style MT fill:#10b981,stroke:#065f46,color:#fff
 style W1 fill:#f59e0b,stroke:#b45309,color:#fff
 style W2 fill:#f59e0b,stroke:#b45309,color:#fff

Info

Todos los hilos dentro de un proceso comparten la misma memoria. Esto hace la comunicación entre hilos muy rápida, pero introduce el riesgo de condiciones de carrera si no se maneja con cuidado.

Verificándolo en Python

Puedes inspeccionar el proceso e hilo actual con los módulos os y threading:

import os
import threading

print(f'Proceso de Python con PID: {os.getpid()}')
total_threads = threading.active_count()
thread_name = threading.current_thread().name

print(f'Python está ejecutando {total_threads} hilo(s)')
print(f'El hilo actual es: {thread_name}')

# Output esperado
Proceso de Python con PID: 48672
Python está ejecutando 1 hilo(s)
El hilo actual es: MainThread

Por defecto, tu programa Python corre en un solo hilo (MainThread) dentro de un solo proceso.

El Global Interpreter Lock (GIL)

El GIL (Global Interpreter Lock) es uno de los temas más debatidos en la comunidad Python. En términos simples: el GIL impide que un proceso de Python ejecute más de una instrucción de bytecode a la vez, incluso si tienes múltiples hilos.

Esto significa que aunque crees varios hilos con threading, solo uno ejecuta código Python en cualquier instante.

sequenceDiagram
 participant GIL
 participant T1 as Hilo 1
 participant T2 as Hilo 2

 GIL->>T1: 🔓 GIL adquirido
 activate T1
 T1->>T1: Ejecuta bytecode
 T1->>GIL: 🔒 Libera GIL
 deactivate T1
 GIL->>T2: 🔓 GIL adquirido
 activate T2
 T2->>T2: Ejecuta bytecode
 T2->>GIL: 🔒 Libera GIL
 deactivate T2
 GIL->>T1: 🔓 GIL adquirido
 activate T1
 T1->>T1: Ejecuta bytecode
 deactivate T1

¿El GIL se libera alguna vez?

Sí. El GIL se libera durante las operaciones de I/O. Cuando un hilo hace una petición de red o una lectura de disco, libera el GIL, permitiendo que otro hilo tome el control y ejecute código Python mientras tanto.

Esto es lo que hace que threading sea útil para trabajo I/O-bound, pero ineficaz para trabajo CPU-bound.

flowchart LR
 A["Operación\nCPU-bound"] -->|"GIL retenido 🔒"| B["Solo 1 hilo\nejecuta a la vez"]
 C["Operación\nI/O-bound"] -->|"GIL liberado 🔓"| D["Otros hilos pueden\nejecutar código"]

 style A fill:#ef4444,stroke:#991b1b,color:#fff
 style B fill:#ef4444,stroke:#991b1b,color:#fff
 style C fill:#10b981,stroke:#065f46,color:#fff
 style D fill:#10b981,stroke:#065f46,color:#fff

`asyncio` y el GIL

asyncio aprovecha exactamente este comportamiento: como las operaciones de I/O liberan el GIL, puede lograr concurrencia con un solo hilo. En lugar de crear múltiples hilos, asyncio crea objetos llamados coroutines — que puedes pensar como hilos ultra-ligeros.

Note

Mientras una coroutine espera por una operación de I/O, el event loop ejecuta otras coroutines que estén listas. El resultado: concurrencia sin los problemas de sincronización del multithreading.

Concurrencia de Un Solo Hilo

La concurrencia de un solo hilo no se basa en hacer dos cosas simultáneamente (eso sería paralelismo), sino en aprovechar los tiempos de espera de las operaciones de I/O para ejecutar otras tareas. El mecanismo se apoya en tres pilares:

Sockets no bloqueantes
Delegación al SO
Event Loop

1. Sockets no bloqueantes

A diferencia de un socket estándar que detiene el programa hasta recibir una respuesta, un socket no bloqueante permite enviar una petición y devolver el control al programa inmediatamente, sin esperar el resultado.

2. Delegación al sistema operativo

Cuando el código llega a una operación de red o lectura de disco, Python le delega la espera al sistema operativo. El hilo de ejecución queda libre de inmediato.

3. El Event Loop como coordinador

Mientras el SO vigila los sockets, el hilo de Python sigue ejecutando otras tareas. Cuando el SO detecta que los datos llegaron, envía una notificación. El event loop recibe este aviso y “despierta” la tarea pausada para que procese la respuesta.

El siguiente diagrama de secuencia muestra cómo interactúan estos tres pilares:

sequenceDiagram
 participant MT as Main Thread
 participant EL as Event Loop
 participant OS as Sistema Operativo
 participant S1 as Socket 1
 participant S2 as Socket 2

 MT->>EL: Envía tareas
 EL->>EL: Ejecuta tarea 1 hasta I/O
 EL->>OS: Registra Socket 1 para monitoreo
 OS->>S1: Vigila socket
 EL->>EL: Ejecuta tarea 2 hasta I/O
 EL->>OS: Registra Socket 2 para monitoreo
 OS->>S2: Vigila socket
 S1-->>OS: Datos listos ✅
 OS-->>EL: Notifica Socket 1
 EL->>EL: Reanuda tarea 1
 S2-->>OS: Datos listos ✅
 OS-->>EL: Notifica Socket 2
 EL->>EL: Reanuda tarea 2

Cómo Funciona el Event Loop

En su forma más básica, un event loop es simplemente un bucle infinito que procesa mensajes de una cola, uno a la vez:

from collections import deque

messages = deque()

while True:
 if messages:
 message = messages.pop()
 process_message(message)

En asyncio, el event loop mantiene una cola de tasks (tareas) en lugar de mensajes simples. Cada task es un wrapper alrededor de una coroutine. Cuando una coroutine alcanza una operación de I/O, se pausa y le devuelve el control al event loop, que puede ejecutar otras tareas que no estén esperando I/O.

flowchart TD
 A["Event Loop inicia"] --> B["¿Hay tareas en la cola?"]
 B -->|Sí| C["Tomar siguiente tarea"]
 C --> D{"¿La tarea tiene\nI/O pendiente?"}
 D -->|No| E["Ejecutar hasta\nel próximo await"]
 E --> F{"¿La tarea alcanzó\nuna operación I/O?"}
 F -->|Sí| G["Pausar tarea y registrar\nsocket en el SO"]
 F -->|No| H["Tarea completada ✅\nRemover de la cola"]
 G --> B
 H --> B
 D -->|Sí, datos listos| I["Reanudar tarea"]
 I --> F
 D -->|Sí, esperando aún| B
 B -->|No| J["Esperar notificaciones\ndel SO"]
 J --> B

 style A fill:#3b82f6,stroke:#1e40af,color:#fff
 style H fill:#10b981,stroke:#065f46,color:#fff

Note

Este ciclo se repite indefinidamente hasta que todas las tareas se completan o el programa se cierra explícitamente. Si una coroutine ejecuta trabajo CPU-bound sin ceder control con await, bloqueará todo el event loop y ninguna otra tarea podrá avanzar.

En conclusión

Un proceso tiene memoria aislada; un hilo comparte memoria dentro de su proceso.
El GIL impide paralelismo real con hilos en Python, pero se libera durante operaciones de I/O.
asyncio aprovecha esta liberación del GIL para lograr concurrencia en un solo hilo mediante coroutines.
El event loop coordina las tareas: ejecuta coroutines hasta que alcanzan un await, las pausa, y reanuda otras que ya tengan datos listos.
Los sockets no bloqueantes y la delegación al SO son los mecanismos que permiten esta concurrencia sin crear múltiples hilos.

Referencias

asyncio: Los Fundamentos de la Programación Asíncrona en Python

Dacadev — Sun, 10 May 2026 00:00:00 -0500

Tabla de Contenido

Si alguna vez construiste un scraper que recorre decenas de páginas, un microservicio que atiende cientos de peticiones o un bot que consume múltiples APIs, seguro sentiste la frustración de esperar. Una petición termina, la siguiente arranca, y tu programa queda ahí sin hacer nada útil.

La librería asyncio de Python fue diseñada para resolver exactamente este problema. En este artículo vamos a construir un modelo mental sólido sobre los conceptos clave: concurrencia, paralelismo, multitarea y la diferencia entre operaciones limitadas por CPU y por E/S.

¿Qué es la programación asíncrona?

La programación asíncrona es un modelo donde las tareas de larga duración se ejecutan en segundo plano, separadas del flujo principal de tu aplicación. En lugar de bloquear todo mientras esperas una respuesta de red o una lectura de archivo, el sistema queda libre para hacer otro trabajo. Cuando la tarea termina, tu código recibe una notificación y puede procesar el resultado.

Note

asyncio — abreviación de asynchronous I/O — es la librería estándar de Python que implementa este modelo. Fue introducida en Python 3.4 y hoy es la base de frameworks modernos como FastAPI, aiohttp y Starlette.

CPU-bound vs. I/O-bound

Antes de avanzar, necesitas entender una distinción fundamental: ¿en qué está gastando tiempo tu código?

Operaciones limitadas por E/S (I/O-bound)

Tu programa pasa la mayor parte del tiempo esperando un sistema externo: la red, el disco, una base de datos. La CPU está prácticamente ociosa. Ejemplos:

Hacer peticiones HTTP.
Leer o escribir archivos en disco.
Consultar una base de datos.

Operaciones limitadas por CPU (CPU-bound)

El procesador es el cuello de botella. La CPU está activamente calculando, sin esperas externas. Ejemplos:

Calcular dígitos de pi.
Aplicar lógica de negocio sobre estructuras de datos grandes.
Procesamiento de imágenes o entrenamiento de modelos.

Ejemplo práctico

Considera este fragmento de código:

import requests

response = requests.get('https://www.example.com') # 1 - I/O-bound
items = response.headers.items()
headers = [f'{key}: {header}' for key, header in items] # 2 - CPU-bound

formatted_headers = '\n'.join(headers) # 3 - CPU-bound

with open('headers.txt', 'w') as file:
 file.write(formatted_headers) # 4 - I/O-bound

El siguiente diagrama muestra el flujo de ejecución y clasifica cada paso:

flowchart LR
 A["1. requests.get()"] -->|respuesta| B["2. List comprehension"]
 B --> C["3. join() headers"]
 C --> D["4. file.write()"]

 style A fill:#3b82f6,stroke:#1e40af,color:#fff
 style B fill:#f59e0b,stroke:#b45309,color:#fff
 style C fill:#f59e0b,stroke:#b45309,color:#fff
 style D fill:#3b82f6,stroke:#1e40af,color:#fff

🔵 Azul = I/O-bound (esperando red o disco) · 🟡 Amarillo = CPU-bound (procesando en memoria)

Info

asyncio brilla con cargas I/O-bound. Si tu cuello de botella es la CPU, necesitarás multiprocessing o concurrent.futures.

Concurrencia vs. Paralelismo

Estos dos términos se confunden constantemente, pero describen cosas distintas.

Concurrencia: alternar entre tareas

Concurrencia significa gestionar múltiples tareas en períodos de tiempo superpuestos, sin necesidad de ejecutarlas en el mismo instante. Piensa en un chef preparando dos platos: pica verduras para el plato A, lo mete al horno y empieza a trabajar en el plato B mientras el A se cocina. Solo hace una cosa a la vez, pero ambos platos avanzan.

En un sistema concurrente, una sola CPU alterna entre tareas. Mientras la tarea #1 espera por E/S, la CPU toma la tarea #2.

gantt
 title Concurrencia — Una sola CPU alternando entre tareas
 dateFormat X
 axisFormat %s

 section CPU
 App #1 :a1, 0, 2
 App #2 :a2, 2, 4
 App #1 :a3, 4, 6
 App #2 :a4, 6, 8
 App #1 :a5, 8, 10

Paralelismo: ejecución simultánea real

Paralelismo significa ejecutar múltiples tareas al mismo tiempo, lo cual requiere múltiples CPUs o núcleos.

gantt
 title Paralelismo — Múltiples CPUs ejecutando simultáneamente
 dateFormat X
 axisFormat %s

 section CPU 1
 App #1 :a1, 0, 10

 section CPU 2
 App #2 :b1, 0, 10

En palabras de Rob Pike (co-creador de Go): “La concurrencia se trata de lidiar con muchas cosas a la vez. El paralelismo se trata de hacer muchas cosas a la vez.”

Note

La concurrencia es un patrón de diseño; el paralelismo es un modelo de ejecución. asyncio logra concurrencia en un solo hilo, sin paralelismo.

Tipos de Multitarea

Existen dos enfoques principales para la multitarea, y entender la diferencia es clave para comprender dónde encaja asyncio.

Multitarea preventiva (Preemptive)

El sistema operativo decide cuándo cambiar entre tareas mediante un mecanismo llamado time slicing: divide el tiempo de CPU en intervalos pequeños y rota entre las tareas activas. Cuando el SO fuerza un cambio, se dice que está haciendo preemption.

En Python, este es el modelo que usan los módulos threading (hilos) y multiprocessing (procesos). La ventaja es que no tienes que pensar en cuándo ceder el control. La desventaja: los cambios pueden ocurrir en cualquier momento, lo que introduce condiciones de carrera y la necesidad de locks.

Multitarea cooperativa (Cooperative)

Las propias tareas deciden cuándo ceder el control. Cada tarea señala explícitamente: “Me pauso aquí, ejecuta otras tareas.” No hay intervención del SO.

Este es exactamente el modelo de asyncio. En Python, la palabra clave await es esa señal explícita:

import asyncio

async def obtener_datos():
 print("Obteniendo datos...")
 await asyncio.sleep(2) # 👈 "Me pauso aquí, ejecuta otras tareas"
 print("Datos obtenidos!")

async def procesar_datos():
 print("Procesando datos...")
 await asyncio.sleep(1) # 👈 Misma señal
 print("Datos procesados!")

async def main():
 await asyncio.gather(obtener_datos(), procesar_datos())

asyncio.run(main())

La ventaja es la predictibilidad: tú controlas exactamente dónde ocurren los cambios. El riesgo: si una tarea olvida hacer await o ejecuta una operación CPU-bound larga sin ceder control, bloquea todo el event loop.

El siguiente diagrama de secuencia ilustra cómo el event loop coordina las tareas cooperativamente:

sequenceDiagram
 participant EL as Event Loop
 participant T1 as obtener_datos()
 participant T2 as procesar_datos()

 EL->>T1: Ejecutar
 T1->>EL: await sleep(2) — cede control
 EL->>T2: Ejecutar
 T2->>EL: await sleep(1) — cede control
 EL->>T2: sleep completado — reanudar
 T2->>EL: Finalizada ✅
 EL->>T1: sleep completado — reanudar
 T1->>EL: Finalizada ✅

Comparación rápida

Preventiva
Cooperativa

Multitarea Preventiva

¿Quién cambia? El Sistema Operativo
Mecanismo: Time slicing
Herramientas en Python: threading, multiprocessing
Riesgo principal: Condiciones de carrera
Ideal para: Cargas CPU-bound o mixtas

Multitarea Cooperativa

¿Quién cambia? La propia tarea
Mecanismo: await / yield
Herramientas en Python: asyncio
Riesgo principal: Bloquear el event loop
Ideal para: Cargas I/O-bound

¿Dónde encaja `asyncio`?

Con todos estos conceptos claros, el siguiente diagrama te ayuda a decidir qué herramienta usar según tu caso:

flowchart TD
 A["¿Qué tipo de operación\nnecesitas optimizar?"] --> B{"¿Es I/O-bound?"}
 B -->|Sí| C{"¿Necesitas manejar\nmuchas conexiones?"}
 C -->|Sí| D["✅ asyncio"]
 C -->|No| E["threading o\nasyncio"]
 B -->|No| F{"¿Es CPU-bound?"}
 F -->|Sí| G{"¿Necesitas compartir\nmemoria entre tareas?"}
 G -->|Sí| H["threading\n+ locks"]
 G -->|No| I["multiprocessing"]
 F -->|Mixto| J["asyncio +\nrun_in_executor()"]

 style D fill:#10b981,stroke:#065f46,color:#fff
 style E fill:#10b981,stroke:#065f46,color:#fff
 style H fill:#f59e0b,stroke:#b45309,color:#fff
 style I fill:#3b82f6,stroke:#1e40af,color:#fff
 style J fill:#8b5cf6,stroke:#5b21b6,color:#fff

En conclusión

asyncio ofrece concurrencia, no paralelismo — todo corre en un solo hilo.
Usa multitarea cooperativa — tu código cede control explícitamente con await.
Destaca en cargas I/O-bound — peticiones de red, operaciones de archivo, consultas a bases de datos.
No es la solución para trabajo CPU-bound — para eso, combínalo con multiprocessing o usa loop.run_in_executor().

Referencias

Tipado en Python: Estructuras de datos

Dacadev — Tue, 13 Aug 2024 00:00:00 -0500

Tabla de Contenido

Cuando una función recibe datos de un producto, un usuario o una respuesta de una API, el problema no suele ser solamente el tipo de cada valor, sino la forma completa del objeto. Las estructuras de datos tipadas en Python nos permiten documentar y validar mejor esa forma: qué claves existen, cuáles son opcionales y cuándo conviene pasar de un diccionario a una estructura con comportamiento propio.

Note

Este artículo es parte de una serie que explica el tipado en Python. A continuación, puedes ver la recopilación de todos los posts de la serie.

Ver serie

En artículos anteriores vimos cómo agregar tipos a variables, colecciones y funciones. Ahora vamos a llevar esa idea a estructuras que representan datos con significado dentro de una aplicación: productos, órdenes, usuarios, configuraciones o payloads de entrada/salida.

Diccionarios tipados en Python

Los diccionarios son una de las formas más comunes de representar datos en Python. Nos permiten asociar llaves con valores, y esas llaves deben ser objetos hashables, normalmente str, int o tuplas inmutables.

Para agregar tipado a un diccionario podemos usar dict[<tipo_llave>, <tipo_valor>]:

product: dict[str, str | int] = {
 "name": "Camisa",
 "price": 20,
}

En este ejemplo estamos indicando que las llaves son str y que los valores pueden ser str o int. Esto ayuda a evitar errores como usar una llave de tipo incorrecto o asignar un valor fuera del rango esperado.

Sin embargo, esta aproximación tiene una limitación importante: no transmite qué claves se esperan dentro del diccionario. El analizador estático sabe que puede existir cualquier llave str, pero no sabe que esperamos exactamente name y price.

product: dict[str, str | int] = {
 "name": "Camisa",
 "price": 20,
}

product["name"] # ✅ válido
product["category"] # ✅ también parece válido para el type checker

El segundo acceso puede fallar en tiempo de ejecución con un KeyError, pero el tipo dict[str, str | int] no expresa que category no hace parte del contrato de esa estructura.

Info

Un diccionario tipado con dict[str, ...] es útil cuando trabajas con pares clave-valor homogéneos o dinámicos. Cuando necesitas describir una forma específica de datos, conviene usar TypedDict.

TypedDict: diccionarios con forma definida

TypedDict, disponible desde el módulo typing, nos permite definir un diccionario con claves conocidas y valores tipados. Es especialmente útil para payloads JSON, respuestas de APIs o datos que siguen siendo diccionarios, pero tienen una estructura clara.

from typing import TypedDict


class Product(TypedDict):
 name: str
 price: int
 tags: list[str]
 active: bool


product: Product = {
 "name": "Camisa",
 "price": 20,
 "tags": ["ropa"],
 "active": True,
}

Con esta definición, el type checker entiende que Product debe tener las claves name, price, tags y active, y que cada una espera un tipo específico.

Es importante recordar que TypedDict no cambia el comportamiento del diccionario en tiempo de ejecución. Seguimos trabajando con un dict, no con una clase tradicional.

product["name"] # ✅ funciona
product.name # ❌ no funciona

TypedDict mejora la información disponible para herramientas como editores, linters y analizadores estáticos. Pero el acceso sigue siendo por llave, igual que en cualquier diccionario.

Warning

No uses TypedDict esperando validación automática en tiempo de ejecución. Su objetivo principal es mejorar el tipado estático y la documentación del contrato de datos.

Llaves opcionales con NotRequired

En muchos casos una estructura tiene campos obligatorios y campos opcionales. Por ejemplo, un producto puede requerir name, price y active, pero permitir que tags no exista.

Para ese caso podemos usar NotRequired:

from typing import NotRequired, TypedDict


class Product(TypedDict):
 name: str
 price: int
 tags: NotRequired[list[str]]
 active: bool


product_without_tags: Product = {
 "name": "Camisa",
 "price": 20,
 "active": True,
}

La clave tags ahora puede omitirse. Esto es diferente a decir que tags puede ser None. Con NotRequired[list[str]], la llave completa puede no existir.

class Product(TypedDict):
 name: str
 tags: NotRequired[list[str]]


product: Product = {"name": "Camisa"}

product.get("tags") # ✅ acceso seguro si la llave puede no existir
product["tags"] # ⚠️ puede lanzar KeyError en tiempo de ejecución

Tip

Si una llave es opcional, usa get() o valida su existencia antes de acceder con []. El tipado te ayuda a diseñar el contrato, pero no elimina los errores de acceso en tiempo de ejecución.

Enfoque inverso: total=False y Required

También podemos definir el caso contrario: que todas las llaves sean opcionales por defecto y marcar únicamente algunas como obligatorias. Para ello usamos total=False junto con Required.

from typing import Required, TypedDict


class Product(TypedDict, total=False):
 name: Required[str]
 price: Required[int]
 tags: list[str]
 active: bool


product: Product = {
 "name": "Camisa",
 "price": 20,
}

Aquí name y price son obligatorias, mientras que tags y active pueden omitirse. Este enfoque es útil cuando la mayoría de campos son opcionales y solo necesitas destacar unos pocos como requeridos.

La decisión entre NotRequired y total=False + Required depende de la forma dominante de tu estructura:

Usa NotRequired cuando la mayoría de campos son obligatorios.
Usa total=False + Required cuando la mayoría de campos son opcionales.

Dataclass: estructuras de datos con atributos

Una dataclass es una clase diseñada para almacenar datos con menos código repetitivo. Python agregó este decorador en la versión 3.7, y desde entonces se convirtió en una herramienta muy práctica para modelar objetos de datos.

from dataclasses import dataclass


@dataclass
class Product:
 name: str
 price: int
 active: bool
 tags: list[str]


product = Product(name="Camisa", price=20, active=True, tags=["ropa"])

print(product.name)
print(product.price)

A diferencia de TypedDict, aquí sí accedemos a los datos como atributos: product.name, product.price, product.tags. Además, dataclass genera automáticamente métodos como __init__, __repr__ y __eq__, lo que reduce la cantidad de código necesario.

product_1 = Product(name="Camisa", price=20, active=True, tags=["ropa"])
product_2 = Product(name="Camisa", price=20, active=True, tags=["ropa"])

print(product_1 == product_2) # True
print(product_1) # Product(name='Camisa', price=20, active=True, tags=['ropa'])

Info

dataclass sigue siendo una clase de Python. El decorador solo genera código común por ti, sin impedir que agregues métodos, validaciones o comportamiento adicional cuando lo necesites.

Dataclass vs class tradicional

Podemos escribir una clase tradicional para representar el mismo producto:

class Product:
 def __init__(
 self,
 name: str,
 price: int,
 active: bool,
 tags: list[str],
 ) -> None:
 self.name = name
 self.price = price
 self.active = active
 self.tags = tags

El código funciona, pero gran parte de la implementación es repetitiva. Solo estamos recibiendo argumentos y asignándolos como atributos. Con dataclass, expresamos la misma estructura de forma más directa:

from dataclasses import dataclass


@dataclass
class Product:
 name: str
 price: int
 active: bool
 tags: list[str]

La diferencia no es solamente estética. dataclass comunica intención: esta clase existe principalmente para alojar datos. Además, mantiene una buena integración con type hints y reduce el riesgo de inconsistencias entre los argumentos de __init__ y los atributos reales.

También puedes agregar comportamiento cuando haga falta:

from dataclasses import dataclass


@dataclass
class Product:
 name: str
 price: int
 active: bool
 tags: list[str]

 def has_tag(self, tag: str) -> bool:
 return tag in self.tags


product = Product(name="Camisa", price=20, active=True, tags=["ropa"])

print(product.has_tag("ropa")) # True

Tip

Si tu clase solo define __init__, __repr__ o comparaciones básicas para alojar datos, probablemente una dataclass expresa mejor la intención.

Cuándo usar cada estructura de datos

No existe una única estructura correcta para todos los casos. La decisión depende de si estás modelando datos dinámicos, contratos de intercambio o entidades con comportamiento.

flowchart TD
 A[Necesitas representar datos con estructura] --> B{¿Debe seguir siendo un dict?}
 B -- Sí --> C{¿Conoces las claves esperadas?}
 C -- No --> D["Usa dict[str, tipo]"]
 C -- Sí --> E[Usa TypedDict]
 B -- No --> F{¿Principalmente almacena datos?}
 F -- Sí --> G[Usa dataclass]
 F -- No --> H[Usa class tradicional]

Como regla práctica:

dict[str, tipo]: úsalo cuando las claves son dinámicas o la estructura es homogénea. Por ejemplo, contadores, mapas de configuración simples o agrupaciones donde todas las llaves comparten el mismo tipo de valor.
TypedDict: úsalo cuando necesitas conservar el comportamiento de diccionario, pero quieres describir claves específicas. Es una buena opción para JSON, payloads de APIs y datos serializables.
dataclass: úsala cuando quieres representar datos con atributos, comparación automática y una intención clara de modelo de datos. Funciona muy bien para capas internas de dominio o estructuras intermedias.
class tradicional: úsala cuando el objeto necesita controlar invariantes complejas, encapsular estado mutable o exponer comportamiento más importante que los datos que almacena.

La frontera entre dataclass y class tradicional no es rígida. Una dataclass puede tener métodos, y una clase tradicional puede almacenar datos. La clave está en comunicar intención y evitar código accidentalmente complejo.

Warning

No conviertas todo diccionario en dataclass ni todo objeto en TypedDict. Elige la estructura según el contrato que quieres expresar y el comportamiento que necesitas en el sistema.

Cierre

Las estructuras de datos tipadas en Python nos ayudan a hacer explícitos los contratos que antes quedaban implícitos en diccionarios o clases repetitivas. dict[str, ...] funciona para casos homogéneos, TypedDict describe diccionarios con forma específica, NotRequired y Required permiten modelar campos opcionales, y dataclass reduce el código necesario para representar datos con atributos.

Lo importante es usar el tipado como una herramienta de diseño. Cuando la estructura comunica intención, el código se vuelve más fácil de leer, refactorizar y validar antes de llegar a producción.

Note

Esta es la pieza final de la serie hasta el momento. Puedes volver a la recopilación completa para repasar los conceptos anteriores sobre tipado en Python.

Ver serie

Tipado en Python: Tipado de clases

Dacadev — Mon, 12 Aug 2024 00:00:00 -0500

Tabla de Contenido

Cuando un proyecto empieza a tener modelos de dominio, servicios y objetos que se pasan entre capas, el tipado de clases en Python se vuelve una herramienta clave para mantener contratos claros. Ya no se trata solo de saber si una variable es str o int; también necesitamos expresar que un método recibe un User, que un atributo guarda un datetime, o que una operación entre contadores devuelve otro contador compatible.

Note

Este artículo es parte de una serie que explica el tipado en Python. A continuación, puedes ver la recopilación de todos los posts de la serie.

Ver serie

En esta entrega nos concentraremos en clases: cómo usarlas como tipos, cómo declarar atributos de instancia, cuándo aplicar ClassVar, y cómo resolver referencias hacia la propia clase con strings, from __future__ import annotations y typing.Self.

Usar clases como tipos en Python

En Python, una clase también puede usarse como anotación de tipo. Esto aplica tanto para clases que tú defines como para clases de la librería estándar. Por ejemplo, el módulo datetime define tipos como date, datetime y timedelta, mientras que uuid define UUID.

import datetime
import uuid

birth_date: datetime.date = datetime.date(2020, 2, 7)
timestamp: datetime.datetime = datetime.datetime(2020, 2, 7, 10, 0)
duration: datetime.timedelta = datetime.timedelta(hours=1)

uid1: uuid.UUID = uuid.uuid1()
uid4: uuid.UUID = uuid.uuid4()

Este código no cambia el comportamiento en tiempo de ejecución. Su valor está en la señal que le entregamos al IDE, al analizador estático y a otros desarrolladores que lean el código.

import datetime

created_at: datetime.datetime = datetime.datetime.now() # ✅
created_at = "2024-08-12" # ❌ el contrato dejó de ser datetime.datetime

Info

Las anotaciones no reemplazan la validación de datos externos. Si recibes JSON, entrada de usuario o información desde una API, sigue siendo necesario validar en los bordes del sistema.

Tipar atributos de instancia en la clase

Cuando trabajamos con clases propias, podemos declarar los atributos esperados directamente en el cuerpo de la clase. Esto ayuda a que el analizador entienda qué atributos existen en cada instancia, incluso si se asignan dentro de __init__.

class Counter:
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

En este ejemplo, n: int describe un atributo de instancia. Cada objeto Counter tendrá su propio valor de n, asignado en el constructor.

counter = Counter(start=10)
print(counter.n) # ✅ 10
print(repr(counter)) # ✅ "10"

counter.n = "10" # ❌ rompe el contrato declarado para la instancia

La anotación en el cuerpo de la clase no inicializa el atributo por sí sola. Si declaras n: int, pero nunca asignas self.n, la instancia no tendrá ese atributo disponible en tiempo de ejecución.

Warning

Anotar un atributo no es lo mismo que crearlo. La anotación describe el contrato; la asignación en __init__ crea el estado real de la instancia.

ClassVar para variables de clase

No todos los atributos declarados en una clase pertenecen a cada instancia. Algunas variables funcionan como configuración compartida para todas las instancias. Para estos casos existe ClassVar, disponible desde typing.

from typing import ClassVar

class Counter:
 STEP: ClassVar[int] = 1
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

 def increment(self) -> None:
 self.n += self.STEP

STEP representa una variable de clase. El valor vive en la clase Counter, no como parte del estado individual de cada objeto.

Counter.STEP = 2 # ✅ configuración compartida
counter = Counter(10)
counter.increment()
print(counter.n) # 12

counter.STEP = 5 # ❌ puede ocultar la variable de clase en esa instancia

Técnicamente Python permite asignar counter.STEP = 5, pero eso crea o modifica un atributo en la instancia, lo cual puede generar confusión. ClassVar permite que herramientas como mypy o Pyright detecten este uso como una señal de diseño incorrecta.

Tip

Usa ClassVar cuando el atributo describe configuración, constantes o metadatos compartidos por todas las instancias de una clase.

Referencias hacia la propia clase con strings

Un caso común aparece cuando un método recibe o devuelve otra instancia de la misma clase. Por ejemplo, podemos definir la suma de dos contadores con __add__.

from typing import ClassVar

class Counter:
 STEP: ClassVar[int] = 1
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

 def __add__(self, other: "Counter") -> "Counter":
 return Counter(start=self.n + other.n)

La anotación "Counter" es una referencia adelantada o forward reference. Se escribe como string porque, mientras Python está evaluando el cuerpo de la clase, el nombre Counter todavía no terminó de definirse.

first = Counter(2)
second = Counter(3)

result = first + second
print(result) # 5

El siguiente diagrama resume el contrato principal de la clase:

classDiagram
 class Counter {
 +int n
 +ClassVar~int~ STEP
 +__init__(int start) None
 +__repr__() str
 +__add__(Counter other) Counter
 }

Esta forma es compatible con versiones antiguas de Python y sigue siendo frecuente en bases de código que necesitan soportar varios entornos.

Evaluación diferida con `from future import annotations`

Desde Python 3.7 podemos activar la evaluación diferida de anotaciones usando from __future__ import annotations. Con esto, las anotaciones no se resuelven inmediatamente al definir la clase, lo que permite escribir Counter sin comillas.

from __future__ import annotations

from typing import ClassVar

class Counter:
 STEP: ClassVar[int] = 1
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

 def __add__(self, other: Counter) -> Counter:
 return Counter(start=self.n + other.n)

La ventaja principal es legibilidad. El código se ve más cercano a una anotación normal y reduce el ruido de comillas en modelos con muchas referencias cruzadas.

# ✅ con evaluación diferida
from __future__ import annotations

class Node:
 parent: Node | None

 def __init__(self, parent: Node | None = None) -> None:
 self.parent = parent

Info

from __future__ import annotations debe aparecer al inicio del archivo, antes de otros imports normales. Es una decisión por módulo, no por clase.

`typing.Self` para métodos que devuelven la misma clase

Python 3.11 incorporó typing.Self para expresar que un método devuelve una instancia del mismo tipo concreto que lo invoca. Esto es especialmente útil en métodos fluidos, constructores alternativos y operaciones que deberían preservar el subtipo.

from typing import Self

class Counter:
 n: int

 def __init__(self, start: int = 0) -> None:
 self.n = start

 def __repr__(self) -> str:
 return str(self.n)

 def __add__(self, other: Self) -> Self:
 return type(self)(start=self.n + other.n)

Aquí usamos type(self)(...) en lugar de Counter(...) para respetar el tipo concreto de la instancia. Si más adelante existe una subclase de Counter, el método tiene mejores posibilidades de devolver esa misma subclase.

Warning

Si anotas un método con Self, procura que la implementación realmente devuelva el mismo tipo concreto. Anotar Self pero retornar siempre Counter(...) puede engañar al analizador estático.

Herencia: cuando la clase base no es suficiente

El beneficio de Self se ve más claro con herencia. Consideremos una clase base A y una subclase B. Si el método me se anota devolviendo A, el tipo estático del resultado será siempre A, incluso cuando el objeto real sea B.

from __future__ import annotations

class A:
 def me(self) -> A:
 return self

class B(A):
 pass

b = B()
result = b.me() # tipo estático: A

Ese contrato es correcto, pero pierde información. El método devuelve self, así que cuando lo invoca una instancia de B, el resultado debería conservar el tipo B.

from typing import Self

class A:
 def me(self) -> Self:
 return self

class B(A):
 pass

b = B()
result = b.me() # tipo estático: B

La diferencia es importante cuando encadenas métodos o cuando la subclase agrega comportamiento adicional.

from typing import Self

class A:
 def me(self) -> Self:
 return self

class B(A):
 def only_b(self) -> str:
 return "B"

b = B()
print(b.me().only_b()) # ✅ el analizador conserva que b.me() es B

Sin Self, el analizador puede asumir que b.me() es A, y por tanto marcar only_b() como un método inexistente.

class A:
 def me(self) -> "A":
 return self

class B(A):
 def only_b(self) -> str:
 return "B"

b = B()
b.me().only_b() # ❌ para el analizador, me() devuelve A

Tip

Usa Self cuando el contrato del método sea “devuelvo el mismo tipo concreto que recibió la llamada”. Usa el nombre de la clase cuando el método debe devolver explícitamente una instancia de esa clase base.

Cierre

El tipado de clases permite expresar contratos más precisos entre objetos. Puedes usar clases estándar como datetime.datetime o uuid.UUID, declarar atributos de instancia, diferenciar variables compartidas con ClassVar, y manejar referencias hacia la propia clase con strings o evaluación diferida.

Para jerarquías de herencia, typing.Self mejora la precisión del análisis estático porque conserva el tipo concreto de la instancia. Esta diferencia se vuelve relevante cuando diseñas APIs orientadas a objetos, métodos encadenables o modelos que se especializan mediante subclases.

Note

En el próximo artículo veremos cómo aplicar tipado a estructuras de datos para modelar colecciones más expresivas y mantenibles.

Estructuras de datos

Tipado en Python: Tipado de funciones

Dacadev — Sun, 11 Aug 2024 00:00:00 -0500

Tabla de Contenido

Cuando un módulo crece y varias funciones empiezan a pasar datos entre capas, el contrato entre parámetros y retorno se vuelve crítico. El tipado de funciones en Python nos permite documentar ese contrato directamente en el código, mejorar la autocompletación del IDE y detectar inconsistencias antes de ejecutar el flujo completo en producción.

Note

Este artículo es parte de una serie que explica el tipado en Python. A continuación, puedes ver la recopilación de todos los posts de la serie.

Ver serie

En la entrega anterior vimos cómo anotar variables y colecciones. Ahora aplicaremos esa misma idea en funciones: parámetros, retornos, valores por defecto, argumentos dinámicos y objetos que se pueden invocar como funciones.

Info

Las anotaciones de tipo no cambian el comportamiento de Python en tiempo de ejecución. Su valor principal está en herramientas de análisis estático como mypy, pyright, IDEs y revisiones de código.

Sintaxis general para tipar funciones

La sintaxis base para agregar tipos a una función consiste en anotar cada argumento después de : y declarar el tipo de retorno después de ->.

def my_function(arg1: type, arg2: type) -> return_type:
 ...

Esta estructura expresa dos cosas importantes:

arg1: type: el argumento arg1 debería recibir valores compatibles con type.
-> return_type: la función debería devolver un valor compatible con return_type.

Por ejemplo, una función que recibe dos enteros y retorna otro entero se puede escribir así:

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

Si la función no retorna un valor útil, se usa None como tipo de retorno:

def log_message(message: str) -> None:
 print(message)

Tip

Anotar el retorno es tan importante como anotar los argumentos. Muchas inconsistencias aparecen cuando una función empieza devolviendo int, luego en una rama retorna None y el consumidor asume que siempre puede operar con números.

Ejemplo con `Counter`

Supongamos que tenemos una lista de elementos y cada elemento contiene una lista de etiquetas. Queremos contar cuántas veces aparece cada etiqueta.

from collections import Counter


def counter_tags(items: list[dict[str, list[str]]]) -> Counter[str]:
 return Counter(tag for item in items for tag in item["tags"])

La firma de counter_tags nos dice que items debe ser una lista de diccionarios. Cada diccionario usa llaves de tipo str y valores de tipo list[str]. La función retorna un Counter[str], es decir, un contador cuyas llaves son cadenas.

counter_tags([{"tags": ["python", "typing"]}, {"tags": ["python"]}]) # ✅
counter_tags([{"tags": ["python", 1]}, {"tags": ["typing"]}]) # ❌

La segunda llamada es problemática porque la lista de tags mezcla str con int. Python puede ejecutarla, pero un analizador estático marcará que 1 no coincide con list[str].

Warning

El tipado describe la forma esperada de los datos, pero no reemplaza validaciones de entrada cuando los datos vienen de usuarios, APIs externas, archivos o mensajes de una cola.

Valores por defecto tipados

Cuando una función tiene valores por defecto, también conviene anotar esos parámetros. El valor asignado debe ser compatible con el tipo declarado.

def sum_numbers(numbers: list[int], start: int = 0) -> int:
 total = start

 for n in numbers:
 total += n

 return total


sum_numbers([1, 2, 3, 4], start=100) # ✅
sum_numbers([1, 2, 3, 4]) # ✅
sum_numbers([1, 2, "A"]) # ❌
sum_numbers([1, 2, 3, 4], start="B") # ❌

En este caso numbers debe ser una lista de enteros y start también debe ser un entero. Si no se pasa start, Python usa 0, que cumple con la anotación int.

Este patrón es útil en funciones acumuladoras, paginadores, transformaciones de datos y cualquier API interna donde un valor opcional modifica el cálculo sin cambiar el tipo esperado.

`*args` tipados

Python permite recibir una cantidad variable de argumentos posicionales con *args. Para tiparlos, se anota el tipo de cada elemento recibido, no el tipo de la tupla completa.

def sum_args(*args: int) -> int:
 total = 0

 for n in args:
 total += n

 return total


sum_args(1, 2, 3, 4, 5) # ✅
sum_args(1, "A") # ❌

La anotación *args: int significa que cada argumento posicional adicional debe ser int. Internamente, Python sigue recibiendo una tupla, pero desde el punto de vista del contrato de la función, cada elemento debe respetar el tipo indicado.

Info

Si necesitas aceptar varios tipos en *args, puedes combinar tipos con |, por ejemplo *args: int | float. Esto mantiene el contrato explícito sin convertir la función en una entrada completamente abierta.

`*args` con parámetros keyword-only

También podemos combinar argumentos dinámicos con parámetros que solo se reciben por nombre. En Python, todo parámetro declarado después de *args se vuelve keyword-only.

def sum_args(*args: int, start: int = 0) -> int:
 total = start

 for n in args:
 total += n

 return total


sum_args(1, 2, 3, 4) # ✅
sum_args(1, 2, 3, start=100) # ✅
sum_args(1, 2, 3, start="x") # ❌
sum_args(1, 2, "3") # ❌

Aquí start no puede pasarse como otro argumento posicional más; debe enviarse usando su nombre. Esto mejora la legibilidad cuando el parámetro tiene un rol especial dentro del cálculo.

Este estilo es recomendable cuando una función acepta una secuencia flexible de valores, pero también necesita opciones de configuración con nombres claros.

Funciones de primer orden y `Callable`

En Python podemos pasar funciones como argumentos de otras funciones. Para anotar este tipo de contrato usamos Callable, disponible en collections.abc.

import time
from collections.abc import Callable


def work(send_notification: Callable[[str], None]) -> None:
 for i in range(3):
 time.sleep(1)

 send_notification(f"Finished {i + 1} rounds of work!")

La anotación Callable[[str], None] indica que send_notification debe ser invocable, recibir un str y no retornar un valor útil.

def notify(message: str) -> None:
 print(message)


def bad_notify(message: int) -> None:
 print(message)


work(notify) # ✅
work(bad_notify) # ❌

En Callable, el primer bloque define la lista de argumentos y el segundo define el retorno:

Callable[[str], None]
Callable[[str, int], bool]
Callable[[bytes], str]

flowchart LR
 A["Callable[[str, int], bool]"] --> B[Entrada 1: str]
 A --> C[Entrada 2: int]
 B --> D[Función compatible]
 C --> D
 D --> E[Salida: bool]

Tip

Usa Callable cuando la función consumidora solo necesita ejecutar un comportamiento. Esto reduce acoplamiento porque no obliga a depender de una implementación concreta.

`Callable` con clases y `call`

Callable no se limita a funciones definidas con def. Una instancia de clase también puede ser invocable si implementa el método especial __call__.

class Notifier:
 def __call__(self, message: str) -> None:
 print(f"Notifier sends: '{message}'")


notifier = Notifier()
work(notifier) # ✅

En este ejemplo, notifier se comporta como una función porque Notifier define __call__. Para el contrato de work, lo importante es que el objeto pueda invocarse con un str y retornar None.

Este patrón aparece con frecuencia cuando necesitas combinar estado interno con una interfaz funcional. Por ejemplo, un notificador podría guardar credenciales, configuración del canal o métricas, pero seguir exponiendo una firma simple para el consumidor.

Warning

No confundas Callable con una clase específica. Callable[[str], None] describe una capacidad de invocación; no exige que el objeto sea una función tradicional ni una instancia de una clase concreta.

Conclusión

El tipado de funciones en Python permite hacer explícitos los contratos entre piezas de código: qué argumentos acepta una función, qué retorna y qué forma deben tener los callables que recibe como dependencias.

En código de aplicación, estas anotaciones mejoran la navegación, reducen errores de integración y facilitan refactors. En librerías o módulos compartidos, además funcionan como documentación ejecutable para otros desarrolladores y herramientas.

Note

En el siguiente artículo continuaremos con el tipado aplicado a clases, atributos y métodos.

Tipado en clases

Tipado básico en Python

Dacadev — Sat, 10 Aug 2024 00:00:00 -0500

Tabla de Contenido

Note

Este artículo es parte de una serie que explica el tipado en Python. A continuación, puedes ver la recopilación de todos los posts de la serie.

Ver serie

Agregar tipos en Python es muy sencillo y tiene una sintaxis similar a otros lenguajes como Typescript. No es obligatorio aplicar tipado en cada pieza de código, lo que permite agregarlo de manera gradual. Además, agregar o no tipos no afectará el comportamiento del código.

Info

La posibilidad de agregar tipado en Python está disponible desde la versión 3.5. Desde entonces, se han añadido nuevas características y mejoras.

Tipos Buitl-in in Python

Los tipos built-in son aquellos que vienen por defecto en Python, como str, int, float, bool, bytes, None, list, dict, tuple, set, entre otros.

Para agregar tipado a una variable, simplemente añade : después del nombre de la variable y luego especifica el tipo de dato. La sintaxis es:

<variable>: <type> = <value>

Ejemplo:

n: int = 1
f: float = 10.0
c: complex = 1 + 2j
b: bool = True
s: bytes = b'bytes'
t: str = "hello world"
v: None = None

En el anterior ejemplo estamos definiendo que cada una de las variables solo van a manejar un tipo de datos a lo largo de vida en el programa.

Note

Recuerda que el agregar el tipo de dato no afecta el comportamiento del código, es solo una ayuda para el programador, analizadores de código estáticos e IDEs.

Tipado en colecciones

Para colecciones como list, dict, tuple, set, la sintaxis es similar a la de las variables simples. salvo que podemos definir o nor el tipo de variable que cada variable va a contener. es decir que tenemos dos tipos de sintaxis que podemos utilizar.

<variable>: <collection> = <value>
<variable>: <collection>[<type>...] = <value>

En la primera opción estamos definiendo que la variable va a ser de tipo list, dict, tuple, set y en la segunda opción estamos definiendo que la variable va a ser de tipo list, dict, tuple, set y que va a contener un tipo de dato especifico. Veamos como se aplica esto en algunos ejemplos, para ello es importante tener en cuenta la versión de Python que estás utilizando.

Python 3.5 a 3.8: Es necesario importar los tipos de la librería typing:

from typing import List, Set, Tuple, Dict

l: List = [1, 2, 3, 4]
s: Set[str] = {"hello", "world"}
t: Tuple[int, str, bool] = (10, "Python", True)
d: Dict[str, bool] = {"active": True, "admin": False}

Python 3.9 y posteriores: Puedes utilizar la sintaxis estándar sin importar typing:

l: list = [1, 2, 3, 4]
s: set[str] = {"hello", "world"}
t: tuple[int, str, bool] = (10, "Python", True)
d: dict[str, bool] = {"active": True, "admin": False}

En los ejemplos anteriores podemos observar que estamos definiendo un tipo de colección diferente por cada varibale y cabe destacar que en el caso de las colecciones podemos definir el tipo de dato que va a contener cada una de las variables, debes tener en cuenta que:

para list y set se utiliza el tipo de dato que va a contener entre corchetes [].
para tuple se define el tipo de dato y la posición dentro de la tupla entre corchetes [], es decir que en el ejemplo se espera que sea una tupla de tres elementos que estaran en el siguiente orden int, str, bool.
para dict se define el tipo de dato que va a contener la llave y el valor entre corchetes [], es decir que en el ejemplo se espera que sea un diccionario con llaves de tipo str y valores de tipo bool.

Combinación de Tipos en Python

En algunos casos, es necesario que las variables puedan contener más de un tipo de dato o incluso que puedan ser opcionales. Para ello se han definido diversas estrategias para alcanzar esta funcionalidad

Definir Más de un Tipo

Utiliza el carácter | para definir más de un tipo de dato en una variable, este carácter actúa como un OR lógico:

a: int | str = 1
b: int | str = "one"

Para versiones anteriores a Python 3.9, importa Union de typing:

from typing import Union

a: Union[int, str] = 1
b: Union[int, str] = "one"

Valores Opcionales o `None`

Para definir que un valor es opcional, añade None como parte de los tipos posibles:

a: int | None = 1
b: int | None = None

Para versiones anteriores a Python 3.9, utiliza Optional o Union:

# Opción 1
from typing import Optional

a: Optional[int] = 1

# Opción 2
from typing import Union

a: Union[int, None] = None

Definir Valores Fijos

Si deseas restringir los valores que puede tomar una variable, usa Literal de typing:

from typing import Literal

cards: Literal["clubs", "diamonds", "hearts", "spades"]
cards = "clubs"

Definir Tipos Personalizados

EN Python asi como con las variables es posible definir tipos personalizados, para simplificar la lectura del código o incluso para darle un mejor entendimiento al código. en la siguiente pieza de código podemos ver esta funcionalidad.

from typing import Literal

UserType = Literal["admin", "user"]
ID = int | str
PersonalData = dict[str, str | bool| float | None]

User = tuple[ID, PersonalData, UserType]
UserUgly = tuple[int | str, dict[str, str | bool| float | None], Literal["admin", "user"]]

Como podemos observa en el ejemplo anterior estamos separando nuestra definición de tipos en otros tipos para facilitar la lectura de nuestro código, en el caso de User y UserUgly estamos definiendo un tipo de dato que va a ser una tupla que va a contener un ID, PersonalData y UserType y en el caso de UserUgly estamos definiendo el mismo tipo de dato pero de una manera menos legible.

si escribieramos el mismo código para versiones anteriores a Python 3.9, el código se vería de la siguiente manera:

from typing import Literal, Union, Optional

UserType = Literal["admin", "user"]
ID = Union[int, str]
PersonalData = dict[str, Optional[str, bool, float]]

User = tuple[ID, PersonalData, UserType]

Datos IO en Python

Cuando trabajes con datos de entrada/salida, como la lectura de archivos, usa el tipo IO de typing:

from typing import IO

text_file: IO[str] # text, json, xml, html...
bin_file: IO[bytes] # jpeg, png, pdf, mp3...

El tipo IO es un tipo genérico que se utiliza para representar objetos que son streams de entrada o salida, como archivos y sockets, y solo admite tipos de datos str y bytes.

Info

En este artículo, hemos cubierto las nociones básicas sobre cómo agregar tipos a tus variables en Python. En el próximo artículo, exploraremos cómo agregar tipos a funciones.

Tipado de funciones

Tipado en Python: Introducción

Dacadev — Fri, 09 Aug 2024 00:00:00 -0500

Tabla de Contenido

Note

Este artículo hace parte de una serie que explicará el tipado en Python, a continuación puedes ver la recopilación de todos los posts de la serie.

Ver serie

¿Por qué es importante el tipado?

Antes de ahondar en el uso de tipos en python, debemos hacer un pequeño énfasis de porque nace la necesidad de implementar “tipado” y análisis estático de código en Python

Info

Escribo tipado entre comillas porque realmente no implementamos tipado en python, sino que simulamos tener tipos en Python, esto lo veremos vas adelante, pero es importante tenerlo en cuenta.

Python, al ser un lenguaje interpretado, significa que el código es leído y ejecutado solamente cuando el interprete pasa por la línea de código, por lo que el error, si existe, solo aparecerá cuando ejecutamos dicha línea de código. Por el contrario en un lenguaje compilado como Go o Java, el código debe primero construido (compilado) y después usado, pero es en el proceso de compilación en donde se realizan validaciones de tipos dentro del código y estas validaciones permiten capturar errores tempranos.

Tipos de errores

En este punto vale la pena agrupar los errores en dos grupos:

Errores de excepción: Son errores que se generan cuando un programa falla al ejecutar una acción determinada, como por ejemplo abrir un archivo que no existe.
Errores de lógica: Son errores que no generan excepción sino que generan un resultado errado al esperado.

Warning

Los errores de lógica son los mas peligrosos ya que al no levantar una excepción normalmente permiten que el flujo de trabajo continue con los errores.

En ese orden de ideas nos centraremos en los errores de lógica ya que son los errores que podemos “capturar” gracias a los tipos, por ejemplo con ayuda de tipos podemos capturar errores tempranos como:

validar el uso de los tipos de datos dentro de nuestro código, por ejemplo si estamos usando un string en un lugar donde deberíamos de usar un entero
validar que los métodos que estamos llamando existan en el objeto que estamos usando
validar que los atributos que estamos usando en un objeto existan
validar que los argumentos que estamos pasando a una función sean los correctos

Veamos la forma tradicional de validar y capturar errores de tipos en Python. Para ello debemos de implementar una serie sentencias en nuestro código para asegurarnos que estamos usando los tipos correctos. esto puede afectar la legibilidad del código y la productividad, e incluso el rendimiento de nuestros programas en algunos casos.

def clean_text(a):
 assert isinstance(a, str), "Input must be a string"
 # process a

def calculate_sum(*nums):
 sum = 0

 for num in nums:
 if not isinstance(num, (int, float)):
 raise ValueError("Input must be a number")

 sum += num

 return sum

En el caso de clean_text estamos validando que el argumento a sea un string, en caso de que no sea un string, levantamos una excepción. En el caso de calculate_sum estamos validando que los argumentos que estamos pasando sean int o float, en caso de que no sea alguno de estos, levantamos una excepción.

Info

En el caso clean_text estamos usando assert para validar el tipo de dato, sin embargo assert no es recomendado para validar tipos de datos, ya que se puede desactivar en tiempo de ejecución, por lo que no es una buena práctica usarlo como captura de errores en código, sin embargo es probable que lo encuentres en tu día a día como desarrollador.

Si miramos a profundidad el código no esta mal, sino que estamos agregando lógica adicional que esta afectando la legibilidad del código, y un de los principales objetivos que tenemos como programadores es escribir código limpio y legible. para los demás o tu yo del futuro. Imagina si hicieramos esto en códigos mas complejos y extensos.

Note

La siguiente entrega de esta seria aborda el tema de como implementar tipado en Python, y como podemos mejorar la legibilidad del código y la productividad. para verla da click en el siguiente botón.

Tipado básico en Python

Tipado en Python: Serie de DacaDev

Dacadev — Thu, 08 Aug 2024 00:00:00 -0500

Python, al ser un lenguaje interpretado y dinámicamente tipado, no incluye de forma nativa la gestión y manejo de tipos. Esta característica es extremadamente útil y práctica, especialmente para quienes están comenzando en el mundo del desarrollo de software.

Sin embargo, a medida que los proyectos crecen, esta ventaja inicial puede convertirse en un desafío. La ausencia de un sistema de tipos explícito puede complicar la lectura del código, dificultar la depuración de errores y limitar la escalabilidad del proyecto.

Por esta razón, ha surgido la iniciativa de implementar tipado en Python. Con esta herramienta, los desarrolladores pueden tener un mayor control sobre los tipos de datos en su código, lo que permite capturar errores tempranos y mejorar la calidad del software desde las primeras etapas del desarrollo.

En DacaDev, hemos creado una serie de artículos que explican de manera detallada el tipado en Python. A continuación, puedes acceder a cada uno de los artículos de la serie:

Colecciones en Python: namedtuple()

Dacadev — Tue, 14 May 2024 00:00:00 -0500

Tabla de Contenido

Note

En este artículo, conocerás la función namedtuple del módulo collections de la biblioteca estándar de Python.

¿Qué es `namedtuple()`?

namedtuple() es una función que retorna una nueva clase, la cual permite acceder a los valores de una tupla tanto por índice como a través de un nombre definido al crear la tupla.

Primero, examinaremos la firma de la función para entender cómo funciona y, posteriormente, analizaremos por qué y cuándo es beneficioso usarla.

def namedtuple(typename, field_names, *, rename=False, defaults=None, module=None):

Esta firma revela cinco argumentos importantes:

typename: el nombre que se asignará a la nueva clase creada.
field_names: ya sea un string o un iterable de strings que representan los nombres de los campos de la tupla. El orden de estos strings determina cómo se accederán los valores.
rename: un valor booleano que, si se activa, permite que la función reemplace nombres duplicados o conflictivos automáticamente.
defaults: permite definir valores predeterminados para los campos de la tupla, asignando valores desde el final hacia el inicio de la lista de campos.
module: un string que asocia la nueva tupla a un módulo específico.

Note

Los argumentos definidos después de * son argumentos que deben pasarse como keyword arguments (es decir, como nombre=valor), no de manera posicional.

Ejemplos de uso

Crear una `namedtuple`

Primero, veamos cómo crear una nueva tupla sencilla:

from collections import namedtuple

Coordinates = namedtuple("Coordinates", ["x", "y", "z"])

point_1 = Coordinates(1, 2, 3)
print(point_1)
print('x:', point_1.x, 'y:', point_1.y, 'z:', point_1.z)
print('x:', point_1[0], 'y:', point_1[1], 'z:', point_1[2])

El resultado de este código será:

$ python main.py
Coordinates(x=1, y=2, z=3)
x: 1 y: 2 z: 3
x: 1 y: 2 z: 3

Como observamos, creamos una nueva clase llamada Coordinates con campos x, y, y z. Luego instanciamos point_1 y accedimos a sus valores tanto por nombre como por índice.

Note

Al declarar point_1, los valores se asignan en el mismo orden en que se especifican en la tupla: primero x, después y, y finalmente z.

Crear una `namedtuple` con valores por defecto

Definiendo valores por defecto, que deben ser iterables, podemos especificar los valores que se asignarán a los campos si no se proporcionan al crear la instancia:

from collections import namedtuple

UserData = namedtuple(
 "UserData",
 ["name", "age", "email", "country"],
 defaults=("example@mail.com", "CO")
)

david = UserData( "David", 28, )
juan = UserData("Juan", 24, "juan@mail.com")

print(david)
print(juan)

El resultado de este código será:

UserData(name='David', age=28, email='example@mail.com', country='CO')
UserData(name='Juan', age=24, email='juan@mail.com', country='CO')

Los valores por defecto se asignan de derecha a izquierda a los campos que no tienen valores asignados al crear la instancia.

Pero debemos de tener en cuenta que si no pasamos todos los argumentos que no están definidos por defecto, la función lanzará un error.

unknown = UserData()
print(unknown)

Traceback (most recent call last):
 File "/home/dacacode/dacadev/personal-blog/tempCodeRunnerFile.python", line 9, in <module>
 unknown = UserData()
 ^^^^^^^^^^
TypeError: UserData.__new__() missing 2 required positional arguments: 'name' and 'age'

Controlar el renombramiento de los campos

Activando el argumento rename como True, la función automáticamente renombra campos duplicados o que sean palabras reservadas del lenguaje. Primero vamos a crear una tupla normal con nombres de campos que pueden entrar en conflicto.

from collections import namedtuple

dynamic_fields = ['name', 'def', 'arg', 'name']
EspecialInfo = namedtuple("EspecialInfo", dynamic_fields)

print(EspecialInfo)

Al ejecutar el código vas a obtener un error como el siguiente:

Traceback (most recent call last):
 File "/home/dacacode/dacadev/personal-blog/tempCodeRunnerFile.python", line 4, in <module>
 EspecialInfo = namedtuple("EspecialInfo", dynamic_fields)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "/home/dacacode/.pyenv/versions/3.11.5/lib/python3.11/collections/__init__.py", line 398, in namedtuple
 raise ValueError('Type names and field names cannot be a '..)
ValueError: Type names and field names cannot be a keyword: 'def'

Pero si habilitamos la opcion de rename el código funcionará, ya que la función se encarga de procesar esos casos.

from collections import namedtuple

dynamic_fields = ['name', 'def', 'arg', 'name']
EspecialInfoV2 = namedtuple("EspecialInfoV2", dynamic_fields, rename=True)

print(EspecialInfoV2)
data = EspecialInfoV2('David', 'print', 'Hello, World!', 'David')
print(data)

Ahora si obtendremos un resultado positivo:

<class '__main__.EspecialInfoV2'>
EspecialInfoV2(name='David', _1='print', arg='Hello, World!', _3='David')

En donde podemos ver que los atributos que son keywords y duplicados han sido renombrados por valores posicionales, en este caso _1 y _3.

Las `namedtuples` son Clases

Por último, pero no menos importante, recuerda que el resultado de la función namedtuple es una clase que hereda de tuple, lo que significa que podemos usarla como cualquier otra clase. Por ejemplo, podemos usar la nueva clase como padre de otra para extender su funcionalidad:

from collections import namedtuple

Coordinates = namedtuple("Coordinates", ["x", "y", "z"])

class Point(Coordinates):

 def __add__(self, other):
 return Point(self.x + other.x, self.y + other.y, self.z + other.z)

point_1 = Point(1, 2, 3)
point_2 = Point(4, 5, 6)

print(point_1)
print(point_2)
print(point_1 + point_2)

El resultado de este código será:

Point(x=1, y=2, z=3)
Point(x=4, y=5, z=6)
Point(x=5, y=7, z=9)

¿Por qué usar `namedtuples`?

Una de las principales razones para usar las namedtuple es la mejora de la legibilidad del código, ya que al momento los atributos para acceder a sus elementos es más fácil de entender que si lo hacemos por índice.

from collections import namedtuple

UserInfo = namedtuple('UserInfo', ['name', 'age', 'email'])

# Mejora la legibilidad
user = UserInfo('David', 28, 'mail@mail.com')

user.name # David
user.age # 30
user.email # mail@mail.com

# Debes tener en tu mente el orden de los campos, no es lo ideal!
userRaw = {'David', 28, 'mail@mail.com'}
user[0] # David
user[1] # 30
user[2] # mail@mail.com

Otros beneficios que encontramos es en la eficiencia del código, ya que al utilizar tuplas (o nametuples) encontramos que:

Las tuplas tienen mayor rendimiento al momento de ser creadas, debido a que son objetos inmutables y su alocación en memoria es mucho ams eficiente que las clasicas lsitas o diccionarios.
Son ideales para procesar información que debe mantenerse constante durante todo su tiempo de vida, ya que las tuplas son inmutables.
El tiempo de acceso a los elementos de la tupla es más rápido que las listas o los diccionarios.

Note

Esto no significa que las tuplas sean mejores que otras estructuras de datos, esto depende de cada caso en particular y debes analizarlo antes de tomar una decisión.

Info

Para más información sobre namedtuple, visita la documentación oficial en este enlace

Pythons · DacaCode

aiohttp: Peticiones HTTP Concurrentes con asyncio

El Patrón async with: Context Managers Asíncronos

aiohttp: Sesiones y Connection Pooling

Configurando Timeouts

La Trampa del await Secuencial

gather: Recolectar Todos los Resultados

Manejo de Excepciones en gather

as_completed: Procesar a Medida que Terminan

wait: Control Fino sobre la Espera

¿Cuál Debo Usar?

En conclusión

Referencias

Futures, Awaitables y Errores Comunes en asyncio

Futures: Un Valor que Aún No Existe

Futures en la práctica

La Jerarquía de los Awaitables

Midiendo el Tiempo de Ejecución

Uso en la práctica

Errores Comunes en asyncio

1. Ejecutar código CPU-bound en coroutines

2. Usar APIs bloqueantes

No uses estas funciones dentro de coroutines

Usa las alternativas asíncronas

En conclusión

Referencias

Coroutines y async/await: Tu Primer Código Asíncrono en Python

¿Qué es una Coroutine?

Creando Coroutines

Ejecutando Coroutines con asyncio.run

Pausando la Ejecución con await

Simulando Operaciones Largas con asyncio.sleep

La Trampa del await Secuencial

El problema visualizado

¿Cómo logramos concurrencia real?

En conclusión

Referencias

asyncio: Cómo Funcionan los Procesos, Hilos y el Event Loop

Procesos e Hilos

¿Qué es un proceso?

¿Qué es un hilo (thread)?

Verificándolo en Python

El Global Interpreter Lock (GIL)

¿El GIL se libera alguna vez?

asyncio y el GIL

Concurrencia de Un Solo Hilo

1. Sockets no bloqueantes

2. Delegación al sistema operativo

3. El Event Loop como coordinador

Cómo Funciona el Event Loop

En conclusión

Referencias

asyncio: Los Fundamentos de la Programación Asíncrona en Python

¿Qué es la programación asíncrona?

CPU-bound vs. I/O-bound

Operaciones limitadas por E/S (I/O-bound)

Operaciones limitadas por CPU (CPU-bound)

Ejemplo práctico

Concurrencia vs. Paralelismo

Concurrencia: alternar entre tareas

Paralelismo: ejecución simultánea real

Tipos de Multitarea

Multitarea preventiva (Preemptive)

Multitarea cooperativa (Cooperative)

Comparación rápida

Multitarea Preventiva

Multitarea Cooperativa

¿Dónde encaja asyncio?

En conclusión

Referencias

Tipado en Python: Estructuras de datos

Diccionarios tipados en Python

TypedDict: diccionarios con forma definida

Llaves opcionales con NotRequired

Enfoque inverso: total=False y Required

Dataclass: estructuras de datos con atributos

Dataclass vs class tradicional

Cuándo usar cada estructura de datos

Cierre

Tipado en Python: Tipado de clases

El Patrón `async with`: Context Managers Asíncronos

La Trampa del `await` Secuencial

`gather`: Recolectar Todos los Resultados

Manejo de Excepciones en `gather`

`as_completed`: Procesar a Medida que Terminan

`wait`: Control Fino sobre la Espera

Errores Comunes en `asyncio`

Ejecutando Coroutines con `asyncio.run`

Pausando la Ejecución con `await`

Simulando Operaciones Largas con `asyncio.sleep`

La Trampa del `await` Secuencial

`asyncio` y el GIL

¿Dónde encaja `asyncio`?

Evaluación diferida con `from future import annotations`

`typing.Self` para métodos que devuelven la misma clase

Ejemplo con `Counter`

`*args` tipados

`*args` con parámetros keyword-only

Funciones de primer orden y `Callable`

`Callable` con clases y `call`

Valores Opcionales o `None`

¿Qué es `namedtuple()`?

Crear una `namedtuple`

Crear una `namedtuple` con valores por defecto

Las `namedtuples` son Clases

¿Por qué usar `namedtuples`?