asyncio — escalonador de I/O assíncrono

Este módulo fornece um escalonador de multitarefa cooperativa para corrotinas async/await, juntamente com primitivos de sincronização (bloqueios, eventos) e rede TCP não bloqueante via leitores e escritores de fluxo. As tarefas são executadas de forma concorrente num único ciclo de eventos; a tarefa em execução cede o controlo ao ciclo com await.

Exemplo:

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

Funções principais

asyncio.create_task(coro: Coroutine) → Task

Cria uma nova tarefa a partir da corrotina indicada e agenda a sua execução.

Devolve o objeto Task correspondente.

asyncio.current_task() → Task

Devolve o objeto Task associado à tarefa em execução no momento.

asyncio.run(coro: Coroutine) → Any

Cria uma nova tarefa a partir da corrotina indicada e executa-a até à conclusão.

Devolve o valor devolvido por coro.

asyncio.sleep(t: float) → None

Aguarda t segundos (pode ser um número de vírgula flutuante).

Esta é uma corrotina.

asyncio.sleep_ms(t: int) → None

Aguarda t milissegundos.

Esta é uma corrotina e uma extensão MicroPython.

Funções adicionais

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

Aguarda a conclusão do awaitable, mas cancela-o se demorar mais de timeout segundos. Se awaitable não for uma tarefa, será criada uma tarefa a partir dele.

Se ocorrer um tempo limite, a tarefa é cancelada e é lançada a exceção asyncio.TimeoutError: esta deve ser tratada pelo chamador. A tarefa recebe asyncio.CancelledError, que pode ser ignorada ou tratada com try...except ou try...finally para executar código de limpeza.

Devolve o valor de retorno de awaitable.

Esta é uma corrotina.

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

Semelhante a wait_for(), mas timeout é um inteiro em milissegundos.

Esta é uma corrotina e uma extensão MicroPython.

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

Executa todos os awaitables de forma concorrente. Os awaitables que não sejam tarefas são promovidos a tarefas.

Devolve uma lista com os valores de retorno de todos os awaitables.

Esta é uma corrotina.

class Task

class asyncio.Task

Este objeto encapsula uma corrotina numa tarefa em execução. As tarefas podem ser aguardadas com await task, o que aguardará a conclusão da tarefa e devolverá o seu valor de retorno.

As tarefas não devem ser criadas diretamente; utilize create_task() para as criar.

cancel() → None

Cancela a tarefa injetando asyncio.CancelledError nela. A tarefa pode ignorar esta exceção. O código de limpeza pode ser executado capturando a exceção ou com try ... finally.

class Event

class asyncio.Event

Cria um novo evento que pode ser utilizado para sincronizar tarefas. Os eventos são iniciados no estado limpo.

is_set() → bool

Devolve True se o evento estiver definido, False caso contrário.

set() → None

Define o evento. Quaisquer tarefas à espera do evento serão agendadas para execução.

Nota: Este método deve ser chamado a partir de uma tarefa. Não é seguro chamá-lo a partir de uma IRQ, callback do escalonador ou outra thread. Consulte ThreadSafeFlag.

clear() → None

Limpa o evento.

wait() → None

Aguarda que o evento seja definido. Se o evento já estiver definido, retorna imediatamente.

Esta é uma corrotina.

class ThreadSafeFlag

class asyncio.ThreadSafeFlag

Cria uma nova bandeira que pode ser utilizada para sincronizar uma tarefa com código a executar fora do ciclo asyncio, como outras threads, IRQs ou callbacks do escalonador. As bandeiras são iniciadas no estado limpo.

set() → None

Define a bandeira. Se houver uma tarefa à espera da bandeira, esta será agendada para execução.

clear() → None

Limpa a bandeira. Pode ser utilizado para garantir que uma bandeira possivelmente definida anteriormente seja limpa antes de aguardar por ela.

wait() → None

Aguarda que a bandeira seja definida. Se a bandeira já estiver definida, retorna imediatamente. A bandeira é automaticamente reposta após o retorno de wait.

Uma bandeira só pode ser aguardada por uma única tarefa de cada vez.

Esta é uma corrotina.

class Lock

class asyncio.Lock

Cria um novo bloqueio que pode ser utilizado para coordenar tarefas. Os bloqueios são iniciados no estado desbloqueado.

Para além dos métodos abaixo, os bloqueios podem ser utilizados numa instrução async with.

locked() → bool

Devolve True se o bloqueio estiver bloqueado, False caso contrário.

acquire() → bool

Aguarda que o bloqueio esteja no estado desbloqueado e, em seguida, bloqueia-o de forma atómica. Apenas uma tarefa pode adquirir o bloqueio de cada vez.

