tutorial: come utilizzare le api twitter (via python) e creare bot / app sul raspberry pi zero

Benvenuti!
Questo tutorial vi fornirà una panoramica sulle Twitter API, in particolare sulla libreria twython (scritta in python) che facilita il dialogo con il social network e consente di creare rapidamente applicazioni e bot capaci di agire in autonomia sulla piattaforma Twitter stessa.

Nota: il presente articolo contiene una infarinatura generale ed alcuni dettagli sono stati tralasciati. Se volete approfondire, non esitate a lasciare un commento o a contattarmi sui canali social.

Prima di addentrarci, vi riporto il video di supporto a questa guida che ho pubblicato sul mio canale YouTube:

Inoltre vi segnalo che nella pagina dedicata troverete tutti i tutorial da me pubblicati.

1. l'attrezzatura minima per iniziare

Per adoperare le API Twitter occorrono:

• un Raspberry Pi qualsiasi (in questo tutorial viene utilizzato il modello Zero) + una microSD + un alimentatore (da almeno 2.1A)
• Raspbian OS Lite
• un PC per accedere via SSH al pi e sviluppare
• una connessione ad Internet per dialogare con il social network

Per quanto riguarda il primo punto non occorre altro: il Raspberry Pi verrà acceduto via SSH per la configurazione generale. Sarà invece indispensabile avere un alimentatore che eroghi in uscita almeno 2.1A.
Raspbian OS Lite è probabilmente la scelta migliore poiché è un sistema leggero, consuma poche risorse ed ha la possibilità di farci installare dai repository tutto il necessario.
Il PC sarà lo strumento con cui svilupperemo le applicazioni che saranno poi eseguite sul pi.
La connessione ad internet serve perché chiaramente si dovrà interagire con Twitter.

2. twython e i developer account

Come fortunatamente spesso accade, e visto che Twitter è uno dei social network più utilizzati al mondo, esistono delle librerie gratuite, open source e già pronte all'uso che consentono di interagire con esso e semplificano di molto la vita a chi voglia costruire BOT o applicazioni.

Una delle librerie che consentono di accedere rapidamente alle API esposte da Twitter è twython, scritta completamente in python ed installabile su raspberry pi in pochissimi minuti. Utilizzando Raspbian OS come sistema operativo si avrà già gran parte del necessario preinstallato, quindi sarà sufficiente sfruttare pip per recuperare l'unico pezzetto mancante, cioè la libreria stessa: collegati in SSH al pi, digitate pip install twython ed in poco tempo sarete già operativi.

Nota: nel qual caso non aveste pip, basterà aggiungerlo con sudo apt-get install python-pip così come se non aveste preinstallato python3 sarà sufficiente un sudo apt-get install python3

