xml.sax — Stöd för SAX2-parser

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

Paketet xml.sax innehåller ett antal moduler som implementerar Simple API for XML (SAX)-gränssnittet för Python. Paketet i sig innehåller SAX-undantagen och de bekvämlighetsfunktioner som kommer att användas mest av användare av SAX API.

Anteckning

Om du behöver analysera otillförlitliga eller oautentiserade data, se XML-säkerhet.

Ändrad i version 3.7.1: SAX-parsern bearbetar inte längre allmänna externa entiteter som standard för att öka säkerheten. Tidigare skapade parsern nätverksanslutningar för att hämta fjärrfiler eller läste in lokala filer från filsystemet för DTD och entiteter. Funktionen kan aktiveras igen med metod setFeature() på parserobjektet och argument feature_external_ges.

De praktiska funktionerna är:

xml.sax.make_parser(parser_list=[])

Skapar och returnerar ett SAX XMLReader-objekt. Den första parsern som hittas kommer att användas. Om parser_list anges måste det vara en iterabel av strängar som namnger moduler som har en funktion med namnet create_parser(). Moduler som listas i parser_list kommer att användas före moduler i standardlistan över parsers.

Ändrad i version 3.8: Argumentet parser_list kan vara vilken iterabel som helst, inte bara en lista.

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

Skapa en SAX-parser och använd den för att analysera ett dokument. Dokumentet, som skickas in som filnamn_eller_ström, kan vara ett filnamn eller ett filobjekt. Parametern handler måste vara en SAX-instans av ContentHandler. Om error_handler anges måste den vara en SAX ErrorHandler-instans; om den utelämnas kommer SAXParseException att aktiveras vid alla fel. Det finns inget returvärde; allt arbete måste utföras av den handler som skickas in.

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

Liknar parse(), men analyserar från en buffert string som tas emot som en parameter. string måste vara en str-instans eller en bytes-like object.

Ändrad i version 3.5: Lagt till stöd för str-instanser.

En typisk SAX-applikation använder tre typer av objekt: läsare, hanterare och indatakällor. ”Reader” är i det här sammanhanget en annan term för parser, dvs. en kod som läser bytes eller tecken från inmatningskällan och producerar en sekvens av händelser. Händelserna distribueras sedan till hanterarobjekten, dvs. läsaren anropar en metod i hanteraren. En SAX-applikation måste därför skaffa ett läsarobjekt, skapa eller öppna inmatningskällorna, skapa hanterarna och koppla ihop alla dessa objekt. Som sista steg i förberedelserna anropas läsaren för att parsa indata. Under parsningen anropas metoder i hanterarobjekten baserat på strukturella och syntaktiska händelser från indata.

För dessa objekt är det bara gränssnitten som är relevanta; de instansieras normalt inte av själva applikationen. Eftersom Python inte har ett explicit begrepp för gränssnitt introduceras de formellt som klasser, men applikationer kan använda implementationer som inte ärver från de tillhandahållna klasserna. Gränssnitten InputSource, Locator, Attributes, AttributesNS och XMLReader definieras i modulen xml.sax.xmlreader. Hanterargränssnitten definieras i xml.sax.handler. För enkelhetens skull är InputSource (som ofta instansieras direkt) och klasserna för hantering också tillgängliga från xml.sax. Dessa gränssnitt beskrivs nedan.

Utöver dessa klasser tillhandahåller xml.sax följande undantagsklasser.

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

Kapslar in ett XML-fel eller en XML-varning. Den här klassen kan innehålla grundläggande fel- eller varningsinformation från antingen XML-parsern eller programmet: den kan underklassas för att ge ytterligare funktionalitet eller för att lägga till lokalisering. Observera att även om de hanterare som definieras i ErrorHandler-gränssnittet tar emot instanser av detta undantag, är det inte nödvändigt att faktiskt lyfta undantaget — det är också användbart som en behållare för information.

När msg instansieras bör det vara en mänskligt läsbar beskrivning av felet. Den valfria parametern exception, om den anges, ska vara None eller ett undantag som fångades upp av parsningskoden och som skickas vidare som information.

Detta är basklassen för de andra SAX-undantagsklasserna.

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

Underklass till SAXException som uppstår vid parse-fel. Instanser av den här klassen skickas till metoderna i SAX ErrorHandler-gränssnittet för att ge information om parse-felet. Denna klass stöder SAX Locator-gränssnittet samt SAXException-gränssnittet.

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

Subklass av SAXException som uppstår när en SAX XMLReader konfronteras med en funktion eller egenskap som inte känns igen. SAX-applikationer och tillägg kan använda denna klass för liknande ändamål.

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

Subklass av SAXException som uppstår när en SAX XMLReader ombeds aktivera en funktion som inte stöds, eller att sätta en egenskap till ett värde som implementationen inte stöder. SAX-applikationer och tillägg kan använda denna klass för liknande ändamål.

Se även

SAX: Det enkla API:et för XML

Den här webbplatsen är en samlingsplats för definitionen av SAX API. Här finns en Java-implementation och dokumentation online. Länkar till implementationer och historisk information finns också tillgängliga.

Modul xml.sax.handler

Definitioner av gränssnitt för objekt som tillhandahålls av applikationen.

Modul xml.sax.saxutils

Praktiska funktioner för användning i SAX-applikationer.

Modul xml.sax.xmlreader

Definitioner av gränssnitten för objekt som tillhandahålls av parsern.

SAXException-objekt

Undantagsklassen SAXException har stöd för följande metoder:

SAXException.getMessage()

Returnerar ett mänskligt läsbart meddelande som beskriver feltillståndet.

SAXException.getException()

Returnerar ett inkapslat undantagsobjekt, eller None.