xml.etree.ElementTree — Die ElementTree XML API

Quellcode: Lib/xml/etree/ElementTree.py

---

Das Modul xml.etree.ElementTree implementiert eine einfache und effiziente API zum Parsen und Erstellen von XML-Daten.

Geändert in Version 3.3: Dieses Modul verwendet, sofern verfügbar, eine schnelle Implementierung.

Veraltet seit Version 3.3: Das Modul xml.etree.cElementTree ist veraltet.

Hinweis

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

Tutorial

Dies ist ein kurzes Tutorial zur Verwendung von xml.etree.ElementTree (kurz ET). Das Ziel ist es, einige der Bausteine und grundlegenden Konzepte des Moduls zu demonstrieren.

XML-Baum und Elemente

XML ist ein inhärent hierarchisches Datenformat, und die natürlichste Art, es darzustellen, ist ein Baum. ET hat zu diesem Zweck zwei Klassen – ElementTree repräsentiert das gesamte XML-Dokument als Baum, und Element repräsentiert einen einzelnen Knoten in diesem Baum. Interaktionen mit dem gesamten Dokument (Lesen und Schreiben von/zu Dateien) werden normalerweise auf der Ebene von ElementTree durchgeführt. Interaktionen mit einem einzelnen XML-Element und seinen Unterelementen werden auf der Ebene von Element durchgeführt.

XML parsen

Wir werden das fiktive XML-Dokument country_data.xml als Beispieldaten für diesen Abschnitt verwenden.

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank>1</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank>4</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank>68</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Wir können diese Daten importieren, indem wir aus einer Datei lesen.

import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()

Oder direkt aus einem String.

root = ET.fromstring(country_data_as_string)

fromstring() parst XML aus einem String direkt in ein Element, welches das Wurzellement des geparsten Baumes ist. Andere Parsing-Funktionen erstellen möglicherweise ein ElementTree. Schauen Sie in der Dokumentation nach, um sicher zu sein.

Als Element hat root ein Tag und ein Wörterbuch von Attributen.

>>> root.tag
'data'
>>> root.attrib
{}

Es hat auch Kindknoten, über die wir iterieren können.

>>> for child in root:
...     print(child.tag, child.attrib)
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}

Kinder sind verschachtelt, und wir können über den Index auf bestimmte Kindknoten zugreifen.

>>> root[0][1].text
'2008'

Hinweis

Nicht alle Elemente der XML-Eingabe werden zu Elementen des geparsten Baumes. Derzeit überspringt dieses Modul alle XML-Kommentare, Verarbeitungsanweisungen und Dokumenttypdeklarationen in der Eingabe. Dennoch können Bäume, die mit der API dieses Moduls anstelle des Parsens aus XML-Text erstellt wurden, Kommentare und Verarbeitungsanweisungen enthalten; diese werden bei der Generierung von XML-Ausgaben einbezogen. Eine Dokumenttypdeklaration kann durch Übergabe einer benutzerdefinierten TreeBuilder-Instanz an den Konstruktor von XMLParser abgerufen werden.

Pull-API für nicht-blockierendes Parsen

Die meisten von diesem Modul bereitgestellten Parsing-Funktionen erfordern, dass das gesamte Dokument auf einmal gelesen wird, bevor ein Ergebnis zurückgegeben wird. Es ist möglich, einen XMLParser zu verwenden und Daten inkrementell hineinzufüttern, aber es ist eine Push-API, die Methoden auf einem Callback-Ziel aufruft, was für die meisten Bedürfnisse zu low-level und umständlich ist. Manchmal möchte der Benutzer eigentlich XML inkrementell parsen, ohne blockierende Operationen, und dabei den Komfort von vollständig konstruierten Element-Objekten genießen.

Das mächtigste Werkzeug dafür ist XMLPullParser. Er erfordert kein blockierendes Lesen, um die XML-Daten zu erhalten, und wird stattdessen inkrementell mit Aufrufen von XMLPullParser.feed() gefüttert. Um die geparsten XML-Elemente zu erhalten, ruft man XMLPullParser.read_events() auf. Hier ist ein Beispiel:

>>> parser = ET.XMLPullParser(['start', 'end'])
>>> parser.feed('<mytag>sometext')
>>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> parser.feed(' more text</mytag>')
>>> for event, elem in parser.read_events():
...     print(event)
...     print(elem.tag, 'text=', elem.text)
...
end
mytag text= sometext more text

Der offensichtliche Anwendungsfall sind Anwendungen, die nicht-blockierend arbeiten, bei denen die XML-Daten von einem Socket empfangen oder inkrementell von einem Speichermedium gelesen werden. In solchen Fällen sind blockierende Lesevorgänge nicht akzeptabel.

Da er so flexibel ist, kann XMLPullParser für einfachere Anwendungsfälle umständlich zu bedienen sein. Wenn es Ihnen nichts ausmacht, dass Ihre Anwendung beim Lesen von XML-Daten blockiert, aber Sie dennoch inkrementelle Parsing-Fähigkeiten wünschen, werfen Sie einen Blick auf iterparse(). Dies kann nützlich sein, wenn Sie ein großes XML-Dokument lesen und es nicht vollständig im Speicher halten möchten.

Wenn *sofortiges* Feedback durch Ereignisse gewünscht wird, kann der Aufruf der Methode XMLPullParser.flush() helfen, die Verzögerung zu reduzieren; bitte stellen Sie sicher, dass Sie die zugehörigen Sicherheitshinweise studieren.

Interessante Elemente finden

Element hat einige nützliche Methoden, die helfen, rekursiv über den gesamten Unterbaum darunter zu iterieren (seine Kinder, deren Kinder usw.). Zum Beispiel Element.iter().

>>> for neighbor in root.iter('neighbor'):
...     print(neighbor.attrib)
...
{'name': 'Austria', 'direction': 'E'}
{'name': 'Switzerland', 'direction': 'W'}
{'name': 'Malaysia', 'direction': 'N'}
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}

Element.findall() findet nur Elemente mit einem Tag, die direkte Kinder des aktuellen Elements sind. Element.find() findet das *erste* Kind mit einem bestimmten Tag, und Element.text greift auf den Textinhalt des Elements zu. Element.get() greift auf die Attribute des Elements zu.

>>> for country in root.findall('country'):
...     rank = country.find('rank').text
...     name = country.get('name')
...     print(name, rank)
...
Liechtenstein 1
Singapore 4
Panama 68

Eine ausgefeiltere Spezifikation, nach welchen Elementen gesucht werden soll, ist durch die Verwendung von XPath möglich.

Eine XML-Datei ändern

ElementTree bietet eine einfache Möglichkeit, XML-Dokumente zu erstellen und in Dateien zu schreiben. Die Methode ElementTree.write() dient diesem Zweck.

Ein Element-Objekt kann nach seiner Erstellung manipuliert werden, indem seine Felder (wie Element.text) direkt geändert, Attribute hinzugefügt und geändert werden (Methode Element.set()) sowie neue Kinder hinzugefügt werden (z. B. mit Element.append()).

