xml.sax.handler — Basklasser för SAX-hanterare

Källkod: Lib/xml/sax/handler.py

---

SAX API definierar fem typer av hanterare: innehållshanterare, DTD-hanterare, felhanterare, entitetslösare och lexikala hanterare. Applikationer behöver normalt bara implementera de gränssnitt vars händelser de är intresserade av; de kan implementera gränssnitten i ett enda objekt eller i flera objekt. Implementeringar av hanterare bör ärva från de basklasser som tillhandahålls i modulen xml.sax.handler, så att alla metoder får standardimplementeringar.

class xml.sax.handler.ContentHandler

Detta är det huvudsakliga callback-gränssnittet i SAX och det som är viktigast för applikationer. Ordningen på händelserna i detta gränssnitt speglar ordningen på informationen i dokumentet.

class xml.sax.handler.DTDHandler

Hantera DTD-händelser.

Detta gränssnitt specificerar endast de DTD-händelser som krävs för grundläggande parsning (ej parsade entiteter och attribut).

class xml.sax.handler.EntityResolver

Grundläggande gränssnitt för att lösa upp entiteter. Om du skapar ett objekt som implementerar detta gränssnitt och sedan registrerar objektet med din parser, kommer parsern att anropa metoden i ditt objekt för att lösa alla externa entiteter.

class xml.sax.handler.ErrorHandler

Gränssnitt som används av parsern för att presentera fel- och varningsmeddelanden till applikationen. Metoderna i detta objekt styr om fel omedelbart konverteras till undantag eller hanteras på något annat sätt.

class xml.sax.handler.LexicalHandler

Gränssnitt som används av parsern för att representera lågfrekventa händelser som kanske inte är av intresse för många applikationer.

Utöver dessa klasser tillhandahåller xml.sax.handler symboliska konstanter för namn på funktioner och egenskaper.

xml.sax.handler.feature_namespaces

värde: "http://xml.org/sax/features/namespaces"

sant: Utför bearbetning av namnrymden.

false: Utför eventuellt inte Namespace-bearbetning (innebär namespace-prefix; standard).

access: (parsing) skrivskyddad; (inte parsing) läs/skriv

xml.sax.handler.feature_namespace_prefixes

värde: "http://xml.org/sax/features/namespace-prefixes"

sant: Rapportera de ursprungliga prefixnamn och attribut som används för Namespace-deklarationer.

false (falsk): Rapportera inte attribut som används för namnrymdsdeklarationer, och rapportera eventuellt inte ursprungliga prefixnamn (standard).

access: (parsing) skrivskyddad; (inte parsing) läs/skriv

xml.sax.handler.feature_string_interning

värde: "http://xml.org/sax/features/string-interning"

sant: Alla elementnamn, prefix, attributnamn, Namespace URI:er och lokala namn interneras med hjälp av den inbyggda intern-funktionen.

false: Namn är inte nödvändigtvis internaliserade, även om de kan vara det (standard).

access: (parsing) skrivskyddad; (inte parsing) läs/skriv

xml.sax.handler.feature_validation

värde: "http://xml.org/sax/features/validation"

sant: Rapportera alla valideringsfel (innebär external-general-entities och external-parameter-entities).

falskt: Rapportera inte valideringsfel.

access: (parsing) skrivskyddad; (inte parsing) läs/skriv

xml.sax.handler.feature_external_ges

värde: "http://xml.org/sax/features/external-general-entities"

true: Inkluderar alla externa allmänna (text) enheter.

felaktig: Inkludera inte externa allmänna enheter.

access: (parsing) skrivskyddad; (inte parsing) läs/skriv

xml.sax.handler.feature_external_pes

värde: "http://xml.org/sax/features/external-parameter-entities"

true: Inkluderar alla externa parameterenheter, inklusive den externa DTD-delmängden.

falsk: Inkludera inte några externa parameterenheter, inte ens den externa DTD-delmängden.

access: (parsing) skrivskyddad; (inte parsing) läs/skriv

xml.sax.handler.all_features

