> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Listeners

> Scopri come usare i listeners nella tua applicazione tramite l'SDK python di squarecloud.

A volte è molto utile avere dei listeners per le richieste, che ti permettono di implementare funzionalità da richiamare ogni volta che "qualcosa" accade nella tua applicazione.

Per questo scopo sono stati aggiunti due tipi di listeners.

## Capture Listener

Ad esempio, immagina che ogni volta che viene effettuata una richiesta alla rotta '/logs', il mio codice esegua un'operazione che verifica se i nuovi log differiscono da quelli precedenti. Bene, vediamo come si può fare:

```python theme={null}
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'New logs!!! {after}')

async def main():
    client = square.Client('your api key')
    app = await client.app('application_id')

    await app.logs()  # True
    await app.logs()  # False
```

Come mostrato sopra, usando il decoratore app.capture su una funzione, questa funzione verrà chiamata ogni volta che viene effettuata una richiesta all'endpoint specificato nel decoratore. Gli endpoint accettati sono `APP_STATUS`, `LOGS` o `BACKUP`. Questa funzione dovrebbe accettare due parametri:

* `before` (rappresenta lo stato prima della richiesta)
* `after` (rappresenta lo stato dopo la richiesta)

Il tipo di dato restituito da `before` e `after` dipende da quale endpoint il listener sta "ascoltando". Se si tratta della rotta **APP\_STATUS**, riceverà uno `StatusData`, **LOGS** riceverà un `LogsData` e **BACKUP** riceverà un `BackupData`.

Come avrai notato nell'esempio sopra, la prima volta che avviene il confronto tra i log, `after != before` restituisce True. Questo accade proprio perché after è uguale a `LogsData(logs='')`, dato che non è ancora stato memorizzato nulla nella cache interna.

<Accordion title="Informazioni aggiuntive su questo decoratore">
  * Se usi discord.py o qualche suo fork (probabilmente lo usi), dovresti
    sapere che ciò che differenzia gli eventi è il nome
    delle funzioni che il decoratore avvolge, ma qui è diverso. Per sapere
    quale
    rotta API il decoratore deve "ascoltare", usiamo il parametro `endpopint`, che
    riceve una classe `Endpoint`, quindi il nome della funzione che il decoratore
    avvolge dipende da te.
  * La funzione che il decoratore avvolge può in realtà essere qualsiasi cosa che sia
    un callable. Questo include funzioni normali, coroutine e persino
    classi (`__init__` verrà chiamato).
  * Se l'endpoint non è un \[Endpoint.app\_status()], \[Endpoint.logs()] o \[Endpoint.backup()],
    verrà restituito solo un parametro `response` (di tipo `squarecloud.http.Response`).
</Accordion>

<Tip>
  Puoi usare il parametro `avoid_listener=True` affinché il listener dell'applicazione non venga chiamato.
</Tip>

## Request Listener

I "request listeners" fanno praticamente la stessa cosa. Ma qui usi il \[Client], e il valore restituito da tutti gli endpoint è un oggetto `squarecloud.http.Response`.

```python theme={null}
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('your api key')
    await client.get_logs(app_id='application_id')  # 1, Response(success)
```

## Passare argomenti aggiuntivi

Puoi passare ad alcuni metodi un argomento con parola chiave chiamato `extra`, che verrà passato al tuo listener

```python theme={null}
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('your api key')
    await client.app_status('application_id', extra={'name': 'robertinho'})
```

<Tip>Puoi ottenere alcune funzionalità interessanti nei listeners usando pydantic nel tuo progetto, dai un'occhiata a [using pydantic](./using_pydantic)</Tip>