xml.sax.handler — Basisklassen für SAX-Handler

Quellcode: Lib/xml/sax/handler.py

Die SAX-API definiert fünf Arten von Handlern: Content Handler, DTD Handler, Error Handler, Entity Resolver und Lexical Handler. Anwendungen müssen normalerweise nur die Schnittstellen implementieren, deren Ereignisse sie interessieren; sie können die Schnittstellen in einem einzigen Objekt oder in mehreren Objekten implementieren. Handler-Implementierungen sollten von den im Modul xml.sax.handler bereitgestellten Basisklassen erben, damit alle Methoden Standardimplementierungen erhalten.

class xml.sax.handler.ContentHandler

Dies ist die Haupt-Callback-Schnittstelle in SAX und die für Anwendungen wichtigste. Die Reihenfolge der Ereignisse in dieser Schnittstelle spiegelt die Reihenfolge der Informationen im Dokument wider.

class xml.sax.handler.DTDHandler

Behandelt DTD-Ereignisse.

Diese Schnittstelle spezifiziert nur die DTD-Ereignisse, die für eine grundlegende Analyse erforderlich sind (nicht analysierte Entitäten und Attribute).

class xml.sax.handler.EntityResolver

Grundlegende Schnittstelle zur Auflösung von Entitäten. Wenn Sie ein Objekt erstellen, das diese Schnittstelle implementiert, und dieses Objekt bei Ihrem Parser registrieren, ruft der Parser die Methode Ihres Objekts auf, um alle externen Entitäten aufzulösen.

class xml.sax.handler.ErrorHandler

Schnittstelle, die vom Parser verwendet wird, um dem Anwendung Fehlermeldungen und Warnungen zu präsentieren. Die Methoden dieses Objekts steuern, ob Fehler sofort in Ausnahmen umgewandelt werden oder auf andere Weise behandelt werden.

class xml.sax.handler.LexicalHandler

Schnittstelle, die vom Parser verwendet wird, um seltene Ereignisse darzustellen, die für viele Anwendungen möglicherweise nicht von Interesse sind.

Zusätzlich zu diesen Klassen stellt xml.sax.handler symbolische Konstanten für die Feature- und Property-Namen bereit.

xml.sax.handler.feature_namespaces
Wert: "http://xml.org/sax/features/namespaces"
true: Namespace-Verarbeitung durchführen.
false: Namespace-Verarbeitung optional nicht durchführen (impliziert namespace-prefixes; Standard).
Zugriff: (Parsen) schreibgeschützt; (Nicht-Parsen) Lese-/Schreibzugriff
xml.sax.handler.feature_namespace_prefixes
Wert: "http://xml.org/sax/features/namespace-prefixes"
true: Die ursprünglichen Präfix-Namen und Attribute, die für Namespace-Deklarationen verwendet wurden, melden.
false: Attribute, die für Namespace-Deklarationen verwendet wurden, nicht melden und optional keine ursprünglichen Präfix-Namen melden (Standard).
Zugriff: (Parsen) schreibgeschützt; (Nicht-Parsen) Lese-/Schreibzugriff
xml.sax.handler.feature_string_interning
Wert: "http://xml.org/sax/features/string-interning"
true: Alle Elementnamen, Präfixe, Attributnamen, Namespace-URIs und lokalen Namen werden mit der integrierten `intern`-Funktion intern behandelt.
false: Namen werden nicht zwangsläufig intern behandelt, obwohl sie es sein können (Standard).
Zugriff: (Parsen) schreibgeschützt; (Nicht-Parsen) Lese-/Schreibzugriff
xml.sax.handler.feature_validation
Wert: "http://xml.org/sax/features/validation"
true: Alle Validierungsfehler melden (impliziert external-general-entities und external-parameter-entities).
false: Keine Validierungsfehler melden.
Zugriff: (Parsen) schreibgeschützt; (Nicht-Parsen) Lese-/Schreibzugriff
xml.sax.handler.feature_external_ges
Wert: "http://xml.org/sax/features/external-general-entities"
true: Alle externen allgemeinen (Text-)Entitäten einschließen.
false: Keine externen allgemeinen Entitäten einschließen.
Zugriff: (Parsen) schreibgeschützt; (Nicht-Parsen) Lese-/Schreibzugriff
xml.sax.handler.feature_external_pes
Wert: "http://xml.org/sax/features/external-parameter-entities"
true: Alle externen Parameter-Entitäten einschließen, einschließlich des externen DTD-Subsets.
false: Keine externen Parameter-Entitäten einschließen, auch nicht das externe DTD-Subset.
Zugriff: (Parsen) schreibgeschützt; (Nicht-Parsen) Lese-/Schreibzugriff
xml.sax.handler.all_features

Liste aller Features.