Lista över alla funktioner.

xml.sax.handler.property_lexical_handler

värde: "http://xml.org/sax/properties/lexical-handler"

datatyp: xml.sax.handler.LexicalHandler (stöds inte i Python 2)

beskrivning: En valfri tilläggshanterare för lexikala händelser som kommentarer.

åtkomst: läs/skriv

xml.sax.handler.property_declaration_handler

värde: "http://xml.org/sax/properties/declaration-handler"

datatyp: xml.sax.sax2lib.DeclHandler (stöds inte i Python 2)

beskrivning: En valfri tilläggshanterare för DTD-relaterade händelser andra än notationer och oanalyserade entiteter.

åtkomst: läs/skriv

xml.sax.handler.property_dom_node

värde: "http://xml.org/sax/properties/dom-node"

datatyp: org.w3c.dom.Node (stöds inte i Python 2)

beskrivning: När den analyseras, den aktuella DOM-noden som besöks om detta är en DOM-iterator; när den inte analyseras, DOM-rotnoden för iteration.

access: (parsing) skrivskyddad; (inte parsing) läs/skriv

xml.sax.handler.property_xml_string

värde: "http://xml.org/sax/properties/xml-string"

datatyp: Byte

beskrivning: Den bokstavliga teckensträng som var källan till den aktuella händelsen.

åtkomst: skrivskyddad

xml.sax.handler.all_properties

Lista över alla kända fastighetsnamn.

ContentHandler-objekt

Användare förväntas underklassa ContentHandler för att stödja sin applikation. Följande metoder anropas av parsern vid lämpliga händelser i indatadokumentet:

ContentHandler.setDocumentLocator(locator)

Anropas av parsern för att ge programmet en lokator för att lokalisera ursprunget till dokumenthändelser.

SAX-parsare uppmuntras starkt (men är inte absolut nödvändiga) att tillhandahålla en lokator: om den gör det måste den tillhandahålla lokatorn till applikationen genom att anropa denna metod innan den anropar någon av de andra metoderna i DocumentHandler-gränssnittet.

Med hjälp av lokatorn kan programmet fastställa slutpositionen för alla dokumentrelaterade händelser, även om parsern inte rapporterar något fel. Vanligtvis kommer programmet att använda denna information för att rapportera sina egna fel (t.ex. teckeninnehåll som inte överensstämmer med programmets affärsregler). Den information som returneras av locatorn är förmodligen inte tillräcklig för att användas med en sökmotor.

Observera att lokatorn endast kommer att returnera korrekt information under anrop av händelserna i detta gränssnitt. Applikationen bör inte försöka använda den vid någon annan tidpunkt.

ContentHandler.startDocument()

Ta emot meddelande om början på ett dokument.

SAX-parsern kommer att anropa denna metod endast en gång, före alla andra metoder i detta gränssnitt eller i DTDHandler (utom setDocumentLocator()).

ContentHandler.endDocument()

Ta emot meddelande om slutet på ett dokument.

SAX-parsern anropar denna metod endast en gång, och det är den sista metoden som anropas under parsningen. Parsern ska inte anropa denna metod förrän den antingen har avbrutit parsningen (på grund av ett fel som inte kan återställas) eller nått slutet av inmatningen.

ContentHandler.startPrefixMapping(prefix, uri)

Börja omfattningen av en prefix-URI-namnrymdsmappning.

Informationen från denna händelse är inte nödvändig för normal Namespace-behandling: SAX XML-läsaren ersätter automatiskt prefix för element- och attributnamn när funktionen feature_namespaces är aktiverad (standard).

Det finns dock fall då program behöver använda prefix i teckendata eller i attributvärden, där de inte kan expanderas automatiskt på ett säkert sätt; händelserna startPrefixMapping() och endPrefixMapping() ger programmet information om att själv expandera prefix i dessa sammanhang, om det behövs.

