asyncio — planificador de E/S asíncrona

Este módulo proporciona un planificador de multitarea cooperativa para corrutinas async/await, junto con primitivas de sincronización (bloqueos, eventos) y redes TCP no bloqueantes mediante lectores y escritores de flujos. Las tareas se ejecutan de forma concurrente en un único bucle de eventos; la tarea que se está ejecutando devuelve el control al bucle con await.

Ejemplo:

import asyncio

async def blink(led, period_ms):
    while True:
        led.on()
        await asyncio.sleep_ms(5)
        led.off()
        await asyncio.sleep_ms(period_ms)

async def main(led1, led2):
    asyncio.create_task(blink(led1, 700))
    asyncio.create_task(blink(led2, 400))
    await asyncio.sleep_ms(10_000)

# Running on an OpenMV Cam
from machine import LED
asyncio.run(main(LED(1), LED(2)))

Funciones principales

asyncio.create_task(coro: Coroutine) → Task

Crea una nueva tarea a partir de la corrutina dada y la planifica para su ejecución.

Devuelve el objeto Task correspondiente.

asyncio.current_task() → Task

Devuelve el objeto Task asociado a la tarea que se está ejecutando actualmente.

asyncio.run(coro: Coroutine) → Any

Crea una nueva tarea a partir de la corrutina dada y la ejecuta hasta que finaliza.

Devuelve el valor devuelto por coro.

asyncio.sleep(t: float) → None

Duerme durante t segundos (puede ser un valor de tipo float).

Esto es una corrutina.

asyncio.sleep_ms(t: int) → None

Duerme durante t milisegundos.

Esto es una corrutina, y una extensión de MicroPython.

Funciones adicionales

asyncio.wait_for(awaitable: Awaitable, timeout: float) → Any

Espera a que el awaitable finalice, pero lo cancela si tarda más de timeout segundos. Si awaitable no es una tarea, se creará una tarea a partir de él.

Si se produce un tiempo de espera agotado, se cancela la tarea y se lanza asyncio.TimeoutError: esto debería ser capturado por quien realiza la llamada. La tarea recibe asyncio.CancelledError, que puede ignorarse o capturarse usando try...except o try...finally para ejecutar código de limpieza.

Devuelve el valor de retorno de awaitable.

Esto es una corrutina.

asyncio.wait_for_ms(awaitable: Awaitable, timeout: int) → Any

Similar a wait_for(), pero timeout es un entero en milisegundos.

Esto es una corrutina, y una extensión de MicroPython.

asyncio.gather(*awaitables, return_exceptions: bool = False) → List

Ejecuta todos los awaitables de forma concurrente. Cualquier awaitable que no sea una tarea se promueve a tarea.

Devuelve una lista con los valores de retorno de todos los awaitables.

Esto es una corrutina.

class Task

class asyncio.Task

Este objeto envuelve una corrutina en una tarea en ejecución. Se puede esperar a las tareas usando await task, lo que esperará a que la tarea finalice y devolverá el valor de retorno de la tarea.

Las tareas no deben crearse directamente, sino que se debe usar create_task() para crearlas.

cancel() → None

Cancela la tarea inyectando asyncio.CancelledError en ella. La tarea puede ignorar esta excepción. El código de limpieza puede ejecutarse capturándola, o mediante try ... finally.

class Event

class asyncio.Event

Crea un nuevo evento que puede usarse para sincronizar tareas. Los eventos comienzan en el estado borrado.

is_set() → bool

Devuelve True si el evento está establecido, False en caso contrario.

set() → None

Establece el evento. Cualquier tarea que esté esperando el evento se planificará para su ejecución.

Nota: Esto debe llamarse desde dentro de una tarea. No es seguro llamarlo desde una IRQ, una función de retorno (callback) del planificador u otro hilo. Consulte ThreadSafeFlag.

clear() → None

Borra el evento.

wait() → None

Espera a que el evento se establezca. Si el evento ya está establecido, regresa inmediatamente.

Esto es una corrutina.

class ThreadSafeFlag

class asyncio.ThreadSafeFlag

Crea una nueva bandera que puede usarse para sincronizar una tarea con código que se ejecuta fuera del bucle de asyncio, como otros hilos, IRQs o funciones de retorno (callbacks) del planificador. Las banderas comienzan en el estado borrado.

set() → None

Establece la bandera. Si hay una tarea esperando la bandera, se planificará para su ejecución.

clear() → None

Borra la bandera. Esto puede usarse para asegurar que una bandera posiblemente establecida con anterioridad esté borrada antes de esperarla.

wait() → None

Espera a que la bandera se establezca. Si la bandera ya está establecida, regresa inmediatamente. La bandera se reinicia automáticamente al regresar de wait.

Solo una tarea a la vez puede esperar una bandera.

Esto es una corrutina.

class Lock

class asyncio.Lock

Crea un nuevo bloqueo que puede usarse para coordinar tareas. Los bloqueos comienzan en el estado desbloqueado.

Además de los métodos siguientes, los bloqueos pueden usarse en una sentencia async with.

locked() → bool

Devuelve True si el bloqueo está bloqueado, False en caso contrario.

