xml.dom — Die Document Object Model API

Quellcode: Lib/xml/dom/__init__.py

---

Das Document Object Model, oder „DOM“, ist eine sprachübergreifende API des World Wide Web Consortium (W3C) für den Zugriff auf und die Modifikation von XML-Dokumenten. Eine DOM-Implementierung präsentiert ein XML-Dokument als Baumstruktur oder ermöglicht es dem Client-Code, eine solche Struktur von Grund auf neu aufzubauen. Anschließend gewährt sie Zugriff auf die Struktur über eine Reihe von Objekten, die bekannte Schnittstellen bereitstellen.

DOM ist äußerst nützlich für Anwendungen mit wahlfreiem Zugriff. SAX bietet Ihnen nur jeweils eine Ansicht eines Teils des Dokuments. Wenn Sie gerade ein SAX-Element betrachten, haben Sie keinen Zugriff auf ein anderes. Wenn Sie einen Textknoten betrachten, haben Sie keinen Zugriff auf ein enthaltendes Element. Wenn Sie eine SAX-Anwendung schreiben, müssen Sie die Position Ihres Programms im Dokument irgendwo in Ihrem eigenen Code verfolgen. SAX tut dies nicht für Sie. Wenn Sie außerdem im XML-Dokument vorausschauen müssen, haben Sie einfach Pech.

Einige Anwendungen sind in einem ereignisgesteuerten Modell ohne Baumzugriff schlicht unmöglich. Natürlich könnten Sie bei SAX-Ereignissen eine Art Baum selbst aufbauen, aber DOM ermöglicht es Ihnen, das Schreiben dieses Codes zu vermeiden. DOM ist eine standardisierte Baurepräsentation für XML-Daten.

Das Document Object Model wird vom W3C in Phasen oder „Levels“ in deren Terminologie definiert. Die Python-Abbildung der API basiert im Wesentlichen auf der DOM Level 2 Empfehlung.

DOM-Anwendungen beginnen typischerweise damit, ein XML in ein DOM zu parsen. Wie dies erreicht wird, wird von DOM Level 1 überhaupt nicht behandelt, und Level 2 bietet nur begrenzte Verbesserungen: Es gibt eine DOMImplementation Objektklasse, die Zugriff auf Document Erstellungsmethoden bietet, aber keine Möglichkeit, einen XML-Reader/Parser/Dokument-Builder auf eine implementierungsunabhängige Weise anzusprechen. Es gibt auch keine gut definierte Möglichkeit, auf diese Methoden ohne ein vorhandenes Document Objekt zuzugreifen. In Python stellt jede DOM-Implementierung eine Funktion getDOMImplementation() bereit. DOM Level 3 fügt eine Load/Store-Spezifikation hinzu, die eine Schnittstelle zum Reader definiert, aber diese ist in der Python-Standardbibliothek noch nicht verfügbar.

Sobald Sie ein DOM-Dokumentobjekt haben, können Sie auf die Teile Ihres XML-Dokuments über seine Eigenschaften und Methoden zugreifen. Diese Eigenschaften sind in der DOM-Spezifikation definiert; dieser Teil des Referenzhandbuchs beschreibt die Interpretation der Spezifikation in Python.

Die vom W3C bereitgestellte Spezifikation definiert die DOM-API für Java, ECMAScript und OMG IDL. Die hier definierte Python-Abbildung basiert größtenteils auf der IDL-Version der Spezifikation, aber eine strikte Konformität ist nicht erforderlich (obwohl Implementierungen frei stehen, die strikte Abbildung von IDL zu unterstützen). Siehe Abschnitt Konformität für eine detaillierte Diskussion der Abbildungsanforderungen.

Siehe auch

Document Object Model (DOM) Level 2 Specification

Die W3C-Empfehlung, auf der die Python DOM API basiert.

Document Object Model (DOM) Level 1 Specification

Die W3C-Empfehlung für das von xml.dom.minidom unterstützte DOM.

Python Language Mapping Specification

Diese spezifiziert die Abbildung von OMG IDL auf Python.

Modulinhalt

Das xml.dom enthält die folgenden Funktionen

xml.dom.registerDOMImplementation(name, factory)

Registriert die factory-Funktion unter dem Namen name. Die factory-Funktion sollte ein Objekt zurückgeben, das die DOMImplementation Schnittstelle implementiert. Die factory-Funktion kann jedes Mal dasselbe Objekt zurückgeben oder bei jedem Aufruf ein neues, je nach spezifischer Implementierung (z.B. wenn diese eine gewisse Anpassung unterstützt).

xml.dom.getDOMImplementation(name=None, features=())

