xml.sax.xmlreader — Gränssnitt för XML-parser

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

SAX-parsers implementerar gränssnittet XMLReader. De implementeras i en Python-modul, som måste tillhandahålla en funktion create_parser(). Denna funktion anropas av xml.sax.make_parser() utan argument för att skapa ett nytt parser-objekt.

class xml.sax.xmlreader.XMLReader

Basklass som kan ärvas av SAX-parsers.

class xml.sax.xmlreader.IncrementalParser

I vissa fall är det önskvärt att inte analysera en inmatningskälla på en gång, utan att mata in delar av dokumentet allteftersom de blir tillgängliga. Observera att läsaren normalt inte kommer att läsa hela filen, utan även läsa den i bitar; ändå kommer parse() inte att returnera förrän hela dokumentet har bearbetats. Så dessa gränssnitt bör användas om det blockerande beteendet hos parse() inte är önskvärt.

När parsern instansieras är den redo att omedelbart börja ta emot data från feed-metoden. Efter att parsningen har avslutats med ett anrop till close måste reset-metoden anropas för att göra parsaren redo att ta emot nya data, antingen från feed eller med parse-metoden.

Observera att dessa metoder inte får anropas under parsningen, dvs. efter att parse har anropats och innan den returneras.

Som standard implementerar klassen också parse-metoden i XMLReader-gränssnittet med hjälp av feed-, close- och reset-metoderna i IncrementalParser-gränssnittet för att underlätta för skrivare av SAX 2.0-drivrutiner.

class xml.sax.xmlreader.Locator

Gränssnitt för att associera en SAX-händelse med en dokumentplats. Ett locator-objekt returnerar giltiga resultat endast under anrop till DocumentHandler-metoder; vid varje annan tidpunkt är resultaten oförutsägbara. Om information inte är tillgänglig kan metoderna returnera None.

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

Inkapsling av den information som behövs av XMLReader för att läsa entiteter.

Denna klass kan innehålla information om den offentliga identifieraren, systemidentifieraren, byteströmmen (eventuellt med information om teckenkodning) och/eller teckenströmmen för en enhet.

Applikationer kommer att skapa objekt av denna klass för användning i XMLReader.parse()-metoden och för returnering från EntityResolver.resolveEntity.

En InputSource tillhör applikationen, XMLReader får inte modifiera InputSource-objekt som skickas till den från applikationen, även om den får göra kopior och modifiera dessa.

class xml.sax.xmlreader.AttributesImpl(attrs)

Detta är en implementation av gränssnittet Attributes (se avsnitt Gränssnittet Attributes). Detta är ett ordboksliknande objekt som representerar elementattributen i ett startElement()-anrop. Förutom de mest användbara ordboksoperationerna stöder det ett antal andra metoder som beskrivs av gränssnittet. Objekt av denna klass bör instansieras av läsare; attrs måste vara ett ordboksliknande objekt som innehåller en mappning från attributnamn till attributvärden.

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

Namnrymdsmedveten variant av AttributesImpl, som kommer att skickas till startElementNS(). Den härstammar från AttributesImpl, men förstår attributnamn som två dupletter av namespaceURI och localname. Dessutom innehåller den ett antal metoder som förväntar sig kvalificerade namn så som de förekommer i originaldokumentet. Denna klass implementerar gränssnittet AttributesNS (se avsnitt Gränssnittet AttributesNS).

XMLReader-objekt

Gränssnittet XMLReader har stöd för följande metoder:

XMLReader.parse(source)

Bearbetar en indatakälla och producerar SAX-händelser. Objektet source kan vara en systemidentifierare (en sträng som identifierar indatakällan - vanligtvis ett filnamn eller en URL), ett pathlib.Path- eller path-like-objekt, eller ett InputSource-objekt. När parse() returneras har indata bearbetats fullständigt och parser-objektet kan kasseras eller återställas.

Ändrad i version 3.5: Stöd för teckenströmmar har lagts till.

Ändrad i version 3.8: Stöd för vägliknande objekt har lagts till.

XMLReader.getContentHandler()

Returnerar den aktuella ContentHandler.

XMLReader.setContentHandler(handler)

Ställ in den aktuella ContentHandler. Om ingen ContentHandler är inställd kommer innehållshändelser att kasseras.

XMLReader.getDTDHandler()

Returnerar den aktuella DTDHandler.

XMLReader.setDTDHandler(handler)

Ställ in den aktuella DTDHandler. Om ingen DTDHandler anges kommer DTD-händelser att kasseras.

XMLReader.getEntityResolver()

Returnerar den aktuella EntityResolver.

XMLReader.setEntityResolver(handler)

Ange den aktuella EntityResolver. Om ingen EntityResolver har angetts kommer försök att lösa en extern entitet att resultera i att systemidentifieraren för entiteten öppnas och misslyckas om den inte är tillgänglig.

XMLReader.getErrorHandler()

Returnerar den aktuella ErrorHandler.

XMLReader.setErrorHandler(handler)

Ställer in den aktuella felhanteraren. Om ingen ErrorHandler anges, kommer fel att tas upp som undantag och varningar kommer att skrivas ut.

XMLReader.setLocale(locale)

Tillåt en applikation att ange språk för fel och varningar.