Nehmen wir an, wir möchten jedem Land einen Rang hinzufügen und dem Rang-Element ein Attribut updated hinzufügen.

>>> for rank in root.iter('rank'):
...     new_rank = int(rank.text) + 1
...     rank.text = str(new_rank)
...     rank.set('updated', 'yes')
...
>>> tree.write('output.xml')

Unser XML sieht nun so aus:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank updated="yes">69</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Wir können Elemente mit Element.remove() entfernen. Nehmen wir an, wir möchten alle Länder mit einem Rang über 50 entfernen.

>>> for country in root.findall('country'):
...     # using root.findall() to avoid removal during traversal
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

Beachten Sie, dass gleichzeitige Änderungen während der Iteration zu Problemen führen können, genau wie bei der Iteration und Änderung von Python-Listen oder -Dictionaries. Daher sammelt das Beispiel zuerst alle übereinstimmenden Elemente mit root.findall() und iteriert dann erst über die Liste der Übereinstimmungen.

Unser XML sieht nun so aus:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
</data>

XML-Dokumente erstellen

Die Funktion SubElement() bietet ebenfalls eine bequeme Möglichkeit, neue Unterelemente für ein gegebenes Element zu erstellen.

>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>

XML mit Namespaces parsen

Wenn die XML-Eingabe Namespaces hat, werden Tags und Attribute mit Präfixen der Form prefix:sometag zu {uri}sometag erweitert, wobei das *Präfix* durch die vollständige *URI* ersetzt wird. Wenn es auch einen Standard-Namespace gibt, wird diese vollständige URI allen nicht präfixierten Tags vorangestellt.

Hier ist ein XML-Beispiel, das zwei Namespaces enthält, einen mit dem Präfix „fictional“ und den anderen, der als Standard-Namespace dient.

<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
        xmlns="http://people.example.com">
    <actor>
        <name>John Cleese</name>
        <fictional:character>Lancelot</fictional:character>
        <fictional:character>Archie Leach</fictional:character>
    </actor>
    <actor>
        <name>Eric Idle</name>
        <fictional:character>Sir Robin</fictional:character>
        <fictional:character>Gunther</fictional:character>
        <fictional:character>Commander Clement</fictional:character>
    </actor>
</actors>

Eine Möglichkeit, dieses XML-Beispiel zu durchsuchen und zu untersuchen, besteht darin, die URI manuell zu jedem Tag oder Attribut im XPath eines find() oder findall() hinzuzufügen.

root = fromstring(xml_text)
for actor in root.findall('{http://people.example.com}actor'):
    name = actor.find('{http://people.example.com}name')
    print(name.text)
    for char in actor.findall('{http://characters.example.com}character'):
        print(' |-->', char.text)

Eine bessere Methode, das Namespaces-XML-Beispiel zu durchsuchen, ist die Erstellung eines Wörterbuchs mit eigenen Präfixen und deren Verwendung in den Suchfunktionen.

ns = {'real_person': 'http://people.example.com',
      'role': 'http://characters.example.com'}

for actor in root.findall('real_person:actor', ns):
    name = actor.find('real_person:name', ns)
    print(name.text)
    for char in actor.findall('role:character', ns):
        print(' |-->', char.text)

Diese beiden Ansätze ergeben beides:

John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement

XPath-Unterstützung

Dieses Modul bietet eingeschränkte Unterstützung für XPath-Ausdrücke zum Auffinden von Elementen in einem Baum. Das Ziel ist die Unterstützung einer kleinen Teilmenge der abgekürzten Syntax; eine vollständige XPath-Engine liegt außerhalb des Rahmens des Moduls.

Beispiel

Hier ist ein Beispiel, das einige der XPath-Fähigkeiten des Moduls demonstriert. Wir verwenden das XML-Dokument countrydata aus dem Abschnitt XML parsen.

import xml.etree.ElementTree as ET

root = ET.fromstring(countrydata)

# Top-level elements
root.findall(".")

# All 'neighbor' grand-children of 'country' children of the top-level
# elements
root.findall("./country/neighbor")

# Nodes with name='Singapore' that have a 'year' child
root.findall(".//year/..[@name='Singapore']")

# 'year' nodes that are children of nodes with name='Singapore'
root.findall(".//*[@name='Singapore']/year")

# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")

Für XML mit Namespaces verwenden Sie die übliche qualifizierte Notation {namespace}tag.

# All dublin-core "title" tags in the document
root.findall(".//{http://purl.org/dc/elements/1.1/}title")

Unterstützte XPath-Syntax

Syntax	Bedeutung
tag	Wählt alle Kindelemente mit dem gegebenen Tag aus. Zum Beispiel wählt spam alle Kindelemente mit dem Namen spam aus, und spam/egg wählt alle Enkel mit dem Namen egg in allen Kindern mit dem Namen spam aus. {namespace}* wählt alle Tags im gegebenen Namespace aus, {*}spam wählt Tags mit dem Namen spam in irgendeinem (oder keinem) Namespace aus, und {}* wählt nur Tags aus, die nicht in einem Namespace sind. Geändert in Version 3.8: Unterstützung für Sternchen-Wildcards wurde hinzugefügt.
*	Wählt alle Kindelemente aus, einschließlich Kommentare und Verarbeitungsanweisungen. Zum Beispiel wählt */egg alle Enkel mit dem Namen egg aus.
.	Wählt den aktuellen Knoten aus. Dies ist meist am Anfang des Pfads nützlich, um anzuzeigen, dass es sich um einen relativen Pfad handelt.
//	Wählt alle Unterelemente auf allen Ebenen unterhalb des aktuellen Elements aus. Zum Beispiel wählt .//egg alle egg-Elemente im gesamten Baum aus.
..	Wählt das Elternelement aus. Gibt None zurück, wenn der Pfad versucht, die Vorfahren des Startelements (das Element, auf dem find aufgerufen wurde) zu erreichen.
[@attrib]	Wählt alle Elemente aus, die das gegebene Attribut haben.
[@attrib='value']	Wählt alle Elemente aus, für die das gegebene Attribut den gegebenen Wert hat. Der Wert darf keine Anführungszeichen enthalten.
[@attrib!='value']	Wählt alle Elemente aus, für die das gegebene Attribut nicht den gegebenen Wert hat. Der Wert darf keine Anführungszeichen enthalten. Hinzugefügt in Version 3.10.
[tag]	Wählt alle Elemente aus, die ein Kind mit dem Namen tag haben. Nur direkte Kinder werden unterstützt.
[.='text']	Wählt alle Elemente aus, deren vollständiger Textinhalt, einschließlich Nachkommen, dem gegebenen text entspricht. Hinzugefügt in Version 3.7.
[.!='text']	Wählt alle Elemente aus, deren vollständiger Textinhalt, einschließlich Nachkommen, nicht dem gegebenen text entspricht. Hinzugefügt in Version 3.10.
[tag='text']	Wählt alle Elemente aus, die ein Kind mit dem Namen tag haben, dessen vollständiger Textinhalt, einschließlich Nachkommen, dem gegebenen text entspricht.
[tag!='text']	Wählt alle Elemente aus, die ein Kind mit dem Namen tag haben, dessen vollständiger Textinhalt, einschließlich Nachkommen, nicht dem gegebenen text entspricht. Hinzugefügt in Version 3.10.
[position]	Wählt alle Elemente aus, die sich an der gegebenen Position befinden. Die Position kann entweder eine Ganzzahl sein (1 ist die erste Position), der Ausdruck last() (für die letzte Position) oder eine Position relativ zur letzten Position (z. B. last()-1).

