xml.dom — Die API des Document Object Model

Quellcode: Lib/xml/dom/__init__.py

---

Das Document Object Model, kurz „DOM“, ist eine sprachübergreifende API des World Wide Web Consortium (W3C), um XML-Dokumente zu lesen und zu ändern. Eine DOM-Umsetzung stellt ein XML-Dokument als Baumstruktur dar oder erlaubt es dem Code des Clients, eine solche Struktur von Grund auf aufzubauen. Den Zugriff auf die Struktur gewährt sie dann über eine Reihe von Objekten mit wohlbekannten Schnittstellen.

Für Anwendungen mit wahlfreiem Zugriff ist das DOM ausgesprochen nützlich. SAX zeigt dir immer nur einen Ausschnitt des Dokuments auf einmal. Siehst du ein SAX-Element an, hast du keinen Zugriff auf ein anderes. Siehst du einen Textknoten an, hast du keinen Zugriff auf das umgebende Element. Wer eine SAX-Anwendung schreibt, muss im eigenen Code irgendwo mitverfolgen, an welcher Stelle des Dokuments das Programm gerade steht; SAX nimmt dir das nicht ab. Und wer im XML-Dokument vorausschauen muss, hat schlicht Pech.

Manche Anwendungen sind in einem ereignisgesteuerten Modell ohne Zugriff auf einen Baum einfach nicht möglich. Natürlich könntest du in den SAX-Ereignissen selbst eine Art Baum aufbauen, doch das DOM erspart dir diesen Code. Es ist die standardisierte Baumdarstellung für XML-Daten.

Das W3C definiert das Document Object Model in Stufen, in seiner Begriffswelt „Levels“. Die Python-Abbildung der API beruht im Wesentlichen auf der Empfehlung DOM Level 2.

DOM-Anwendungen beginnen üblicherweise damit, XML in ein DOM einzulesen. Wie das geschieht, lässt DOM Level 1 völlig offen, und Level 2 bringt nur begrenzte Verbesserungen: Es gibt die Objektklasse DOMImplementation, die Zugriff auf die Methoden zum Erzeugen von Document gewährt, aber keinen Weg, unabhängig von der Umsetzung auf einen XML-Reader, -Parser oder Document-Builder zuzugreifen. Es gibt auch keinen klar festgelegten Weg, diese Methoden ohne ein vorhandenes Document-Objekt zu erreichen. In Python stellt jede DOM-Umsetzung eine Funktion getDOMImplementation() bereit. DOM Level 3 ergänzt eine Load/Store-Spezifikation, die eine Schnittstelle zum Reader festlegt. In der Python-Standardbibliothek steht sie aber noch nicht zur Verfügung.

Sobald du ein DOM-Dokumentobjekt hast, erreichst du die Teile deines XML-Dokuments über seine Eigenschaften und Methoden. Diese Eigenschaften legt die DOM-Spezifikation fest. Dieser Teil des Referenzhandbuchs beschreibt, wie die Spezifikation in Python gedeutet wird.

Die Spezifikation des W3C legt die DOM-API für Java, ECMAScript und OMG IDL fest. Die hier festgelegte Python-Abbildung beruht zum großen Teil auf der IDL-Fassung der Spezifikation, strenge Einhaltung ist aber nicht gefordert (Umsetzungen dürfen die strenge Abbildung aus IDL durchaus unterstützen). Eine ausführliche Erörterung der Anforderungen an die Abbildung steht im Abschnitt Konformität.

Siehe auch

Document Object Model (DOM) Level 2 Specification

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

Document Object Model (DOM) Level 1 Specification

Die Empfehlung des W3C für das DOM, das xml.dom.minidom unterstützt.

Python Language Mapping Specification

Sie legt die Abbildung von OMG IDL auf Python fest.

Inhalt des Moduls

xml.dom enthält die folgenden Funktionen:

xml.dom.registerDOMImplementation(name, factory)

Meldet die Factory-Funktion factory unter dem Namen name an. Die Factory-Funktion sollte ein Objekt zurückgeben, das die Schnittstelle DOMImplementation umsetzt. Sie kann jedes Mal dasselbe Objekt oder bei jedem Aufruf ein neues zurückgeben, je nachdem, was zur jeweiligen Umsetzung passt – etwa wenn diese Umsetzung Anpassungen erlaubt.

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

Gibt eine passende DOM-Umsetzung zurück. name ist entweder ein wohlbekannter Name, der Modulname einer DOM-Umsetzung oder None. Ist er nicht None, wird das entsprechende Modul importiert und bei Erfolg ein DOMImplementation-Objekt zurückgegeben. Ist kein Name angegeben und die Umgebungsvariable PYTHON_DOM gesetzt, dient diese Variable dazu, die Umsetzung zu finden. Der einzige wohlbekannte Name in der Standardbibliothek ist 'minidom' für xml.dom.minidom.

Ist kein Name angegeben, werden die verfügbaren Umsetzungen daraufhin untersucht, welche die verlangten Merkmale mitbringt. Lässt sich keine Umsetzung finden, wird ein ImportError ausgelöst. Die Liste der Merkmale muss eine Sequenz von Paaren (feature, version) sein, die an die Methode hasFeature() der verfügbaren DOMImplementation-Objekte übergeben werden.

Außerdem gibt es einige praktische Konstanten:

xml.dom.EMPTY_NAMESPACE

