Forse non lo sapete, ma uTorrent, ormai celebre client per il download dalla rete BitTorrent, dispone di potenti API. Con le API di uTorrent realizzare software che lavorino affiancati a uTorrent è veramente facile.
In questo articolo presentiamo un semplice script in Python 3.4 per interrogare uTorrent tramite API. Non è una classe generica ma una funzione che mostra il progresso dell’ultimo torrent in download.

Iniziamo la prefazione spiegando come abilitare le API di uTorrent e proseguiamo mostrando come funzionano.

Come abilitarle le API di uTorrent?

Abilitare le API è un gioco da ragazzi. E’ sufficiente andare nelle Impostazioni da Opzioni > Impostazioni.
Nella finestra che si apre, andiamo sulla voce Interfaccia Web e mettiamo una spunta su Abilita Interfaccia Web come mostrato in figura:

Interfaccia web uTorrent - API

Eventualmente è possibile consentire l’accesso all’interfaccia web di uTorrent solo da parte degli indirizzi IP selezionati. Possiamo impostare una password e impostare la porta d’ascolto per il web server.

Come funzionano le API?

Ogni richiesta che avviene sui vari endpoint disponibili restituisce una risposta in JSON.
La prima cosa da sapere è che, gli sviluppatori delle API, per evitare attacchi di tipo XRSF (Cross-site request forgery attacks) hanno introdotto un sistema d’autenticazione basato su token.

Per fare i primi test dopo aver attivato la Web UI potete andare al seguente indirizzo:

http://[IP_LOCALE]:[PORTA]/gui/token.html

e nel sorgente della pagina potete copiare il token (valido per un’intera sessione, se riavviate uTorrent sarà necessario ottenerne uno nuovo).

Sotto lo script in Python che permette di interagire con le WebApi di uTorrent.
L’unica dipendenza necessaria per l’esecuzione del nostro programma è la libreria “requests”, scaricabile gratuitamente.

Consigliamo l’installazione attraverso l’installer pip incluso di default nella versione Python 3.4 (quella attualmente utilizzata in questa guida). Il comando per installare requests, aperto il terminale, è il seguente:

python -m pip install requests

Ricordate prima ovviamente di recarvi nella cartella d’installazione di Python (nel mio caso C:\Python34\).

import requests # installare con C:\Python34\ > python -m pip install requests
import re
import socket
import time
#import json
 
hostname = socket.gethostname()
IP = socket.gethostbyname(hostname) # oppure scrivere manualmente ex. 192.168.1.7 (se vogliamo un altro host della rete)
 
UTORRENT_URL = 'http://%s:%s/gui/' % (IP, '2323')
UTORRENT_URL_TOKEN = '%stoken.html' % UTORRENT_URL
UTORRENT_TORRENT_LIST = UTORRENT_URL + '?list=1&'
REGEX_UTORRENT_TOKEN = r'<div[^>]*id=[\"\']token[\"\'][^>]*>([^<]*)</div>'
 
auth = requests.auth.HTTPBasicAuth('admin', 'admin')
json_data = ""
 
def progresso_torrent():
    global json_data
    l = requests.get(UTORRENT_TORRENT_LIST, auth=auth, cookies=cookies)
 
    json_data = l.text
    #data = json.loads(json_data) # non parsiamo il json, ma effettuiamo una semplice ricerca all'interno del documento.
    indice_start = json_data.find(',"Downloading', 0) + 2
    if indice_start > 5:
        indice_stop = json_data.find('"', indice_start)
        string_progresso = json_data[indice_start:indice_stop]
        perc_progresso = string_progresso.split()[1] # progresso in percentuale
 
        try:
          if type(float(perc_progresso)) is not float:
            perc_progresso = float(perc_progresso)
        except ValueError:
          perc_progresso = 0
    else:
        perc_progresso = 100
 
    print("Progresso torrent: "+str(perc_progresso)+"%")
    return perc_progresso
 
try:
    r = requests.get(UTORRENT_URL_TOKEN, auth=auth)
    #print(r)
 
    token = re.search(REGEX_UTORRENT_TOKEN, r.text).group(1)
    guid = r.cookies['GUID']
    cookies = dict(GUID = guid)
    print("Token uTorrent: "+ token)
    UTORRENT_TORRENT_LIST += ('token=%s' % token)
 
 
except requests.exceptions.ConnectionError:
    print("Connessione rifiutata, assicurati che le WebAPI uTorrent siano attive con porta e dati d'accesso corretti")
 
except requests.packages.urllib3.exceptions.ProtocolError:
    print("Errore protocollo")
 
# funzione per ottenere la lista di file su uTorrent...
 
'''
params = {'action':'add-file','token': token}
files = {'torrent_file': open('C:\\x.torrent', 'rb')}
r = requests.post(url=UTORRENT_URL, auth=auth, cookies=cookies, params=params, files=files)
'''
 
if __name__ == "__main__":
    mins = 1
    while mins:
            print(str(mins)+" richiesta")
 
            # stampiamo a schermo il progresso del torrent
            progresso_torrent()
            print("...")
 
            # Sleep for half a minute
            time.sleep(30)
            # Increment the mins total
            mins += 1

Lo script, una volta avviato, si collega automaticamente all’interfaccia web (che si presupponga sia sullo stesso PC da cui eseguiamo lo script python, altrimenti bisogna inserire manualmente l’indirizzo IP), e ottiene il token che userà per effettuare le richieste. La porta usata di default è la 2323. E i dati d’accesso sono admin e admin, rispettivamente username e password (che impostiamo noi da uTorrent!). Dopodichè ciclicamente (ogni 60 secondi) richiama la funzione progresso_torrent() che mostra il progresso dell’ultimo torrent in lista.

Per qualsiasi delucidazione o se volete segnalare un bug, commentate sotto.