Esta é uma corrotina.

release() → None

Liberta o bloqueio. Se houver tarefas à espera do bloqueio, a próxima na fila é agendada para execução e o bloqueio permanece bloqueado. Caso contrário, não há tarefas à espera e o bloqueio passa ao estado desbloqueado.

Ligações TCP de fluxo

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

Abre uma ligação TCP ao host e port indicados. O endereço de host será resolvido com socket.getaddrinfo(), que é atualmente uma chamada bloqueante. Se ssl for um objeto ssl.SSLContext, este contexto é utilizado para criar o transporte; se ssl for True, é utilizado um contexto predefinido.

Devolve um par de fluxos: um leitor e um escritor. Lançará um OSError específico de socket se o host não puder ser resolvido ou se a ligação não puder ser estabelecida.

Esta é uma corrotina.

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

Inicia um servidor TCP no host e port indicados. O callback será chamado com as ligações recebidas e aceites, recebendo 2 argumentos: fluxos de leitura e escrita para a ligação.

Se ssl for um objeto ssl.SSLContext, este contexto é utilizado para criar o transporte.

Devolve um objeto Server.

Esta é uma corrotina.

class asyncio.Stream

Representa uma ligação TCP de fluxo. Para minimizar o código, esta classe implementa tanto um leitor como um escritor, e tanto StreamReader como StreamWriter são alias desta classe.

get_extra_info(v: str) → Any

Obtém informações adicionais sobre o fluxo, indicadas por v. Os valores válidos para v são: peername.

close() → None

Fecha o fluxo.

wait_closed() → None

Aguarda que o fluxo seja fechado.

Esta é uma corrotina.

read(n: int = -1) → bytes

Lê até n bytes e devolve-os. Se n não for fornecido ou for -1, lê todos os bytes até ao EOF. O valor devolvido será um objeto bytes vazio se o EOF for encontrado antes de qualquer byte ser lido.

Esta é uma corrotina.

readinto(buf: bytearray | memoryview) → int

Lê até n bytes para buf, sendo n igual ao comprimento de buf.

Devolve o número de bytes lidos para buf.

Esta é uma corrotina e uma extensão MicroPython.

readexactly(n: int) → bytes

Lê exatamente n bytes e devolve-os como objeto bytes.

Lança uma exceção EOFError se o fluxo terminar antes de ler n bytes.

Esta é uma corrotina.

readline() → bytes

Lê uma linha e devolve-a.

Esta é uma corrotina.

write(buf: bytes) → None

Acumula buf no buffer de saída. Os dados só são enviados quando Stream.drain() é chamado. Recomenda-se chamar Stream.drain() imediatamente após chamar esta função.

drain() → None

Esvazia (escreve) todos os dados de saída em buffer para o fluxo.

Esta é uma corrotina.

class asyncio.Server

Representa a classe de servidor devolvida por start_server(). Pode ser utilizada numa instrução async with para fechar o servidor ao sair.

close() → None

Fecha o servidor.

wait_closed() → None

Aguarda que o servidor seja fechado.

Esta é uma corrotina.

Ciclo de Eventos

asyncio.get_event_loop() → Loop

Devolve o ciclo de eventos utilizado para agendar e executar tarefas. Consulte Loop.

asyncio.new_event_loop() → Loop

Reinicia o ciclo de eventos e devolve-o.

Nota: como o MicroPython tem apenas um único ciclo de eventos, esta função limita-se a repor o estado do ciclo, não cria um novo.

class asyncio.Loop

Representa o objeto que agenda e executa tarefas. Não pode ser criado diretamente; utilize get_event_loop() em vez disso.

create_task(coro: Coroutine) → Task

Cria uma tarefa a partir de coro e devolve o novo objeto Task.

run_forever() → None

Executa o ciclo de eventos até que stop() seja chamado.

run_until_complete(awaitable: Awaitable) → Any

Executa o awaitable indicado até à sua conclusão. Se awaitable não for uma tarefa, será promovido a uma.

stop() → None

Para o ciclo de eventos.

close() → None

Fecha o ciclo de eventos.

set_exception_handler(handler: Callable) → None

Define o tratador de exceções a chamar quando uma Task lança uma exceção não capturada. O handler deve aceitar dois argumentos: (loop, context).

get_exception_handler() → Callable | None

Obtém o tratador de exceções atual. Devolve o tratador, ou None se nenhum tratador personalizado estiver definido.

default_exception_handler(context: dict) → None

O tratador de exceções predefinido que é chamado.

call_exception_handler(context: dict) → None

Chama o tratador de exceções atual. O argumento context é passado diretamente e é um dicionário contendo as chaves: 'message', 'exception', 'future'.