Der Wert, der angibt, dass einem Knoten im DOM kein Namensraum zugeordnet ist. Üblicherweise steht er in der namespaceURI eines Knotens oder wird als Parameter namespaceURI an eine Methode übergeben, die mit Namensräumen arbeitet.

xml.dom.XML_NAMESPACE

Die Namensraum-URI, die zum vorbehaltenen Präfix xml gehört, wie in Namespaces in XML (Abschnitt 4) festgelegt.

xml.dom.XMLNS_NAMESPACE

Die Namensraum-URI für Namensraumdeklarationen, wie in Document Object Model (DOM) Level 2 Core Specification (Abschnitt 1.1.8) festgelegt.

xml.dom.XHTML_NAMESPACE

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

Außerdem enthält xml.dom eine Basisklasse Node und die DOM-Ausnahmeklassen. Die Node-Klasse dieses Moduls setzt keine der Methoden und Attribute um, die die DOM-Spezifikation festlegt – das müssen die konkreten DOM-Umsetzungen leisten. Die mit diesem Modul gelieferte Node-Klasse stellt aber die Konstanten für das Attribut nodeType konkreter Node-Objekte bereit. Diese liegen in der Klasse und nicht auf Modulebene, um den DOM-Spezifikationen zu entsprechen.

Objekte im DOM

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

Die in diesem Abschnitt beschriebenen Namen sind DOM-Schnittstellen. Mit Ausnahme von Node und den Ausnahmeklassen stellt sie nicht das Modul xml.dom selbst bereit, sondern die konkreten DOM-Umsetzungen wie xml.dom.minidom.

Beachte, dass sich DOM-Attribute auch als Knoten statt als einfache Zeichenketten bearbeiten lassen. Nötig ist das allerdings recht selten, daher ist diese Verwendung noch nicht beschrieben.

Schnittstelle	Abschnitt	Zweck
DOMImplementation	DOMImplementation-Objekte	Schnittstelle zur zugrunde liegenden Umsetzung.
Node	Node-Objekte	Basisschnittstelle für die meisten Objekte eines Dokuments.
NodeList	NodeList-Objekte	Schnittstelle für eine Folge von Knoten.
DocumentType	DocumentType-Objekte	Angaben zu den Deklarationen, die zum Verarbeiten eines Dokuments nötig sind.
Document	Document-Objekte	Objekt, das ein gesamtes Dokument darstellt.
Element	Element-Objekte	Elementknoten in der Dokumenthierarchie.
Attr	Attr-Objekte	Knoten für Attributwerte an Elementknoten.
Comment	Comment-Objekte	Darstellung von Kommentaren im Quelldokument.
Text	Text- und CDATASection-Objekte	Knoten, die Textinhalt aus dem Dokument enthalten.
ProcessingInstruction	ProcessingInstruction-Objekte	Darstellung einer Verarbeitungsanweisung.

Ein weiterer Abschnitt beschreibt die Ausnahmen, die für die Arbeit mit dem DOM in Python festgelegt sind.

DOMImplementation-Objekte

Über die Schnittstelle DOMImplementation können Anwendungen feststellen, ob bestimmte Merkmale in dem DOM zur Verfügung stehen, das sie verwenden. Mit DOM Level 2 kam hinzu, über DOMImplementation auch neue Document- und DocumentType-Objekte zu erzeugen.

DOMImplementation.hasFeature(feature, version)

Gibt True zurück, wenn das Merkmal umgesetzt ist, das das Zeichenkettenpaar feature und version benennt.

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

Gibt ein neues Document-Objekt zurück (die Wurzel des DOM) mit einem Element-Kindknoten, der namespaceUri und qualifiedName trägt. doctype muss ein DocumentType-Objekt sein, das createDocumentType() erzeugt hat, oder None. In der Python-DOM-API dürfen die ersten beiden Argumente auch None sein; das bedeutet, dass kein Element-Kindknoten erzeugt werden soll.

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

Gibt ein neues DocumentType-Objekt zurück, das die Zeichenketten qualifiedName, publicId und systemId kapselt und damit die Angaben einer XML-Dokumenttypdeklaration darstellt.

Node-Objekte

Alle Bestandteile eines XML-Dokuments sind Unterklassen von Node.

Nur Knoten der folgenden Typen können Kindknoten haben, und nur Kindknoten der aufgeführten Typen:

Document

höchstens ein Element, höchstens ein DocumentType, ProcessingInstruction und Comment

DocumentFragment und Element

Element, Text, CDATASection, ProcessingInstruction und Comment

Attr

Text

Knoten anderer Typen können keine Kindknoten haben. Einen Kindknoten eines nicht erlaubten Typs einzufügen löst HierarchyRequestErr aus.

Node.nodeType

Eine ganze Zahl, die den Knotentyp angibt. Symbolische Konstanten für die Typen stehen am Node-Objekt. Dieses Attribut ist nur lesbar.

Node.ELEMENT_NODE

Node.ATTRIBUTE_NODE

Node.TEXT_NODE

Node.CDATA_SECTION_NODE

Node.ENTITY_REFERENCE_NODE

Node.ENTITY_NODE

Node.PROCESSING_INSTRUCTION_NODE

Node.COMMENT_NODE

Node.DOCUMENT_NODE

Node.DOCUMENT_TYPE_NODE

Node.DOCUMENT_FRAGMENT_NODE

Node.NOTATION_NODE

Ganzzahlige Konstanten für die möglichen Werte des Attributs nodeType.

