11.4 `urllib` -- Apertura di risorse arbitrarie tramite URL

Questo modulo fornisce un'interfaccia di alto livello per estrarre dati attraverso il World Wide Web. In particolare, la funzione urlopen() è simile alla funzione built-in open(), ma accetta Universal Resurce Locators (URL) invece dei nomi di file. Vengono applicate alcune restrizioni: può aprire solo URL in lettura, e non sono disponibili funzioni di seek.

Definisce le seguenti funzioni pubbliche:

urlopen( url[, data[, proxies]])

Apre un oggetto di rete denotato da una URL in lettura. Se l'URL non possiede uno schema identificativo, o se ha un file: come per lo schema identificativo, apre un file locale (senza i fine riga universali); altrimenti apre un socket verso un server da qualche parte nella rete. Se la connessione non può essere instaurata, o se il server restituisce un codice di errore, viene sollevata l'eccezione IOError. Se tutto va bene, viene restituito un oggetto simile a file. Questo supporterà i seguenti metodi: read(), readline(), readlines(), fileno(), close(), info() e geturl(). Inoltre possiede un proprio supporto per il protocollo di iterazione. Un ammonimento: il metodo read(), se la dimensione dell'argomento viene omessa o è negativa, può non riuscire a leggere fino alla fine del flusso di dati; questa non è una soluzione adatta a determinare che l'intero flusso di dati proveniente dal socket venga letto in casi generali.

Ad eccezione di info() e geturl(), questi metodi possiedono la stessa interfaccia di un oggetto file -- vedere la sezione 2.3.9 di questo manuale. (Non è un oggetto file built-in, comunque, cosìcché non può essere usato in quelle poche situazioni dove è richiesto un vero oggetto file built-in.)

Il metodo info() restituisce un'istanza della classe mimetools.Message contenente meta informazioni associate all'URL. Quando il metodo è HTTP, queste intestazioni sono quelle restituite dal server all'inizio della pagina HTML recuperata (incluso Content-Length e Content-Type). Quando il metodo è FTP restituisce la richiesta. Una intestazione Content-Type sarà presente se il tipo MIME può essere analizzato. Quando il metodo è un file locale, le intestazioni restituite includeranno una rappresentazione Date dell'ora dell'ultima modifica al file, un Content-Lenght indicante la dimensione del file, ed un Content-Type contenente un riferimento al tipo di file. Vedere anche la descrizione del modulo mimetools.

Il metodo geturl() restituisce l'URL reale della pagina. In alcuni casi, il server HTTP redirige un client verso un altra URL. La funzione urlopen() lo gestisce in modo trasparente, ma in alcuni casi il chiamante ha la necessità di sapere verso quale URL è stato rediretto il client. Il metodo geturl() può anche essere usato per posizionarsi su questa URL rediretta.

Se l'url utilizza lo schema identificativo http: l'argomento facoltativo data può essere indicato per specificare una richiesta POST (normalmente il tipo di richiesta è GET). L'argomento data deve essere nel formato standard application/x-www-form-urlencoded; vedere sotto alla funzione urlencode().

La funzione urlopen() lavora in modo trasparente con i proxy che non richiedono autenticazione. In un ambiente Unix o Windows, impostare le variabili d'ambiente http_proxy, ftp_proxy o gopher_proxy alla URL che identifica il proxy server prima di avviare l'interprete Python. Per esempio (il "%" è il comando del prompt):

% http_proxy="http://www.someproxy.com:3128"
% export http_proxy
% python
...

In un ambiente Windows, se le variabili ambiente di proxy non sono impostate, l'impostazione del proxy sono ottenute dalla sezione delle impostazioni Internet del registro.

In un ambiente Macintosh, urlopen() recupererà le informazioni sul proxy da Internet Config.

Alternativamente, l'argomento facoltativo proxies può essere usato per specificare esplicitamente i proxy. Deve essere un dizionario con lo schema dei nomi delle URL del proxy mappati, un dizionario vuoto ottiene il risultato di non permettere l'uso di alcun proxy, e None (il valore predefinito) causa l'uso delle impostazioni proxy dell'ambiente, come discusso precedentemente. Per esempio:

# Usa http://www.someproxy.com:3128 come http proxy
proxies = proxies={'http': 'http://www.someproxy.com:3128'}
filehandle = urllib.urlopen(some_url, proxies=proxies)
# Non usa alcun proxy
filehandle = urllib.urlopen(some_url, proxies={})
# Usa i proxy dall'ambiente - entrambe le versioni sono equivalenti
filehandle = urllib.urlopen(some_url, proxies=None)
filehandle = urllib.urlopen(some_url)