Observera att händelserna startPrefixMapping() och endPrefixMapping() inte garanteras vara korrekt nästlade i förhållande till varandra: alla händelser i startPrefixMapping() kommer att inträffa före motsvarande händelse i startElement() och alla händelser i endPrefixMapping() kommer att inträffa efter motsvarande händelse i endElement(), men deras ordning garanteras inte.

ContentHandler.endPrefixMapping(prefix)

Avsluta räckvidden för en prefix-URI-mappning.

Se startPrefixMapping() för detaljer. Denna händelse kommer alltid att inträffa efter motsvarande händelse endElement(), men ordningen på händelserna endPrefixMapping() är inte garanterad på annat sätt.

ContentHandler.startElement(name, attrs)

Signalerar början på ett element i icke-namnrymdsläge.

Parametern name innehåller det råa XML 1.0-namnet på elementtypen som en sträng och parametern attrs innehåller ett objekt i gränssnittet Attributes (se Gränssnittet Attributes) som innehåller elementets attribut. Objektet som skickas som attrs kan återanvändas av parsern; att hålla fast vid en referens till det är inte ett tillförlitligt sätt att behålla en kopia av attributen. För att behålla en kopia av attributen, använd copy()-metoden för attrs-objektet.

ContentHandler.endElement(name)

Signalerar slutet på ett element i icke-namnrymdsläge.

Parametern name innehåller namnet på elementtypen, precis som i händelsen startElement().

ContentHandler.startElementNS(name, qname, attrs)

Signalerar början på ett element i namespace-läge.

Parametern name innehåller namnet på elementtypen som en tupel (uri, localname), parametern qname innehåller det råa XML 1.0-namnet som används i källdokumentet och parametern attrs innehåller en instans av AttributesNS-gränssnittet (se Gränssnittet AttributesNS) som innehåller elementets attribut. Om inget namnrymd är associerat med elementet kommer uri-komponenten i name att vara None. Objektet som skickas som attrs kan återanvändas av parsern; att behålla en referens till det är inte ett tillförlitligt sätt att behålla en kopia av attributen. För att behålla en kopia av attributen använder du metoden copy() i objektet attrs.

Parsers kan sätta parametern qname till None, såvida inte funktionen feature_namespace_prefixes är aktiverad.

ContentHandler.endElementNS(name, qname)

Signalerar slutet på ett element i namespace-läge.

Parametern name innehåller namnet på elementtypen, precis som i metoden startElementNS(), och likaså parametern qname.

ContentHandler.characters(content)

Ta emot meddelande om teckendata.

Parsern anropar denna metod för att rapportera varje bit av teckendata. SAX-parsers kan returnera all sammanhängande teckeninformation i en enda del eller dela upp den i flera delar, men alla tecken i en enskild händelse måste komma från samma externa enhet för att Locator ska kunna ge användbar information.

content kan vara en sträng eller en bytes-instans; läsarmodulen expat producerar alltid strängar.

Anteckning

Det tidigare SAX 1-gränssnittet som tillhandahölls av Python XML Special Interest Group använde ett mer Java-liknande gränssnitt för denna metod. Eftersom de flesta parsers som används från Python inte utnyttjade det äldre gränssnittet, valdes den enklare signaturen för att ersätta det. För att konvertera gammal kod till det nya gränssnittet, använd content istället för att skiva innehåll med de gamla parametrarna offset och length.

ContentHandler.ignorableWhitespace(whitespace)

Få meddelande om oacceptabla blanksteg i elementinnehåll.

Validerande parsare måste använda den här metoden för att rapportera varje bit av ignorabelt blanksteg (se W3C:s rekommendation XML 1.0, avsnitt 2.10): icke validerande parsare kan också använda den här metoden om de kan parsa och använda innehållsmodeller.

SAX-parser kan returnera allt sammanhängande blanksteg i en enda del eller dela upp det i flera delar, men alla tecken i en enda händelse måste komma från samma externa enhet så att Locator ger användbar information.

ContentHandler.processingInstruction(target, data)

Ta emot meddelande om en bearbetningsinstruktion.