xml.sax.handler.property_lexical_handler
Wert: "http://xml.org/sax/properties/lexical-handler"
Datentyp: xml.sax.handler.LexicalHandler (nicht unterstützt in Python 2)
Beschreibung: Ein optionaler Erweiterungshandler für lexikalische Ereignisse wie Kommentare.
Zugriff: Lese-/Schreibzugriff
xml.sax.handler.property_declaration_handler
Wert: "http://xml.org/sax/properties/declaration-handler"
Datentyp: xml.sax.sax2lib.DeclHandler (nicht unterstützt in Python 2)
Beschreibung: Ein optionaler Erweiterungshandler für DTD-bezogene Ereignisse außer Notationen und nicht analysierten Entitäten.
Zugriff: Lese-/Schreibzugriff
xml.sax.handler.property_dom_node
Wert: "http://xml.org/sax/properties/dom-node"
Datentyp: org.w3c.dom.Node (nicht unterstützt in Python 2)
Beschreibung: Beim Parsen der aktuelle DOM-Knoten, der besucht wird, wenn dies ein DOM-Iterator ist; beim Nicht-Parsen der Stamm-DOM-Knoten für die Iteration.
Zugriff: (Parsen) schreibgeschützt; (Nicht-Parsen) Lese-/Schreibzugriff
xml.sax.handler.property_xml_string
Wert: "http://xml.org/sax/properties/xml-string"
Datentyp: Bytes
Beschreibung: Die wörtliche Zeichenkette, die die Quelle für das aktuelle Ereignis war.
Zugriff: schreibgeschützt
xml.sax.handler.all_properties

Liste aller bekannten Property-Namen.

ContentHandler-Objekte

Es wird erwartet, dass Benutzer von ContentHandler erben, um ihre Anwendung zu unterstützen. Die folgenden Methoden werden vom Parser bei den entsprechenden Ereignissen im Eingabedokument aufgerufen

ContentHandler.setDocumentLocator(locator)

Wird vom Parser aufgerufen, um der Anwendung einen Locator zur Verfügung zu stellen, mit dem der Ursprung von Dokumentereignissen ermittelt werden kann.

SAX-Parser werden dringend ermutigt (wenn auch nicht absolut erforderlich), einen Locator bereitzustellen: Wenn sie dies tun, müssen sie den Locator der Anwendung zur Verfügung stellen, indem sie diese Methode aufrufen, bevor sie eine der anderen Methoden der DocumentHandler-Schnittstelle aufrufen.

Der Locator ermöglicht es der Anwendung, die Endposition eines beliebigen dokumentbezogenen Ereignisses zu ermitteln, auch wenn der Parser keinen Fehler meldet. Typischerweise wird die Anwendung diese Informationen zur Meldung eigener Fehler verwenden (z. B. Zeicheninhalt, der nicht mit den Geschäftsregeln einer Anwendung übereinstimmt). Die vom Locator zurückgegebenen Informationen sind wahrscheinlich nicht ausreichend für die Verwendung mit einer Suchmaschine.

Beachten Sie, dass der Locator nur während der Ausführung der Ereignisse dieser Schnittstelle korrekte Informationen zurückgibt. Die Anwendung sollte nicht versuchen, ihn zu einem anderen Zeitpunkt zu verwenden.

ContentHandler.startDocument()

Benachrichtigung über den Anfang eines Dokuments erhalten.

Der SAX-Parser ruft diese Methode nur einmal auf, bevor andere Methoden dieser Schnittstelle oder der DTDHandler (außer setDocumentLocator()) aufgerufen werden.

ContentHandler.endDocument()

Benachrichtigung über das Ende eines Dokuments erhalten.

Der SAX-Parser ruft diese Methode nur einmal auf, und sie ist die letzte Methode, die während des Parsens aufgerufen wird. Der Parser darf diese Methode erst aufrufen, wenn er entweder das Parsen abgebrochen hat (wegen eines nicht behebbaren Fehlers) oder das Ende der Eingabe erreicht hat.

ContentHandler.startPrefixMapping(prefix, uri)

Beginnt den Geltungsbereich einer Präfix-URI-Namespace-Zuordnung.

Die Informationen aus diesem Ereignis sind für die normale Namespace-Verarbeitung nicht erforderlich: Der SAX XML-Reader ersetzt automatisch Präfixe für Element- und Attributnamen, wenn das Feature feature_namespaces aktiviert ist (Standard).

Es gibt jedoch Fälle, in denen Anwendungen Präfixe in Zeicheninhalt oder Attributwerten verwenden müssen, wo sie nicht sicher automatisch erweitert werden können. Die Ereignisse startPrefixMapping() und endPrefixMapping() liefern der Anwendung die Informationen, um Präfixe in diesen Kontexten bei Bedarf selbst zu erweitern.