La funzione urlopen() non supporta la specifica esplicita del proxy. Se si ha la necessità di sovrascrivere l'impostazione d'ambiente del proxy, si usi URLopener, o una sua sotto classe come FancyURLopener.

I proxy che richiedono l'autenticazione per il loro utilizzo, non sono attualmente supportati; questa è considerata una implementazione limitata.

Modificato nella versione 2.3: Added the proxies support.

urlretrieve( url[, filename[, reporthook[, data]]])

Copia un oggetto di rete denotato da una URL verso un file locale, se necessario. Se la URL punta ad un file locale, o se esiste una copia valida dell'oggetto, l'oggetto non viene copiato. Restituisce una tupla (filename, headers) dove filename è il nome del file locale in cui l'oggetto può essere trovato, e headers è qualsiasi cosa il metodo info() dell'oggetto restituito da urlopen() restituisca (per un oggetto remoto, possibilmente posizionato nella cache). Le eccezioni sono le stesse di urlopen().

Il secondo argomento, se presente, specifica la posizione del file su cui copiare (se assente, la locazione sarà un file temporaneo con un nome generato). Il terzo argomento, se presente, è una funzione di aggancio che verrà chiamata una volta sulla connessione della rete ed una volta che un blocco verrà letto successivamente. L'aggancio passerà tre argomenti: un numero dei blocchi trasferiti fino a quel momento, una dimensione in byte del blocco, e la dimensione totale del file. Il terzo argomento deve essere un -1 sui vecchi server FTP che non restituiscono la dimensione del file su di una richiesta di recupero.

Se la url usa lo schema identificativo http:, l'argomento facoltativo data può essere indicato per specificare una richiesta POST (normalmente il tipo di richiesta è GET). L'argomento data deve essere nel formato standard application/x-www-form-urlencoded; vedere sotto la funzione urlencode().

_urlopener

Le funzioni pubbliche urlopen() e urlretrieve() creano una istanza della classe FancyURLopener e la usano per migliorare le loro azioni di richiesta. Per sovrascrivere queste funzionalità, i programmatori possono creare una sotto classe di URLopener o FancyURLopener, che assegna una istanza della classe alla variabile urllib._urlopener prima di chiamare la funzione desiderata. Per esempio, le applicazioni possono voler specificare un differente header User-Agent: rispetto a quello definito da URLopener. Questo può essere realizzato con il seguente codice:

import urllib

class AppURLopener(urllib.FancyURLopener):
    def __init__(self, *args):
        self.version = "App/1.7"
        urllib.FancyURLopener.__init__(self, *args)

urllib._urlopener = AppURLopener()

urlcleanup( ): Pulisce la cache che potrebbe essere stata costruita da una precedente chiamata a urlretrieve().

quote( string[, safe]): Sostituisce i carattere speciali all'interno della stringa string, usando il carattere di protezione "%xx". Lettere, numeri ed i caratteri "_.-" non vengono mai quotati. Il parametro facoltativo safe specifica caratteri aggiuntivi che non dovrebbero essere quotati -- il suo valore predefinito è '/'.
Esempio: quote('/~connolly/') yields '/%7econnolly/'.

quote_plus( string[, safe]): Come quote(), ma sostituisce anche gli spazi con un segno "+", come richiesto per la quotatura dei valori di form HTML. I segni "+" nella stringa originale vengono protetti finché non vengono inclusi in safe. Inoltre non possiede un predefinito safe per '/'.

unquote( string): Sostituisce il carattere di protezione "%xx" con i loro equivalenti in singolo carattere.
Esempio: unquote('/%7Econnolly/') yields '/~connolly/'.

unquote_plus( string): Come unquote(), ma sostituisce anche i segni "+" con spazi, come richiesto quando si toglie la quotatura ai valori delle form HTML.

urlencode( query[, doseq]): Converte un oggetto mappato o una sequenza di tuple di due elementi in una stringa ``url codificata'', passibile di essere passata a urlopen() come argomento facoltativo data. Questo è utile per passare un dizionario di campi di form ad una richiesta POST. La stringa risultante è una serie di coppie chiave=valore separate dal carattere "&", dove ogni chiave ed ogni valore vengono quotati usando la funzione quote_plus() indicata sopra. Se il parametro facoltativo doseq è presente e valutato come vero, le coppie individuali chiave=valore vengono generate per ogni elemento della sequenza. Quando una sequenza di tuple di due elementi viene usata come argomento di query, il primo elemento di ogni tupla è una chiave e il secondo è un valore. L'ordine dei parametri nella stringa codificata deve corrispondere all'ordine delle tuple dei parametri nella sequenza. Il modulo cgi fornisce le funzioni parse_qs() e parse_qsl() che vengono usate per analizzare le stringhe di interrogazione nelle strutture dati di Python.

