asyncio — ordonnanceur d’entrées/sorties asynchrones

Ce module fournit un ordonnanceur multitâche coopératif pour les coroutines async/await, ainsi que des primitives de synchronisation (verrous, événements) et la mise en réseau TCP non bloquante via des lecteurs et écrivains de flux. Les tâches s’exécutent simultanément sur une unique boucle d’événements ; la tâche en cours d’exécution rend le contrôle à la boucle avec await.

Exemple

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)))

Fonctions principales

asyncio.create_task(coro: Coroutine) → Task

Crée une nouvelle tâche à partir de la coroutine donnée et la planifie pour exécution.

Renvoie l’objet Task correspondant.

asyncio.current_task() → Task

Renvoie l’objet Task associé à la tâche en cours d’exécution.

asyncio.run(coro: Coroutine) → Any

Crée une nouvelle tâche à partir de la coroutine donnée et l’exécute jusqu’à son achèvement.

Renvoie la valeur renvoyée par coro.

asyncio.sleep(t: float) → None

Met en pause pendant t secondes (peut être un flottant).

Ceci est une coroutine.

asyncio.sleep_ms(t: int) → None

Met en pause pendant t millisecondes.

Ceci est une coroutine, ainsi qu’une extension MicroPython.

Fonctions supplémentaires

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

Attend que l”awaitable se termine, mais l’annule s’il prend plus de timeout secondes. Si l”awaitable n’est pas une tâche, une tâche en sera créée.

En cas de dépassement de délai, la tâche est annulée et une asyncio.TimeoutError est levée : celle-ci doit être interceptée par l’appelant. La tâche reçoit asyncio.CancelledError qui peut être ignorée ou interceptée à l’aide de try...except ou try...finally pour exécuter du code de nettoyage.

Renvoie la valeur de retour de l”awaitable.

Ceci est une coroutine.

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

Similaire à wait_for() mais timeout est un entier en millisecondes.

Ceci est une coroutine, ainsi qu’une extension MicroPython.

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

Exécute simultanément tous les awaitables. Tout awaitable qui n’est pas une tâche est promu en tâche.

Renvoie une liste des valeurs de retour de tous les awaitables.

Ceci est une coroutine.

class Task

class asyncio.Task

Cet objet encapsule une coroutine dans une tâche en cours d’exécution. Il est possible d’attendre les tâches avec await task, ce qui attendra l’achèvement de la tâche et renverra sa valeur de retour.

Les tâches ne doivent pas être créées directement ; utilisez plutôt create_task() pour les créer.

cancel() → None

Annule la tâche en y injectant asyncio.CancelledError. La tâche peut ignorer cette exception. Du code de nettoyage peut être exécuté en l’interceptant, ou via try ... finally.

class Event

class asyncio.Event

Crée un nouvel événement pouvant servir à synchroniser des tâches. Les événements démarrent à l’état effacé.

is_set() → bool

Renvoie True si l’événement est positionné, False sinon.

set() → None

Positionne l’événement. Toutes les tâches en attente de l’événement seront planifiées pour exécution.

Remarque : ceci doit être appelé depuis une tâche. Il n’est pas sûr de l’appeler depuis une IRQ, une fonction de rappel de l’ordonnanceur ou un autre fil d’exécution. Voir ThreadSafeFlag.

clear() → None

Efface l’événement.

wait() → None

Attend que l’événement soit positionné. Si l’événement est déjà positionné, renvoie immédiatement.

Ceci est une coroutine.

class ThreadSafeFlag

class asyncio.ThreadSafeFlag

Crée un nouveau drapeau pouvant servir à synchroniser une tâche avec du code s’exécutant en dehors de la boucle asyncio, tel que d’autres fils d’exécution, des IRQ ou des fonctions de rappel de l’ordonnanceur. Les drapeaux démarrent à l’état effacé.

set() → None

Positionne le drapeau. Si une tâche est en attente du drapeau, elle sera planifiée pour exécution.

clear() → None

Efface le drapeau. Ceci peut servir à s’assurer qu’un drapeau éventuellement positionné auparavant est effacé avant de l’attendre.

wait() → None

Attend que le drapeau soit positionné. Si le drapeau est déjà positionné, renvoie immédiatement. Le drapeau est automatiquement réinitialisé au retour de wait.

Un drapeau ne peut être attendu que par une seule tâche à la fois.

Ceci est une coroutine.

class Lock

class asyncio.Lock

Crée un nouveau verrou pouvant servir à coordonner des tâches. Les verrous démarrent à l’état déverrouillé.

En plus des méthodes ci-dessous, les verrous peuvent être utilisés dans une instruction async with.

locked() → bool

Renvoie True si le verrou est verrouillé, False sinon.

acquire() → bool

Attend que le verrou soit à l’état déverrouillé puis le verrouille de manière atomique. Une seule tâche peut acquérir le verrou à un instant donné.

Ceci est une coroutine.

release() → None

