`asyncio` — agendador de E/S assíncrona¶

Este módulo fornece um agendador de multitarefa cooperativa para corrotinas async/await, juntamente com primitivas para sincronização (locks, events) e rede TCP não bloqueante por meio de stream readers e writers. As tarefas são executadas concorrentemente em um único loop de eventos; a tarefa em execução cede o controle de volta ao loop 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 fornecida e a agenda para execução.

Retorna o objeto Task correspondente.

asyncio.current_task() → Task¶: Retorna o objeto Task associado à tarefa atualmente em execução.

asyncio.run(coro: Coroutine) → Any¶

Cria uma nova tarefa a partir da corrotina fornecida e a executa até que ela seja concluída.

Retorna o valor retornado por coro.

asyncio.sleep(t: float) → None¶

Dorme por t segundos (pode ser um float).

Esta é uma corrotina.

asyncio.sleep_ms(t: int) → None¶

Dorme por t milissegundos.

Esta é uma corrotina e uma extensão do MicroPython.

Funções adicionais¶

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

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

Se ocorrer um timeout, a tarefa é cancelada e asyncio.TimeoutError é levantada: isso deve ser tratado pelo chamador. A tarefa recebe asyncio.CancelledError, que pode ser ignorada ou tratada usando try...except ou try...finally para executar código de limpeza.

Retorna 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 do MicroPython.

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

Executa todos os awaitables concorrentemente. Quaisquer awaitables que não sejam tarefas são promovidos a tarefas.

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

Esta é uma corrotina.

class Task¶

class asyncio.Task¶

Este objeto envolve uma corrotina em uma tarefa em execução. É possível aguardar tarefas usando await task, o que aguardará a conclusão da tarefa e retornará o valor de retorno dela.

As tarefas não devem ser criadas diretamente; em vez disso, use create_task() para criá-las.

cancel() → None¶: Cancela a tarefa injetando asyncio.CancelledError nela. A tarefa pode ignorar essa exceção. Código de limpeza pode ser executado ao tratá-la ou por meio de try ... finally.

class Event¶

class asyncio.Event¶

Cria um novo event que pode ser usado para sincronizar tarefas. Os events começam no estado limpo (cleared).

is_set() → bool¶: Retorna True se o event estiver definido (set), False caso contrário.

set() → None¶

Define o event. Quaisquer tarefas aguardando o event serão agendadas para execução.

Nota: isto deve ser chamado de dentro de uma tarefa. Não é seguro chamá-lo a partir de uma IRQ, de um callback do agendador ou de outra thread. Veja ThreadSafeFlag.

clear() → None¶: Limpa o event.

wait() → None¶

Aguarda o event ser definido. Se o event já estiver definido, retorna imediatamente.

Esta é uma corrotina.

class ThreadSafeFlag¶

class asyncio.ThreadSafeFlag¶

Cria um novo flag que pode ser usado para sincronizar uma tarefa com código que executa fora do loop do asyncio, como outras threads, IRQs ou callbacks do agendador. Os flags começam no estado limpo (cleared).

set() → None¶: Define o flag. Se houver uma tarefa aguardando o flag, ela será agendada para execução.

clear() → None¶: Limpa o flag. Isso pode ser usado para garantir que um flag possivelmente definido anteriormente esteja limpo antes de aguardá-lo.

wait() → None¶

Aguarda o flag ser definido. Se o flag já estiver definido, retorna imediatamente. O flag é automaticamente redefinido ao retornar de wait.

Um flag só pode ser aguardado por uma única tarefa de cada vez.

Esta é uma corrotina.

class Lock¶

class asyncio.Lock¶

Cria um novo lock que pode ser usado para coordenar tarefas. Os locks começam no estado desbloqueado (unlocked).

Além dos métodos abaixo, os locks podem ser usados em uma instrução async with.

locked() → bool¶: Retorna True se o lock estiver bloqueado, caso contrário False.

acquire() → bool¶

Aguarda o lock estar no estado desbloqueado e então o bloqueia de forma atômica. Apenas uma tarefa pode adquirir o lock por vez.

Esta é uma corrotina.

release() → None¶: Libera o lock. Se houver tarefas aguardando o lock, a próxima na fila é agendada para execução e o lock permanece bloqueado. Caso contrário, não há tarefas aguardando e o lock fica desbloqueado.

Conexões de stream TCP¶

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

