xml.sax.xmlreader — Interface für XML-Parser

Quellcode: Lib/xml/sax/xmlreader.py

SAX-Parser implementieren die XMLReader-Schnittstelle. Sie werden in einem Python-Modul implementiert, das eine Funktion create_parser() bereitstellen muss. Diese Funktion wird von xml.sax.make_parser() ohne Argumente aufgerufen, um ein neues Parser-Objekt zu erstellen.

class xml.sax.xmlreader.XMLReader

Basisklasse, von der SAX-Parser erben können.

class xml.sax.xmlreader.IncrementalParser

In einigen Fällen ist es wünschenswert, eine Eingabequelle nicht auf einmal zu parsen, sondern Teile des Dokuments zu verarbeiten, sobald sie verfügbar sind. Beachten Sie, dass der Reader normalerweise nicht die gesamte Datei liest, sondern sie ebenfalls in Teilen liest; trotzdem wird parse() nicht zurückkehren, bis das gesamte Dokument verarbeitet ist. Daher sollten diese Schnittstellen verwendet werden, wenn das blockierende Verhalten von parse() unerwünscht ist.

Wenn der Parser instanziiert wird, ist er sofort bereit, Daten von der `feed`-Methode zu akzeptieren. Nachdem das Parsen mit einem Aufruf von `close` abgeschlossen wurde, muss die `reset`-Methode aufgerufen werden, um den Parser wieder für die Annahme neuer Daten – entweder von `feed` oder über die `parse`-Methode – vorzubereiten.

Beachten Sie, dass diese Methoden *nicht* während des Parsens aufgerufen werden dürfen, d. h. nachdem `parse` aufgerufen wurde und bevor es zurückkehrt.

Standardmäßig implementiert die Klasse auch die `parse`-Methode der `XMLReader`-Schnittstelle, indem sie die Methoden `feed`, `close` und `reset` der `IncrementalParser`-Schnittstelle als Komfortfunktion für Schreiber von SAX 2.0-Treibern verwendet.

class xml.sax.xmlreader.Locator

Schnittstelle zum Verknüpfen eines SAX-Ereignisses mit einem Dokumentenstandort. Ein Locator-Objekt liefert nur während Aufrufen der DocumentHandler-Methoden gültige Ergebnisse; zu allen anderen Zeiten sind die Ergebnisse unvorhersehbar. Wenn Informationen nicht verfügbar sind, können Methoden None zurückgeben.

class xml.sax.xmlreader.InputSource(system_id=None)

Kapselung der Informationen, die der XMLReader zum Lesen von Entitäten benötigt.

Diese Klasse kann Informationen über den öffentlichen Bezeichner, den Systembezeichner, den Byte-Stream (möglicherweise mit Informationen zur Zeichenkodierung) und/oder den Zeichen-Stream einer Entität enthalten.

Anwendungen erstellen Objekte dieser Klasse zur Verwendung in der Methode XMLReader.parse() und zur Rückgabe aus `EntityResolver.resolveEntity`.

Ein InputSource gehört zur Anwendung; der XMLReader darf von der Anwendung übergebene InputSource-Objekte nicht ändern, obwohl er Kopien erstellen und diese ändern darf.

class xml.sax.xmlreader.AttributesImpl(attrs)

Dies ist eine Implementierung der Attributes-Schnittstelle (siehe Abschnitt Die Attributes-Schnittstelle). Dies ist ein Dictionary-ähnliches Objekt, das die Elementattribute in einem `startElement()`-Aufruf repräsentiert. Zusätzlich zu den nützlichsten Dictionary-Operationen unterstützt es eine Reihe weiterer Methoden, wie sie von der Schnittstelle beschrieben werden. Objekte dieser Klasse sollten von Lesern instanziiert werden; *attrs* muss ein Dictionary-ähnliches Objekt sein, das eine Zuordnung von Attributnamen zu Attributwerten enthält.

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

Namespace-fähige Variante von AttributesImpl, die an startElementNS() übergeben wird. Sie leitet sich von AttributesImpl ab, versteht aber Attributnamen als Tupel aus *namespaceURI* und *localname*. Zusätzlich bietet sie eine Reihe von Methoden, die qualifizierte Namen erwarten, wie sie im Originaldokument erscheinen. Diese Klasse implementiert die AttributesNS-Schnittstelle (siehe Abschnitt Die AttributesNS-Schnittstelle).