Node.parentNode

Der Elternknoten des aktuellen Knotens oder None beim Dokumentknoten. Der Wert ist immer ein Node-Objekt oder None. Bei Element-Knoten ist es das Elternelement, außer beim Wurzelelement – dort ist es das Document-Objekt. Bei Attr-Knoten ist er immer None. Dieses Attribut ist nur lesbar.

Node.attributes

Eine NamedNodeMap von Attributobjekten. Nur Elemente haben hier tatsächliche Werte, alle anderen liefern für dieses Attribut None. Dieses Attribut ist nur lesbar.

Node.previousSibling

Der Knoten, der diesem unmittelbar vorausgeht und denselben Elternknoten hat, zum Beispiel das Element, dessen End-Tag unmittelbar vor dem Start-Tag des self-Elements steht. XML-Dokumente bestehen natürlich aus mehr als nur Elementen, der vorige Geschwisterknoten kann also auch Text, ein Kommentar oder etwas anderes sein. Ist dieser Knoten der erste Kindknoten des Elternknotens, ist dieses Attribut None. Dieses Attribut ist nur lesbar.

Node.nextSibling

Der Knoten, der diesem unmittelbar folgt und denselben Elternknoten hat. Siehe auch previousSibling. Ist dies der letzte Kindknoten des Elternknotens, ist dieses Attribut None. Dieses Attribut ist nur lesbar.

Node.childNodes

Eine NodeList der Kindknoten dieses Knotens. Hat der Knoten keine Kindknoten, ist die Liste leer. Dieses Attribut ist nur lesbar.

Node.firstChild

Der erste Kindknoten des Knotens, sofern es welche gibt, sonst None. Dieses Attribut ist nur lesbar.

Node.lastChild

Der letzte Kindknoten des Knotens, sofern es welche gibt, sonst None. Dieses Attribut ist nur lesbar.

Node.localName

Der Teil des tagName nach dem Doppelpunkt, sofern es einen gibt, sonst der gesamte tagName. Der Wert ist eine Zeichenkette.

Node.prefix

Der Teil des tagName vor dem Doppelpunkt, sofern es einen gibt, sonst die leere Zeichenkette. Der Wert ist eine Zeichenkette oder None.

Node.namespaceURI

Der Namensraum, der zum Elementnamen gehört. Das ist eine Zeichenkette oder None. Dieses Attribut ist nur lesbar.

Node.ownerDocument

Das Document-Objekt, zu dem dieser Knoten gehört, oder None bei einem Dokument selbst. Dieses Attribut ist nur lesbar.

Node.isSupported(feature, version)

Gibt zurück, ob die DOM-Umsetzung ein bestimmtes feature unterstützt, wie DOMImplementation.hasFeature().

Node.setUserData(key, data, handler)

Ordnet data an diesem Knoten dem Schlüssel key zu und gibt die Daten zurück, die vorher zu key gehörten, oder None. Ist data None, wird die Zuordnung aufgehoben. handler wird aufgerufen, wenn der Knoten geklont, importiert, umbenannt oder gelöscht wird. Übergib None, wenn keine Benachrichtigung nötig ist.

Node.getUserData(key)

Gibt die Daten zurück, die setUserData() an diesem Knoten dem Schlüssel key zugeordnet hat, oder None.

Node.nodeName

Der Name dieses Knotens, je nach Typ – siehe die Tabelle unten. Du kannst die Angabe immer auch über eine andere Eigenschaft bekommen, etwa über tagName bei Elementen oder über name bei Attributen. Dieses Attribut ist nur lesbar.

Node.nodeValue

Der Wert dieses Knotens, je nach Typ – siehe die Tabelle unten. Der Wert ist eine Zeichenkette oder None.

Die Werte von nodeName und nodeValue lauten je Knotentyp:

Knotentyp	nodeName	nodeValue
Attr	name	value
CDATASection	'#cdata-section'	der Inhalt
Comment	'#comment'	der Inhalt
Document	'#document'	None
DocumentFragment	'#document-fragment'	None
DocumentType	name	None
Element	tagName	None
Entity	der Name der Entität	None
Notation	der Name der Notation	None
ProcessingInstruction	target	data
Text	'#text'	der Inhalt

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 verweist wie dieser Knoten. Das ist besonders bei DOM-Umsetzungen nützlich, die mit einer Proxy-Architektur arbeiten, denn dort können mehrere Objekte auf denselben Knoten verweisen.

Bemerkung

Das beruht auf einer vorgeschlagenen API für DOM Level 3, die noch im Stadium „working draft“ steckt. Diese Schnittstelle scheint aber unstrittig zu sein. Änderungen des W3C müssen diese Methode in der Python-DOM-Schnittstelle nicht zwingend betreffen – eine neue W3C-API dafür würde allerdings ebenfalls unterstützt.

Node.appendChild(newChild)

Fügt diesem Knoten am Ende der Liste der Kindknoten einen neuen Kindknoten hinzu und gibt newChild zurück. War der Knoten bereits im Baum, wird er zuerst daraus entfernt.

Node.insertBefore(newChild, refChild)

Fügt einen neuen Kindknoten vor einem vorhandenen Kindknoten ein. refChild muss ein Kindknoten dieses Knotens sein, sonst wird NotFoundErr ausgelöst. Zurückgegeben wird newChild. Ist refChild None, wird newChild am Ende der Liste der Kindknoten eingefügt.

