Classe Task

7.1 Criando tarefas

A classe Task no módulo asyncio é usada para gerenciar a execução de corrotinas. As tarefas (Tasks) são um tipo de invólucro para corrotinas, permitindo gerenciar sua execução e acompanhar seu estado. A classe Task permite rodar corrotinas em paralelo, gerenciando-as através do loop de eventos.

Métodos principais da classe Task

A classe Task é um tipo de invólucro sobre uma corrotina, que oferece as seguintes capacidades adicionais:

Gerenciamento de execução de corrotinas:

As tarefas permitem gerenciar facilmente a execução de corrotinas, controlar seu estado e obter resultados.

Cancelamento de tarefas:

A capacidade de cancelar tarefas torna o Task útil para gerenciar operações longas que podem precisar ser interrompidas antes da conclusão.

Callbacks:

As tarefas suportam a adição de callbacks, permitindo realizar ações adicionais quando as tarefas forem concluídas.

Criando tarefas:

Tarefas são criadas usando a função asyncio.create_task(coroutine) ou o método loop.create_task(coroutine), que agenda a execução da corrotina.

import asyncio

async def say_hello():
    print("Hello")
    await asyncio.sleep(1)
    print("World")
            
async def main():
    task = asyncio.create_task(say_hello())
    await task
            
asyncio.run(main())

7.2 Métodos Principais

Método Task.cancel():

Solicita o cancelamento da tarefa. Se a tarefa ainda não foi concluída, ela será concluída com uma exceção CancelledError.

Vamos escrever um pequeno programa que permita demonstrar isso.

1. Criar uma tarefa assíncrona que irá simplesmente esperar 10 segundos
2. Envolvê-la em um objeto Task
3. Esperar um segundo para que a tarefa (Task) comece a ser executada
4. Cancelar a tarefa – task.cancel()
5. Se tentarmos esperar pela conclusão da tarefa (Task) com o operador await, obteremos uma exceção CancelledError.

import asyncio

async def main():
    task = asyncio.create_task(asyncio.sleep(10)) 
    await asyncio.sleep(1)
    task.cancel()
    try:
        await task
    except asyncio.CancelledError:
        print("Task was cancelled")
            
asyncio.run(main())

Método Task.result():

Retorna o resultado da execução da tarefa. Se a tarefa foi concluída com uma exceção, ela será lançada ao chamar result().

import asyncio

async def main():
    task = asyncio.create_task(asyncio.sleep(1, result='Completed'))
    result = await task
    print(result)  # Output: Completed
            
asyncio.run(main())

No nosso caso, nem foi preciso escrever código adicional — o operador await sabe como trabalhar com o objeto Task: após a execução da tarefa, ele chamará o método result() e retornará o resultado obtido.

Método Task.exception():

Retorna a exceção levantada pela tarefa. Se a tarefa foi concluída sem exceção, retorna None.

import asyncio

async def main():
    task = asyncio.create_task(asyncio.sleep(1))
    try:
        result = await task
    except Exception as e:
        print(f"Task failed with exception: {e}")

asyncio.run(main())

Também não é necessário escrever código adicional — se ocorrer uma exceção na tarefa, o método exception() será chamado pelo operador await.

Método Task.add_done_callback(callback):

Adiciona um callback que será chamado quando a tarefa for concluída.

import asyncio

def callback(future):
    print("Task completed")
            
async def main():
    task = asyncio.create_task(asyncio.sleep(1))
    task.add_done_callback(callback)
    await task
            
asyncio.run(main())

Uma função pode ser adicionada à tarefa, que será automaticamente chamada quando a tarefa for concluída. Esta abordagem permite tornar o código muito flexível. Além disso, várias funções podem ser adicionadas, e você pode adicioná-las a qualquer tarefa.

Método Task.done():

Retorna True se a tarefa foi concluída (com sucesso, com erro ou foi cancelada).

import asyncio

async def main():
    task = asyncio.create_task(asyncio.sleep(1))
    await asyncio.sleep(1.5)
    print(task.done())  # Output: True
            
asyncio.run(main())

Com o método done() podemos verificar se a tarefa foi concluída com sucesso. Mais precisamente, se ela foi concluída ou cancelada, porque se ocorrer uma exceção, formalmente a tarefa pode não ter sido concluída, mas também não foi cancelada. Em geral, se a tarefa foi cancelada (cancel), o método retornará False, caso contrário retornará True.