13.5.1 Oggetti XMLParser

Gli oggetti xmlparser hanno i seguenti metodi:

Parse( data[, isfinal]): Analizza i contenuti dei dati di una stringa, chiamando le appropriate funzioni di gestione per elaborare i dati, data, analizzati. isfinal deve essere vero nella chiamata finale a questo metodo. data può essere la stringa vuota in qualsiasi momento.

ParseFile( file): Analizza i dati XML leggendo da un file oggetto. file ha solamente bisogno di fornire il metodo read(nbytes), restituendo la stringa vuota dove non ci sono più dati.

SetBase( base): Imposta la base che deve essere usata per risolvere le relative URI negli identificatori di sistema nelle dichiarazioni. La risoluzione dei relativi identificatori viene lasciata all'applicazione: questo valore verrà passato come argomento base per le funzioni ExternalEntityRefHandler, NotationDeclHandler e UnparsedEntityDeclHandler.

GetBase( ): Restituisce una stringa contenente le impostazioni base da una precedente chiamata a SetBase() o None se SetBase() non è stato chiamato.

GetInputContext( ): Restituisce i dati di input che vengono generati dall'evento corrente come una stringa. I dati sono nella codifica dell'entità che ha generato il testo. Quando chiamata mentre un evento di gestione non è attivo, il valore restituito è None. Nuovo nella versione 2.1.

ExternalEntityParserCreate( context[, encoding]): Crea un analizzatore ``figlio'' che può essere usato per analizzare un'entità esterna analizzata, con riferimento al contenuto analizzato dal parser genitore. Il parametro context dovrebbe essere la stringa passata alla funzione di gestione ExternalEntityRefHandler(), descritta sotto. Il parser figlio viene creato con ordered_attributes, returns_unicode e specified_attributes impostati al valore di questo parser.

Gli oggetti xmlparser hanno i seguenti attributi:

buffer_size: La dimensione del buffer usata quando buffer_text è vero. Questi valori, a questo punto, non possono essere modificati. Nuovo nella versione 2.3.

buffer_text: Impostare buffer_text a vero comporta che l'oggetto xmlparser, rispetto al buffer del contenuto del testo restituito da Expat, eviti molteplici chiamate a CharacterDataHandler() ogni qualvolta sia possibile. Questo può sostanzialmente migliorare le prestazioni da quando Expat normalmente spezza dati costituiti da caratteri in prossimità della fine della riga. Il valore predefinito per questo attributo è falso e può essere modificato in ogni momento. Nuovo nella versione 2.3.

buffer_used: Se buffer_text è abilitato, rappresenta il numero dei byte immagazzinati in un buffer. Questi byte rappresentano la codifica di testo UTF-8. Questo attributo non ha rappresentazioni significative quando buffer_text viene impostato a falso. Nuovo nella versione 2.3.

ordered_attributes: Impostare questo attributo ad un intero diverso da zero comporta il riconoscimento degli attributi come lista piuttosto che come dizionario. Gli attributi vengono rappresentati nello stesso ordine trovato nel documento di testo. Per ogni attributo sono presenti due voci di lista: il nome dell'attributo ed il valore dell'attributo. Anche la versione più vecchia di questo modulo usa lo stesso formato. Per definizione questo attributo è falso; esso può essere cambiato in ogni momento. Nuovo nella versione 2.1.

returns_unicode: Se questo attributo è impostato ad un intero differente da zero, le funzioni di gestione verranno passate come stringhe Unicode. Se returns_unicode è 0, stringhe a 8 bit contenenti dati codificati UTF-8 verranno passate agli appropriati gestori. Modificato nella versione 1.6: Può essere cambiata in ogni momento per influenzare il tipo risultante..

specified_attributes: Se impostato ad un intero diverso da zero, il parser riporterà solo quegli attributi specificati nel documento istanza e non quelli derivati dalle dichiarazioni degli attributi. Le applicazioni così impostate necessitano di particolare attenzione per usare quelle informazioni addizionali rintracciabili nelle dichiarazioni, che devono essere necessariamente compatibili con gli standard per lo sviluppo dei processori XML. Per definizione, questo attributo è falso; può essere cambiato in ogni momento. Nuovo nella versione 2.1.