Node.removeChild(oldChild)

Entfernt einen Kindknoten. oldChild muss ein Kindknoten dieses Knotens sein, sonst wird NotFoundErr ausgelöst. Bei Erfolg wird oldChild zurückgegeben. Wird oldChild nicht weiter verwendet, sollte seine Methode unlink() aufgerufen werden.

Node.replaceChild(newChild, oldChild)

Ersetzt einen vorhandenen Knoten durch einen neuen. oldChild muss ein Kindknoten dieses Knotens sein, sonst wird NotFoundErr ausgelöst.

Node.normalize()

Fügt benachbarte Textknoten zusammen, sodass jeder zusammenhängende Text in einer einzigen Text-Instanz liegt. Für viele Anwendungen wird die Verarbeitung von Text aus einem DOM-Baum dadurch einfacher.

Node.cloneNode(deep)

Klont diesen Knoten. Setzt man deep, werden alle Kindknoten mitgeklont. Zurückgegeben wird der Klon.

NodeList-Objekte

A NodeList represents a sequence of nodes. These objects are used in two ways in the DOM Core recommendation: an Element object provides one as its list of child nodes, and the getElementsByTagName() and getElementsByTagNameNS() methods of Element return objects with this interface to represent query results.

NodeList erbt nicht von Node.

Die Empfehlung DOM Level 2 legt für diese Objekte eine Methode und ein Attribut fest:

NodeList.item(i)

Gibt das i-te Element der Folge zurück oder None, wenn i außerhalb des Bereichs liegt. Negative Indizes werden nicht unterstützt.

NodeList.length

Die Anzahl der Knoten in der Folge.

Zusätzlich verlangt die Python-DOM-Schnittstelle etwas Unterstützung darüber hinaus, damit sich NodeList-Objekte als Python-Sequenzen verwenden lassen. Alle NodeList-Umsetzungen müssen __len__() und __getitem__() unterstützen. Damit lässt sich über die NodeList in for-Anweisungen iterieren, und die integrierte Funktion len() arbeitet richtig.

Erlaubt eine DOM-Umsetzung, das Dokument zu ändern, muss die NodeList-Umsetzung auch die Methoden __setitem__() und __delitem__() unterstützen.

DocumentType-Objekte

Angaben zu den Notationen und Entitäten, die ein Dokument deklariert – einschließlich der externen Teilmenge, sofern der Parser sie verwendet und die Angaben liefern kann –, stehen an einem DocumentType-Objekt. Der DocumentType eines Dokuments steht im Attribut doctype des Document-Objekts. Hat das Dokument keine DOCTYPE-Deklaration, ist sein doctype-Attribut None statt einer Instanz dieser Schnittstelle.

DocumentType ist eine Spezialisierung von Node und ergänzt die folgenden Attribute:

DocumentType.publicId

Der öffentliche Identifikator der externen Teilmenge der Dokumenttypdefinition oder None, wenn die DOCTYPE-Deklaration ihn nicht angibt.

DocumentType.systemId

Der System-Identifikator – eine URI – der externen Teilmenge der Dokumenttypdefinition oder None, wenn die DOCTYPE-Deklaration ihn nicht angibt.

DocumentType.internalSubset

Eine Zeichenkette mit der vollständigen internen Teilmenge des Dokuments, ohne die Klammern, die die Teilmenge einschließen. Hat das Dokument keine interne Teilmenge, sollte der Wert None sein.

DocumentType.name

Der Name des Wurzelelements, wie ihn die DOCTYPE-Deklaration angibt, sofern vorhanden.

DocumentType.entities

Eine NamedNodeMap von Entity-Knoten mit den Definitionen externer Entitäten. Ist ein Entitätsname mehrfach definiert, wird nur die erste Definition geliefert; die übrigen werden übergangen, wie es die XML-Empfehlung verlangt. Der Wert kann None sein, wenn der Parser die Angaben nicht liefert oder keine Entitäten definiert sind.

DocumentType.notations

Eine NamedNodeMap von Notation-Knoten mit den Definitionen der Notationen. Ist ein Notationsname mehrfach definiert, wird nur die erste Definition geliefert; die übrigen werden übergangen, wie es die XML-Empfehlung verlangt. Der Wert kann None sein, wenn der Parser die Angaben nicht liefert oder keine Notationen definiert sind.

Document-Objekte

Ein Document stellt ein gesamtes XML-Dokument dar, samt seinen Elementen, Attributen, Verarbeitungsanweisungen, Kommentaren und so weiter. Denk daran, dass es Eigenschaften von Node erbt.

Document.documentElement

Das eine und einzige Wurzelelement des Dokuments.

Document.doctype

Der DocumentType-Knoten des Dokuments oder None. Dieses Attribut ist nur lesbar.

Document.implementation

Das DOMImplementation-Objekt, das dieses Dokument erzeugt hat. Dieses Attribut ist nur lesbar.

Document.strictErrorChecking

Ob die Fehlerprüfung erzwungen wird.

Document.documentURI

Der Ort des Dokuments oder None, wenn er unbekannt ist.

Document.createDocumentFragment()

Erzeugt einen leeren DocumentFragment-Knoten und gibt ihn zurück.

Document.createCDATASection(data)

Erzeugt einen CDATASection-Knoten mit dem Inhalt data und gibt ihn zurück.

Document.importNode(importedNode, deep)

