La libreria di riferimento di Python

Previous: 13.8.1 Oggetti DOMEventStream Up: 13. Strumenti per l'analisi Next: 13.9.1 Oggetti SAXException

---

13.9 xml.sax -- Supporto per parser SAX2

Nuovo nella versione 2.0.

Il package xml.sax fornisce un numero di moduli che implementano la API di base per l'interfaccia XML (SAX) di Python. Il package stesso fornisce le eccezioni SAX ed utili funzioni che saranno le più usate dagli utenti delle API SAX.

Le funzioni utili sono:

make_parser(

[parser_list])

Crea e restituisce un oggetto SAX XMLReader. Il primo parser trovato verrà usato. Se parser_list viene fornito, dovrà essere composto da una sequenza di stringhe che chiameranno moduli che hanno una funzione chiamata create_parser(). I moduli elencati in parser_list verranno usati prima dei moduli predefiniti dei parser.

parse(

filename_or_stream, handler[, error_handler])

Crea un parser SAX e lo utilizza per analizzare un documento. Il documento, passato come filename_or_stream, può essere un file con nome o un oggetto file. Il parametro handler deve necessariamente essere un'istanza SAX ContentHandler. Se viene passato error_handler, deve essere una istanza SAX ErrorHandler; se omesso, verrà sollevata un'eccezione SAXParseException su tutti gli errori. Questo non restituirà valori;

SAXParseException sollevata per tutti gli errori. Non vi è restituzione di alcun valore; tutte le operazioni devono essere fatte attraverso il gestore, handler passato.

parseString(

string, handler[, error_handler])

Simile a parse(), ma effettua l'analisi da un buffer stringa, string, passato come parametro.

Una tipica applicazione SAX usa tre tipi di oggetti: lettore, gestore e sorgente in ingresso (reader, handler, input source). Il ``lettore'' o ``READER'' in questo contesto non è altro che un altro sinonimo per un parser, per esempio alcuni pezzi di codice che leggono i byte o i caratteri dalla sorgente in ingresso e producono una sequenza di eventi. Gli eventi vengono poi distribuiti agli oggetti gestori, per esempio il reader invoca un metodo sul gestore. Un'applicazione SAX deve prima ottenere un oggetto reader, creare o aprire una sorgente di ingresso, creare i gestori e connettere questi oggetti tutti assieme. Come passaggio finale della preparazione, il reader viene chiamato per analizzare l'input. Durante l'analisi, i metodi sull'oggetto gestore vengono chiamati basandosi su una struttura e sintassi di eventi passati dal sorgente in ingresso.

Per questi oggetti, è rilevante solo l'interfaccia; essi normalmente non vengono istanziati dalle applicazioni. Fino a che Python non ha una esplicita conoscenza dell'interfaccia, questi vengono formalmente introdotti come classi, ma le applicazioni possono usare implementazioni che non ereditano dalle classi indicate. Le interfacce InputSource, Locator, Attributes, AttributesNS e XMLReader vengono definite nel modulo xml.sax.xmlreader. Le interfacce del gestore vengono definite in xml.sax.handler. Per convenienza, InputSource (che viene spesso istanziata direttamente) e la classe handler sono anche disponibili da xml.sax. Queste interfacce vengono descritte di seguito.

In aggiunta a queste classi, xml.sax fornisce le seguenti classi di eccezione.

exception SAXException(

msg[, exception])

Incapsula un errore o un avviso XML. Questa classe può contenere errori di base o informazioni di avviso sia del parser XML che dell'applicazione: può essere derivata per supportare ulteriori funzionalità o per aggiungere la localizzazione. Notare che, diversamente dai gestori definiti nell'interfaccia ErrorHandler, che ricevono le istanze di questa eccezione, non viene richiesto che venga attualmente sollevata una eccezione -- è anche utile come contenitore per informazioni.

Quando istanziata, msg deve essere una descrizione dell'errore chiaro e leggibile. Il parametro facoltativo exception, se indicato, deve essere o None o un'eccezione che viene rilevata dal codice in analisi e viene passata come un'informazione.

Questa è la classe di base per le altre classi di eccezione SAX.

exception SAXParseException(

msg, exception, locator)

Classi derivate da SAXException, sollevate durante l'analisi degli errori. Istanze di questa classe vengono passate ai metodi dell'interfaccia SAX ErrorHandler per fornire informazioni circa l'errore dell'analisi. Questa classe supporta l'interfaccia SAX Locator tanto quanto l'interfaccia SAXException.

exception SAXNotRecognizedException(

msg[, exception])

Classi derivate da SAXException, sollevate quando un SAX XMLReader viene confrontato con una caratteristica non riconosciuta o una proprietà. Le applicazioni SAX e le estensioni possono usare questa classe per scopi simili.

exception SAXNotSupportedException(

msg[, exception])

Classi derivate di SAXException, sollevate quando ad un SAX XMLReader viene richiesto di abilitare una caratteristica che non è supportata, o impostare una proprietà con un valore che l'implementazione non supporta. Le applicazioni SAX e le estensioni possono usare questa classe per scopi simili.

---

La libreria di riferimento di Python

Previous: 13.8.1 Oggetti DOMEventStream Up: 13. Strumenti per l'analisi Next: 13.9.1 Oggetti SAXException

---

Release 2.3.4, documentation updated on 21. maggio 2005.