Gibt eine geeignete DOM-Implementierung zurück. name ist entweder ein bekannter Name, der Modulname einer DOM-Implementierung oder None. Wenn es nicht None ist, wird das entsprechende Modul importiert und ein DOMImplementation Objekt zurückgegeben, falls der Import erfolgreich ist. Wenn kein Name angegeben ist und die Umgebungsvariable PYTHON_DOM gesetzt ist, wird diese Variable verwendet, um die Implementierung zu finden.

Wenn kein Name angegeben ist, werden die verfügbaren Implementierungen untersucht, um eine mit dem erforderlichen Satz von Merkmalen zu finden. Wenn keine Implementierung gefunden werden kann, wird eine ImportError ausgelöst. Die features-Liste muss eine Sequenz von (feature, version)-Paaren sein, die an die hasFeature()-Methode auf verfügbaren DOMImplementation-Objekten übergeben werden.

Einige Komfortkonstanten werden ebenfalls bereitgestellt

xml.dom.EMPTY_NAMESPACE

Der Wert, der verwendet wird, um anzuzeigen, dass kein Namespace mit einem Knoten im DOM verbunden ist. Dies wird typischerweise als namespaceURI eines Knotens gefunden oder als namespaceURI-Parameter für namensraumspezifische Methoden verwendet.

xml.dom.XML_NAMESPACE

Die Namespace-URI, die dem reservierten Präfix xml zugeordnet ist, wie in den Namespaces in XML (Abschnitt 4) definiert.

xml.dom.XMLNS_NAMESPACE

Die Namespace-URI für Namensdeklarationen, wie in Document Object Model (DOM) Level 2 Core Specification (Abschnitt 1.1.8) definiert.

xml.dom.XHTML_NAMESPACE

Die URI des XHTML-Namespaces, wie in XHTML 1.0: The Extensible HyperText Markup Language (Abschnitt 3.1.1) definiert.

Zusätzlich enthält xml.dom eine Basis- Node Klasse und die DOM-Ausnahmeklassen. Die von diesem Modul bereitgestellte Node-Klasse implementiert keine der von der DOM-Spezifikation definierten Methoden oder Attribute; konkrete DOM-Implementierungen müssen diese bereitstellen. Die als Teil dieses Moduls bereitgestellte Node-Klasse bietet die Konstanten, die für das Attribut nodeType auf konkreten Node-Objekten verwendet werden; sie befinden sich innerhalb der Klasse und nicht auf Modulebene, um der DOM-Spezifikation zu entsprechen.

Objekte im DOM

Die maßgebliche Dokumentation für DOM ist die DOM-Spezifikation des W3C.

Beachten Sie, dass DOM-Attribute auch als Knoten und nicht als einfache Zeichenketten manipuliert werden können. Es ist jedoch eher selten, dass Sie dies tun müssen, daher ist diese Verwendung noch nicht dokumentiert.

Schnittstelle	Abschnitt	Zweck
DOMImplementation	DOMImplementation-Objekte	Schnittstelle zur zugrunde liegenden Implementierung.
Node	Node-Objekte	Basisschnittstelle für die meisten Objekte in einem Dokument.
NodeList	NodeList-Objekte	Schnittstelle für eine Sequenz von Knoten.
DocumentType	DocumentType-Objekte	Informationen über die Deklarationen, die zur Verarbeitung eines Dokuments erforderlich sind.
Document	Document-Objekte	Objekt, das ein gesamtes Dokument repräsentiert.
Element	Element-Objekte	Elementknoten in der Dokumenthierarchie.
Attr	Attr-Objekte	Attributwertknoten auf Elementknoten.
Kommentar	Comment-Objekte	Repräsentation von Kommentaren im Quelldokument.
Text	Text- und CDATASection-Objekte	Knoten, die Textinhalte aus dem Dokument enthalten.
ProcessingInstruction	ProcessingInstruction-Objekte	Repräsentation von Verarbeitungshinweisen.

Ein zusätzlicher Abschnitt beschreibt die Ausnahmen, die bei der Arbeit mit DOM in Python definiert sind.

DOMImplementation Objekte

Die DOMImplementation Schnittstelle bietet Anwendungen eine Möglichkeit, die Verfügbarkeit bestimmter Merkmale in dem von ihnen verwendeten DOM zu ermitteln. DOM Level 2 fügte die Möglichkeit hinzu, neue Document und DocumentType Objekte unter Verwendung der DOMImplementation zu erstellen.

DOMImplementation.hasFeature(feature, version)

Gibt True zurück, wenn das Merkmal, das durch das Paar von Zeichenketten feature und version identifiziert wird, implementiert ist.

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