pathname2url( path): Converte dalla sintassi locale, un percorso di nomi path in un percorso nella forma usata nei percorsi di una URL. Questo non produce una URL completa. Il valore restituito sarà già quotato usando la funzione quote().

url2pathname( path): converte il componente path dalla URL codificata, in una sintassi di un percorso locale. Questo non accetta una URL completa. Questa funzione usa unquote() per decodificare path.

class URLopener( [proxies[, **x509]])

Classe di base per l'apertura e la lettura delle URL. Finché si avrà bisogno di supportare l'apertura di oggetti usando schemi diversi da http:, ftp:, gopher: o file:, probabilmente si vorrà usare FancyURLopener.

Predefinitamente, la classe URLopener invia un'intestazioneUser-Agent: di "urllib/VVV", dove VVV è la versione della urllib. Le applicazioni possono definire la propria intestazione User-Agent: attraverso sotto classi di URLopener o FancyURLopener ed impostando l'attributo version dell'istanza ad un appropriato valore stringa prima che il metodo open() venga chiamato.

Il parametro facoltativo proxies dovrebbe essere un dizionario che mappa gli schemi dei nomi in proxy URL, dove un dizionario vuoto imposta il proxy completamente ad off. Il suo valore predefinito è None, nel cui caso le impostazioni d'ambiente del proxy verranno usate se presenti, come discusso precedentemente nella definizione di urlopen().

Parametri di chiavi addizionali, raccolte in x509, vengono usate per l'autenticazione con lo schema https:. Le chiavi key_file e cert_file vengono supportate; entrambe sono attualmente necessarie per recuperare una risorsa da una URL https::

class FancyURLopener( ...)

FancyURLopener (sotto classe di URLopener) fornisce il gestore predefinito per i seguenti codici di risposta HTTP: 301, 302, 303, 307 e 401. Per i codici di risposta 30x indicati sopra, l'intestazione Location: viene usata per scaricare l'URL attuale. Per i codici di risposta 401 (autenticazione richiesta), viene fornita l'autenticazione base dell'HTTP. Per i codici di risposta 30x, la ricorsione viene controllata dal valore dell'attributo maxtries, che ha un valore predefinito impostato a 10.

Note: In accordo alle indicazioni dell'RFC 2616, le risposte 301 e 302 a richieste POST non devono essere automaticamente redirette senza la conferma dell'utente. In realtà, i browser eseguono la redirezione automatica di fronte a queste risposte, cambiando il POST in GET, e urllib riproduce questa caratteristica.

Il parametro passato al costruttore è lo stesso di quello per URLopener.

Note: Quando si esegue l'autenticazione di base, un'istanza FancyURLopener chiama il suo metodo prompt_user_passwd(). L'implementazione predefinita domanda all'utente le informazioni richieste sul terminale in uso. Se necessario, una sotto classe può sovrascrivere questo metodo per supportare caratteristiche più appropriate.

Restrizioni:

Correntemente, solo i seguenti protocolli vengono supportati: HTTP, (Versione 0.9 e 1.0), Gopher (man non Gopher-+), FTP e file locali.
La funzionalità di caching di urlretrieve() è stata disabilitata fino a quando non si troverà il corretto processo per le intestazioni di ``Expiration time''.
Ci dovrebbe essere una funzione per verificare quale particolare URL è nella cache.
Per compatibilità con il passato, se una URL mostra di puntare a un file locale, ma il file non può essere aperto, la URL viene reinterpretata usando il protocollo FTP. Questo può causare in alcune occasione messaggi di errori confusi.
Le funzioni urlopen() e urlretrieve() possono causare lunghi ritardi quando attendono che una connessione di rete venga attivata. Questo significa che è difficile costruire un client Web interattivo usando questa funzione senza l'uso dei threads.
Il dato restituito da urlopen() o urlretrieve() è il dato grezzo restituito dal server. Questo può essere un dato binario (per esempio un'immagine), puro testo o (per esempio) HTML. Il protocollo HTTP fornisce il tipo di informazione nell'intestazione della risposta, che può essere controllato cercando l'intestazione Content-Type:. Per il protocollo , il tipo di informazione è codificata nell'URL; non c'è attualmente nessun modo facile per estrarlo. Se il dato restituito è HTML, si può usare il modulo htmllib per analizzarlo.
Questo modulo non supporta l'uso di proxy che richiedono autenticazione. Questo deve essere implementato in futuro.
Il modulo urllib contiene (non documentate) funzioni per l'analisi e la deanalisi delle stringhe URL, l'interfaccia raccomandata per la manipolazione è nel modulo urlparse.

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

11.4 urllib -- Apertura di risorse arbitrarie tramite URL

11.4 `urllib` -- Apertura di risorse arbitrarie tramite URL