Pular para o conteúdo principal
Às vezes é muito útil ter listeners para requisições, permitindo implementar funcionalidades que precisam ser acionadas sempre que “algo” acontece em sua aplicação. Dois tipos de listeners foram adicionados para esse propósito.

​
Listener de Captura

Por exemplo, imagine que toda vez que é feita uma requisição à rota ‘/logs’, seu código execute uma tarefa que verifica se os novos logs diferem dos anteriores. Vamos ver como isso pode ser feito: 
import squarecloud as square
from squarecloud import Endpoint

@app.capture(endpoint=Endpoint.logs())
async def on_logs_request(before, after):
    if after != before:
        print(f'Novos logs!!! {after}')

async def main():
    client = square.Client(api_key='CHAVE_API')
    app = await client.app('id_aplicacao')

    await app.logs()  # True
    await app.logs()  # False
Como visto acima, ao usar o decorator app.capture em uma função, ela será chamada sempre que for feita uma requisição ao endpoint especificado. Os endpoints aceitos são APP_STATUS, LOGS ou BACKUP. Essa função deve receber dois parâmetros: — before (representa o estado após a requisição) — after (representa o estado antes da requisição) O tipo de dado retornado por before e after depende do endpoint que o listener está observando. Se for a rota APP_STATUS, receberá um StatusData; LOGS receberá um LogsData; e BACKUP receberá um BackupData. Como você deve ter notado no exemplo acima, na primeira comparação de logs, after != before retorna True. Isso ocorre porque after é igual a LogsData(logs=''), já que ainda não há nada armazenado no cache interno.
  • Se você usa discord.py ou algum fork, sabe que o que diferencia eventos é o nome das funções ao redor das quais o decorator é aplicado, mas aqui é diferente. Para saber qual rota da API o decorator deve observar, usamos o parâmetro endpoint, que recebe uma classe Endpoint. Portanto, o nome da função decorada fica a seu critério.
  • A função decorada pode ser qualquer tipo de callable: funções comuns, corrotinas ou até classes (__init__ será chamado).
  • Se o endpoint não for [Endpoint.app_status()], [Endpoint.logs()] ou [Endpoint.backup()], será retornado apenas um parâmetro response (do tipo squarecloud.http.Response).
Você pode usar o parâmetro avoid_listener=True para que o listener da aplicação não seja chamado.

​
Listener de Requisição

Os “request listeners” fazem praticamente a mesma coisa. Aqui você usa o [Client], e o retorno de todos os endpoints são objetos squarecloud.http.Response. 
import squarecloud as square
from squarecloud import Endpoint

@client.on_request(endpoint=Endpoint.logs())
async def on_logs_request(response):
    print(1, response)

async def main():
    client = square.Client(api_key='CHAVE_API')
    await client.get_logs(app_id='id_aplicacao')  # 1, Response(success)

​
Passando argumentos extras

Você pode passar alguns métodos o argumento nomeado extra, que será repassado ao seu listener 
import squarecloud as square
from squarecloud import Endpoint

@client.on_request(Endpoint.status())
async def get_extra_param(before, after, extra: dict[str, str]):
    print(extra)

async def main():
    client = square.Client(api_key='CHAVE_API')
    await client.app_status('id_aplicacao', extra={'name': 'robertinho'})
Você pode obter recursos legais em listeners usando pydantic em seu projeto, veja usando pydantic