I seguenti attributi contengono valori relativi ai più recenti errori incontrati dall'oggetto xmlparser, e avranno solo valori corretti quando un'eccezione xml.parsers.expat.ExpatError verrà sollevata da una chiamata a Parse() o ParseFile().

ErrorByteIndex: Indice del byte dove viene riscontrato l'errore.

ErrorCode: Codice numerico che specifica il problema. Questo valore può essere passato alla funzione ErrorString(), o confrontato con una delle costanti definite nell'oggetto errors.

ErrorColumnNumber: Numero di colonna dove viene riscontrato l'errore.

ErrorLineNumber: Il numero della riga dove viene riscontrato l'errore.

Qui c'è una lista dei gestori che possono essere impostati. Per impostare un gestore su un oggetto xmlparser o, usare o.handlername = func. handlername deve essere preso dalla lista seguente, e func deve essere un oggetto chiamabile che accetta il corretto numero di argomenti. Gli argomenti sono tutte stringhe, salvo indicazioni contrarie.

XmlDeclHandler( versione, codifica, standalone): Chiamato quando una dichiarazione XML viene analizzata. La dichiarazione XML è la dichiarazione (facoltativa) dell'applicabilità della versione XML raccomandata, la codifica del documento di testo ed una facoltativa dichiarazione ``standalone''. versione e codifica dovrebbero essere stringhe del tipo dettato dall'attributo returns_unicode e standalone verrà impostato ad 1 se il documento viene dichiarato standalone, 0 se non viene dichiarato standalone o -1 se la clausola standalone viene omessa. Questo è disponibile solamente con Expat versione 1.95.0 o più recenti. Nuovo nella versione 2.1.

StartDoctypeDeclHandler( doctypeName, systemId, publicId, has_internal_subset): Chiamato quando Expat inizia ad analizzare la dichiarazione del tipo del documento (<!DOCTYPE ...). Il doctypeName viene fornito esattamente come presentato. I parametri systemId e publicId forniscono gli identificatori del sistema locale e pubblico se specificati, o None se omessi. has_internal_subset sarà vero se il documento contiene internamente un altro documento ed è presente un dichiarazione del suddetto sotto insieme. Questo richiede la versione di Expat 1.2 o più recente.

EndDoctypeDeclHandler( ): Chiamato quando Expat sta analizzando la dichiarazione del tipo del documento. Richiede la versione di Expat 1.2 o più recente.

ElementDeclHandler( name, model): Chiamato una volta per ogni dichiarazione del tipo di elemento. name è il nome del tipo di elemento e model è la rappresentazione del contenuto del modello.