Gibt ein neues Document Objekt (die Wurzel des DOM) mit einem untergeordneten Element Objekt zurück, das den angegebenen namespaceUri und qualifiedName hat. Der doctype muss ein DocumentType Objekt sein, das von createDocumentType() erstellt wurde, oder None. In der Python DOM API können die ersten beiden Argumente auch None sein, um anzuzeigen, dass kein untergeordnetes Element erstellt werden soll.

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

Gibt ein neues DocumentType Objekt zurück, das den angegebenen qualifiedName-, publicId- und systemId-Zeichenketten kapselt und die in einer XML-Dokumenttypdeklaration enthaltenen Informationen repräsentiert.

Node Objekte

Alle Komponenten eines XML-Dokuments sind Unterklassen von Node.

Node.nodeType

Eine Ganzzahl, die den Knotentyp darstellt. Symbolische Konstanten für die Typen befinden sich auf dem Node Objekt: ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, ENTITY_NODE, PROCESSING_INSTRUCTION_NODE, COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE. Dies ist ein schreibgeschütztes Attribut.

Node.parentNode

Der übergeordnete Knoten des aktuellen Knotens oder None für den Dokumentknoten. Der Wert ist immer ein Node Objekt oder None. Für Element Knoten ist dies das übergeordnete Element, außer für das Wurzel-Element, in welchem Fall es das Document Objekt ist. Für Attr Knoten ist dies immer None. Dies ist ein schreibgeschütztes Attribut.

Node.attributes

Eine NamedNodeMap von Attributobjekten. Nur Elemente haben tatsächliche Werte dafür; andere liefern None für dieses Attribut. Dies ist ein schreibgeschütztes Attribut.

Node.previousSibling

Der Knoten, der diesem Knoten mit demselben Elternknoten unmittelbar vorausgeht. Zum Beispiel das Element mit einem End-Tag, das direkt vor dem Start-Tag des *selbst*-Elements kommt. Natürlich bestehen XML-Dokumente aus mehr als nur Elementen, sodass das vorherige Geschwisterkind Text, ein Kommentar oder etwas anderes sein kann. Wenn dieser Knoten das erste Kind des Elternknotens ist, wird dieses Attribut None sein. Dies ist ein schreibgeschütztes Attribut.

Node.nextSibling

Der Knoten, der diesem Knoten mit demselben Elternknoten unmittelbar folgt. Siehe auch previousSibling. Wenn dies das letzte Kind des Elternknotens ist, wird dieses Attribut None sein. Dies ist ein schreibgeschütztes Attribut.

Node.childNodes

Eine Liste von Knoten, die in diesem Knoten enthalten sind. Dies ist ein schreibgeschütztes Attribut.

Node.firstChild

Das erste Kind des Knotens, falls vorhanden, oder None. Dies ist ein schreibgeschütztes Attribut.

Node.lastChild

Das letzte Kind des Knotens, falls vorhanden, oder None. Dies ist ein schreibgeschütztes Attribut.

Node.localName

Der Teil des tagName, der dem Doppelpunkt folgt, falls vorhanden, andernfalls der gesamte tagName. Der Wert ist eine Zeichenkette.

Node.prefix

Der Teil des tagName, der dem Doppelpunkt vorausgeht, falls vorhanden, andernfalls die leere Zeichenkette. Der Wert ist eine Zeichenkette oder None.

Node.namespaceURI

Der Namespace, der dem Elementnamen zugeordnet ist. Dies ist eine Zeichenkette oder None. Dies ist ein schreibgeschütztes Attribut.

Node.nodeName

Dies hat eine andere Bedeutung für jeden Knotentyp; siehe die DOM-Spezifikation für Details. Sie können die hier erhaltenen Informationen immer von einer anderen Eigenschaft erhalten, wie z.B. der tagName-Eigenschaft für Elemente oder der name-Eigenschaft für Attribute. Für alle Knotentypen ist der Wert dieses Attributs entweder eine Zeichenkette oder None. Dies ist ein schreibgeschütztes Attribut.

Node.nodeValue

Dies hat eine andere Bedeutung für jeden Knotentyp; siehe die DOM-Spezifikation für Details. Die Situation ist ähnlich wie bei nodeName. Der Wert ist eine Zeichenkette oder None.

Node.hasAttributes()

Gibt True zurück, wenn der Knoten Attribute hat.

Node.hasChildNodes()

Gibt True zurück, wenn der Knoten Kindknoten hat.

Node.isSameNode(other)

Gibt True zurück, wenn other auf denselben Knoten wie dieser Knoten verweist. Dies ist besonders nützlich für DOM-Implementierungen, die eine Art Proxy-Architektur verwenden (da mehr als ein Objekt auf denselben Knoten verweisen kann).