Prädikate (Ausdrücke in eckigen Klammern) müssen einem Tag-Namen, einem Sternchen oder einem anderen Prädikat vorangestellt sein. position-Prädikaten muss ein Tag-Name vorangestellt sein.

Referenz

Funktionen

xml.etree.ElementTree.canonicalize(xml_data=None, *, out=None, from_file=None, **options)

C14N 2.0 Transformationsfunktion.

Kanonisierung ist eine Methode zur Normalisierung von XML-Ausgaben, die Byte-für-Byte-Vergleiche und digitale Signaturen ermöglicht. Sie reduziert die Freiheit, die XML-Serialisierer haben, und erzeugt stattdessen eine eingeschränktere XML-Darstellung. Die Hauptbeschränkungen betreffen die Platzierung von Namespace-Deklarationen, die Reihenfolge von Attributen und ignorierbaren Whitespace.

Diese Funktion nimmt einen XML-Daten-String (xml_data) oder einen Dateipfad oder ein dateiähnliches Objekt (from_file) als Eingabe, konvertiert ihn in die kanonische Form und schreibt ihn mit dem Ausgabedatei(-ähnlichen) Objekt out, falls vorhanden, oder gibt ihn als Textstring zurück, falls nicht. Die Ausgabedatei empfängt Text, keine Bytes. Sie sollte daher im Textmodus mit utf-8-Kodierung geöffnet werden.

Typische Verwendungen

xml_data = "<root>...</root>"
print(canonicalize(xml_data))

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(xml_data, out=out_file)

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(from_file="inputfile.xml", out=out_file)

Die Konfiguration options sind wie folgt:

• with_comments: auf true setzen, um Kommentare einzuschließen (Standard: false)

• strip_text: auf true setzen, um Whitespace vor und nach dem Textinhalt zu entfernen

  (Standard: false)

• rewrite_prefixes: auf true setzen, um Namespace-Präfixe durch „n{number}“ zu ersetzen

  (Standard: false)

• qname_aware_tags: eine Menge von QName-bewussten Tag-Namen, bei denen Präfixe

  im Textinhalt ersetzt werden sollten (Standard: leer)

• qname_aware_attrs: eine Menge von QName-bewussten Attributnamen, bei denen Präfixe

  im Textinhalt ersetzt werden sollten (Standard: leer)

• exclude_attrs: eine Menge von Attributnamen, die nicht serialisiert werden sollten

• exclude_tags: eine Menge von Tag-Namen, die nicht serialisiert werden sollten

In der obigen Optionsliste bezieht sich „eine Menge“ auf jede Sammlung oder jedes iterierbare Element von Strings, es wird keine Reihenfolge erwartet.

Hinzugefügt in Version 3.8.

xml.etree.ElementTree.Comment(text=None)

Kommentar-Element-Factory. Diese Factory-Funktion erstellt ein spezielles Element, das vom Standard-Serializer als XML-Kommentar serialisiert wird. Der Kommentarstring kann entweder ein Byte-String oder ein Unicode-String sein. text ist ein String, der den Kommentarstring enthält. Gibt eine Element-Instanz zurück, die einen Kommentar darstellt.

Beachten Sie, dass XMLParser Kommentare in der Eingabe überspringt, anstatt Kommentarobjekte für sie zu erstellen. Ein ElementTree enthält nur dann Kommentar-Knoten, wenn sie über eine der Element-Methoden in den Baum eingefügt wurden.

xml.etree.ElementTree.dump(elem)

Schreibt einen Elementbaum oder eine Elementstruktur nach sys.stdout. Diese Funktion sollte nur zu Debugging-Zwecken verwendet werden.

Das genaue Ausgabeformat ist implementierungsabhängig. In dieser Version wird es als normale XML-Datei ausgegeben.

elem ist ein Elementbaum oder ein einzelnes Element.

Geändert in Version 3.8: Die Funktion dump() behält nun die vom Benutzer angegebene Attributreihenfolge bei.

xml.etree.ElementTree.fromstring(text, parser=None)

Parst einen XML-Abschnitt aus einer String-Konstante. Gleiche Funktionalität wie XML(). text ist ein String, der XML-Daten enthält. parser ist eine optionale Parser-Instanz. Wenn nicht angegeben, wird der Standard-XMLParser-Parser verwendet. Gibt eine Element-Instanz zurück.

xml.etree.ElementTree.fromstringlist(sequence, parser=None)

Parst ein XML-Dokument aus einer Sequenz von String-Fragmenten. sequence ist eine Liste oder eine andere Sequenz, die XML-Datenfragmente enthält. parser ist eine optionale Parser-Instanz. Wenn nicht angegeben, wird der Standard-XMLParser-Parser verwendet. Gibt eine Element-Instanz zurück.

Hinzugefügt in Version 3.2.

xml.etree.ElementTree.indent(tree, space='  ', level=0)

Fügt Whitespace zum Unterbaum hinzu, um den Baum visuell einzurücken. Dies kann zur Generierung von schön formatierten XML-Ausgaben verwendet werden. tree kann ein Element oder ElementTree sein. space ist der Whitespace-String, der für jede Einrückungsebene eingefügt wird, standardmäßig zwei Leerzeichen. Zum Einrücken von Teilunterbäumen innerhalb eines bereits eingerückten Baumes übergeben Sie die anfängliche Einrückungsebene als level.

Hinzugefügt in Version 3.9.

xml.etree.ElementTree.iselement(element)

Prüft, ob ein Objekt ein gültiges Elementobjekt zu sein scheint. element ist eine Element-Instanz. Gibt True zurück, wenn dies ein Elementobjekt ist.

xml.etree.ElementTree.iterparse(source, events=None, parser=None)

Parst inkrementell einen XML-Abschnitt in einen Elementbaum und berichtet dem Benutzer über den Fortschritt. source ist ein Dateiname oder ein Datei-Objekt, das XML-Daten enthält. events ist eine Sequenz von Ereignissen, über die berichtet werden soll. Die unterstützten Ereignisse sind die Strings "start", "end", "comment", "pi", "start-ns" und "end-ns" (die „ns“-Ereignisse werden verwendet, um detaillierte Namespace-Informationen zu erhalten). Wenn events weggelassen wird, werden nur "end"-Ereignisse gemeldet. parser ist eine optionale Parser-Instanz. Wenn nicht angegeben, wird der Standard-XMLParser-Parser verwendet. parser muss eine Unterklasse von XMLParser sein und kann nur den Standard-TreeBuilder als Ziel verwenden. Gibt einen Iterator zurück, der (event, elem)-Paare liefert; er hat ein Attribut root, das auf das Wurzelelement des resultierenden XML-Baumes verweist, sobald source vollständig gelesen wurde. Der Iterator verfügt über die Methode close(), die das interne Datei-Objekt schließt, wenn source ein Dateiname ist.