Abre uma conexão TCP para o host e a port fornecidos. O endereço host será resolvido usando socket.getaddrinfo(), que atualmente é uma chamada bloqueante. Se ssl for um objeto ssl.SSLContext, esse contexto é usado para criar o transporte; se ssl for True, um contexto padrão é usado.

Retorna um par de streams: um stream de leitura (reader) e um de escrita (writer). Levantará um OSError específico de socket se o host não puder ser resolvido ou se a conexã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 na port fornecidos. O callback será chamado para conexões aceitas e recebidas, e receberá 2 argumentos: os streams de leitura (reader) e de escrita (writer) da conexão.

Se ssl for um objeto ssl.SSLContext, esse contexto é usado para criar o transporte.

Retorna um objeto Server.

Esta é uma corrotina.

class asyncio.Stream¶

Isto representa uma conexão de stream TCP. Para minimizar o código, esta classe implementa tanto um reader quanto um writer, e tanto StreamReader quanto StreamWriter são apelidos (alias) para esta classe.

get_extra_info(v: str) → Any¶: Obtém informações extras sobre o stream, dadas por v. Os valores válidos para v são: peername.

close() → None¶: Fecha o stream.

wait_closed() → None¶

Aguarda o stream ser fechado.

Esta é uma corrotina.

read(n: int = -1) → bytes¶

Lê até n bytes e os retorna. Se n não for fornecido ou for -1, lê todos os bytes até EOF. O valor retornado será um objeto bytes vazio se EOF for encontrado antes que algum byte seja lido.

Esta é uma corrotina.

readinto(buf: bytearray | memoryview) → int¶

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

Retorna o número de bytes lidos em buf.

Esta é uma corrotina e uma extensão do MicroPython.

readexactly(n: int) → bytes¶

Lê exatamente n bytes e os retorna como um objeto bytes.

Levanta uma exceção EOFError se o stream terminar antes de ler n bytes.

Esta é uma corrotina.

readline() → bytes¶

Lê uma linha e a retorna.

Esta é uma corrotina.

write(buf: bytes) → None¶: Acumula buf no buffer de saída. Os dados só são descarregados quando Stream.drain() é chamado. Recomenda-se chamar Stream.drain() imediatamente após chamar esta função.

drain() → None¶

Descarrega (escreve) todos os dados de saída em buffer para o stream.

Esta é uma corrotina.

class asyncio.Server¶

Isto representa a classe de servidor retornada por start_server(). Ela pode ser usada em uma instrução async with para fechar o servidor ao sair.

close() → None¶: Fecha o servidor.

wait_closed() → None¶

Aguarda o servidor ser fechado.

Esta é uma corrotina.

Loop de Eventos¶

asyncio.get_event_loop() → Loop¶: Retorna o loop de eventos usado para agendar e executar tarefas. Veja Loop.

asyncio.new_event_loop() → Loop¶

Redefine o loop de eventos e o retorna.

Nota: como o MicroPython possui apenas um único loop de eventos, esta função apenas redefine o estado do loop, não criando um novo.

class asyncio.Loop¶

Isto representa o objeto que agenda e executa tarefas. Ele não pode ser criado; use get_event_loop() em vez disso.

create_task(coro: Coroutine) → Task¶: Cria uma tarefa a partir do coro fornecido e retorna o novo objeto Task.

run_forever() → None¶: Executa o loop de eventos até que stop() seja chamado.

run_until_complete(awaitable: Awaitable) → Any¶: Executa o awaitable fornecido até que ele seja concluído. Se awaitable não for uma tarefa, ele será promovido a uma.

stop() → None¶: Para o loop de eventos.

close() → None¶: Fecha o loop de eventos.

set_exception_handler(handler: Callable) → None¶: Define o manipulador de exceções a ser chamado quando uma Task levantar uma exceção que não seja capturada. O handler deve aceitar dois argumentos: (loop, context).

get_exception_handler() → Callable | None¶: Obtém o manipulador de exceções atual. Retorna o manipulador, ou None se nenhum manipulador personalizado estiver definido.

default_exception_handler(context: dict) → None¶: O manipulador de exceções padrão que é chamado.

call_exception_handler(context: dict) → None¶: Chama o manipulador de exceções atual. O argumento context é repassado e é um dicionário contendo as chaves: 'message', 'exception', 'future'.

asyncio — agendador de E/S assíncrona¶

Funções principais¶

Funções adicionais¶

class Task¶

class Event¶

class ThreadSafeFlag¶

class Lock¶

Conexões de stream TCP¶

Loop de Eventos¶

`asyncio` — agendador de E/S assíncrona¶