Hinweis

Dies basiert auf einer vorgeschlagenen DOM Level 3 API, die sich noch im „Working Draft“-Stadium befindet, aber diese spezielle Schnittstelle erscheint unkontrovers. Änderungen am W3C werden diese Methode in der Python DOM-Schnittstelle nicht notwendigerweise beeinflussen (obwohl jede neue W3C-API dafür ebenfalls unterstützt würde).

Node.appendChild(newChild)

Fügt einen neuen Kindknoten am Ende der Liste der Kinder zu diesem Knoten hinzu und gibt newChild zurück. Wenn der Knoten bereits im Baum vorhanden war, wird er zuerst entfernt.

Node.insertBefore(newChild, refChild)

Fügt einen neuen Kindknoten vor einem vorhandenen Kind ein. Es muss gelten, dass refChild ein Kind dieses Knotens ist; andernfalls wird ValueError ausgelöst. newChild wird zurückgegeben. Wenn refChild None ist, wird newChild am Ende der Kinderliste eingefügt.

Node.removeChild(oldChild)

Entfernt einen Kindknoten. oldChild muss ein Kind dieses Knotens sein; andernfalls wird ValueError ausgelöst. oldChild wird bei Erfolg zurückgegeben. Wenn oldChild nicht mehr verwendet wird, sollte seine unlink()-Methode aufgerufen werden.

Node.replaceChild(newChild, oldChild)

Ersetzt einen vorhandenen Knoten durch einen neuen Knoten. Es muss gelten, dass oldChild ein Kind dieses Knotens ist; andernfalls wird ValueError ausgelöst.

Node.normalize()

Verbindet benachbarte Textknoten, sodass alle Textabschnitte als einzelne Text-Instanzen gespeichert werden. Dies vereinfacht für viele Anwendungen die Verarbeitung von Text aus einem DOM-Baum.

Node.cloneNode(deep)

Kopiert diesen Knoten. Wenn deep gesetzt ist, werden auch alle Kindknoten kopiert. Dies gibt die Kopie zurück.

NodeList Objekte

Eine NodeList repräsentiert eine Sequenz von Knoten. Diese Objekte werden in der DOM Core Empfehlung auf zwei Arten verwendet: Ein Element Objekt stellt eine solche als Liste seiner Kindknoten bereit, und die Methoden getElementsByTagName() und getElementsByTagNameNS() von Node geben Objekte mit dieser Schnittstelle zurück, um Abfrageergebnisse zu repräsentieren.

Die DOM Level 2 Empfehlung definiert eine Methode und ein Attribut für diese Objekte

NodeList.item(i)

Gibt das i-te Element aus der Sequenz zurück, falls vorhanden, oder None. Der Index i darf nicht kleiner als Null oder größer oder gleich der Länge der Sequenz sein.

NodeList.length

Die Anzahl der Knoten in der Sequenz.

Darüber hinaus erfordert die Python DOM-Schnittstelle, dass zusätzliche Unterstützung bereitgestellt wird, um NodeList Objekte als Python-Sequenzen verwenden zu können. Alle NodeList Implementierungen müssen Unterstützung für __len__() und __getitem__() beinhalten; dies ermöglicht die Iteration über die NodeList in for-Anweisungen und die korrekte Unterstützung für die eingebaute Funktion len().

Wenn eine DOM-Implementierung die Änderung des Dokuments unterstützt, muss die NodeList-Implementierung auch die Methoden __setitem__() und __delitem__() unterstützen.

DocumentType-Objekte

Informationen über die von einem Dokument deklarierten Notationen und Entitäten (einschließlich des externen Teilmengen, falls der Parser diese verwendet und die Informationen bereitstellen kann) sind über ein DocumentType-Objekt verfügbar. Der DocumentType eines Dokuments ist über das Attribut doctype des Document-Objekts verfügbar; wenn für das Dokument keine DOCTYPE-Deklaration vorhanden ist, wird das Attribut doctype des Dokuments auf None anstelle einer Instanz dieser Schnittstelle gesetzt.

DocumentType ist eine Spezialisierung von Node und fügt die folgenden Attribute hinzu

DocumentType.publicId

Der öffentliche Bezeichner für die externe Teilmenge der Dokumenttypdefinition. Dies ist ein String oder None.

DocumentType.systemId

Der Systembezeichner für die externe Teilmenge der Dokumenttypdefinition. Dies ist eine URI als String oder None.

DocumentType.internalSubset

Ein String, der die vollständige interne Teilmenge des Dokuments angibt. Dies schließt die Klammern, die die Teilmenge umschließen, nicht ein. Wenn das Dokument keine interne Teilmenge hat, sollte dies None sein.