Beachten Sie, dass iterparse() zwar den Baum inkrementell erstellt, aber blockierende Lesevorgänge für source (oder die von ihm benannte Datei) ausführt. Daher ist es für Anwendungen, bei denen keine blockierenden Lesevorgänge durchgeführt werden können, ungeeignet. Für vollständig nicht-blockierendes Parsen siehe XMLPullParser.

Hinweis

iterparse() garantiert nur, dass es das Zeichen „>“ eines Start-Tags gesehen hat, wenn es ein „start“-Ereignis ausgibt. Daher sind die Attribute definiert, aber der Inhalt der Attribute text und tail ist zu diesem Zeitpunkt undefiniert. Das Gleiche gilt für die Kindelemente; sie können vorhanden sein oder auch nicht.

Wenn Sie ein vollständig befülltes Element benötigen, suchen Sie stattdessen nach „end“-Ereignissen.

Veraltet seit Version 3.4: Das Argument parser.

Geändert in Version 3.8: Die Ereignisse comment und pi wurden hinzugefügt.

Geändert in Version 3.13: Die Methode close() wurde hinzugefügt.

xml.etree.ElementTree.parse(source, parser=None)

Analysiert einen XML-Abschnitt in einen Elementbaum. source ist ein Dateiname oder ein Datei-Objekt, das XML-Daten enthält. parser ist eine optionale Parser-Instanz. Wenn nicht angegeben, wird der Standard-Parser XMLParser verwendet. Gibt eine ElementTree-Instanz zurück.

xml.etree.ElementTree.ProcessingInstruction(target, text=None)

PI-Element-Fabrik. Diese Fabrikfunktion erstellt ein spezielles Element, das als XML-Verarbeitungsanweisung serialisiert wird. target ist ein String, der das PI-Ziel enthält. text ist ein String, der den PI-Inhalt enthält, falls angegeben. Gibt eine Element-Instanz zurück, die eine Verarbeitungsanweisung darstellt.

Beachten Sie, dass XMLParser Verarbeitungsanweisungen im Eingabestrom überspringt, anstatt PI-Objekte dafür zu erstellen. Ein ElementTree enthält nur Verarbeitungsanweisungs-Knoten, wenn diese über eine der Element-Methoden in den Baum eingefügt wurden.

xml.etree.ElementTree.register_namespace(prefix, uri)

Registriert ein Namespace-Präfix. Die Registrierung ist global, und jede vorhandene Zuordnung für das gegebene Präfix oder die Namespace-URI wird entfernt. prefix ist ein Namespace-Präfix. uri ist eine Namespace-URI. Tags und Attribute in diesem Namespace werden, wenn möglich, mit dem angegebenen Präfix serialisiert.

Hinzugefügt in Version 3.2.

xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)

Sub-Element-Fabrik. Diese Funktion erstellt eine Element-Instanz und fügt sie einem vorhandenen Element hinzu.

Der Elementname, die Attributnamen und die Attributwerte können entweder Bytestrings oder Unicode-Strings sein. parent ist das übergeordnete Element. tag ist der Name des Sub-Elements. attrib ist ein optionales Dictionary, das Elementattribute enthält. extra enthält zusätzliche Attribute, die als Schlüsselwortargumente übergeben werden. Gibt eine Element-Instanz zurück.

