xml.sax — Unterstützung für SAX2-Parser

Quellcode: Lib/xml/sax/__init__.py

Das Paket xml.sax stellt eine Reihe von Modulen zur Verfügung, die die Simple API for XML (SAX) Schnittstelle für Python implementieren. Das Paket selbst stellt die SAX-Ausnahmen und die Hilfsfunktionen bereit, die von Benutzern der SAX-API am häufigsten verwendet werden.

Hinweis

Wenn Sie nicht vertrauenswürdige oder nicht authentifizierte Daten parsen müssen, siehe XML-Sicherheit.

Geändert in Version 3.7.1: Der SAX-Parser verarbeitet standardmäßig keine allgemeinen externen Entitäten mehr, um die Sicherheit zu erhöhen. Zuvor erstellte der Parser Netzwerkverbindungen, um Remote-Dateien abzurufen oder lokale Dateien aus dem Dateisystem für DTDs und Entitäten zu laden. Diese Funktion kann mit der Methode setFeature() auf dem Parser-Objekt und dem Argument feature_external_ges wieder aktiviert werden.

Die Hilfsfunktionen sind

xml.sax.make_parser(parser_list=[])

Erstellt und gibt ein SAX XMLReader-Objekt zurück. Der erste gefundene Parser wird verwendet. Wenn parser_list angegeben wird, muss es sich um ein iterierbares Objekt von Zeichenketten handeln, die Namen von Modulen sind, die eine Funktion namens create_parser() haben. Module, die in parser_list aufgeführt sind, werden vor Modulen in der Standardliste von Parsern verwendet.

Geändert in Version 3.8: Das Argument parser_list kann jedes iterierbare Objekt sein, nicht nur eine Liste.

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

Erstellt einen SAX-Parser und verwendet ihn, um ein Dokument zu parsen. Das Dokument, das als filename_or_stream übergeben wird, kann ein Dateiname oder ein Dateiobjekt sein. Der Parameter handler muss eine Instanz von SAX ContentHandler sein. Wenn error_handler angegeben wird, muss es sich um eine Instanz von SAX ErrorHandler handeln; wenn es weggelassen wird, wird bei allen Fehlern SAXParseException ausgelöst. Es gibt keinen Rückgabewert; alle Arbeit muss vom übergebenen handler geleistet werden.

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

Ähnlich wie parse(), parst aber aus einem als Parameter erhaltenen Puffer string. string muss eine Instanz von str oder ein bytes-ähnliches Objekt sein.

Geändert in Version 3.5: Unterstützung für Instanzen von str hinzugefügt.

Eine typische SAX-Anwendung verwendet drei Arten von Objekten: Reader, Handler und Input-Quellen. "Reader" ist in diesem Zusammenhang ein anderer Begriff für Parser, d. h. ein Code-Teil, der die Bytes oder Zeichen aus der Input-Quelle liest und eine Sequenz von Ereignissen erzeugt. Die Ereignisse werden dann an die Handler-Objekte verteilt, d. h. der Reader ruft eine Methode auf dem Handler auf. Eine SAX-Anwendung muss daher ein Reader-Objekt erhalten, die Input-Quellen erstellen oder öffnen, die Handler erstellen und diese Objekte miteinander verbinden. Als letzter Schritt der Vorbereitung wird der Reader aufgerufen, um die Eingabe zu parsen. Während des Parsens werden Methoden auf den Handler-Objekten basierend auf strukturellen und syntaktischen Ereignissen aus den Eingabedaten aufgerufen.

Für diese Objekte sind nur die Schnittstellen relevant; sie werden normalerweise nicht von der Anwendung selbst instanziiert. Da Python keinen expliziten Begriff von Schnittstellen hat, werden sie formal als Klassen eingeführt, aber Anwendungen können Implementierungen verwenden, die nicht von den bereitgestellten Klassen erben. Die Schnittstellen InputSource, Locator, Attributes, AttributesNS und XMLReader sind im Modul xml.sax.xmlreader definiert. Die Handler-Schnittstellen sind in xml.sax.handler definiert. Zur Vereinfachung sind InputSource (die oft direkt instanziiert wird) und die Handler-Klassen auch aus xml.sax verfügbar. Diese Schnittstellen werden nachfolgend beschrieben.

Zusätzlich zu diesen Klassen stellt xml.sax die folgenden Ausnahmeklassen bereit.

exception xml.sax.SAXException(msg, exception=None)

Kapselt einen XML-Fehler oder eine Warnung. Diese Klasse kann grundlegende Fehler- oder Warnungsinformationen entweder vom XML-Parser oder von der Anwendung enthalten: sie kann unterklassifiziert werden, um zusätzliche Funktionalität bereitzustellen oder Lokalisierung hinzuzufügen. Beachten Sie, dass, obwohl die in der ErrorHandler-Schnittstelle definierten Handler Instanzen dieser Ausnahme erhalten, es nicht erforderlich ist, die Ausnahme tatsächlich auszulösen — sie ist auch als Container für Informationen nützlich.

Bei der Instanziierung sollte msg eine für Menschen lesbare Beschreibung des Fehlers sein. Der optionale Parameter exception, falls angegeben, sollte None oder eine Ausnahme sein, die vom Parsing-Code abgefangen und als Information weitergegeben wird.

Dies ist die Basisklasse für die anderen SAX-Ausnahmeklassen.

exception xml.sax.SAXParseException(msg, exception, locator)

Unterklasse von SAXException, die bei Parsing-Fehlern ausgelöst wird. Instanzen dieser Klasse werden an die Methoden der SAX ErrorHandler-Schnittstelle übergeben, um Informationen über den Parsing-Fehler bereitzustellen. Diese Klasse unterstützt die SAX Locator-Schnittstelle sowie die SAXException-Schnittstelle.

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

Unterklasse von SAXException, die ausgelöst wird, wenn ein SAX XMLReader auf ein nicht erkanntes Merkmal oder eine nicht erkannte Eigenschaft stößt. SAX-Anwendungen und -Erweiterungen können diese Klasse für ähnliche Zwecke verwenden.

exception xml.sax.SAXNotSupportedException(msg, exception=None)

Unterklasse von SAXException, die ausgelöst wird, wenn ein SAX XMLReader aufgefordert wird, ein nicht unterstütztes Merkmal zu aktivieren oder eine Eigenschaft auf einen Wert zu setzen, den die Implementierung nicht unterstützt. SAX-Anwendungen und -Erweiterungen können diese Klasse für ähnliche Zwecke verwenden.

Siehe auch

SAX: The Simple API for XML

Diese Website ist der zentrale Anlaufpunkt für die Definition der SAX-API. Sie bietet eine Java-Implementierung und Online-Dokumentation. Links zu Implementierungen und historischen Informationen sind ebenfalls verfügbar.

Modul xml.sax.handler

Definitionen der Schnittstellen für von der Anwendung bereitgestellte Objekte.

Modul xml.sax.saxutils

Hilfsfunktionen für die Verwendung in SAX-Anwendungen.

Modul xml.sax.xmlreader

Definitionen der Schnittstellen für von der Anwendung bereitgestellte Objekte.

SAXException-Objekte

Die Ausnahmeklasse SAXException unterstützt die folgenden Methoden

SAXException.getMessage()

Gibt eine für Menschen lesbare Meldung zurück, die den Fehlerzustand beschreibt.

SAXException.getException()

Gibt ein gekapseltes Ausnahmeobjekt zurück oder None.