DocumentType.name

Der Name des Wurzelelements gemäß der DOCTYPE-Deklaration, falls vorhanden.

DocumentType.entities

Dies ist ein NamedNodeMap, der die Definitionen externer Entitäten enthält. Bei mehrmals definierten Entitätsnamen wird nur die erste Definition angegeben (andere werden gemäß der XML-Empfehlung ignoriert). Dies kann None sein, wenn die Informationen nicht vom Parser bereitgestellt werden oder wenn keine Entitäten definiert sind.

DocumentType.notations

Dies ist ein NamedNodeMap, der die Definitionen von Notationen enthält. Bei mehrmals definierten Notationsnamen wird nur die erste Definition angegeben (andere werden gemäß der XML-Empfehlung ignoriert). Dies kann None sein, wenn die Informationen nicht vom Parser bereitgestellt werden oder wenn keine Notationen definiert sind.

Document-Objekte

Ein Document repräsentiert ein gesamtes XML-Dokument, einschließlich seiner Bestandteile wie Elemente, Attribute, Verarbeitungsanweisungen, Kommentare usw. Denken Sie daran, dass es Eigenschaften von Node erbt.

Document.documentElement

Das einzige Wurzelelement des Dokuments.

Document.createElement(tagName)

Erstellt und gibt einen neuen Elementknoten zurück. Das Element wird beim Erstellen nicht in das Dokument eingefügt. Sie müssen es explizit mit einer der anderen Methoden wie insertBefore() oder appendChild() einfügen.

Document.createElementNS(namespaceURI, tagName)

Erstellt und gibt ein neues Element mit einem Namespace zurück. Der tagName kann ein Präfix haben. Das Element wird beim Erstellen nicht in das Dokument eingefügt. Sie müssen es explizit mit einer der anderen Methoden wie insertBefore() oder appendChild() einfügen.

Document.createTextNode(data)

Erstellt und gibt einen Textknoten zurück, der die als Parameter übergebenen Daten enthält. Wie bei den anderen Erstellungsmethoden fügt diese die Knoten nicht in den Baum ein.

Document.createComment(data)

Erstellt und gibt einen Kommentar-Knoten zurück, der die als Parameter übergebenen Daten enthält. Wie bei den anderen Erstellungsmethoden fügt diese die Knoten nicht in den Baum ein.

Document.createProcessingInstruction(target, data)

Erstellt und gibt einen Verarbeitungsanweisungs-Knoten zurück, der die als Parameter übergebenen target und data enthält. Wie bei den anderen Erstellungsmethoden fügt diese die Knoten nicht in den Baum ein.

Document.createAttribute(name)

Erstellt und gibt einen Attributknoten zurück. Diese Methode ordnet den Attributknoten keinem bestimmten Element zu. Sie müssen setAttributeNode() auf dem entsprechenden Element-Objekt verwenden, um die neu erstellte Attributinstanz zu verwenden.

Document.createAttributeNS(namespaceURI, qualifiedName)

Erstellt und gibt einen Attributknoten mit einem Namespace zurück. Der tagName kann ein Präfix haben. Diese Methode ordnet den Attributknoten keinem bestimmten Element zu. Sie müssen setAttributeNode() auf dem entsprechenden Element-Objekt verwenden, um die neu erstellte Attributinstanz zu verwenden.

Document.getElementsByTagName(tagName)

Sucht nach allen Nachfahren (direkte Kinder, Kinder von Kindern usw.) mit einem bestimmten Elementtypnamen.

Document.getElementsByTagNameNS(namespaceURI, localName)

Sucht nach allen Nachfahren (direkte Kinder, Kinder von Kindern usw.) mit einem bestimmten Namespace-URI und LocalName. Der LocalName ist der Teil des Namens nach dem Präfix.

Element-Objekte

Element ist eine Unterklasse von Node, erbt also alle Attribute dieser Klasse.

Element.tagName

Der Elementtypname. In einem Namespace-verwendenden Dokument kann er Doppelpunkte enthalten. Der Wert ist ein String.

Element.getElementsByTagName(tagName)

Gleich der gleichnamigen Methode in der Document-Klasse.

Element.getElementsByTagNameNS(namespaceURI, localName)

Gleich der gleichnamigen Methode in der Document-Klasse.

Element.hasAttribute(name)

Gibt True zurück, wenn das Element ein Attribut mit dem Namen name hat.

Element.hasAttributeNS(namespaceURI, localName)

Gibt True zurück, wenn das Element ein Attribut mit dem Namespace-URI namespaceURI und dem LocalName localName hat.

Element.getAttribute(name)