Gibt eine Kopie von importedNode zurück, die zu diesem Dokument gehört. Der ursprüngliche Knoten wird nicht aus seinem Dokument entfernt. Ist deep wahr, werden auch die Nachkommen des Knotens kopiert.

Document.createElement(tagName)

Erzeugt einen neuen Elementknoten und gibt ihn zurück. Beim Erzeugen wird das Element nicht in das Dokument eingefügt; das musst du ausdrücklich mit einer der anderen Methoden tun, etwa insertBefore() oder appendChild().

Document.createElementNS(namespaceURI, tagName)

Erzeugt ein neues Element mit Namensraum und gibt es zurück. tagName darf ein Präfix haben. Beim Erzeugen wird das Element nicht in das Dokument eingefügt; das musst du ausdrücklich mit einer der anderen Methoden tun, etwa insertBefore() oder appendChild().

Document.createTextNode(data)

Erzeugt einen Textknoten mit den als Parameter übergebenen Daten und gibt ihn zurück. Wie die anderen Erzeugungsmethoden fügt auch diese den Knoten nicht in den Baum ein.

Document.createComment(data)

Erzeugt einen Kommentarknoten mit den als Parameter übergebenen Daten und gibt ihn zurück. Wie die anderen Erzeugungsmethoden fügt auch diese den Knoten nicht in den Baum ein.

Document.createProcessingInstruction(target, data)

Erzeugt einen Knoten für eine Verarbeitungsanweisung mit den als Parameter übergebenen Werten target und data und gibt ihn zurück. Wie die anderen Erzeugungsmethoden fügt auch diese den Knoten nicht in den Baum ein.

Document.createAttribute(name)

Erzeugt einen Attributknoten und gibt ihn zurück. Diese Methode ordnet den Attributknoten keinem bestimmten Element zu. Um die neu erzeugte Attributinstanz zu verwenden, musst du setAttributeNode() am passenden Element-Objekt aufrufen.

Document.createAttributeNS(namespaceURI, qualifiedName)

Erzeugt einen Attributknoten mit Namensraum und gibt ihn zurück. tagName darf ein Präfix haben. Diese Methode ordnet den Attributknoten keinem bestimmten Element zu. Um die neu erzeugte Attributinstanz zu verwenden, musst du setAttributeNode() am passenden Element-Objekt aufrufen.

Document.getElementById(id)

Gibt das Element mit der angegebenen ID zurück oder None. Durchsucht werden nur Attribute, die in der DTD oder über Element.setIdAttribute() als Typ ID deklariert sind.

Document.getElementsByTagName(tagName)

Sucht alle Nachkommen – unmittelbare Kindknoten, deren Kindknoten und so weiter – mit einem bestimmten Elementtypnamen.

Document.getElementsByTagNameNS(namespaceURI, localName)

Sucht alle Nachkommen – unmittelbare Kindknoten, deren Kindknoten und so weiter – mit einer bestimmten Namensraum-URI und einem bestimmten lokalen Namen. Der lokale Name ist der Teil des Namensraums nach dem Präfix.

Document.renameNode(n, namespaceURI, name)

Benennt den Element- oder Attributknoten n um und gibt ihn zurück. namespaceURI ist die neue Namensraum-URI oder EMPTY_NAMESPACE, wenn der Knoten zu keinem Namensraum gehört. name ist der neue qualifizierte Name.

Löst WrongDocumentErr aus, wenn n von einem anderen Dokument erzeugt wurde, und NotSupportedErr, wenn es weder ein Element noch ein Attribut ist.

Element-Objekte

Element ist eine Unterklasse von Node und erbt damit alle Attribute dieser Klasse.

Element.tagName

Der Name des Elementtyps. In einem Dokument mit Namensräumen kann er Doppelpunkte enthalten. Der Wert ist eine Zeichenkette.

Element.setIdAttribute(name)

Deklariert das Attribut name als Typ ID, sodass das Element über Document.getElementById() gefunden wird. Löst NotFoundErr aus, wenn das Element kein solches Attribut hat.

Element.setIdAttributeNS(namespaceURI, localName)

Dasselbe wie setIdAttribute(), aber für ein Attribut, das über seine Namensraum-URI und seinen lokalen Namen angegeben wird.

Element.setIdAttributeNode(idAttr)

Dasselbe wie setIdAttribute(), aber für einen bereits abgerufenen Attributknoten.

Element.getElementsByTagName(tagName)

Dasselbe wie die entsprechende Methode der Klasse Document.

Element.getElementsByTagNameNS(namespaceURI, localName)

Dasselbe wie die entsprechende Methode der Klasse Document.

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 namespaceURI und localName hat.

Element.getAttribute(name)

Gibt den Wert des Attributs mit dem Namen name als Zeichenkette zurück. Gibt es kein solches Attribut, wird eine leere Zeichenkette zurückgegeben, als hätte das Attribut keinen Wert.

Element.getAttributeNode(attrname)

Gibt den Attr-Knoten des Attributs mit dem Namen attrname zurück.

Element.getAttributeNS(namespaceURI, localName)

Gibt den Wert des Attributs mit namespaceURI und localName als Zeichenkette zurück. Gibt es kein solches Attribut, wird eine leere Zeichenkette zurückgegeben, als hätte das Attribut keinen Wert.

Element.getAttributeNodeNS(namespaceURI, localName)

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

Element.removeAttribute(name)

Entfernt ein Attribut über seinen Namen.