xml.etree.ElementTree.tostring(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

Generiert eine String-Darstellung eines XML-Elements, einschließlich aller Sub-Elemente. element ist eine Element-Instanz. encoding [1] ist die Ausgabe-Kodierung (Standard ist US-ASCII). Verwenden Sie encoding="unicode", um einen Unicode-String zu generieren (andernfalls wird ein Bytestring generiert). method ist entweder "xml", "html" oder "text" (Standard ist "xml"). xml_declaration, default_namespace und short_empty_elements haben dieselbe Bedeutung wie in ElementTree.write(). Gibt einen (optional) kodierten String mit den XML-Daten zurück.

Geändert in Version 3.4: Der Parameter short_empty_elements wurde hinzugefügt.

Geändert in Version 3.8: Die Parameter xml_declaration und default_namespace wurden hinzugefügt.

Geändert in Version 3.8: Die Funktion tostring() behält jetzt die vom Benutzer angegebene Reihenfolge der Attribute bei.

xml.etree.ElementTree.tostringlist(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

Generiert eine String-Darstellung eines XML-Elements, einschließlich aller Sub-Elemente. element ist eine Element-Instanz. encoding [1] ist die Ausgabe-Kodierung (Standard ist US-ASCII). Verwenden Sie encoding="unicode", um einen Unicode-String zu generieren (andernfalls wird ein Bytestring generiert). method ist entweder "xml", "html" oder "text" (Standard ist "xml"). xml_declaration, default_namespace und short_empty_elements haben dieselbe Bedeutung wie in ElementTree.write(). Gibt eine Liste von (optional) kodierten Strings zurück, die die XML-Daten enthalten. Sie garantiert keine bestimmte Reihenfolge, außer dass b"".join(tostringlist(element)) == tostring(element) gilt.

Hinzugefügt in Version 3.2.

Geändert in Version 3.4: Der Parameter short_empty_elements wurde hinzugefügt.

Geändert in Version 3.8: Die Parameter xml_declaration und default_namespace wurden hinzugefügt.

Geändert in Version 3.8: Die Funktion tostringlist() behält jetzt die vom Benutzer angegebene Reihenfolge der Attribute bei.

xml.etree.ElementTree.XML(text, parser=None)

Analysiert einen XML-Abschnitt aus einer String-Konstante. Diese Funktion kann verwendet werden, um „XML-Literale“ in Python-Code einzubetten. text ist ein String, der XML-Daten enthält. parser ist eine optionale Parser-Instanz. Wenn nicht angegeben, wird der Standard-Parser XMLParser verwendet. Gibt eine Element-Instanz zurück.

xml.etree.ElementTree.XMLID(text, parser=None)

Analysiert einen XML-Abschnitt aus einer String-Konstante und gibt außerdem ein Dictionary zurück, das von Element-IDs zu Elementen abbildet. text ist ein String, der XML-Daten enthält. parser ist eine optionale Parser-Instanz. Wenn nicht angegeben, wird der Standard-Parser XMLParser verwendet. Gibt ein Tupel zurück, das eine Element-Instanz und ein Dictionary enthält.

XInclude-Unterstützung

Dieses Modul bietet begrenzte Unterstützung für XInclude-Direktiven über das Hilfsmodul xml.etree.ElementInclude. Dieses Modul kann verwendet werden, um Unterbäume und Textzeichenketten basierend auf Informationen im Baum in Elementbäume einzufügen.

Beispiel

Hier ist ein Beispiel, das die Verwendung des XInclude-Moduls demonstriert. Um ein XML-Dokument in das aktuelle Dokument einzufügen, verwenden Sie das Element {http://www.w3.org/2001/XInclude}include und setzen Sie das Attribut **parse** auf "xml", und verwenden Sie das Attribut **href**, um das einzufügende Dokument anzugeben.

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>

Standardmäßig wird das Attribut **href** als Dateiname behandelt. Sie können benutzerdefinierte Lader verwenden, um dieses Verhalten zu überschreiben. Beachten Sie auch, dass der Standardhelfer die XPointer-Syntax nicht unterstützt.

Um diese Datei zu verarbeiten, laden Sie sie wie gewohnt und übergeben Sie das Wurzelelement an das Modul xml.etree.ElementTree.

from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)

Das Modul ElementInclude ersetzt das Element {http://www.w3.org/2001/XInclude}include durch das Wurzelelement aus dem Dokument source.xml. Das Ergebnis könnte etwa so aussehen:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>This is a paragraph.</para>
</document>

Wenn das Attribut **parse** weggelassen wird, wird es standardmäßig auf „xml“ gesetzt. Das Attribut href ist erforderlich.

Um ein Textdokument einzufügen, verwenden Sie das Element {http://www.w3.org/2001/XInclude}include und setzen Sie das Attribut **parse** auf „text“.

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>

Das Ergebnis könnte etwa so aussehen:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) 2003.
</document>

Referenz

Funktionen

xml.etree.ElementInclude.default_loader(href, parse, encoding=None)

Standard-Lader. Dieser Standard-Lader liest eine einzufügende Ressource von der Festplatte. href ist eine URL. parse ist für den Parse-Modus entweder „xml“ oder „text“. encoding ist eine optionale Textkodierung. Wenn nicht angegeben, ist die Kodierung utf-8. Gibt die erweiterte Ressource zurück. Wenn der Lader fehlschlägt, kann er None zurückgeben oder eine Ausnahme auslösen.

xml.etree.ElementInclude.include(elem, loader=None, base_url=None, max_depth=6)

Diese Funktion erweitert XInclude-Direktiven inplace im durch elem bezeichneten Baum. elem ist entweder das Wurzelelement Element oder eine ElementTree-Instanz, um ein solches Element zu finden. loader ist ein optionaler Ressourcenlader. Wenn weggelassen, wird standardmäßig default_loader() verwendet. Wenn angegeben, sollte es ein aufrufbares Objekt sein, das dieselbe Schnittstelle wie default_loader() implementiert. base_url ist die Basis-URL der ursprünglichen Datei, um relative Include-Dateireferenzen aufzulösen. max_depth ist die maximale Anzahl rekursiver Einbindungen. Begrenzt, um das Risiko einer bösartigen Inhalts-Explosion zu reduzieren. Übergeben Sie None, um die Einschränkung zu deaktivieren.

Geändert in Version 3.9: Die Parameter base_url und max_depth wurden hinzugefügt.

Element-Objekte

class xml.etree.ElementTree.Element(tag, attrib={}, **extra)

Element-Klasse. Diese Klasse definiert die Element-Schnittstelle und bietet eine Referenzimplementierung dieser Schnittstelle.

Der Elementname, die Attributnamen und die Attributwerte können entweder Bytestrings oder Unicode-Strings sein. tag ist der Elementname. attrib ist ein optionales Dictionary, das Elementattribute enthält. extra enthält zusätzliche Attribute, die als Schlüsselwortargumente übergeben werden.

tag

Ein String, der identifiziert, welche Art von Daten dieses Element darstellt (also der Elementtyp).

text

tail

Diese Attribute können verwendet werden, um zusätzliche Daten zu speichern, die mit dem Element verbunden sind. Ihre Werte sind normalerweise Strings, können aber jedes anwendungsspezifische Objekt sein. Wenn das Element aus einer XML-Datei erstellt wird, enthält das Attribut text entweder den Text zwischen dem Start-Tag des Elements und seinem ersten Kind- oder End-Tag oder None, und das Attribut tail enthält entweder den Text zwischen dem End-Tag des Elements und dem nächsten Tag oder None. Für die XML-Daten

<a><b>1<c>2<d/>3</c></b>4</a>

hat das Element a für beide Attribute text und tail None, das Element b hat text "1" und tail "4", das Element c hat text "2" und tail None, und das Element d hat text None und tail "3".

Um den inneren Text eines Elements zu sammeln, siehe itertext(), zum Beispiel "".join(element.itertext()).

Anwendungen können beliebige Objekte in diesen Attributen speichern.

attrib

Ein Dictionary, das die Attribute des Elements enthält. Beachten Sie, dass der Wert von attrib zwar immer ein echtes, veränderbares Python-Dictionary ist, eine ElementTree-Implementierung jedoch einen anderen internen Repräsentationsweg wählen und das Dictionary nur erstellen kann, wenn jemand danach fragt. Um von solchen Implementierungen zu profitieren, verwenden Sie nach Möglichkeit die unten aufgeführten Dictionary-Methoden.

Die folgenden Dictionary-ähnlichen Methoden funktionieren auf den Elementattributen.

clear()

Setzt ein Element zurück. Diese Funktion entfernt alle Sub-Elemente, löscht alle Attribute und setzt die Attribute text und tail auf None.

get(key, default=None)

Ruft das Elementattribut namens key ab.

Gibt den Attributwert zurück oder default, wenn das Attribut nicht gefunden wurde.

items()

Gibt die Elementattribute als Sequenz von (Name, Wert)-Paaren zurück. Die Attribute werden in beliebiger Reihenfolge zurückgegeben.

keys()

Gibt die Elementattributnamen als Liste zurück. Die Namen werden in beliebiger Reihenfolge zurückgegeben.

set(key, value)

Setzt das Attribut key im Element auf value.

Die folgenden Methoden funktionieren auf den Kindern (Sub-Elementen) des Elements.

append(subelement)

Fügt das Element subelement am Ende der internen Liste von Sub-Elementen dieses Elements hinzu. Löst einen TypeError aus, wenn subelement kein Element ist.

extend(subelements)

Fügt Elemente aus einem Iterable von Elementen hinzu. Löst einen TypeError aus, wenn ein Sub-Element kein Element ist.

Hinzugefügt in Version 3.2.

find(match, namespaces=None)

Findet das erste Sub-Element, das mit match übereinstimmt. match kann ein Tag-Name oder ein Pfad sein. Gibt eine Element-Instanz oder None zurück. namespaces ist eine optionale Zuordnung von Namespace-Präfix zu vollständigem Namen. Übergeben Sie '' als Präfix, um alle nicht-präfixierten Tag-Namen im Ausdruck in den angegebenen Namespace zu verschieben.

findall(match, namespaces=None)

Findet alle übereinstimmenden Sub-Elemente nach Tag-Namen oder Pfad. Gibt eine Liste mit allen übereinstimmenden Elementen in Dokumentenreihenfolge zurück. namespaces ist eine optionale Zuordnung von Namespace-Präfix zu vollständigem Namen. Übergeben Sie '' als Präfix, um alle nicht-präfixierten Tag-Namen im Ausdruck in den angegebenen Namespace zu verschieben.

findtext(match, default=None, namespaces=None)

Findet den Text für das erste Sub-Element, das mit match übereinstimmt. match kann ein Tag-Name oder ein Pfad sein. Gibt den Textinhalt des ersten übereinstimmenden Elements zurück oder default, wenn kein Element gefunden wurde. Beachten Sie, dass eine leere Zeichenkette zurückgegeben wird, wenn das übereinstimmende Element keinen Textinhalt hat. namespaces ist eine optionale Zuordnung von Namespace-Präfix zu vollständigem Namen. Übergeben Sie '' als Präfix, um alle nicht-präfixierten Tag-Namen im Ausdruck in den angegebenen Namespace zu verschieben.

insert(index, subelement)

Fügt subelement an der angegebenen Position in dieses Element ein. Löst einen TypeError aus, wenn subelement kein Element ist.

iter(tag=None)

Erstellt einen Baum-Iterator mit dem aktuellen Element als Wurzel. Der Iterator durchläuft dieses Element und alle darunter liegenden Elemente in Dokumentenreihenfolge (Tiefensuche). Wenn tag nicht None oder '*' ist, werden nur Elemente zurückgegeben, deren Tag mit tag übereinstimmt. Wenn die Baumstruktur während der Iteration geändert wird, ist das Ergebnis undefiniert.

Hinzugefügt in Version 3.2.

iterfind(match, namespaces=None)

Findet alle übereinstimmenden Sub-Elemente nach Tag-Namen oder Pfad. Gibt einen Iterator zurück, der alle übereinstimmenden Elemente in Dokumentenreihenfolge liefert. namespaces ist eine optionale Zuordnung von Namespace-Präfix zu vollständigem Namen.

Hinzugefügt in Version 3.2.

itertext()

Erstellt einen Text-Iterator. Der Iterator durchläuft dieses Element und alle Sub-Elemente in Dokumentenreihenfolge und gibt allen inneren Text zurück.

Hinzugefügt in Version 3.2.

makeelement(tag, attrib)

Erstellt ein neues Element-Objekt vom selben Typ wie dieses Element. Rufen Sie diese Methode nicht auf, verwenden Sie stattdessen die Fabrikfunktion SubElement().

remove(subelement)

Entfernt subelement aus dem Element. Im Gegensatz zu den find*-Methoden vergleicht diese Methode Elemente anhand der Instanzidentität und nicht anhand von Tag-Wert oder Inhalt.

Element-Objekte unterstützen auch die folgenden Sequenztyp-Methoden für die Arbeit mit Unterelementen: __delitem__(), __getitem__(), __setitem__(), __len__().

Vorsicht: Elemente ohne Unterelemente werden als False ausgewertet. In einer zukünftigen Version von Python werden alle Elemente als True ausgewertet, unabhängig davon, ob Unterelemente vorhanden sind. Bevorzugen Sie stattdessen explizite len(elem)- oder elem is not None-Tests.

element = root.find('foo')

if not element:  # careful!
    print("element not found, or element has no subelements")

if element is None:
    print("element not found")

Geändert in Version 3.12: Die Wahrheitswertprüfung eines Elements gibt eine DeprecationWarning aus.

Vor Python 3.8 wurde die Serialisierungsreihenfolge der XML-Attribute von Elementen künstlich vorhersehbar gemacht, indem die Attribute nach ihrem Namen sortiert wurden. Basierend auf der nun garantierten Reihenfolge von Dictionaries wurde diese willkürliche Neuordnung in Python 3.8 entfernt, um die Reihenfolge beizubehalten, in der Attribute ursprünglich geparst oder vom Benutzercode erstellt wurden.

Im Allgemeinen sollte der Benutzercode versuchen, sich nicht auf eine bestimmte Reihenfolge von Attributen zu verlassen, da das XML Information Set die Reihenfolge der Attribute explizit vom Vermitteln von Informationen ausschließt. Der Code sollte darauf vorbereitet sein, jede Reihenfolge bei der Eingabe zu verarbeiten. In Fällen, in denen eine deterministische XML-Ausgabe erforderlich ist, z. B. für kryptografische Signaturen oder Testdatensätze, ist die kanonische Serialisierung mit der Funktion canonicalize() verfügbar.

In Fällen, in denen die kanonische Ausgabe nicht zutreffend ist, aber eine bestimmte Attributreihenfolge bei der Ausgabe noch wünschenswert ist, sollte der Code darauf abzielen, die Attribute direkt in der gewünschten Reihenfolge zu erstellen, um wahrnehmbare Abweichungen für die Leser des Codes zu vermeiden. Wenn dies schwer zu erreichen ist, kann ein Rezept wie das folgende vor der Serialisierung angewendet werden, um eine unabhängige Reihenfolge von der Elementerstellung zu erzwingen.

def reorder_attributes(root):
    for el in root.iter():
        attrib = el.attrib
        if len(attrib) > 1:
            # adjust attribute order, e.g. by sorting
            attribs = sorted(attrib.items())
            attrib.clear()
            attrib.update(attribs)

ElementTree-Objekte

class xml.etree.ElementTree.ElementTree(element=None, file=None)

Wrapper-Klasse für ElementTree. Diese Klasse repräsentiert eine gesamte Elementhierarchie und bietet zusätzliche Unterstützung für die Serialisierung von und zu Standard-XML.

element ist das Wurzelelement. Der Baum wird mit dem Inhalt der XML-Datei initialisiert, wenn diese angegeben ist.

_setroot(element)

Ersetzt das Wurzelelement für diesen Baum. Dies verwirft den aktuellen Inhalt des Baumes und ersetzt ihn durch das angegebene Element. Mit Vorsicht verwenden. element ist eine Elementinstanz.

find(match, namespaces=None)

Gleich wie Element.find(), beginnend am Wurzelelement des Baumes.

findall(match, namespaces=None)

Gleich wie Element.findall(), beginnend am Wurzelelement des Baumes.

findtext(match, default=None, namespaces=None)

Gleich wie Element.findtext(), beginnend am Wurzelelement des Baumes.

getroot()

Gibt das Wurzelelement für diesen Baum zurück.

iter(tag=None)

Erstellt und gibt einen Baum-Iterator für das Wurzelelement zurück. Der Iterator durchläuft alle Elemente in diesem Baum in Sektionsreihenfolge. tag ist das zu suchende Tag (Standard ist die Rückgabe aller Elemente).

iterfind(match, namespaces=None)

Gleich wie Element.iterfind(), beginnend am Wurzelelement des Baumes.

Hinzugefügt in Version 3.2.

parse(source, parser=None)

Lädt einen externen XML-Abschnitt in diesen Elementbaum. source ist ein Dateiname oder ein Datei-Objekt. parser ist eine optionale Parser-Instanz. Wenn nicht angegeben, wird der Standard-XMLParser-Parser verwendet. Gibt das Wurzelelement des Abschnitts zurück.

write(file, encoding='us-ascii', xml_declaration=None, default_namespace=None, method='xml', *, short_empty_elements=True)

Schreibt den Elementbaum in eine Datei als XML. file ist ein Dateiname oder ein Datei-Objekt, das zum Schreiben geöffnet ist. encoding [1] ist die Ausgabekodierung (Standard ist US-ASCII). xml_declaration steuert, ob eine XML-Deklaration zur Datei hinzugefügt werden soll. Verwenden Sie False für niemals, True für immer, None für nur, wenn nicht US-ASCII oder UTF-8 oder Unicode (Standard ist None). default_namespace legt den Standard-XML-Namensraum fest (für „xmlns“). method ist entweder "xml", "html" oder "text" (Standard ist "xml"). Der nur-Schlüsselwort-Parameter short_empty_elements steuert die Formatierung von Elementen, die keinen Inhalt haben. Wenn True (Standard), werden sie als einzelnes selbsterzeugendes Tag ausgegeben, andernfalls als Paar aus Start- und End-Tag.

Die Ausgabe ist entweder ein String (str) oder Binärdaten (bytes). Dies wird durch das Argument encoding gesteuert. Wenn encoding "unicode" ist, ist die Ausgabe ein String; andernfalls sind es Binärdaten. Beachten Sie, dass dies mit dem Typ von file in Konflikt geraten kann, wenn es sich um ein geöffnetes Datei-Objekt handelt; stellen Sie sicher, dass Sie nicht versuchen, einen String in einen Binärstrom und umgekehrt zu schreiben.

Geändert in Version 3.4: Der Parameter short_empty_elements wurde hinzugefügt.

Geändert in Version 3.8: Die Methode write() behält nun die vom Benutzer angegebene Attributreihenfolge bei.

Dies ist die XML-Datei, die manipuliert werden soll.

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>Moved to <a href="http://example.org/">example.org</a>
        or <a href="http://example.com/">example.com</a>.</p>
    </body>
</html>

Beispiel für die Änderung des Attributs "target" jedes Links im ersten Absatz.

>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a"))   # Returns list of all links
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links:             # Iterates through all found links
...     i.attrib["target"] = "blank"
...
>>> tree.write("output.xhtml")

QName-Objekte

class xml.etree.ElementTree.QName(text_or_uri, tag=None)

QName-Wrapper. Dies kann verwendet werden, um einen QName-Attributwert zu umschließen, um eine ordnungsgemäße Namespace-Handhabung bei der Ausgabe zu erhalten. text_or_uri ist ein String, der den QName-Wert enthält, im Format {uri}local, oder, wenn das Argument tag angegeben ist, der URI-Teil eines QName. Wenn tag angegeben ist, wird das erste Argument als URI interpretiert und dieses Argument als lokaler Name interpretiert. QName-Instanzen sind opak.

TreeBuilder-Objekte

class xml.etree.ElementTree.TreeBuilder(element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)

Generischer Builder für Elementstrukturen. Dieser Builder konvertiert eine Sequenz von start-, data-, end-, comment- und pi-Methodenaufrufen in eine wohlgeformte Elementstruktur. Sie können diese Klasse verwenden, um eine Elementstruktur mit einem benutzerdefinierten XML-Parser oder einem Parser für ein anderes XML-ähnliches Format zu erstellen.

element_factory muss, wenn gegeben, ein aufrufbares Objekt sein, das zwei Positionsargumente akzeptiert: einen Tag und ein Dictionary von Attributen. Es wird erwartet, dass es eine neue Elementinstanz zurückgibt.

Die Funktionen comment_factory und pi_factory müssen, wenn gegeben, wie die Funktionen Comment() und ProcessingInstruction() funktionieren, um Kommentare und Verarbeitungshinweise zu erstellen. Wenn sie nicht gegeben sind, werden die Standard-Factories verwendet. Wenn insert_comments und/oder insert_pis wahr sind, werden Kommentare/PIs in den Baum eingefügt, wenn sie innerhalb des Wurzelelements erscheinen (aber nicht außerhalb davon).

close()

Leert die Builder-Puffer und gibt das obere Dokumentenelement zurück. Gibt eine Element-Instanz zurück.

data(data)

Fügt Text zum aktuellen Element hinzu. data ist ein String. Dies sollte entweder ein Bytestring oder ein Unicode-String sein.

end(tag)

Schließt das aktuelle Element. tag ist der Elementname. Gibt das geschlossene Element zurück.

start(tag, attrs)

Öffnet ein neues Element. tag ist der Elementname. attrs ist ein Dictionary, das Elementattribute enthält. Gibt das geöffnete Element zurück.

comment(text)

Erstellt einen Kommentar mit dem angegebenen text. Wenn insert_comments wahr ist, wird dieser auch in den Baum eingefügt.

Hinzugefügt in Version 3.8.

pi(target, text)

Erstellt eine Verarbeitungsinstruktion mit dem angegebenen target-Namen und text. Wenn insert_pis wahr ist, wird diese auch in den Baum eingefügt.

Hinzugefügt in Version 3.8.

Zusätzlich kann ein benutzerdefiniertes TreeBuilder-Objekt die folgenden Methoden bereitstellen:

doctype(name, pubid, system)

Verarbeitet eine Doctype-Deklaration. name ist der Doctype-Name. pubid ist der öffentliche Bezeichner. system ist der Systembezeichner. Diese Methode existiert nicht in der Standard-TreeBuilder-Klasse.

Hinzugefügt in Version 3.2.

start_ns(prefix, uri)

Wird aufgerufen, wenn der Parser eine neue Namespace-Deklaration erkennt, bevor der start()-Callback für das öffnende Element, das sie definiert, aufgerufen wird. prefix ist '' für den Standard-Namespace und ansonsten der deklarierte Namespace-Präfixname. uri ist die Namespace-URI.

Hinzugefügt in Version 3.8.

end_ns(prefix)

Wird nach dem end()-Callback eines Elements aufgerufen, das eine Namespace-Präfixzuordnung deklariert hat, mit dem Namen des prefix, der außer Reichweite geraten ist.

Hinzugefügt in Version 3.8.

class xml.etree.ElementTree.C14NWriterTarget(write, *, with_comments=False, strip_text=False, rewrite_prefixes=False, qname_aware_tags=None, qname_aware_attrs=None, exclude_attrs=None, exclude_tags=None)

Ein C14N 2.0-Schreiber. Argumente sind dieselben wie für die Funktion canonicalize(). Diese Klasse baut keinen Baum auf, sondern übersetzt die Callback-Ereignisse direkt in eine serialisierte Form unter Verwendung der write-Funktion.

Hinzugefügt in Version 3.8.

XMLParser-Objekte

class xml.etree.ElementTree.XMLParser(*, target=None, encoding=None)

Diese Klasse ist der Low-Level-Baustein des Moduls. Sie verwendet xml.parsers.expat für effizientes, ereignisbasiertes Parsen von XML. Sie kann inkrementell mit der Methode feed() mit XML-Daten gefüttert werden, und Parsing-Ereignisse werden in eine Push-API übersetzt – durch Aufrufen von Callbacks auf dem target-Objekt. Wenn target weggelassen wird, wird der Standard-TreeBuilder verwendet. Wenn encoding [1] angegeben ist, überschreibt dieser Wert die im XML-Datei angegebene Kodierung.

Geändert in Version 3.8: Parameter sind jetzt keyword-only. Das Argument html wird nicht mehr unterstützt.

close()

Beendet die Zufuhr von Daten an den Parser. Gibt das Ergebnis des Aufrufs der Methode close() des während der Konstruktion übergebenen target zurück; standardmäßig ist dies das obere Dokumentenelement.

feed(data)

Füttert Daten in den Parser. data sind kodierte Daten.

flush()

Löst das Parsen aller zuvor zugeführten, nicht geparsten Daten aus, was für eine sofortigere Rückmeldung sorgen kann, insbesondere bei Expat >= 2.6.0. Die Implementierung von flush() deaktiviert temporär die Wiederparsierungsverzögerung bei Expat (falls gerade aktiviert) und löst ein Wiederparsen aus. Die Deaktivierung der Wiederparsierungsverzögerung hat Sicherheitsauswirkungen; siehe xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() für Details.

Beachten Sie, dass flush() in einige frühere Versionen von CPython als Sicherheitskorrektur zurückportiert wurde. Prüfen Sie die Verfügbarkeit von flush() mit hasattr(), wenn Code ausgeführt wird, der über verschiedene Python-Versionen hinweg läuft.

Hinzugefügt in Version 3.13.

XMLParser.feed() ruft die Methode target's start(tag, attrs_dict) für jedes öffnende Tag, seine Methode end(tag) für jedes schließende Tag auf, und Daten werden von der Methode data(data) verarbeitet. Für weitere unterstützte Callback-Methoden siehe die Klasse TreeBuilder. XMLParser.close() ruft die Methode target's close() auf. XMLParser kann nicht nur zum Erstellen einer Baumstruktur verwendet werden. Dies ist ein Beispiel für das Zählen der maximalen Tiefe einer XML-Datei.

>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth:                     # The target object of the parser
...     maxDepth = 0
...     depth = 0
...     def start(self, tag, attrib):   # Called for each opening tag.
...         self.depth += 1
...         if self.depth > self.maxDepth:
...             self.maxDepth = self.depth
...     def end(self, tag):             # Called for each closing tag.
...         self.depth -= 1
...     def data(self, data):
...         pass            # We do not need to do anything with data.
...     def close(self):    # Called when all data has been parsed.
...         return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
...   <b>
...   </b>
...   <b>
...     <c>
...       <d>
...       </d>
...     </c>
...   </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4

XMLPullParser-Objekte

class xml.etree.ElementTree.XMLPullParser(events=None)

Ein Pull-Parser, der für nicht-blockierende Anwendungen geeignet ist. Seine Input-seitige API ähnelt der von XMLParser, aber anstatt Aufrufe an ein Callback-Ziel zu pushen, sammelt XMLPullParser eine interne Liste von Parsing-Ereignissen und lässt den Benutzer daraus lesen. events ist eine Sequenz von zurückzugebenden Ereignissen. Die unterstützten Ereignisse sind die Strings "start", "end", "comment", "pi", "start-ns" und "end-ns" (die "ns"-Ereignisse werden verwendet, um detaillierte Namespace-Informationen zu erhalten). Wenn events weggelassen wird, werden nur "end"-Ereignisse zurückgegeben.

feed(data)

Führt die gegebenen Byte-Daten dem Parser zu.

flush()

Löst das Parsen aller zuvor zugeführten, nicht geparsten Daten aus, was für eine sofortigere Rückmeldung sorgen kann, insbesondere bei Expat >= 2.6.0. Die Implementierung von flush() deaktiviert temporär die Wiederparsierungsverzögerung bei Expat (falls gerade aktiviert) und löst ein Wiederparsen aus. Die Deaktivierung der Wiederparsierungsverzögerung hat Sicherheitsauswirkungen; siehe xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() für Details.

Beachten Sie, dass flush() in einige frühere Versionen von CPython als Sicherheitskorrektur zurückportiert wurde. Prüfen Sie die Verfügbarkeit von flush() mit hasattr(), wenn Code ausgeführt wird, der über verschiedene Python-Versionen hinweg läuft.

Hinzugefügt in Version 3.13.

close()

Signalisiert dem Parser, dass der Datenstrom beendet ist. Im Gegensatz zu XMLParser.close() gibt diese Methode immer None zurück. Noch nicht abgerufene Ereignisse, wenn der Parser geschlossen wird, können immer noch mit read_events() gelesen werden.

read_events()

Gibt einen Iterator über die Ereignisse zurück, die in den an den Parser übergebenen Daten aufgetreten sind. Der Iterator liefert Paare von (event, elem), wobei event ein String ist, der den Typ des Ereignisses darstellt (z. B. "end") und elem das aufgetretene Element-Objekt oder ein anderer Kontextwert wie folgt ist.

• start, end: das aktuelle Element.

• comment, pi: der aktuelle Kommentar / die aktuelle Verarbeitungsinstruktion

• start-ns: ein Tupel (prefix, uri), das die deklarierte Namespace-Zuordnung benennt.

• end-ns: None (dies kann sich in einer zukünftigen Version ändern)

In einem früheren Aufruf von read_events() bereitgestellte Ereignisse werden nicht erneut ausgeliefert. Ereignisse werden erst aus der internen Warteschlange konsumiert, wenn sie vom Iterator abgerufen werden. Mehrere parallel iterierende Leser über von read_events() erhaltene Iteratoren führen zu unvorhersehbaren Ergebnissen.

Hinweis

XMLPullParser garantiert nur, dass er das Zeichen ">" eines Start-Tags gesehen hat, wenn er ein "start"-Ereignis ausgibt. Die Attribute sind dann definiert, aber die Inhalte der Text- und Tail-Attribute sind zu diesem Zeitpunkt undefiniert. Dasselbe gilt für Elementkinder; sie sind möglicherweise vorhanden oder auch nicht.

Wenn Sie ein vollständig befülltes Element benötigen, suchen Sie stattdessen nach „end“-Ereignissen.

Hinzugefügt in Version 3.4.

Geändert in Version 3.8: Die Ereignisse comment und pi wurden hinzugefügt.

Ausnahmen

Klasse xml.etree.ElementTree.ParseError

XML-Analysefehler, der von den verschiedenen Parsing-Methoden in diesem Modul ausgelöst wird, wenn das Parsen fehlschlägt. Die String-Darstellung einer Instanz dieser Ausnahme enthält eine benutzerfreundliche Fehlermeldung. Zusätzlich sind die folgenden Attribute verfügbar:

code

Ein numerischer Fehlercode vom expat-Parser. Siehe die Dokumentation von xml.parsers.expat für die Liste der Fehlercodes und ihre Bedeutung.

position

Ein Tupel von Zeilen- und Spaltennummern, das angibt, wo der Fehler aufgetreten ist.

Fußnoten

[1] (1,2,3,4)

Die in der XML-Ausgabe enthaltene Kodierungszeichenkette sollte den entsprechenden Standards entsprechen. Zum Beispiel ist "UTF-8" gültig, aber "UTF8" nicht. Siehe https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl und https://www.iana.org/assignments/character-sets/character-sets.xhtml.