Parsern kommer att anropa denna metod en gång för varje bearbetningsinstruktion som hittas: observera att bearbetningsinstruktioner kan förekomma före eller efter huvuddokumentelementet.

En SAX-parser bör aldrig rapportera en XML-deklaration (XML 1.0, avsnitt 2.8) eller en textdeklaration (XML 1.0, avsnitt 4.3.1) med denna metod.

ContentHandler.skippedEntity(name)

Ta emot meddelande om en överhoppad enhet.

Parsern kommer att anropa denna metod en gång för varje entitet som hoppas över. Processorer som inte validerar kan hoppa över entiteter om de inte har sett deklarationerna (t.ex. för att entiteten har deklarerats i en extern DTD-delmängd). Alla processorer kan hoppa över externa entiteter, beroende på värdena för egenskaperna feature_external_ges och feature_external_pes.

DTDHandler-objekt

DTDHandler-instanser tillhandahåller följande metoder:

DTDHandler.notationDecl(name, publicId, systemId)

Hantera en händelse för en notationsdeklaration.

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

Hantera en händelse med en oanalyserad enhetsdeklaration.

EntityResolver-objekt

EntityResolver.resolveEntity(publicId, systemId)

Resolverar systemidentifieraren för en entitet och returnerar antingen systemidentifieraren att läsa från som en sträng eller en InputSource att läsa från. Standardimplementeringen returnerar systemId.

ErrorHandler-objekt

Objekt med detta gränssnitt används för att ta emot fel- och varningsinformation från XMLReader. Om du skapar ett objekt som implementerar detta gränssnitt och sedan registrerar objektet med din XMLReader, kommer parsern att anropa metoderna i ditt objekt för att rapportera alla varningar och fel. Det finns tre olika nivåer av fel: varningar, (eventuellt) återställbara fel och oåterställbara fel. Alla metoder tar en SAXParseException som enda parameter. Fel och varningar kan konverteras till ett undantag genom att skapa det undantag som skickas in.

ErrorHandler.error(exception)

Anropas när parsern stöter på ett återställbart fel. Om denna metod inte ger upphov till ett undantag kan parsningen fortsätta, men ytterligare dokumentinformation bör inte förväntas av programmet. Om parsern tillåts fortsätta kan det leda till att ytterligare fel upptäcks i indatadokumentet.

ErrorHandler.fatalError(exception)

Anropas när parsaren stöter på ett fel som den inte kan återhämta sig från; parsningen förväntas avslutas när denna metod returneras.

ErrorHandler.warning(exception)

Anropas när parsern presenterar mindre varningsinformation till programmet. Parsningen förväntas fortsätta när denna metod returneras, och dokumentinformation kommer att fortsätta att skickas till programmet. Om ett undantag uppstår i denna metod kommer parsningen att avbrytas.

LexicalHandler-objekt

Valfri SAX2-hanterare för lexikala händelser.

Denna hanterare används för att erhålla lexikal information om ett XML-dokument. Lexikal information omfattar information som beskriver den dokumentkodning som används och XML-kommentarer som är inbäddade i dokumentet, samt avsnittsgränser för DTD och för eventuella CDATA-avsnitt. De lexikala hanterarna används på samma sätt som innehållshanterarna.

Ange LexicalHandler för en XMLReader genom att använda setProperty-metoden med egenskapsidentifieraren 'http://xml.org/sax/properties/lexical-handler'.

LexicalHandler.comment(content)

Rapporterar en kommentar var som helst i dokumentet (inklusive DTD och utanför dokumentelementet).

LexicalHandler.startDTD(name, public_id, system_id)

Rapporterar början på DTD-deklarationerna om dokumentet har en tillhörande DTD.

LexicalHandler.endDTD()

Rapporterar slutet av DTD-deklarationen.

LexicalHandler.startCDATA()

Rapporterar början på ett CDATA-märkt avsnitt.

Innehållet i den CDATA-märkta sektionen kommer att rapporteras via teckenhanteraren.

LexicalHandler.endCDATA()

Rapporterar slutet på ett CDATA-märkt avsnitt.