AttlistDeclHandler( elname, attname, tipo, default, required): Chiamato per ogni dichiarazione di attributo per ogni tipo di elemento. Se la dichiarazione, in forma di lista, degli attributi dichiara tre attributi, questo gestore viene chiamato tre volte, una volta aperto, ogni attributo. elname è il nome dell'elemento al quale la dichiarazione si applica e attname è il nome dell'attributo dichiarato. Il tipo di attributo è una stringa passata come tipo type; i possibili valori sono 'CDATA', 'ID', 'IDREF', ... default fornisce il valore predefinito per l'attributo usato, quando l'attributo non viene specificato dall'istanza del documento, o None se non c'è un valore predefinito (#IMPLIED valore). Se l'attributo viene richiesto per essere fornito all'istanza del documento, required dovrebbe essere vero. Questo richiede Expat versione 1.95.0 o più recente.

StartElementHandler( name, attributes): Chiamato per l'avvio di ogni elemento. name è una stringa contenente il nome dell'elemento, e attributes è il dizionario che tiene traccia dei nomi degli attributi attraverso i loro valori.

EndElementHandler( name): Chiamato per la fine di ogni elemento.

ProcessingInstructionHandler( target, data): Chiamato per ogni istruzione eleborata.

CharacterDataHandler( data): Chiamato per i dati carattere. Questo verrà chiamato per i dati carattere normali, contenuti marcati CDATA, e spazi vuoti ignorabili. Le applicazioni che devono distinguere questi casi possono usare le chiamate StartCdataSectionHandler, EndCdataSectionHandler e ElementDeclHandler per raccogliere le informazioni richieste.

UnparsedEntityDeclHandler( entityName, base, systemId, publicId, notationName): Chiamata per dichiarazioni di entità non analizzate (NDATA). Questo è presente solo nella versione 1.2 della libreria Expat; per versioni più recenti, usare invece EntityDeclHandler. La funzione sottostante nella libreria di Expat è stata dichiarata obsoleta.

EntityDeclHandler( entityName, is_parameter_entity, value, base, systemId, publicId, notationName): Chiamato da tutte le dichiarazioni di entità. Per parametri ed entità interne, value sarà una stringa che fornirà il contenuto dichiarato dall'entità; questo varrà None per le entità esterne. Il parametro notationName avrà il valore None per le entità analizzate, ed il nome della notazione per le entità non analizzate. is_parameter_entity sarà vero se l'entità è un parametro o falso per entità generiche (la maggior parte delle applicazioni ha bisogno soltanto di essere interessata ad entità generiche). Questo comportamento è disponibile solamente a partire dalla versione 1.95.0 della libreria Expat. Nuovo nella versione 2.1.

NotationDeclHandler( notationName, base, systemId, publicId): Chiamato per notazioni di dichiarazioni. notationName, base, systemId e publicId sono stringhe, se presenti. Se l'identificatore pubblico viene omesso, publicId varrà None.

StartNamespaceDeclHandler( prefix, uri): Chiamato quando un elemento contiene una dichiarazione sullo spazio dei nomi. Le dichiarazioni sullo spazio dei nomi vengono elaborate prima che StartElementHandler venga chiamato per l'elemento sul quale le dichiarazioni vengono disposte.

EndNamespaceDeclHandler( prefix): Chiamato quando il tag di chiusura viene richiesto per un elemento che contiene una dichiarazione sullo spazio dei nomi. Questo viene chiamato una volta per ogni dichiarazione concernente lo spazio dei nomi, sull'elemento, nell'ordine inverso per il quale StartNamespaceDeclHandler veniva chiamato per indicare l'inizio di ogni ambito di visibilità dello spazio dei nomi. Le chiamate a questo gestore vengono fatte dopo il corrispondente EndElementHandler per la fine dell'elemento.

CommentHandler( data): Chiamato per i commenti. data è il testo del commento, escluso i caratteri di inizio `'`'.

StartCdataSectionHandler( ): Chiamato all'inizio di una sezione CDATA. Questo e StartCdataSectionHandler vengono richiesti per essere in grado di identificare l'inizio e la fine sintattiche per le sezioni CDATA.

EndCdataSectionHandler( ): Chiamato alla fine di una sezione CDATA.

DefaultHandler( data): Chiamato da ogni carattere nel documento XML per il quale non è stato specificato nessun gestore applicabile. Questo significa che i caratteri fanno parte di un costrutto che potrebbe essere riportato, ma per il quale non è stato fornito alcun gestore.

DefaultHandlerExpand( data): Questo è la stessa cosa del DefaultHandler, ma non inibisce l'espansione delle entità interne. Il riferimento all'entità non verrà passato al gestore predefinito.

NotStandaloneHandler( ): Called if the Chiamato nel documento XML che non è stato dichiarato come inizio di un documento autonomo. Questo succede quando c'è un sotto insieme esterno o un riferimento ad un parametro entità, ma la dichiarazione XML non imposta in autonomia a sì una dichiarazione XML. Se il gestore restituisce 0, allora il parser provocherà un errore XML_ERROR_NOT_STANDALONE. Se questo gestore non è impostato, non viene sollevata alcuna eccezione per questa condizione del parser.

ExternalEntityRefHandler( context, base, systemId, publicId)

Chiamato per riferimento ad entità esterne. base è la base corrente, è stata impostata da una chiamata precedente a SetBase(). Gli identificatori systemId e publicId, se passati, sono stringhe; se l'identificatore pubblico non viene passato, publicId varrà None. Il valore di context è poco chiaro, dovrebbe essere usato solo come descritto qui sotto.

Per analizzare entità esterne da analizzare, deve essere implementato questo gestore. È responsabile della creazione di un sotto parser usando ExternalEntityParserCreate(context), inizializzandolo con le appropriate callbacks ed analizzando l'entità. Questo gestore dovrebbe restituire un intero; se restituisce 0, il parser provocherà un errore XML_ERROR_EXTERNAL_ENTITY_HANDLING, altrimenti l'analisi continuerà.

Se il gestore non viene fornito, le entità esterne vengono riportate dal DefaultHandler, sempre che questo sia fornito.

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