A questo punto manca un piccolo ma fondamentale passetto aggiuntivo: creare un account su Twitter (oppure, se ne avete già uno, utilizzare quello) ed accedere alla sezione per gli sviluppatori (https://apps.twitter.com). Questo passo vi permetterà di rendere l'account che avete scelto come un Developer Account.
Negli ultimi mesi Twitter ha deciso di eliminare le tonnellate di account fasulli ed utenti fake che da sempre popolano il social network, per questo la procedura di creazione degli account developer è stata leggermente rinforzata. Fatto sta che i passi indispensabili da compiere per poter accedere alle Twitter API sono:

1. se non lo avete fatto, inserire un numero di telefono valido associato all'account Twitter che state utilizzando (questo numero potrà poi essere rimosso in seguito);
2. accettare le varie condizioni d'uso proposte nella sezione Developer;
3. compilare la richiesta di abilitazione almeno all'uso individuale delle API (se non volete creare un qualcosa di commerciale), e qui c'è un form in cui indicare che cosa si vuole sviluppare, il proprio nome e qualche altra informazione secondaria
4. ora sarà possibile iniziare a creare una o più app.

Ad ogni utente possono essere associate una o più applicazioni che permettono di scrivere sulla timeline, oppure analizzare i messaggi che vengono inviati sullo stream pubblico di Twitter, e così via. E queste applicazioni, essendo a loro volta pubbliche, possono essere utilizzate da qualsiasi utente Twitter, compresi chiaramente i BOT che sono utenti come tutti gli altri ma capaci di vivere ed operare autonomamente.

Una volta creata la vostra app (formata solitamente da un titolo, un'icona, una descrizione, una URL di atterraggio obbligatoria ma non validata finché si rimane in fase di test, e qualche altra informazione secondaria), vanno recuperate le API key ed i token di accesso che consentiranno di interrogare le API di Twitter e allo stesso tempo accedere alla timeline dell'utente che utilizza l'app.

Nota: attenzione, queste informazioni sono strettamente riservate e non vanno condivise con nessuno. Nel qual caso doveste creare codice da distribuire o salvare online, evitate di lasciare memorizzate tali chiavi.

Il grosso, o comunque la parte più rognosa, è stata completata: c'è l'hardware su cui girerà il bot / app (cioè il pi), c'è la libreria che ci consente di interrogare le API di Twitter per fare quello che si desidera (cioè twython), e ci sono le chiavi di accesso / autenticazione per interrogare con successo le API esposte dal social network e scrivere nella timeline oppure leggere dal firehose dei messaggi pubblici.

3. esempi di applicazioni

Tutte le applicazioni che sfruttano le API Twitter devono utilizzare le API key e token di accesso generati nel punto 2. Queste informazioni possono essere inserite in un file dedicato (che può banalmente essere chiamato auth.py) in cui inserire le 4 chiavi richieste. A quel punto è possibile spostarsi su altri file che conterranno il codice vero e proprio delle app che interagiranno con Twitter.

Creato quindi il file auth.py con le chiavi ed inizializzato un nuovo file python in cui si scriverà il codice della applicazione, il primo passo è quello di importare la libreria twython e dal file auth.py (se lo avete così nominato) le chiavi memorizzate:

from twython import Twython
from auth import (
    consumer_key,
    consumer_secret,
    access_token,
    access_token_secret
)

A questo punto è possibile sfruttare la libreria twython ad esempio per inviare un primo messaggio di testo. E per farlo occorre dapprima instanziare la libreria stessa all'interno di una variabile (passandogli le chiavi di autenticazione), quindi preparare il messaggio che si vuole twittare e sfruttare la funzione update_status fornita dalla libreria stessa che consente di aggiornare lo stato dell'utente scrivendo nella sua timeline.

[...] #import
twitter = Twython(
    consumer_key,
    consumer_secret,
    access_token,
    access_token_secret
)
message = "Ciao a tutti da geekonerd.xyz!"
twitter.update_status(status=message)
print("Messaggio twittato: %s" % message)

Salvato il tutto, tramite il comando python3 twitter.py (se questo è il nome del file contenente la logica appena descritta) verrà inviato il nuovo status. Dal browser web, accedendo al profilo dell'utente che sta utilizzando l'app sviluppata, dovrebbe poter essere visibile il tweet.


Ovviamente si può fare molto di più, ad esempio allegare al tweet una immagine o un video, ed ovviamente la libreria offre delle funzioni che consentono di fare proprio ciò.
Tornando sul codice, prima della riga in cui viene chiamata la update_status è possibile aggiungere una variabile image che conterrà l'immagine stessa da allegare al tweet, immagine che sarà caricata con la funzione open che accetta due parametri: il path dell'immagine ed i permessi di lettura. Supponendo che l'immagine si trovi nella stessa cartella del python contenente l'applicazione che si sta costruendo, basterà indicarne il nome e poi specificare che dovrà essere aperto in sola lettura (r) quel file binario (b).

[...] #import e instanziamento della libreria
message = "Ciao a tutti da geekonerd.xyz! Con una immagine allegata:"
image = open('path/to/image.jpg', 'rb')

Il file in questione andrà caricato su Twitter, e la libreria twython fornisce una funzione apposita: upload_media che accetta un parametro che è proprio la variabile image in cui abbiamo aperto il file. Questa funzione dà una risposta che contiene l'ID che Twitter avrà associato al file caricato. Tale ID si trova all'interno dell'array restituito, sotto la chiave media_id. Conviene quindi salvare la risposta ottenuta in una variabile response.

[...] #import, instanziamento, messaggio e caricamento file
response = twitter.upload_media(media=image)
media_id = [response['media_id']]

Nota: è possibile abbinare fino a 4 immagini per un singolo tweet, ma per testare la funzionalità al momento ne invieremo soltanto una.

A questo punto va modificata funzione update_status aggiungendo un secondo parametro che è l'array contenente tutte le immagini da abbinare al tweet (in questo caso soltanto una). Quindi update_status avrà per secondo parametro media_ids che sarà proprio l'array contenente tutti gli ID delle immagini già caricate ed ottenuti da Twitter stesso.

[...] #import, instanziamento, messaggio, caricamento file e recupero ID
twitter.update_status(status=message, media_ids=media_id)

Salvare il file e avviare l'app con lo stesso comando di prima: una volta completato l'upload è possibile controllare nel profilo dell'utente se sulla sua timeline sarà apparso il nuovo messaggio con tanto di immagine abbinata.

4. streamer

Finora sono state inviate informazioni solamente verso Twitter, cosa chiaramente importante per dialogare con l'esterno. Ma, ancora più interessante, è poter catturare i messaggi inviati dagli altri utenti, ed eseguire azioni in base al loro contenuto. Si potrebbe creare un BOT che retweetti in automatico tutti i messaggi contenenti una determinata parola chiave, oppure una app che permetta di inserire in una lista privata o condivisa -automaticamente- specifici tweet, e così via. Qui, chiaramente, l'immaginazione è l'unico limite...

Per poter leggere dallo stream i contenuti che vengono costantemente pubblicati su Twitter, occorre utilizzare una funzionalità ben precisa della libreria twython: lo streamer.
TwythonStreamer va incorporato nel codice tramite uno specifico import e, per continuare con i test, conviene creare un nuovo file python dedicato a questa applicazione. Al suo interno va aggiunto l'import per lo streamer e replicato l'import delle chiavi di autenticazione.

from twython import TwythonStreamer
from auth import (
    consumer_key,
    consumer_secret,
    access_token,
    access_token_secret
)

Affinché sia possibile compiere azioni custom, TwythonStreamer richiede l'implementazione di una classe che lo estenda. Si può creare una classe, denominata ad esempio MyStreamer, che appunto estende quella fornita dalla libreria: essa potrà sovrascrivere il metodo on_success che viene chiamato ogni qualvolta lo streamer rileva un tweet di interesse per eseguire una azione personalizzata. Il metodo on_success ha due parametri, di cui il secondo sarà proprio il messaggio che è stato catturato dal social network e che viene restituito sotto forma di un array: in questo array una chiave conterrà i dati dell'utente che ha inviato il tweet, ed un'altra chiave il testo del tweet vero e proprio.

Per testare il funzionamento è possibile ad esempio stampare a video tutti i tweet che vengono inviati e che contengono una determinata parola di interesse. Nel metodo on_success della classe che estende TwythonStreamer si può analizzare l'array ricevuto con i dati dei tweet catturati dallo streamer, quindi estrarre il nickname dell'utente che ha scritto il messaggio ed il testo relativo.
La classe MyStreamer che estende quella fornita dalla libreria va instanziata passando sempre le chiavi di autenticazione, e poi va richiamanto il metodo statuses.filter per tracciare la parola ricercata (ad esempio "tutorial").

[...] #import
class MyStreamer(TwythonStreamer):
    def on_success(self, data):
        if 'text' in data:
            username = data['user']['screen_name]
            tweet = data['text]
            print("@{} : {}".format(username, tweet))

    def on_error(self, status_code, data):
        print(status_code)

stream = MyStreamer(
    consumer_key,
    consumer_secret,
    access_token,
    access_token_secret
)
stream.statuses.filter(track='tutorial')

Salvato il tutto, lanciare l'app con il comando python3 streamer.py (se questo è il nome del file python contenete il codice appena sviluppato) e rimanere in attesa che qualche utente -prima o poi, da questo istante- invii un messaggio contenente la parola richiesta.

5. conclusioni ed ultime note

In questa guida abbiamo visto come scrivere sulla timeline di un utente associato ad una app Twitter oppure leggere in tempo reale dallo stream di Twitter grazie a codici python in esecuzione su un raspberry pi zero. Potenzialmente sarà possibile inviare messaggi a comando in base ad informazioni ricevute, oppure fare tanto altro ancora.

La libreria Twython offre una piccola guida all'uso delle funzioni offerte, con tanto di esempi e maggiori dettagli. Ancora più importante, però, è dare uno sguardo alle API vere e proprie di Twitter, perché contengono tutto ciò che è possibile fare e come farlo in modo corretto. Twython offre alcuni metodi che mappano una parte dell'infinità delle operazioni fattibili tramite API dirette, ed alcune cose non sono ancora presenti, anche se tale libreria viene costantemente e frequentemente aggiornata.
In ogni caso, grosso modo, tutto ciò che riguarda le Streaming API e le Core API (quindi timeline, messaggi diretti, profilo, ricerca, liste e quant'altro) è già presente. Ed è anche possibile recuperare i tweet sotto forma di codice HTML cosicché possano essere inclusi in pagine web con facilità.


Bene: come indicato ad inizio guida, alcuni aspetti sono stati lasciati in secondo piano, ma se siete interessati ad approfondirli non esitate a contattarmi nei commenti di questo tutorial o del video ad esso correlato, oppure sui canali social!

Spero che la guida vi sia stata utile. Al prossimo tutorial!