La libreria di riferimento di Python

Previous: 13.12.6 L'interfaccia AttributesNS Up: 13. Strumenti per l'analisi Next: 13.13.1 Spazio dei nomi

---

13.13 xmllib -- Un parser per documenti XML

Modificato nella versione 1.5.2: Aggiunto il supporto per lo spazio dei nomi.

Questo modulo definisce una classe XMLParser che serve da base per l'analisi di file di testo formattati in XML (Extensible Markup Language).

class XMLParser(

)

La classe XMLParser deve essere istanziata senza argomenti.^13.1

Questa classe fornisce i seguenti metodi di interfaccia e variabili d'istanza:

attributes

Una mappatura dei nomi di elementi in un dizionario. L'ultima mappatura mappa i nomi degli attributi validi per l'elemento al valore predefinito valido per l'attributo o, se non vi è valore predefinito, a None. Il valore predefinito è un dizionario vuoto. Questa variabile si intende sovrascritta, non viene estesa poiché il valore predefinito viene condiviso da tutte le istanze di XMLParser.

elements

Una mappatura di nomi di elementi in tuple. Le tuple contengono una funzione per la gestione rispettivamente del tag di inizio e di fine dell'elemento, oppure None se viene chiamato il metodo unknown_starttag() o unknown_endtag(). Il valore predefinito è il dizionario vuoto. Questa variabile si intende sovrascritta, non viene estesa poiché il valore predefinito viene condiviso da tutte le istanze di XMLParser.

entitydefs

Un mappatura di nomi di entità nei propri valori. Il valore predefinito contiene definizioni per 'lt', 'gt', 'amp', 'quot', e 'apos'.

reset(

)

Resetta l'istanza. Si perdono tutti i dati non processati. Viene chiamata implicitamente al momento dell'istanziazione.

setnomoretags(

)

Interrompe l'elaborazione dei tag. Tutto l'input successivo viene trattato come input literal (CDATA).

setliteral(

)

Entra in modalità costante (modalità CDATA). Esce automaticamente da questa modalità quando incontra un tag close che chiude l'ultimo tag rimasto aperto.

feed(

data)

Fornisce del testo al parser. Tale testo viene processato fintanto che si riscontrano tag completi; dati incompleti vengono bufferizzati fino a quando non se ne forniscono altri o fino alla chiamata close().

close(

)

Forza l'elaborazione di tutti i dati bufferizzati come se fossero seguiti da un segno di fine file. Questo metodo può essere ridefinito da una classe derivata per impostare ulteriori elaborazioni alla fine dell'input, comunque la versione ridefinita deve sempre chiamare close().

translate_references(

data)

Converte tutte le entità ed i riferimenti ai carattere in dati, data, e restituisce la stringa convertita.

getnamespace(

)

Restituisce una mappatura di abbreviazioni di spazi dei nomi in spazi dei nomi URI esistenti al momento.

handle_xml(

encoding, standalone)

Questo metodo viene chiamato quando viene elaborato il tag "<?xml ...?>". Gli argomenti sono i valori della codifica e attributi isolati del tag. Sia la codifica che gli attributi isolati sono facoltativi. I valori predefiniti passati a handle_xml() sono rispettivamente None e la stringa 'no'.

handle_doctype(

tag, pubid, syslit, data)

Questo metodo viene chiamato quando si processa la dichiarazione "<!DOCTYPE...>". Gli argomenti sono il nome del tag dell'elemento radice, il Formal Public Identifier (o None se non specificato), l'identificatore di sistema ed i contenuti non interpretati del sotto insieme interno DTD sotto forma di stringa (o None se non presenti).

handle_starttag(

tag, method, attributes)

Questo metodo viene chiamato per gestire i tag di inizio per i quali viene definita un'istanza variabile di elements. L'argomento tag è il nome del tag e l'argomento method è la funzione (metodo) che si dovrebbe usare per supportare l'interpretazione semantica del tag di inizio. L'argomento attributes è un dizionario di attributi, dove la chiave è il nome name ed il valore value è il valore dell'attributo trovato tra i delimitatori <> del tag. I riferimenti di entità e caratteri in value vengono interpretati. Ad esempio per il tag di inizio <A HREF="http://www.cwi.nl/">, questo metodo verrebbe chiamato come handle_starttag('A', self.elements['A'][0], {'HREF': 'http://www.cwi.nl/'}). L'implementazione base chiama semplicemente il metodo method con l'attributo attributes come unico argomento.

handle_endtag(

tag, method)

Questo metodo viene chiamato per gestire i tag di fine per i quali viene definito nelle istanze variabili di elements. L'argomento tag è il nome del tag e l'argomento method è la funzione (metodo) che si dovrebbe usare per supportare l'interpretazione semantica del tag di fine. Ad esempio per il tag di fine </A> questo metodo verrebbe chiamato come handle_endtag('A', self.elements['A'][1]). L'implementazione base chiama semplicemente method.

handle_data(

data)

Questo metodo viene chiamato per elaborare dati arbitrari. Su di esso viene effettuata una sovrascrittura mediante una classe derivata. L'implementazione della classe base non fa nulla.