Libère le verrou. Si des tâches sont en attente du verrou, la suivante dans la file est planifiée pour exécution et le verrou reste verrouillé. Sinon, aucune tâche n’est en attente et le verrou devient déverrouillé.

Connexions de flux TCP

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

Ouvre une connexion TCP vers le host et le port donnés. L’adresse host sera résolue à l’aide de socket.getaddrinfo(), qui est actuellement un appel bloquant. Si ssl est un objet ssl.SSLContext, ce contexte est utilisé pour créer le transport ; si ssl vaut True, un contexte par défaut est utilisé.

Renvoie une paire de flux : un flux lecteur et un flux écrivain. Lève une OSError spécifique à la socket si l’hôte n’a pas pu être résolu ou si la connexion n’a pas pu être établie.

Ceci est une coroutine.

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

Démarre un serveur TCP sur le host et le port donnés. Le callback sera appelé pour les connexions entrantes acceptées, et recevra 2 arguments : les flux lecteur et écrivain de la connexion.

Si ssl est un objet ssl.SSLContext, ce contexte est utilisé pour créer le transport.

Renvoie un objet Server.

Ceci est une coroutine.

class asyncio.Stream

Ceci représente une connexion de flux TCP. Pour minimiser le code, cette classe implémente à la fois un lecteur et un écrivain, et StreamReader et StreamWriter sont tous deux des alias de cette classe.

get_extra_info(v: str) → Any

Obtient des informations supplémentaires sur le flux, indiquées par v. Les valeurs valides pour v sont : peername.

close() → None

Ferme le flux.

wait_closed() → None

Attend la fermeture du flux.

Ceci est une coroutine.

read(n: int = -1) → bytes

Lit jusqu’à n octets et les renvoie. Si n n’est pas fourni ou vaut -1, lit tous les octets jusqu’à EOF. La valeur renvoyée sera un objet bytes vide si EOF est rencontré avant qu’aucun octet n’ait été lu.

Ceci est une coroutine.

readinto(buf: bytearray | memoryview) → int

Lit jusqu’à n octets dans buf, n étant égal à la longueur de buf.

Renvoie le nombre d’octets lus dans buf.

Ceci est une coroutine, ainsi qu’une extension MicroPython.

readexactly(n: int) → bytes

Lit exactement n octets et les renvoie sous forme d’objet bytes.

Lève une exception EOFError si le flux se termine avant la lecture de n octets.

Ceci est une coroutine.

readline() → bytes

Lit une ligne et la renvoie.

Ceci est une coroutine.

write(buf: bytes) → None

Accumule buf dans le tampon de sortie. Les données ne sont vidées que lorsque Stream.drain() est appelée. Il est recommandé d’appeler Stream.drain() immédiatement après l’appel de cette fonction.

drain() → None

Vide (écrit) toutes les données de sortie mises en tampon vers le flux.

Ceci est une coroutine.

class asyncio.Server

Ceci représente la classe de serveur renvoyée par start_server(). Elle peut être utilisée dans une instruction async with pour fermer le serveur à la sortie.

close() → None

Ferme le serveur.

wait_closed() → None

Attend la fermeture du serveur.

Ceci est une coroutine.

Boucle d’événements

asyncio.get_event_loop() → Loop

Renvoie la boucle d’événements utilisée pour planifier et exécuter les tâches. Voir Loop.

asyncio.new_event_loop() → Loop

Réinitialise la boucle d’événements et la renvoie.

Remarque : étant donné que MicroPython ne possède qu’une seule boucle d’événements, cette fonction réinitialise uniquement l’état de la boucle, elle n’en crée pas de nouvelle.

class asyncio.Loop

Ceci représente l’objet qui planifie et exécute les tâches. Il ne peut pas être créé ; utilisez get_event_loop() à la place.

create_task(coro: Coroutine) → Task

Crée une tâche à partir du coro donné et renvoie le nouvel objet Task.

run_forever() → None

Exécute la boucle d’événements jusqu’à ce que stop() soit appelée.

run_until_complete(awaitable: Awaitable) → Any

Exécute l”awaitable donné jusqu’à son achèvement. Si l”awaitable n’est pas une tâche, il sera promu en tâche.

stop() → None

Arrête la boucle d’événements.

close() → None

Ferme la boucle d’événements.

set_exception_handler(handler: Callable) → None

Définit le gestionnaire d’exceptions à appeler lorsqu’une tâche lève une exception qui n’est pas interceptée. Le handler doit accepter deux arguments : (loop, context).

get_exception_handler() → Callable | None

Obtient le gestionnaire d’exceptions actuel. Renvoie le gestionnaire, ou None si aucun gestionnaire personnalisé n’est défini.

default_exception_handler(context: dict) → None

Le gestionnaire d’exceptions par défaut qui est appelé.

call_exception_handler(context: dict) → None

Appelle le gestionnaire d’exceptions actuel. L’argument context est transmis tel quel et est un dictionnaire contenant les clés : 'message', 'exception', 'future'.