XMLReader-Objekte

Die XMLReader-Schnittstelle unterstützt die folgenden Methoden

XMLReader.parse(source)

Verarbeitet eine Eingabequelle und erzeugt SAX-Ereignisse. Das *source*-Objekt kann ein Systembezeichner sein (ein String, der die Eingabequelle identifiziert – typischerweise ein Dateiname oder eine URL), ein pathlib.Path- oder ein pfadähnliches Objekt oder ein InputSource-Objekt. Wenn parse() zurückkehrt, ist die Eingabe vollständig verarbeitet, und das Parser-Objekt kann verworfen oder zurückgesetzt werden.

Geändert in Version 3.5: Unterstützung für Zeichen-Streams hinzugefügt.

Geändert in Version 3.8: Unterstützung für pfadähnliche Objekte hinzugefügt.

XMLReader.getContentHandler()

Gibt den aktuellen ContentHandler zurück.

XMLReader.setContentHandler(handler)

Setzt den aktuellen ContentHandler. Wenn kein ContentHandler gesetzt ist, werden Inhaltsereignisse verworfen.

XMLReader.getDTDHandler()

Gibt den aktuellen DTDHandler zurück.

XMLReader.setDTDHandler(handler)

Setzt den aktuellen DTDHandler. Wenn kein DTDHandler gesetzt ist, werden DTD-Ereignisse verworfen.

XMLReader.getEntityResolver()

Gibt den aktuellen EntityResolver zurück.

XMLReader.setEntityResolver(handler)

Setzt den aktuellen EntityResolver. Wenn kein EntityResolver gesetzt ist, führen Versuche, eine externe Entität aufzulösen, dazu, dass der Systembezeichner für die Entität geöffnet wird, und schlagen fehl, wenn er nicht verfügbar ist.

XMLReader.getErrorHandler()

Gibt den aktuellen ErrorHandler zurück.

XMLReader.setErrorHandler(handler)

Setzt den aktuellen Fehlerbehandler. Wenn kein ErrorHandler gesetzt ist, werden Fehler als Ausnahmen ausgelöst und Warnungen ausgegeben.

XMLReader.setLocale(locale)

Ermöglicht einer Anwendung, die Locale für Fehler und Warnungen festzulegen.

SAX-Parser sind nicht verpflichtet, die Lokalisierung von Fehlern und Warnungen bereitzustellen; wenn sie die angeforderte Locale jedoch nicht unterstützen, müssen sie eine SAX-Ausnahme auslösen. Anwendungen können mitten im Parsen eine Locale-Änderung anfordern.

XMLReader.getFeature(featurename)

Gibt die aktuelle Einstellung für das Feature *featurename* zurück. Wenn das Feature nicht erkannt wird, wird eine SAXNotRecognizedException ausgelöst. Die bekannten Featurenamen sind im Modul xml.sax.handler aufgeführt.

XMLReader.setFeature(featurename, value)

Setzt *featurename* auf *value*. Wenn das Feature nicht erkannt wird, wird eine SAXNotRecognizedException ausgelöst. Wenn das Feature oder seine Einstellung vom Parser nicht unterstützt wird, wird *SAXNotSupportedException* ausgelöst.

XMLReader.getProperty(propertyname)

Gibt die aktuelle Einstellung für die Property *propertyname* zurück. Wenn die Property nicht erkannt wird, wird eine SAXNotRecognizedException ausgelöst. Die bekannten Propertynamen sind im Modul xml.sax.handler aufgeführt.

XMLReader.setProperty(propertyname, value)

Setzt *propertyname* auf *value*. Wenn die Property nicht erkannt wird, wird eine SAXNotRecognizedException ausgelöst. Wenn die Property oder ihre Einstellung vom Parser nicht unterstützt wird, wird *SAXNotSupportedException* ausgelöst.

IncrementalParser-Objekte

Instanzen von IncrementalParser bieten die folgenden zusätzlichen Methoden

IncrementalParser.feed(data)

Verarbeitet einen Datenblock (*data*).

IncrementalParser.close()

Nimmt das Ende des Dokuments an. Dies überprüft wohlgeformte Bedingungen, die nur am Ende überprüft werden können, ruft Handler auf und kann Ressourcen bereinigen, die während des Parsens zugewiesen wurden.

IncrementalParser.reset()