Gibt den Wert des Attributs mit dem Namen name als String zurück. Wenn kein solches Attribut existiert, wird ein leerer String zurückgegeben, als ob das Attribut keinen Wert hätte.

Element.getAttributeNode(attrname)

Gibt den Attr-Knoten für das Attribut mit dem Namen attrname zurück.

Element.getAttributeNS(namespaceURI, localName)

Gibt den Wert des Attributs mit dem Namespace-URI namespaceURI und dem LocalName localName als String zurück. Wenn kein solches Attribut existiert, wird ein leerer String zurückgegeben, als ob das Attribut keinen Wert hätte.

Element.getAttributeNodeNS(namespaceURI, localName)

Gibt einen Attributwert als Knoten zurück, gegeben einen namespaceURI und localName.

Element.removeAttribute(name)

Entfernt ein Attribut anhand des Namens. Wenn kein passendes Attribut vorhanden ist, wird ein NotFoundErr ausgelöst.

Element.removeAttributeNode(oldAttr)

Entfernt und gibt oldAttr aus der Attributliste zurück, falls vorhanden. Wenn oldAttr nicht vorhanden ist, wird ein NotFoundErr ausgelöst.

Element.removeAttributeNS(namespaceURI, localName)

Entfernt ein Attribut anhand des Namens. Beachten Sie, dass hierfür ein LocalName und kein QName verwendet wird. Es wird keine Ausnahme ausgelöst, wenn kein passendes Attribut vorhanden ist.

Element.setAttribute(name, value)

Setzt einen Attributwert aus einem String.

Element.setAttributeNode(newAttr)

Fügt dem Element einen neuen Attributknoten hinzu und ersetzt gegebenenfalls ein vorhandenes Attribut, wenn der Attributname name übereinstimmt. Wenn eine Ersetzung stattfindet, wird der alte Attributknoten zurückgegeben. Wenn newAttr bereits in Gebrauch ist, wird ein InuseAttributeErr ausgelöst.

Element.setAttributeNodeNS(newAttr)

Fügt dem Element einen neuen Attributknoten hinzu und ersetzt gegebenenfalls ein vorhandenes Attribut, wenn der Namespace-URI und der LocalName des Attributs übereinstimmen. Wenn eine Ersetzung stattfindet, wird der alte Attributknoten zurückgegeben. Wenn newAttr bereits in Gebrauch ist, wird ein InuseAttributeErr ausgelöst.

Element.setAttributeNS(namespaceURI, qname, value)

Setzt einen Attributwert aus einem String, gegeben einen namespaceURI und einen qname. Beachten Sie, dass ein qname der gesamte Attributname ist. Dies ist anders als oben.

Attr-Objekte

Attr erbt von Node und erbt daher alle seine Attribute.

Attr.name

Der Attributname. In einem Namespace-verwendenden Dokument kann er einen Doppelpunkt enthalten.

Attr.localName

Der Teil des Namens nach dem Doppelpunkt, falls vorhanden, andernfalls der gesamte Name. Dies ist ein schreibgeschütztes Attribut.

Attr.prefix

Der Teil des Namens vor dem Doppelpunkt, falls vorhanden, andernfalls der leere String.

Attr.value

Der Textwert des Attributs. Dies ist ein Synonym für das Attribut nodeValue.

NamedNodeMap-Objekte

NamedNodeMap erbt *nicht* von Node.

NamedNodeMap.length

Die Länge der Attributliste.

NamedNodeMap.item(index)

Gibt ein Attribut mit einem bestimmten Index zurück. Die Reihenfolge, in der die Attribute zurückgegeben werden, ist willkürlich, aber für die Lebensdauer eines DOM konsistent. Jedes Element ist ein Attributknoten. Sein Wert kann über das Attribut value abgerufen werden.

Es gibt auch experimentelle Methoden, die dieser Klasse mehr Mapping-Funktionen verleihen. Sie können diese verwenden oder die standardisierten getAttribute*()-Methoden auf den Element-Objekten verwenden.

Comment-Objekte

Comment repräsentiert einen Kommentar im XML-Dokument. Es ist eine Unterklasse von Node, kann aber keine Kindknoten haben.

Comment.data

Der Inhalt des Kommentars als String. Das Attribut enthält alle Zeichen zwischen den führenden <!-- und den abschließenden -->, schließt diese aber nicht ein.

Text- und CDATASection-Objekte

Die Schnittstelle Text repräsentiert Text im XML-Dokument. Wenn der Parser und die DOM-Implementierung die XML-Erweiterung des DOM unterstützen, werden Teile des Texts, die in CDATA-Markierungsabschnitten eingeschlossen sind, in CDATASection-Objekten gespeichert. Diese beiden Schnittstellen sind identisch, liefern aber unterschiedliche Werte für das Attribut nodeType.