Element.removeAttributeNode(oldAttr)

Entfernt oldAttr aus der Attributliste und gibt es zurück, sofern es vorhanden ist. Ist oldAttr nicht vorhanden, wird NotFoundErr ausgelöst.

Element.removeAttributeNS(namespaceURI, localName)

Entfernt ein Attribut über seinen Namen. Beachte, dass dabei ein localName verwendet wird und kein qname.

Element.setAttribute(name, value)

Setzt einen Attributwert aus einer Zeichenkette.

Element.setAttributeNode(newAttr)

Fügt dem Element einen neuen Attributknoten hinzu und ersetzt dabei nötigenfalls ein vorhandenes Attribut, wenn das Attribut name übereinstimmt. Kommt es zu einer Ersetzung, wird der alte Attributknoten zurückgegeben. Ist newAttr schon in Verwendung, wird InuseAttributeErr ausgelöst.

Element.setAttributeNodeNS(newAttr)

Fügt dem Element einen neuen Attributknoten hinzu und ersetzt dabei nötigenfalls ein vorhandenes Attribut, wenn die Attribute namespaceURI und localName übereinstimmen. Kommt es zu einer Ersetzung, wird der alte Attributknoten zurückgegeben. Ist newAttr schon in Verwendung, wird InuseAttributeErr ausgelöst.

Element.setAttributeNS(namespaceURI, qname, value)

Setzt einen Attributwert aus einer Zeichenkette, zu gegebenem namespaceURI und qname. Beachte, dass ein qname der gesamte Attributname ist – anders als oben.

Attr-Objekte

Attr erbt von Node und damit alle seine Attribute.

Attributknoten gehören nicht zum Dokumentbaum. Sie liegen in der attributes-Abbildung eines Elements und nicht unter seinen Kindknoten, und parentNode, previousSibling und nextSibling sind bei ihnen immer None.

Attr.name

Der Name des Attributs. In einem Dokument mit Namensräumen kann er einen Doppelpunkt enthalten.

Attr.localName

Der Teil des Namens nach dem Doppelpunkt, sofern es einen gibt, sonst der gesamte Name. Dieses Attribut ist nur lesbar.

Attr.prefix

Der Teil des Namens vor dem Doppelpunkt, sofern es einen gibt, sonst die leere Zeichenkette.

Attr.isId

Ob dieses Attribut den Typ ID hat, weil es entweder in der DTD so deklariert ist oder weil Element.setIdAttribute() verwendet wurde. Dieses Attribut ist nur lesbar.

Attr.ownerElement

Der Element-Knoten, zu dem dieses Attribut gehört, oder None, wenn es nicht verwendet wird. Dieses Attribut ist nur lesbar.

Attr.specified

Ob der Wert des Attributs im Dokument ausdrücklich gesetzt wurde, im Gegensatz zu einem Vorgabewert aus der DTD. Dieses Attribut ist nur lesbar.

Attr.value

Der Textwert des Attributs. 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 das Attribut an einem bestimmten Index zurück. In welcher Reihenfolge du die Attribute bekommst, ist beliebig, bleibt aber über die Lebensdauer eines DOM gleich. Jedes Element ist ein Attributknoten. Seinen Wert bekommst du über das Attribut value.

NamedNodeMap.getNamedItem(name)

Gibt den Knoten mit dem angegebenen name zurück oder None, wenn es keinen solchen Knoten gibt.

NamedNodeMap.getNamedItemNS(namespaceURI, localName)

Gibt den Knoten mit der angegebenen Namensraum-URI und dem angegebenen lokalen Namen zurück oder None, wenn es keinen solchen Knoten gibt.

NamedNodeMap.setNamedItem(node)

Fügt node der Abbildung hinzu, mit seinem name als Schlüssel. Gibt den Knoten zurück, den er ersetzt, oder None, wenn er keinen Knoten ersetzt.

NamedNodeMap.setNamedItemNS(node)

Fügt node der Abbildung hinzu, mit seiner Namensraum-URI und seinem lokalen Namen als Schlüssel. Gibt den Knoten zurück, den er ersetzt, oder None, wenn er keinen Knoten ersetzt.

NamedNodeMap.removeNamedItem(name)

Entfernt den Knoten mit dem angegebenen name und gibt ihn zurück. Löst NotFoundErr aus, wenn es keinen solchen Knoten gibt.

NamedNodeMap.removeNamedItemNS(namespaceURI, localName)

Entfernt den Knoten mit der angegebenen Namensraum-URI und dem angegebenen lokalen Namen und gibt ihn zurück. Löst NotFoundErr aus, wenn es keinen solchen Knoten gibt.

Du kannst an den Element-Objekten auch die standardisierte Methodenfamilie getAttribute*() verwenden.

DocumentFragment-Objekte

DocumentFragment ist ein leichtgewichtiger Behälter für Knoten und eine Unterklasse von Node. Wird es in den Dokumentbaum eingefügt, werden an seiner Stelle seine Kindknoten eingefügt und es bleibt leer zurück.

CharacterData-Objekte

CharacterData stellt textartige Daten im XML-Dokument dar. Es ist eine Unterklasse von Node und die Basisklasse von Text, CDATASection und Comment. Solche Knoten können keine Kindknoten haben.

CharacterData.data

Der Inhalt des Knotens als Zeichenkette.

CharacterData.length

Die Anzahl der Zeichen in data. Dieses Attribut ist nur lesbar.