Beachten Sie, dass die Ereignisse startPrefixMapping() und endPrefixMapping() nicht garantiert ordnungsgemäß verschachtelt sind: Alle startPrefixMapping() Ereignisse treten vor dem entsprechenden startElement() Ereignis auf, und alle endPrefixMapping() Ereignisse treten nach dem entsprechenden endElement() Ereignis auf, aber ihre Reihenfolge ist nicht garantiert.

ContentHandler.endPrefixMapping(prefix)

Beendet den Geltungsbereich einer Präfix-URI-Zuordnung.

Siehe startPrefixMapping() für Details. Dieses Ereignis tritt immer nach dem entsprechenden endElement() Ereignis auf, aber die Reihenfolge der endPrefixMapping() Ereignisse ist ansonsten nicht garantiert.

ContentHandler.startElement(name, attrs)

Signalisiert den Beginn eines Elements im Nicht-Namespace-Modus.

Der Parameter name enthält den rohen XML 1.0 Namen des Elementtyps als Zeichenkette, und der Parameter attrs enthält ein Objekt der Attributes-Schnittstelle, die die Attribute des Elements enthält. Das als attrs übergebene Objekt kann vom Parser wiederverwendet werden; das Halten einer Referenz darauf ist keine zuverlässige Methode, um eine Kopie der Attribute zu behalten. Um eine Kopie der Attribute zu behalten, verwenden Sie die Methode copy() des attrs-Objekts.

ContentHandler.endElement(name)

Signalisiert das Ende eines Elements im Nicht-Namespace-Modus.

Der Parameter name enthält den Namen des Elementtyps, genau wie beim startElement()-Ereignis.

ContentHandler.startElementNS(name, qname, attrs)

Signalisiert den Beginn eines Elements im Namespace-Modus.

Der Parameter name enthält den Namen des Elementtyps als Tupel (uri, localname), der Parameter qname enthält den rohen XML 1.0 Namen, der im Quelldokument verwendet wurde, und der Parameter attrs enthält eine Instanz der AttributesNS-Schnittstelle, die die Attribute des Elements enthält. Wenn kein Namespace mit dem Element verknüpft ist, ist die uri-Komponente von name None. Das als attrs übergebene Objekt kann vom Parser wiederverwendet werden; das Halten einer Referenz darauf ist keine zuverlässige Methode, um eine Kopie der Attribute zu behalten. Um eine Kopie der Attribute zu behalten, verwenden Sie die Methode copy() des attrs-Objekts.

Parser können den Parameter qname auf None setzen, es sei denn, das Feature feature_namespace_prefixes ist aktiviert.

ContentHandler.endElementNS(name, qname)

Signalisiert das Ende eines Elements im Namespace-Modus.

Der Parameter name enthält den Namen des Elementtyps, genau wie bei der Methode startElementNS(), ebenso der Parameter qname.

ContentHandler.characters(content)

Benachrichtigung über Zeicheninhalt erhalten.

Der Parser ruft diese Methode auf, um jeden Teil des Zeicheninhalts zu melden. SAX-Parser können alle zusammenhängenden Zeicheninhalte in einem einzigen Teil zurückgeben oder sie in mehrere Teile aufteilen; alle Zeichen in einem einzelnen Ereignis müssen jedoch aus derselben externen Entität stammen, damit der Locator nützliche Informationen liefert.

content kann eine Zeichenkette oder ein Bytes-Objekt sein; das expat Reader-Modul erzeugt immer Zeichenketten.

Hinweis

Die ältere SAX 1-Schnittstelle, die vom Python XML Special Interest Group bereitgestellt wurde, verwendete eine eher Java-ähnliche Schnittstelle für diese Methode. Da die meisten von Python verwendeten Parser die ältere Schnittstelle nicht nutzten, wurde die einfachere Signatur gewählt, um sie zu ersetzen. Um alten Code in die neue Schnittstelle zu konvertieren, verwenden Sie content anstelle des Slicings von content mit den alten Parametern offset und length.

ContentHandler.ignorableWhitespace(whitespace)

Benachrichtigung über ignoriere Leerzeichen im Elementinhalt erhalten.

Validierende Parser müssen diese Methode verwenden, um jeden Teil ignorierten Leerzeichens zu melden (siehe W3C XML 1.0 Empfehlung, Abschnitt 2.10): Nicht-validierende Parser können diese Methode ebenfalls verwenden, wenn sie Inhaltsmodelle parsen und verwenden können.

SAX-Parser können alle zusammenhängenden Leerzeichen in einem einzigen Teil zurückgeben oder sie in mehrere Teile aufteilen; alle Zeichen in einem einzelnen Ereignis müssen jedoch aus derselben externen Entität stammen, damit der Locator nützliche Informationen liefert.

ContentHandler.processingInstruction(target, data)

Benachrichtigung über eine Verarbeitungsanweisung erhalten.

