11.5 `urllib2` -- Libreria estensibile per l'apertura delle URL

Il modulo urllib2 definisce funzioni e classi che aiutano nell'apertura di URL (in massima parte HTTP) in un mondo complesso: autenticazione di base e digest, redirezione e altro.

il modulo urllib2 definisce le seguenti funzioni:

urlopen( url[, data])

Apre l'URL url, che può essere sia una stringa che un oggetto Request (attualmente il codice verifica che sia realmente un'istanza Request, o un'istanza di una sotto classe di Request).

data dovrebbe essere una stringa, che specifica ulteriori dati da inviare al server. In una richiesta HTTP, che è l'unica a supportare data, dovrebbe essere un buffer nel formato di application/x-www-form-urlencoded, per esempio come quello restituito da urllib.urlencode().

La funzione restituisce un oggetto simile a file con due ulteriori metodi:

geturl() -- restituisce l'URL della risorsa recuperata
info() -- restituisce le meta informazioni della pagina, come un oggetto simile ad un dizionario

In caso di errore solleva l'eccezione URLError.

install_opener( opener): Installa un oggetto OpenerDirector nel predefinito opener. Il codice non verifica per un OpenerDirector reale, ed ogni classe con l'appropriata interfaccia sarà in grado di lavorare.

build_opener( [handler, ...])

Restituisce un'istanza di OpenerDirector, che concatena gli handler nell'ordine in cui vengono forniti. Gli handler possono essere sia istanze di BaseHandler, o sotto classi di BaseHandler (in tal caso è possibile chiamare il costruttore senza alcun parametro). Le istanze delle seguenti classi verranno inserite nelle prime posizioni nell'handler, fino a che l'handler stesso le conterrà, o conterrà istanze o sotto classi di loro stesse: ProxyHandler, UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, HTTPErrorProcessor.

Se l'installazione di Python ha il supporto SSL (se socket.ssl() esiste), verrà aggiunto anche HTTPSHandler.

A partire da Python 2.3, una sotto classe di BaseHandler può anche cambiare la propria variabile handler_order per modificare la sua posizione nella lista degli handler. Dopo ProxyHandler, che ha un handler_order del valore di 100, tutti gli handler vengono impostati a 500.

Le seguenti eccezioni vengono sollevate quando necessario:

exception URLError: Gli handler (NdT: gestori) sollevano questa eccezione (o l'eccezione derivata) quando incappano in un problema. Si tratta di una sotto classe di IOError.

exception HTTPError: Una sotto classe di URLError, può anche funzionare restituendo un valore simile a file non particolare (la stessa cosa restituita da urlopen()). Questo è utile quando si gestiscono errori HTTP particolari, come una richiesta di autenticazione.

exception GopherError: Una sotto classe di URLError, questo è un errore sollevato dall'handler del Gopher.

Sono disponibili le seguenti classi:

class Request( url[, data[, headers]]): Questa classe è una astrazione di una richiesta URL.
url dovrebbe essere una stringa che rappresenta una URL valida. Per una descrizione di data vedere la descrizione di add_data(). Gli headers dovrebbero essere un dizionario, e verranno trattati come quando add_header() viene chiamato con ogni chiave e valore per argomento.

class OpenerDirector( ): La classe OpenerDirector apre gli URL tramite BaseHandler congiuntamente. Gestisce il collegamento degli handler, ed il recupero dagli errori.

class BaseHandler( ): Questa è una classe di base per tutti gli handler registrati; e gestisce solo i semplici meccanismi di registrazione.

class HTTPDefaultErrorHandler( ): Una classe che definisce un handler predefinito per le risposte di errore HTTP; tutte le risposte sono convertite in eccezioni HTTPError.

class HTTPRedirectHandler( ): Una classe che gestisce le redirezioni.

class ProxyHandler( [proxies]): Fa sì che le richieste transitino attraverso un proxy. Se proxies viene indicato, deve essere un dizionario che mappi i nomi di protocollo in URL di proxy. Il predefinito è leggere la lista di proxy dalla variabili ambiente protocol_proxy.

class HTTPPasswordMgr( ): Mantiene un database di (realm, uri) -> (user, password) mappate.

class HTTPPasswordMgrWithDefaultRealm( ): Mantiene un database di (realm, uri) -> (user, password) mappati. Un insieme di None viene considerato un insieme catch-all (NdT: acchiappa tutto) che viene ricercato se nessun altro insieme corrisponde.

class AbstractBasicAuthHandler( [password_mgr]): Questa è una classe intermedia che aiuta con l'autenticazione HTTP, sia verso host remoti che verso proxy. password_mgr, se passata, dovrebbe essere qualcosa di compatibile con HTTPPasswordMgr; fare riferimento alla sezione 11.5.6 per informazioni sull'interfaccia che deve essere supportata.

class HTTPBasicAuthHandler( [password_mgr]): Gestisce l'autenticazione con l'host remoto. password_mgr, se passata, dovrebbe essere qualcosa di compatibile con HTTPPasswordMgr; fare riferimento alla sezione 11.5.6 per informazioni sulle interfacce che devono essere supportate.

class ProxyBasicAuthHandler( [password_mgr]): Gestisce l'autenticazione con il proxy. password_mgr, se passata, dovrebbe essere qualcosa di compatibile con HTTPPasswordMgr; fare riferimento alla sezione 11.5.6 per informazioni sull'interfaccia deve dev'essere supportata.

class AbstractDigestAuthHandler( [password_mgr]): Questa è una classe intermedia che aiuta con l'autenticazione HTTP, sia verso host remoti che verso proxy. password_mgr, se passata, dovrebbe essere qualcosa che sia compatibile con HTTPPasswordMgr; fare riferimento alla sezione 11.5.6 per informazioni circa l'interfaccia che deve essere supportata.

class HTTPDigestAuthHandler( [password_mgr]): Gestisce l'autenticazione con l'host remoto. password_mgr, se passata, dovrebbe essere qualcosa di compatibile con HTTPPasswordMgr; fare riferimento alla sezione 11.5.6 per informazioni sull'interfaccia che deve essere supportata.

class ProxyDigestAuthHandler( [password_mgr]): Gestisce le autenticazioni con il proxy. password_mgr, se passata, dovrebbe essere qualcosa di compatibile con HTTPPasswordMgr; fare riferimento alla sezione 11.5.6 per informazioni sull'interfaccia che deve essere supportata.

class HTTPHandler( ): Una classe che gestisce l'apertura di URL HTTP.

class HTTPSHandler( ): Una classe che gestisce l'apertura di URL HTTPS.

class FileHandler( ): Apre file locali.

class FTPHandler( ): Apre URL FTP.

class CacheFTPHandler( ): Apre URL FTP, mantenendo una cache delle connessioni FTP aperte per minimizzare i ritardi.

class GopherHandler( ): Apre URL gopher.

class UnknownHandler( ): Una classe acchiappa tutto per gestire URL non riconosciute.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.

11.5 urllib2 -- Libreria estensibile per l'apertura delle URL

11.5 `urllib2` -- Libreria estensibile per l'apertura delle URL