handle_charref(

ref)

Questo metodo viene chiamato per processare un riferimento a caratteri del tipo "&#ref;". ref può essere sia un numero decimale che un esadecimale quando preceduto da una "x". Nell'implementazione base, ref deve essere un numero compreso nell'intervallo 0-255. Converte il carattere in ASCII e chiama il metodo handle_data() con il carattere come argomento. Se ref non è valido o eccede l'intervallo, viene chiamato il metodo unknown_charref(ref) per gestire l'errore. Una sotto classe deve effettuare la sovrascrittura di questo metodo per fornire un supporto per quei riferimenti a caratteri non compresi nell'intervallo ASCII.

handle_comment(

comment)

Questo metodo viene chiamato quando si incontra un commento. L'argomento comment è una stringa che contiene il testo compreso tra i delimitatori "<!--" e "-->" ma non i delimitatori stessi. Ad esempio il commento "<!--text-->" causerà la chiamata di questo metodo con 'text' come argomento. Il metodo predefinito non fa nulla.

handle_cdata(

data)

Questo metodo viene chiamato quando si incontra un elemento CDATA. L'argomento data è una stringa che contiene il testo compreso tra i delimitatori "<![CDATA[" e "]]>" ma non i delimitatori stessi. Ad esempio l'entità "<![CDATA[text]]>" causerà la chiamata di questo metodo con text come argomento. Il metodo predefinito non fa nulla ed è inteso come da sovrascrivere.

handle_proc(

name, data)

Questo metodo viene chiamato quando si incontra un'istruzione che indica un'elaborazione (PI (NdT: Processing Instruction)). name è l'obiettivo della PI e l'argomento data è una stringa che contiene il testo compreso tra il target della PI ed il delimitatore di chiusura ma non il delimitatore stesso. Ad esempio l'istruzione "<?XML text?>" causerà la chiamata di questo metodo con 'XML' e 'text' come argomenti. Il metodo predefinito non fa nulla. Notare che se un documento inizia con "<?xml ..?>", per gestirlo viene chiamato handle_xml().

handle_special(

data)

Questo metodo viene chiamato quando viene incontrata una dichiarazione. L'argomento data è una stringa che contiene il testo compreso tra i delimitatori "<!" e ">" ma non i delimitatori stessi. Ad esempio la dichiarazione di entità "<!ENTITY text>" causerà la chiamata di questo metodo con 'ENTITY text' come argomento. Il metodo predefinito non fa nulla. Notare che "<!DOCTYPE ...>"viene gestito separatamente se si trova all'inizio del documento.

syntax_error(

message)

Questo metodo viene chiamato quando viene incontrato un errore di sintassi. message è una descrizione di ciò che non va. Il metodo predefinito solleva un'eccezione RuntimeError. Se di questo metodo è stata effettuata una sovrascrittura è possibile la restituzione di un valore. Questo metodo viene chiamato solo quando l'errore è recuperabile. Gli errori irrecuperabili sollevano un'eccezione RuntimeError senza prima chiamare syntax_error().

unknown_starttag(

tag, attributes)

Questo metodo viene chiamato per processare un tag di inizio sconosciuto. Su di esso si effettua una sovrascrittura da una classe derivata; l'implementazione della classe base non fa nulla.

unknown_endtag(

tag)

Questo metodo viene chiamato per processare un tag di fine sconosciuto. Su di esso si effettua una sovrascrittura da una classe derivata; l'implementazione della classe base non fa nulla.

unknown_charref(

ref)

Questo metodo viene chiamato per processare un riferimento a caratteri numerici irrisolvibili. Su di esso si effettua una sovrascrittura da una classe derivata; l'implementazione della classe base non fa nulla.

unknown_entityref(

ref)

Questo metodo viene chiamato per processare un riferimento ad entità sconosciuta. Su di esso si effettua una sovrascrittura da una classe derivata; l'implementazione della classe base chiama syntax_error() per segnalare un errore.

Footnotes

... argomenti.^13.1

Attualmente, un certo numero di particolari argomenti possono influenzare l'interprete ad accettare costrutti non standard. Segue una lista di questi argomenti. Per tutti il valore predefinito è 0 (false) eccetto che per l'ultimo, per il quale è 1 (vero). accept_unquoted_attributes (accetta certi valori senza le virgolette), accept_missing_endtag_name (accetta tag finali simili a </>), map_case (considera le maiuscole come minuscole nei tag e negli attributi), accept_utf8 (permette caratteri UTF-8 in input; questo viene richiesto dallo standard XML, ma Python non si trova bene con questi caratteri, così non è l'impostazione predefinita), translate_attribute_references (non tenta di tradurre i riferimenti a caratteri ed entità in valori attributo).

---

La libreria di riferimento di Python

Previous: 13.12.6 L'interfaccia AttributesNS Up: 13. Strumenti per l'analisi Next: 13.13.1 Spazio dei nomi

---

Release 2.3.4, documentation updated on 21. maggio 2005.