SAX-parsers behöver inte tillhandahålla lokalisering för fel och varningar, men om de inte kan stödja den begärda språkdräkten måste de ge upphov till ett SAX-undantag. Applikationer kan begära en lokaländring mitt under en parsning.

XMLReader.getFeature(featurename)

Returnerar den aktuella inställningen för funktionen featurename. Om funktionen inte känns igen, SAXNotRecognizedException. De välkända funktionsnamnen finns listade i modulen xml.sax.handler.

XMLReader.setFeature(featurename, value)

Ställ in featurename till value. Om egenskapen inte känns igen, SAXNotRecognizedException utlöses. Om funktionen eller dess inställning inte stöds av parsern, genereras SAXNotSupportedException.

XMLReader.getProperty(propertyname)

Returnerar den aktuella inställningen för egenskapen propertyname. Om egenskapen inte känns igen kommer ett SAXNotRecognizedException att uppstå. De välkända egenskapsnamnen finns listade i modulen xml.sax.handler.

XMLReader.setProperty(propertyname, value)

Ställ in propertyname till value. Om egenskapen inte känns igen, SAXNotRecognizedException utlöses. Om egenskapen eller dess inställning inte stöds av parsern, genereras SAXNotSupportedException.

IncrementalParser-objekt

Instanser av IncrementalParser erbjuder följande ytterligare metoder:

IncrementalParser.feed(data)

Behandla en bit av data.

IncrementalParser.close()

Anta att dokumentet är slut. Det kommer att kontrollera villkor för välformadhet som bara kan kontrolleras i slutet, anropa hanterare och kan rensa upp resurser som tilldelats under parsning.

IncrementalParser.reset()

Denna metod anropas efter att close har anropats för att återställa parsern så att den är redo att parsa nya dokument. Resultatet av att anropa parse eller feed efter close utan att anropa reset är odefinierat.

Lokaliseringsobjekt

Instanser av Locator tillhandahåller dessa metoder:

Locator.getColumnNumber()

Returnerar kolumnnumret där den aktuella händelsen börjar.

Locator.getLineNumber()

Returnerar radnumret där den aktuella händelsen börjar.

Locator.getPublicId()

Returnerar den offentliga identifieraren för den aktuella händelsen.

Locator.getSystemId()

Returnerar systemidentifieraren för den aktuella händelsen.

InputSource-objekt

InputSource.setPublicId(id)

Anger den offentliga identifieraren för denna InputSource.

InputSource.getPublicId()

Returnerar den offentliga identifieraren för denna InputSource.

InputSource.setSystemId(id)

Ställer in systemidentifieraren för denna InputSource.

InputSource.getSystemId()

Returnerar systemidentifieraren för denna InputSource.

InputSource.setEncoding(encoding)

Ställer in teckenkodningen för denna InputSource.

Kodningen måste vara en sträng som är godtagbar för en XML-kodningsdeklaration (se avsnitt 4.3.3 i XML-rekommendationen).

Encoding-attributet för InputSource ignoreras om InputSource också innehåller en teckenström.

InputSource.getEncoding()

Hämta teckenkodningen för denna InputSource.

InputSource.setByteStream(bytefile)

Ange byteströmmen (en binary file) för denna inmatningskälla.

SAX-parsern ignorerar detta om det också finns en teckenström angiven, men den kommer att använda en byte-ström i stället för att öppna en URI-anslutning själv.

Om applikationen känner till teckenkodningen för byteströmmen bör den ange den med metoden setEncoding.

InputSource.getByteStream()

Hämta byte-strömmen för denna inmatningskälla.

Metoden getEncoding returnerar teckenkodningen för denna byte-ström, eller None om den är okänd.

InputSource.setCharacterStream(charfile)

Ange teckenflödet (en textfil) för denna inmatningskälla.

Om en teckenström anges kommer SAX-parsern att ignorera eventuella byteflöden och inte försöka öppna en URI-anslutning till systemidentifieraren.

InputSource.getCharacterStream()

Hämta teckenströmmen för denna inmatningskälla.

Gränssnittet Attributes

Attributes-objekt implementerar en del av mapping-protokollet, inklusive metoderna copy(), get(), __contains__(), items(), keys(), och values(). Följande metoder tillhandahålls också:

Attributes.getLength()

Returnera antalet attribut.

Attributes.getNames()

Returnerar namnen på attributen.

Attributes.getType(name)

Returnerar typen av attributet name, som normalt är 'CDATA'.

Attributes.getValue(name)

Returnera värdet för attributet name.

Gränssnittet AttributesNS

Detta gränssnitt är en subtyp av gränssnittet Attributes (se avsnitt Gränssnittet Attributes). Alla metoder som stöds av det gränssnittet är också tillgängliga på AttributesNS-objekt.

Följande metoder är också tillgängliga:

AttributesNS.getValueByQName(name)

Returnera värdet för ett kvalificerat namn.

AttributesNS.getNameByQName(name)

Returnerar paret (namespace, localname) för ett kvalificerat namn.

AttributesNS.getQNameByName(name)

Returnerar det kvalificerade namnet för ett par (namespace, localname).

AttributesNS.getQNames()

Returnerar de kvalificerade namnen på alla attribut.