CharacterData.substringData(offset, count)

Gibt die Teilzeichenkette von data zurück, die count Zeichen ab offset umfasst.

CharacterData.appendData(arg)

Hängt die Zeichenkette arg an data an.

CharacterData.insertData(offset, arg)

Fügt die Zeichenkette arg in data an offset ein.

CharacterData.deleteData(offset, count)

Entfernt count Zeichen aus data ab offset.

CharacterData.replaceData(offset, count, arg)

Ersetzt count Zeichen von data ab offset durch die Zeichenkette arg.

Comment-Objekte

Comment stellt einen Kommentar im XML-Dokument dar. Es ist eine Unterklasse von CharacterData.

Comment.data

Der Inhalt des Kommentars als Zeichenkette. Das Attribut enthält alle Zeichen zwischen dem einleitenden <!-- und dem abschließenden -->, diese selbst aber nicht.

Text- und CDATASection-Objekte

Die Schnittstelle Text stellt Text im XML-Dokument dar. Unterstützen Parser und DOM-Umsetzung die XML-Erweiterung des DOM, werden Textteile in markierten CDATA-Abschnitten in CDATASection-Objekten abgelegt. Die beiden Schnittstellen sind gleich, liefern aber verschiedene Werte für das Attribut nodeType.

Text erweitert die Schnittstelle CharacterData, und CDATASection erweitert Text.

Text.data

Der Inhalt des Textknotens als Zeichenkette.

Text.wholeText

Der Text aller Text-Knoten, die logisch an diesen Knoten angrenzen, in der Reihenfolge des Dokuments aneinandergefügt. Dieses Attribut ist nur lesbar.

Text.replaceWholeText(content)

Ersetzt den Text aller Text-Knoten, die logisch an diesen Knoten angrenzen, durch content und entfernt die übrigen Knoten. Gibt diesen Knoten zurück oder None, wenn content leer ist.

Text.splitText(offset)

Teilt diesen Knoten an offset in zwei Knoten, behält den ersten Teil in diesem Knoten und gibt einen neuen Geschwisterknoten mit dem Rest zurück.

Bemerkung

Dass ein CDATASection-Knoten verwendet wird, bedeutet nicht, dass der Knoten einen vollständigen markierten CDATA-Abschnitt darstellt, sondern nur, dass sein Inhalt Teil eines CDATA-Abschnitts war. Ein einzelner CDATA-Abschnitt kann im Dokumentbaum durch mehrere Knoten dargestellt werden. Es gibt keine Möglichkeit festzustellen, ob zwei benachbarte CDATASection-Knoten zu verschiedenen markierten CDATA-Abschnitten gehören.

ProcessingInstruction-Objekte

Stellt eine Verarbeitungsanweisung im XML-Dokument dar. Erbt von der Schnittstelle Node und kann keine Kindknoten haben.

ProcessingInstruction.target

Der Inhalt der Verarbeitungsanweisung bis zum ersten Leerraumzeichen. Dieses Attribut ist nur lesbar.

ProcessingInstruction.data

Der Inhalt der Verarbeitungsanweisung nach dem ersten Leerraumzeichen.

Entity-Objekte

Entity stellt eine geparste oder nicht geparste Entität dar, die in der DTD deklariert ist. Es ist eine Unterklasse von Node. Entitätsknoten liegen in DocumentType.entities und lassen sich nicht in den Dokumentbaum einfügen. Der Name der Entität ist ihr nodeName.

Entity.publicId

Der öffentliche Identifikator der Entität oder None, wenn er nicht angegeben ist. Dieses Attribut ist nur lesbar.

Entity.systemId

Der System-Identifikator der Entität oder None, wenn er nicht angegeben ist. Dieses Attribut ist nur lesbar.

Entity.notationName

Der Name der Notation bei einer nicht geparsten Entität oder None bei einer geparsten Entität. Dieses Attribut ist nur lesbar.

Notation-Objekte

Notation stellt eine Notation dar, die in der DTD deklariert ist. Es ist eine Unterklasse von Node und kann keine Kindknoten haben. Notationsknoten liegen in DocumentType.notations und lassen sich nicht in den Dokumentbaum einfügen. Der Name der Notation ist ihr nodeName.

Notation.publicId

Der öffentliche Identifikator der Notation oder None, wenn er nicht angegeben ist. Dieses Attribut ist nur lesbar.

Notation.systemId

Der System-Identifikator der Notation oder None, wenn er nicht angegeben ist. Dieses Attribut ist nur lesbar.

Ausnahmen

Die Empfehlung DOM Level 2 legt eine einzige Ausnahme, DOMException, und eine Reihe von Konstanten fest, mit denen Anwendungen feststellen können, welche Art von Fehler aufgetreten ist. DOMException-Instanzen tragen ein Attribut code mit dem passenden Wert für die jeweilige Ausnahme.

Die Python-DOM-Schnittstelle stellt diese Konstanten bereit, erweitert aber zugleich den Satz der Ausnahmen, sodass es für jeden vom DOM festgelegten Ausnahmecode eine eigene Ausnahme gibt. Die Umsetzungen müssen die passende eigene Ausnahme auslösen. Jede davon trägt den passenden Wert für das Attribut code.

exception xml.dom.DOMException

Basisausnahmeklasse für alle einzelnen DOM-Ausnahmen. Diese Ausnahmeklasse lässt sich nicht unmittelbar instanzieren.