Diese Methode wird nach dem Aufruf von `close` aufgerufen, um den Parser zurückzusetzen, damit er neue Dokumente parsen kann. Die Ergebnisse des Aufrufs von `parse` oder `feed` nach `close` ohne Aufruf von `reset` sind undefiniert.

Locator-Objekte

Instanzen von Locator stellen diese Methoden bereit

Locator.getColumnNumber()

Gibt die Spaltennummer zurück, an der das aktuelle Ereignis beginnt.

Locator.getLineNumber()

Gibt die Zeilennummer zurück, an der das aktuelle Ereignis beginnt.

Locator.getPublicId()

Gibt den öffentlichen Bezeichner für das aktuelle Ereignis zurück.

Locator.getSystemId()

Gibt den Systembezeichner für das aktuelle Ereignis zurück.

InputSource-Objekte

InputSource.setPublicId(id)

Setzt den öffentlichen Bezeichner dieses InputSource.

InputSource.getPublicId()

Gibt den öffentlichen Bezeichner dieses InputSource zurück.

InputSource.setSystemId(id)

Setzt den Systembezeichner dieses InputSource.

InputSource.getSystemId()

Gibt den Systembezeichner dieses InputSource zurück.

InputSource.setEncoding(encoding)

Setzt die Zeichenkodierung dieses InputSource.

Die Kodierung muss ein String sein, der für eine XML-Kodierungsdeklaration akzeptabel ist (siehe Abschnitt 4.3.3 der XML-Empfehlung).

Das Attribut `encoding` des InputSource wird ignoriert, wenn der InputSource auch einen Zeichen-Stream enthält.

InputSource.getEncoding()

Ruft die Zeichenkodierung dieses InputSource ab.

InputSource.setByteStream(bytefile)

Setzt den Byte-Stream (eine Binärdatei) für diese Eingabequelle.

Der SAX-Parser wird dies ignorieren, wenn auch ein Zeichen-Stream angegeben ist, aber er wird einen Byte-Stream bevorzugen, anstatt selbst eine URI-Verbindung zu öffnen.

Wenn die Anwendung die Zeichenkodierung des Byte-Streams kennt, sollte sie diese mit der Methode `setEncoding` setzen.

InputSource.getByteStream()

Ruft den Byte-Stream für diese Eingabequelle ab.

Die Methode `getEncoding` gibt die Zeichenkodierung für diesen Byte-Stream zurück oder None, wenn sie unbekannt ist.

InputSource.setCharacterStream(charfile)

Setzt den Zeichen-Stream (eine Textdatei) für diese Eingabequelle.

Wenn ein Zeichen-Stream angegeben ist, ignoriert der SAX-Parser jeden Byte-Stream und versucht nicht, eine URI-Verbindung zum Systembezeichner zu öffnen.

InputSource.getCharacterStream()

Ruft den Zeichen-Stream für diese Eingabequelle ab.

Die Attributes-Schnittstelle

Attributes-Objekte implementieren einen Teil des Mapping-Protokolls, einschließlich der Methoden copy(), get(), __contains__(), items(), keys() und values(). Die folgenden Methoden werden ebenfalls bereitgestellt:

Attributes.getLength()

Gibt die Anzahl der Attribute zurück.

Attributes.getNames()

Gibt die Namen der Attribute zurück.

Attributes.getType(name)

Gibt den Typ des Attributs *name* zurück, der normalerweise 'CDATA' ist.

Attributes.getValue(name)

Gibt den Wert des Attributs *name* zurück.

Die AttributesNS-Schnittstelle

Diese Schnittstelle ist ein Untertyp der Attributes-Schnittstelle (siehe Abschnitt Die Attributes-Schnittstelle). Alle von dieser Schnittstelle unterstützten Methoden sind auch für AttributesNS-Objekte verfügbar.

Die folgenden Methoden sind ebenfalls verfügbar:

AttributesNS.getValueByQName(name)

Gibt den Wert für einen qualifizierten Namen zurück.

AttributesNS.getNameByQName(name)

Gibt das Tupel *(namespace, localname)* für einen qualifizierten Namen zurück.

AttributesNS.getQNameByName(name)

Gibt den qualifizierten Namen für ein *(namespace, localname)*-Tupel zurück.

AttributesNS.getQNames()

Gibt die qualifizierten Namen aller Attribute zurück.