Der Parser ruft diese Methode einmal für jede gefundene Verarbeitungsanweisung auf: Beachten Sie, dass Verarbeitungsanweisungen vor oder nach dem Hauptelement des Dokuments auftreten können.

Ein SAX-Parser sollte niemals eine XML-Deklaration (XML 1.0, Abschnitt 2.8) oder eine Textdeklaration (XML 1.0, Abschnitt 4.3.1) mit dieser Methode melden.

ContentHandler.skippedEntity(name)

Benachrichtigung über eine übersprungene Entität erhalten.

Der Parser ruft diese Methode einmal für jede übersprungene Entität auf. Nicht-validierende Prozessoren können Entitäten überspringen, wenn sie die Deklarationen nicht gesehen haben (weil sie z. B. in einem externen DTD-Subset deklariert wurden). Alle Prozessoren können externe Entitäten überspringen, abhängig von den Werten der Eigenschaften feature_external_ges und feature_external_pes.

DTDHandler-Objekte

DTDHandler-Instanzen stellen die folgenden Methoden bereit

DTDHandler.notationDecl(name, publicId, systemId)

Behandelt ein Notationsdeklarationsereignis.

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

Behandelt ein Ereignis zur Deklaration einer nicht analysierten Entität.

EntityResolver-Objekte

EntityResolver.resolveEntity(publicId, systemId)

Löst den Systembezeichner einer Entität auf und gibt entweder den Systembezeichner zum Lesen als Zeichenkette oder ein InputSource zum Lesen zurück. Die Standardimplementierung gibt systemId zurück.

ErrorHandler-Objekte

Objekte mit dieser Schnittstelle werden verwendet, um Fehler- und Warninformationen vom XMLReader zu erhalten. Wenn Sie ein Objekt erstellen, das diese Schnittstelle implementiert, und das Objekt bei Ihrem XMLReader registrieren, ruft der Parser die Methoden Ihres Objekts auf, um alle Warnungen und Fehler zu melden. Es gibt drei Fehlerstufen: Warnungen, (möglicherweise) behebbar Fehler und nicht behebbare Fehler. Alle Methoden nehmen ein SAXParseException als einziges Argument. Fehler und Warnungen können durch Auslösen des übergebenen Ausnahmeobjekts in eine Ausnahme umgewandelt werden.

ErrorHandler.error(exception)

Wird aufgerufen, wenn der Parser einen behebbaren Fehler feststellt. Wenn diese Methode keine Ausnahme auslöst, kann die Verarbeitung fortgesetzt werden, aber weitere Dokumentinformationen sollten von der Anwendung nicht erwartet werden. Das Zulassen, dass der Parser fortfährt, kann dazu führen, dass zusätzliche Fehler im Eingabedokument entdeckt werden.

ErrorHandler.fatalError(exception)

Wird aufgerufen, wenn der Parser einen Fehler feststellt, von dem er sich nicht erholen kann; die Verarbeitung wird voraussichtlich beendet, wenn diese Methode zurückkehrt.

ErrorHandler.warning(exception)

Wird aufgerufen, wenn der Parser dem Anwendung geringfügige Warninformationen präsentiert. Die Verarbeitung wird voraussichtlich fortgesetzt, wenn diese Methode zurückkehrt, und Dokumentinformationen werden weiterhin an die Anwendung übermittelt. Das Auslösen einer Ausnahme in dieser Methode beendet die Verarbeitung.

LexicalHandler-Objekte

Optionaler SAX2-Handler für lexikalische Ereignisse.

Dieser Handler wird verwendet, um lexikalische Informationen über ein XML-Dokument zu erhalten. Lexikalische Informationen umfassen Informationen zur Dokumentenkodierung und XML-Kommentare, die im Dokument eingebettet sind, sowie Abschnittsgrenzen für die DTD und für alle CDATA-Abschnitte. Die lexikalischen Handler werden auf dieselbe Weise wie Content Handler verwendet.

Setzen Sie den LexicalHandler eines XMLReader mit der Methode `setProperty` und dem Property-Identifier 'http://xml.org/sax/properties/lexical-handler'.

LexicalHandler.comment(content)

Meldet einen Kommentar an einer beliebigen Stelle im Dokument (einschließlich der DTD und außerhalb des Hauptelements des Dokuments).

LexicalHandler.startDTD(name, public_id, system_id)

Meldet den Beginn der DTD-Deklarationen, wenn das Dokument eine zugehörige DTD hat.

LexicalHandler.endDTD()

Meldet das Ende der DTD-Deklaration.

LexicalHandler.startCDATA()

Meldet den Beginn eines CDATA-markierten Abschnitts.

Der Inhalt des CDATA-markierten Abschnitts wird über den Zeichen-Handler gemeldet.

LexicalHandler.endCDATA()

Meldet das Ende eines CDATA-markierten Abschnitts.