acquire() → bool

Espera a que el bloqueo esté en el estado desbloqueado y luego lo bloquea de forma atómica. Solo una tarea puede adquirir el bloqueo a la vez.

Esto es una corrutina.

release() → None

Libera el bloqueo. Si hay tareas esperando el bloqueo, la siguiente en la cola se planifica para su ejecución y el bloqueo permanece bloqueado. De lo contrario, ninguna tarea está esperando y el bloqueo pasa a estar desbloqueado.

Conexiones de flujo TCP

asyncio.open_connection(host: str, port: int, ssl: ssl.SSLContext | bool | None = None) → Tuple[Stream, Stream]

Abre una conexión TCP al host y port dados. La dirección de host se resolverá usando socket.getaddrinfo(), que actualmente es una llamada bloqueante. Si ssl es un objeto ssl.SSLContext, este contexto se usa para crear el transporte; si ssl es True, se usa un contexto predeterminado.

Devuelve un par de flujos: un flujo lector y un flujo escritor. Lanzará un OSError específico del socket si no se pudo resolver el host o si no se pudo establecer la conexión.

Esto es una corrutina.

asyncio.start_server(callback: Callable, host: str, port: int, backlog: int = 5, ssl: ssl.SSLContext | None = None) → Server

Inicia un servidor TCP en el host y port dados. La callback se llamará con las conexiones entrantes y aceptadas, y se le pasarán 2 argumentos: el flujo lector y el flujo escritor de la conexión.

Si ssl es un objeto ssl.SSLContext, este contexto se usa para crear el transporte.

Devuelve un objeto Server.

Esto es una corrutina.

class asyncio.Stream

Esto representa una conexión de flujo TCP. Para minimizar el código, esta clase implementa tanto un lector como un escritor, y tanto StreamReader como StreamWriter son alias de esta clase.

get_extra_info(v: str) → Any

Obtiene información adicional sobre el flujo, indicada por v. Los valores válidos para v son: peername.

close() → None

Cierra el flujo.

wait_closed() → None

Espera a que el flujo se cierre.

Esto es una corrutina.

read(n: int = -1) → bytes

Lee hasta n bytes y los devuelve. Si no se proporciona n o es -1, lee todos los bytes hasta EOF. El valor devuelto será un objeto bytes vacío si se encuentra EOF antes de leer algún byte.

Esto es una corrutina.

readinto(buf: bytearray | memoryview) → int

Lee hasta n bytes en buf, siendo n igual a la longitud de buf.

Devuelve el número de bytes leídos en buf.

Esto es una corrutina, y una extensión de MicroPython.

readexactly(n: int) → bytes

Lee exactamente n bytes y los devuelve como un objeto bytes.

Lanza una excepción EOFError si el flujo termina antes de leer n bytes.

Esto es una corrutina.

readline() → bytes

Lee una línea y la devuelve.

Esto es una corrutina.

write(buf: bytes) → None

Acumula buf en el búfer de salida. Los datos solo se vacían cuando se llama a Stream.drain(). Se recomienda llamar a Stream.drain() inmediatamente después de llamar a esta función.

drain() → None

Vacía (escribe) todos los datos de salida almacenados en el búfer hacia el flujo.

Esto es una corrutina.

class asyncio.Server

Esto representa la clase de servidor devuelta por start_server(). Puede usarse en una sentencia async with para cerrar el servidor al salir.

close() → None

Cierra el servidor.

wait_closed() → None

Espera a que el servidor se cierre.

Esto es una corrutina.

Bucle de eventos

asyncio.get_event_loop() → Loop

Devuelve el bucle de eventos usado para planificar y ejecutar tareas. Consulte Loop.

asyncio.new_event_loop() → Loop

Reinicia el bucle de eventos y lo devuelve.

Nota: dado que MicroPython solo tiene un único bucle de eventos, esta función simplemente reinicia el estado del bucle, no crea uno nuevo.

class asyncio.Loop

Esto representa el objeto que planifica y ejecuta tareas. No puede crearse; use get_event_loop() en su lugar.

create_task(coro: Coroutine) → Task

Crea una tarea a partir del coro dado y devuelve el nuevo objeto Task.

run_forever() → None

Ejecuta el bucle de eventos hasta que se llama a stop().

run_until_complete(awaitable: Awaitable) → Any

Ejecuta el awaitable dado hasta que finaliza. Si awaitable no es una tarea, se promoverá a una.

stop() → None

Detiene el bucle de eventos.

close() → None

Cierra el bucle de eventos.

set_exception_handler(handler: Callable) → None

Establece el manejador de excepciones que se llamará cuando una Task lance una excepción que no se captura. El handler debe aceptar dos argumentos: (loop, context).

get_exception_handler() → Callable | None

Obtiene el manejador de excepciones actual. Devuelve el manejador, o None si no se ha establecido ningún manejador personalizado.

default_exception_handler(context: dict) → None

El manejador de excepciones predeterminado que se llama.

call_exception_handler(context: dict) → None

Llama al manejador de excepciones actual. El argumento context se pasa a través y es un diccionario que contiene las claves: 'message', 'exception', 'future'.