exception xml.dom.DomstringSizeErr

Wird ausgelöst, wenn ein angegebener Textbereich nicht in eine Zeichenkette passt. In den Python-DOM-Umsetzungen ist keine Verwendung bekannt, aus DOM-Umsetzungen, die nicht in Python geschrieben sind, kann die Ausnahme aber kommen.

exception xml.dom.HierarchyRequestErr

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

exception xml.dom.IndexSizeErr

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

exception xml.dom.InuseAttributeErr

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

exception xml.dom.InvalidAccessErr

Wird ausgelöst, wenn ein Parameter oder eine Operation am zugrunde liegenden Objekt nicht unterstützt wird.

exception xml.dom.InvalidCharacterErr

Diese Ausnahme wird ausgelöst, wenn ein Zeichenkettenparameter ein Zeichen enthält, das die XML-1.0-Empfehlung im jeweiligen Zusammenhang nicht erlaubt. Versucht man zum Beispiel, einen Element-Knoten mit einem Leerzeichen im Elementtypnamen zu erzeugen, wird dieser Fehler ausgelöst.

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 brauchbar ist.

exception xml.dom.NamespaceErr

Wird ausgelöst, wenn versucht wird, ein Objekt auf eine Weise zu ändern, die die Empfehlung Namespaces in XML nicht erlaubt.

exception xml.dom.NotFoundErr

Ausnahme, wenn ein Knoten im angesprochenen Zusammenhang nicht vorhanden ist. NamedNodeMap.removeNamedItem() löst sie zum Beispiel aus, wenn der übergebene Knoten nicht in der Abbildung vorkommt.

exception xml.dom.NotSupportedErr

Wird ausgelöst, wenn die Umsetzung den verlangten Objekttyp oder die verlangte Operation nicht unterstützt.

exception xml.dom.NoDataAllowedErr

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

exception xml.dom.NoModificationAllowedErr

Wird ausgelöst, wenn versucht wird, ein Objekt zu ändern, bei dem Änderungen nicht erlaubt sind, etwa bei nur lesbaren Knoten.

exception xml.dom.SyntaxErr

Wird ausgelöst, wenn eine ungültige oder unerlaubte Zeichenkette angegeben wird.

exception xml.dom.ValidationErr

Wird ausgelöst, wenn eine Operation das Dokument im Sinne der teilweisen Gültigkeit ungültig machen würde. In den Python-DOM-Umsetzungen ist keine Verwendung bekannt, aus DOM-Umsetzungen, die nicht in Python geschrieben sind, kann die Ausnahme aber kommen.

exception xml.dom.WrongDocumentErr

Wird ausgelöst, wenn ein Knoten in ein anderes Dokument eingefügt wird als das, zu dem er derzeit gehört, und die Umsetzung es nicht unterstützt, den Knoten von einem Dokument in das andere zu überführen.

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

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

Konformität

Dieser Abschnitt beschreibt die Anforderungen an die Konformität und die Beziehungen zwischen der Python-DOM-API, den DOM-Empfehlungen des W3C und der OMG-IDL-Abbildung für Python.

Typabbildung

Die IDL-Typen der DOM-Spezifikation werden gemäß der folgenden Tabelle auf Python-Typen abgebildet.

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

Zugriffsmethoden

Die Abbildung von OMG IDL auf Python legt Zugriffsfunktionen für attribute-Deklarationen in IDL weitgehend so fest, wie es die Java-Abbildung tut. Bildet man die IDL-Deklarationen

readonly attribute string someValue;
         attribute string anotherValue;

ab, so ergeben sich drei Zugriffsfunktionen: eine „get“-Methode für someValue (_get_someValue()) sowie „get“- und „set“-Methoden für anotherValue (_get_anotherValue() und _set_anotherValue()). Insbesondere verlangt die Abbildung nicht, dass die IDL-Attribute wie gewöhnliche Python-Attribute zugänglich sind: object.someValue muss nicht funktionieren und darf einen AttributeError auslösen.

Die Python-DOM-API verlangt dagegen schon, dass der gewöhnliche Attributzugriff funktioniert. Die typischen Surrogate, die Python-IDL-Compiler erzeugen, funktionieren daher wahrscheinlich nicht, und auf der Client-Seite können Hüllobjekte nötig sein, wenn die DOM-Objekte über CORBA angesprochen werden. Für CORBA-DOM-Clients heißt das etwas zusätzliche Überlegung. Wer Erfahrung damit hat, DOM aus Python über CORBA zu verwenden, hält das aber nicht für ein Problem. Attribute, die als readonly deklariert sind, schränken den Schreibzugriff nicht in allen DOM-Umsetzungen ein.

In der Python-DOM-API sind Zugriffsfunktionen nicht erforderlich. Werden sie bereitgestellt, sollten sie die Form haben, die die Python-IDL-Abbildung festlegt; sie gelten aber als unnötig, da die Attribute aus Python unmittelbar zugänglich sind. „Set“-Zugriffsfunktionen sollten für readonly-Attribute nie bereitgestellt werden.

Die IDL-Definitionen geben die Anforderungen der W3C-DOM-API nicht vollständig wieder, etwa die Vorstellung, dass bestimmte Objekte „lebend“ sind – zum Beispiel der Rückgabewert von getElementsByTagName(). Die Python-DOM-API verlangt nicht, dass Umsetzungen solche Anforderungen durchsetzen.