Diese Schnittstellen erweitern die Node-Schnittstelle. Sie können keine Kindknoten haben.

Text.data

Der Inhalt des Textknotens als String.

Hinweis

Die Verwendung eines CDATASection-Knotens zeigt nicht an, dass der Knoten einen vollständigen CDATA-Markierungsabschnitt darstellt, sondern nur, dass der Inhalt des Knotens Teil eines CDATA-Abschnitts war. Ein einzelner CDATA-Abschnitt kann durch mehr als einen Knoten im Dokumentbaum repräsentiert werden. Es gibt keine Möglichkeit festzustellen, ob zwei benachbarte CDATASection-Knoten unterschiedliche CDATA-Markierungsabschnitte darstellen.

ProcessingInstruction-Objekte

Repräsentiert eine Verarbeitungsanweisung im XML-Dokument; dies erbt von der Node-Schnittstelle und kann keine Kindknoten haben.

ProcessingInstruction.target

Der Inhalt der Verarbeitungsanweisung bis zum ersten Leerzeichen. Dies ist ein schreibgeschütztes Attribut.

ProcessingInstruction.data

Der Inhalt der Verarbeitungsanweisung nach dem ersten Leerzeichen.

Ausnahmen

Die DOM Level 2-Empfehlung definiert eine einzige Ausnahme, DOMException, und eine Reihe von Konstanten, die es Anwendungen ermöglichen, den aufgetretenen Fehlertyp zu ermitteln. DOMException-Instanzen enthalten ein Attribut code, das den entsprechenden Wert für die spezifische Ausnahme liefert.

Die Python DOM-Schnittstelle stellt die Konstanten bereit, erweitert aber auch die Menge der Ausnahmen, sodass für jeden von der DOM definierten Ausnahmecode eine spezifische Ausnahme existiert. Die Implementierungen müssen die entsprechende spezifische Ausnahme auslösen, die jeweils den richtigen Wert für das Attribut code enthält.

exception xml.dom.DOMException

Basisklassen für Ausnahmen, die für alle spezifischen DOM-Ausnahmen verwendet werden. Diese Ausnahmeklasse kann nicht direkt instanziiert werden.

exception xml.dom.DomstringSizeErr

Wird ausgelöst, wenn ein angegebener Textbereich nicht in einen String passt. Dies wird in den Python DOM-Implementierungen nicht verwendet, kann aber von DOM-Implementierungen empfangen werden, die nicht in Python geschrieben sind.

exception xml.dom.HierarchyRequestErr

Wird ausgelöst, wenn versucht wird, einen Knoten einzufügen, wo der Knotentyp nicht erlaubt ist.

exception xml.dom.IndexSizeErr

Wird ausgelöst, wenn ein Index- oder Größenparameter einer Methode negativ ist oder die zulässigen Werte überschreitet.

exception xml.dom.InuseAttributeErr

Wird ausgelöst, wenn versucht wird, einen Attr-Knoten einzufügen, der bereits an anderer Stelle im Dokument vorhanden ist.

exception xml.dom.InvalidAccessErr

Wird ausgelöst, wenn ein Parameter oder eine Operation für das zugrunde liegende Objekt nicht unterstützt wird.

exception xml.dom.InvalidCharacterErr

Diese Ausnahme wird ausgelöst, wenn ein String-Parameter ein Zeichen enthält, das im Kontext, in dem es von der XML 1.0-Empfehlung verwendet wird, nicht zulässig ist. Zum Beispiel wird der Versuch, einen Element-Knoten mit einem Leerzeichen im Elementtypnamen zu erstellen, diesen Fehler auslösen.

exception xml.dom.InvalidModificationErr

Wird ausgelöst, wenn versucht wird, den Typ eines Knotens zu ändern.

exception xml.dom.InvalidStateErr

Wird ausgelöst, wenn versucht wird, ein Objekt zu verwenden, das nicht definiert oder nicht mehr verwendbar ist.

exception xml.dom.NamespaceErr

Wenn versucht wird, ein Objekt so zu ändern, dass dies im Hinblick auf die Namespaces in XML-Empfehlung nicht zulässig ist, wird diese Ausnahme ausgelöst.

exception xml.dom.NotFoundErr

Ausnahme, wenn ein Knoten im referenzierten Kontext nicht existiert. Zum Beispiel löst NamedNodeMap.removeNamedItem() diesen Fehler aus, wenn der übergebene Knoten nicht in der Map vorhanden ist.

exception xml.dom.NotSupportedErr

Wird ausgelöst, wenn die Implementierung den angeforderten Objekttyp oder die Operation nicht unterstützt.

exception xml.dom.NoDataAllowedErr

Dies wird ausgelöst, wenn Daten für einen Knoten angegeben werden, der keine Daten unterstützt.

exception xml.dom.NoModificationAllowedErr

Wird bei Versuchen ausgelöst, ein Objekt zu ändern, bei dem Änderungen nicht erlaubt sind (z. B. bei schreibgeschützten Knoten).

exception xml.dom.SyntaxErr

Wird ausgelöst, wenn ein ungültiger oder illegaler String angegeben wird.

exception xml.dom.WrongDocumentErr

Wird ausgelöst, wenn ein Knoten in ein anderes Dokument eingefügt wird, als zu dem er derzeit gehört, und die Implementierung das Verschieben des Knotens von einem Dokument zum anderen nicht unterstützt.

Die in der DOM-Empfehlung definierten Ausnahmecodes entsprechen den oben beschriebenen Ausnahmen gemäß dieser Tabelle

Konstante	Exception
DOMSTRING_SIZE_ERR	DomstringSizeErr
HIERARCHY_REQUEST_ERR	HierarchyRequestErr
INDEX_SIZE_ERR	IndexSizeErr
INUSE_ATTRIBUTE_ERR	InuseAttributeErr
INVALID_ACCESS_ERR	InvalidAccessErr
INVALID_CHARACTER_ERR	InvalidCharacterErr
INVALID_MODIFICATION_ERR	InvalidModificationErr
INVALID_STATE_ERR	InvalidStateErr
NAMESPACE_ERR	NamespaceErr
NOT_FOUND_ERR	NotFoundErr
NOT_SUPPORTED_ERR	NotSupportedErr
NO_DATA_ALLOWED_ERR	NoDataAllowedErr
NO_MODIFICATION_ALLOWED_ERR	NoModificationAllowedErr
SYNTAX_ERR	SyntaxErr
WRONG_DOCUMENT_ERR	WrongDocumentErr

Konformität

Dieser Abschnitt beschreibt die Konformitätsanforderungen und Beziehungen zwischen der Python DOM API, den W3C DOM-Empfehlungen und dem OMG IDL-Mapping für Python.

Typ-Mapping

Die in der DOM-Spezifikation verwendeten IDL-Typen werden gemäß der folgenden Tabelle Python-Typen zugeordnet.

IDL Typ	Python Typ
boolean	bool oder int
int	int
long int	int
unsigned int	int
DOMString	str oder bytes
null	None

Accessor-Methoden

Das Mapping von OMG IDL zu Python definiert Accessor-Funktionen für IDL attribute-Deklarationen auf ähnliche Weise wie das Java-Mapping. Das Mapping der IDL-Deklarationen

readonly attribute string someValue;
         attribute string anotherValue;

liefert drei Zugriffsfunktionen: eine „get“-Methode für someValue (_get_someValue()) und „get“- und „set“-Methoden für anotherValue (_get_anotherValue() und _set_anotherValue()). Insbesondere erfordert die Zuordnung nicht, dass die IDL-Attribute als normale Python-Attribute zugänglich sind: object.someValue muss nicht funktionieren und kann einen AttributeError auslösen.

Die Python DOM API erfordert jedoch, dass der normale Attributzugriff funktioniert. Das bedeutet, dass die typischen Stellvertreter, die von Python IDL-Compilern generiert werden, wahrscheinlich nicht funktionieren, und Wrapper-Objekte können auf der Clientseite benötigt werden, wenn die DOM-Objekte über CORBA aufgerufen werden. Obwohl dies einige zusätzliche Überlegungen für CORBA DOM-Clients erfordert, betrachten Implementierer mit Erfahrung in der Verwendung von DOM über CORBA von Python aus dies nicht als Problem. Attribute, die als readonly deklariert sind, schränken den Schreibzugriff möglicherweise nicht in allen DOM-Implementierungen ein.

In der Python DOM API sind Zugriffsfunktionen nicht erforderlich. Wenn sie bereitgestellt werden, sollten sie die vom Python IDL-Mapping definierte Form annehmen, aber diese Methoden werden als unnötig betrachtet, da die Attribute direkt von Python aus zugänglich sind. „Set“-Zugriffsfunktionen sollten niemals für readonly-Attribute bereitgestellt werden.

Die IDL-Definitionen verkörpern nicht vollständig die Anforderungen der W3C DOM API, wie die Vorstellung, dass bestimmte Objekte, wie der Rückgabewert von getElementsByTagName(), „live“ sind. Die Python DOM API verlangt von Implementierungen nicht, solche Anforderungen durchzusetzen.