xml.dom --- The Document Object Model API

Code source: Lib/xml/dom/__init__.py

---

Le Document Object Model, ou "DOM," est une API inter-langage du World Wide Web Consortium (W3C) pour accéder et modifier les documents XML. Une implémentation DOM présente le document XML comme un arbre ou autorise le code client à construire une telle structure depuis zéro. Il permet alors d'accéder à la structure à l'aide d'un ensemble d'objet qui fournissent des interfaces bien connues.

Le DOM est extrêmement utile pour les applications à accès aléatoire. SAX ne vous permet de visualiser qu'un seul morceau du document à la fois. Si vous regardez un élément SAX, vous n'avez pas accès à un autre. Si vous regardez un nœud de texte, vous n'avez pas accès à un élément parent. Lorsque vous écrivez une application SAX, vous devez suivre la position de votre programme dans le document quelque part dans votre propre code. SAX ne le fait pas pour vous. De plus, si vous devez examiner un nœud plus lus loin dans le document XML, vous n'avez pas de chance.

Il est tout simplement impossible d'implémenter certains algorithmes avec un modèle évènementiel, sans un accès à un arbre. Bien sûr, vous pourriez construire vous même un arbre à partir des événements SAX mais DOM vous permet d'éviter d'écrire ce code. Le DOM est représentation standard en arbre pour des données XML.

Le DOM (Document Object Model) est défini par le W3C en étapes ou "levels" (niveaux) selon leur terminologie. Le couplage de l'API de Python est essentiellement basée sur la recommandation DOM Level 2.

Typiquement, les applications DOM commencent par analyser du XML dans du DOM. Comment cela doit être exposé n'est absolument pas décrit par DOM Level 1 et Level 2 ne fournit que des améliorations limités. Il existe une classe DOMImplementation qui fournit un accès à des méthodes de création de Document mais il n'y a pas de moyen d'accéder à un lecteur/analyseur/constructeur de document de façon indépendante de l'implémentation. Il n'est pas également très bien définis comment accéder à ces méthodes sans un objet Document. En Python, chaque implémentation fournira une fonction getDOMImplementation() . DOM Level 3 ajoute une spécification Load/Store (charge/stocke) qui définie une interface pour le lecteur mais qui n'est pas disponible dans la bibliothèque standard de Python.

Une fois que vous avez un objet document DOM, vous pouvez accéder aux parties de votre document XML à travers ses méthodes et propriétés. Ces propriétés sont définis dans les spécifications DOM ; cette portion du manuel de références décrit l'interprétation des ces spécifications en Python.

Les spécifications fournies par le W3C définissent les API DOM pour Java, ECMAScript, et OMG IDL. Les correspondances de Python définies ici sont basées pour une grande part sur la version IDL de la spécification mais une conformité stricte n'est pas requise (bien que ces implémentations soient libre d'implémenter le support strict des correspondances de IDL). Voir la section Conformité pour une discussion détaillée des pré-requis des correspondances.

Voir aussi

Document Object Model (DOM) Level 2 Specification

La recommandation W3C sur laquelle l'API DOM de Python est basée.

Spécification Level 1 Document Object Model (DOM)

La recommandation du W3C pour le DOM supporté par xml.dom.minidom.

Python Language Mapping Specification

Ceci spécifies les correspondances depuis OMG IDL vers Python.

Contenu du module

Le xml.dom contient les fonctions suivantes :

xml.dom.registerDOMImplementation(name, factory)

Enregistre la fonction factory avec le nom name. La fonction factory doit renvoyer un objet qui implémente l'interface de DOMImplementation. La fonction factory peut renvoyer le même objet à chaque fois ou un nouveau à chaque appel en accord avec les spécificités de l'implémentation (Par exemple si l'implémentation supporte certaines personnalisations).

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

Return a suitable DOM implementation. The name is either well-known, the module name of a DOM implementation, or None. If it is not None, imports the corresponding module and returns a DOMImplementation object if the import succeeds. If no name is given, and if the environment variable PYTHON_DOM is set, this variable is used to find the implementation. The only well-known name in the standard library is 'minidom', for xml.dom.minidom.

If name is not given, this examines the available implementations to find one with the required feature set. If no implementation can be found, raise an ImportError. The features list must be a sequence of (feature, version) pairs which are passed to the hasFeature() method on available DOMImplementation objects.

Quelques constantes pratiques sont également fournies :

xml.dom.EMPTY_NAMESPACE

The value used to indicate that no namespace is associated with a node in the DOM. This is typically found as the namespaceURI of a node, or used as the namespaceURI parameter to a namespaces-specific method.

xml.dom.XML_NAMESPACE

L'URI de l'espace de noms associé avec le préfixe réservé xml comme défini par Namespaces in XML (section 4).

xml.dom.XMLNS_NAMESPACE

L'URI de l'espace de noms pour la déclaration des espaces de noms, tel que défini par Document Object Model (DOM) Level 2 Core Specification (section 1.1.8).

xml.dom.XHTML_NAMESPACE

L'URI de l'espace de noms XHTML tel que défini par XHTML 1.0: The Extensible HyperText Markup Language (section 3.1.1).

In addition, xml.dom contains a base Node class and the DOM exception classes. The Node class provided by this module does not implement any of the methods or attributes defined by the DOM specification; concrete DOM implementations must provide those. The Node class provided as part of this module does provide the constants used for the nodeType attribute on concrete Node objects; they are located within the class rather than at the module level to conform with the DOM specifications.

Objets dans le DOM

La documentation finale pour le DOM est la spécification DOM du W3C.

The names documented in this section are DOM interfaces. With the exception of Node and the exception classes, they are not provided by the xml.dom module itself, but by concrete DOM implementations, such as xml.dom.minidom.

Notez que les attributs DOM peuvent également être manipulés comme des nœuds au lieu de simples chaînes. Il est relativement rare que vous ayez besoin de faire cela, cependant, cet usage n'est pas encore documenté.

Interface	Section	Objectif
DOMImplementation	Objets DOMImplementation	Interface de l'implémentation sous-jacente.
Node	Objets nœuds	Interface de base pour la majorité des objets dans un document.
NodeList	Objet NodeList	Interface pour une séquence de nœuds.
DocumentType	Objets DocumnentType	Informations sur les déclarations nécessaires au traitement d'un document.
Document	Objets Document	Objet représentant un document entier.
Element	Objets Elements	Nœuds éléments dans la hiérarchie d'un document.
Attr	Objets Attr	Valeur des nœuds attributs sur dans des nœuds éléments.
Comment	Objets Comment	Représentation des commentaires dans le fichier source du document.
Text	Objets Text et CDATASection	Nœud contenant un contenu texte du document.
ProcessingInstruction	Objets ProcessingInstruction	Représentation des Processing Instructions.

Une Section additionnelle décrit les exceptions définis pour travailler avec le DOM en Python.

Objets DOMImplementation

L'interface DOMImplementation fournit un moyen pour les applications de déterminer la disponibilité de fonctionnalités particulières dans le DOM qu'elles utilisent. DOM Level 2 ajoute la capacité de créer des nouveaux objets Document et DocumentType utilisant également DOMImplementation.

DOMImplementation.hasFeature(feature, version)

Renvoie True si la fonctionnalité identifiée par le couple de chaînes feature et version est implémentée.

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

Renvoie un nouvel objet Document (la racine du DOM), avec un objet fils Element ayant les namespaceUri et qualifiedName passés en paramètre. Le doctype doit être un objet DocumentType créé par createDocumentType() ou None. Dans l'API DOM de Python, les deux premiers arguments peuvent également être à None de manière à indiquer qu'aucun enfant Element ne soit crée.

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

Renvoie un nouvel objet DocumentType qui encapsule les chaînes qualifiedName, publicId, et systemId passées en paramètre représentant les informations contenues dans dans la déclaration du document XML.

Objets nœuds

Tous les composants d'un document XML sont des sous-classes de Node.

Only nodes of the following types can have children, and only children of the listed types:

Document

at most one Element, at most one DocumentType, ProcessingInstruction and Comment

DocumentFragment and Element

Element, Text, CDATASection, ProcessingInstruction and Comment

Attr

Text

Nodes of other types cannot have children. Inserting a child of a not allowed type raises HierarchyRequestErr.

Node.nodeType

An integer representing the node type. Symbolic constants for the types are on the Node object. This is a read-only attribute.

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

Integer constants for the possible values of the nodeType attribute.

Node.parentNode

Le parent du nœud courant ou None dans le cas du nœud document. La valeur est toujours un objet Node ou None. Pour les nœuds Element, ce sera le parent de l'élément sauf si l'élément est la racine, dans ce cas ce sera l'objet Document. Pour les nœuds Attr, cela sera toujours None. Ceci est un attribut en lecture seule.

Node.attributes

Un objet NamedNodeMap d'objet attributs. Seulement les éléments ayant des valeurs seront listés, les autres renverront None pour cet attribut. Cet attribut est en lecture seule.

Node.previousSibling

Le nœud avec le même parent qui précède immédiatement le nœud courant. Par exemple, l'élément avec la balise fermente qui est juste avant la balise ouvrante de l'élément self. Naturellement, les documents XML sont fait de plus que juste des éléments ; donc le previous sibling peut être du texte, un commentaire ou autre chose. Si le nœud courant est le premier fils du parent, cet attribut vaudra None. Cet attribut est en lecture seule.

Node.nextSibling

Le nœud qui suit immédiatement le nœud courant dans le même parent. Voir également previousSibling. Si ce nœud est le dernier de son parent, alors l'attribut sera None. Cet attribut est en lecture seule.

Node.childNodes

A NodeList of the children of this node. If the node has no children, the list is empty. This is a read-only attribute.

Node.firstChild

S'il y a des fils, premier fils du nœud courant, sinon None. Cet attribut est en lecture seule.

Node.lastChild

S'il y a des fils, le dernier nœud fils du nœud courant. Sinon None. Cet attribut est en lecture seule.

Node.localName

The part of the tagName following the colon if there is one, else the entire tagName. The value is a string.

Node.prefix

The part of the tagName preceding the colon if there is one, else the empty string. The value is a string, or None.

Node.namespaceURI

L'espace de noms associé (namespace en anglais) au nom de l'élément. Cette valeur est une chaîne ou None. Cet attribut est en lecture seule.

Node.ownerDocument

The Document object to which this node belongs, or None for a document itself. This is a read-only attribute.

Node.isSupported(feature, version)

Return whether the DOM implementation supports a particular feature, as DOMImplementation.hasFeature() does.

Node.setUserData(key, data, handler)

Associate data with key on this node and return the data previously associated with key, or None. If data is None, the association is removed. handler is called when the node is cloned, imported, renamed or deleted; pass None if no notification is needed.

Node.getUserData(key)

Return the data associated with key on this node by setUserData(), or None.

Node.nodeName

The name of this node, depending on its type; see the table below. You can always get the information you would get here from another property such as the tagName property for elements or the name property for attributes. This is a read-only attribute.

Node.nodeValue

The value of this node, depending on its type; see the table below. The value is a string or None.

The values of nodeName and nodeValue for each node type are:

Node type	nodeName	nodeValue
Attr	name	value
CDATASection	'#cdata-section'	the content
Comment	'#comment'	the content
Document	'#document'	None
DocumentFragment	'#document-fragment'	None
DocumentType	name	None
Element	tagName	None
Entity	the name of the entity	None
Notation	the name of the notation	None
ProcessingInstruction	target	data
Text	'#text'	the content

Node.hasAttributes()

Renvoie True si le nœud a des attributs.

Node.hasChildNodes()

Renvoie True si le nœud a des nœuds fils.

Node.isSameNode(other)

Renvoie True si other fait référence au même nœud que le nœud courant. Ceci est particulièrement pratique pour une implémentation de DOM qui utilise un ou des mandataires dans son architecture (car plus d'un objet peut se référer au même nœud).

Note

Ceci est basé sur l'API proposé par * DOM Level 3* qui est toujours à l'étape "working draft" mais cette interface particulière ne parait pas controversée. Les changement du W3C n'affecteront pas nécessairement cette méthode dans l'interface DOM de Python. (bien que toute nouvelle API W3C à cet effet soit également supportée).

Node.appendChild(newChild)

Ajoute un nouveau nœud fils à ce nœud à la fin de la liste des fils renvoyant newChild. Si ce nœud est déjà dans l'arbre, il sera d'abord retiré.

Node.insertBefore(newChild, refChild)

Insert a new child node before an existing child. It must be the case that refChild is a child of this node; if not, NotFoundErr is raised. newChild is returned. If refChild is None, it inserts newChild at the end of the children's list.

Node.removeChild(oldChild)

Remove a child node. oldChild must be a child of this node; if not, NotFoundErr is raised. oldChild is returned on success. If oldChild will not be used further, its unlink() method should be called.

Node.replaceChild(newChild, oldChild)

Replace an existing node with a new node. It must be the case that oldChild is a child of this node; if not, NotFoundErr is raised.

Node.normalize()

Jointe les nœuds texte adjacents de manière à ce que tous les segments de texte soient stockés dans une seule instance de Text. Ceci simplifie le traitement du texte d'un arbre DOM pour de nombreuses applications.

Node.cloneNode(deep)

Clone ce nœud. Positionner deep signifie que tous les nœuds fils seront également clonés. La méthode renvoi le clone.

Objet NodeList

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 Node return objects with this interface to represent query results.

NodeList does not inherit from Node.

La recommandation DOM Level 2 définit un attribut et une méthode pour ces objets :

NodeList.item(i)

Return the i'th item from the sequence, or None if i is out of range. Negative indices are not supported.

NodeList.length

Le nombre d'éléments dans la séquence.

En plus, l'interface DOM de Python requiert quelques ajouts supplémentaires pour permettre que les objet NodeList puissent être utilisés comme des séquences Python. Toutes les implémentations de NodeList doivent inclure le support de __len__() et de __getitem__() ; ceci permet l'itération sur NodeList avec l'instruction for et un support de la fonction native len().

Si une implémentation de DOM support les modifications du document, l'implémentation de NodeList doit également supporter les méthodes __setitem__() et __delitem__() .

Objets DocumnentType

Information about the notations and entities declared by a document (including the external subset if the parser uses it and can provide the information) is available from a DocumentType object. The DocumentType for a document is available from the Document object's doctype attribute; if there is no DOCTYPE declaration for the document, the document's doctype attribute will be set to None instead of an instance of this interface.

DocumentType est une spécialisation de Node et ajoute les attributs suivants :

DocumentType.publicId

The public identifier for the external subset of the document type definition, or None if the DOCTYPE declaration does not specify it.

DocumentType.systemId

The system identifier, a URI, for the external subset of the document type definition, or None if the DOCTYPE declaration does not specify it.

DocumentType.internalSubset

Un chaîne donnant le sous ensemble complet du document. Ceci n'inclut pas les chevrons qui englobe le sous ensemble. Si le document n'a pas de sous ensemble, cela devrait être None.

DocumentType.name

Le nom de l'élément racine donné dans la déclaration DOCTYPE si présente.

DocumentType.entities

This is a NamedNodeMap of Entity nodes giving the definitions of external entities. For entity names defined more than once, only the first definition is provided (others are ignored as required by the XML recommendation). This may be None if the information is not provided by the parser, or if no entities are defined.

DocumentType.notations

This is a NamedNodeMap of Notation nodes giving the definitions of notations. For notation names defined more than once, only the first definition is provided (others are ignored as required by the XML recommendation). This may be None if the information is not provided by the parser, or if no notations are defined.

Objets Document

Un Document représente un document XML en son entier, incluant les éléments qui le constitue, les attributs, les processing instructions, commentaires, etc. Rappelez vous qu'il hérite des propriété de Node.

Document.documentElement

Le seul et unique élément racine du document.

Document.doctype

The DocumentType node of the document, or None. This is a read-only attribute.

Document.implementation

The DOMImplementation object which created this document. This is a read-only attribute.

Document.strictErrorChecking

Whether error checking is enforced.

Document.documentURI

The location of the document, or None if it is unknown.

Document.createDocumentFragment()

Create and return an empty DocumentFragment node.

Document.createCDATASection(data)

Create and return a CDATASection node containing data.

Document.importNode(importedNode, deep)

Return a copy of importedNode which belongs to this document. The original node is not removed from its document. If deep is true, the descendants of the node are copied too.

Document.createElement(tagName)

Create and return a new element node. The element is not inserted into the document when it is created. You need to explicitly insert it with one of the other methods such as insertBefore() or appendChild().

Document.createElementNS(namespaceURI, tagName)

Create and return a new element with a namespace. The tagName may have a prefix. The element is not inserted into the document when it is created. You need to explicitly insert it with one of the other methods such as insertBefore() or appendChild().

Document.createTextNode(data)

Créé et renvoi un nœud texte contenant les data passées en paramètre. Comme pour les autres méthodes de création, la méthode n'insère pas le nœud dans l'arbre.

Document.createComment(data)

Créé et renvoi un nœud commentaire contenant les data passé en commentaire. Comme pour les autres méthodes de création, la méthode n'insère pas le nœud dans l'arbre.

Document.createProcessingInstruction(target, data)

Créé et retourne un nœud processing instruction contenant les target et data passés en paramètres. Comme pour les autres méthodes de création, la méthode n'insère pas le nœud dans l'arbre.

Document.createAttribute(name)

Create and return an attribute node. This method does not associate the attribute node with any particular element. You must use setAttributeNode() on the appropriate Element object to use the newly created attribute instance.

Document.createAttributeNS(namespaceURI, qualifiedName)

Create and return an attribute node with a namespace. The tagName may have a prefix. This method does not associate the attribute node with any particular element. You must use setAttributeNode() on the appropriate Element object to use the newly created attribute instance.

Document.getElementById(id)

Return the element with the given ID, or None. Only attributes declared as being of type ID in the DTD or by Element.setIdAttribute() are searched.

Document.getElementsByTagName(tagName)

Cherche tout les descendants (fils directs, fils de fils, etc.) avec un nom de balise particulier.

Document.getElementsByTagNameNS(namespaceURI, localName)

Cherche tous les descendants (fils directs, fils de fils, etc.) avec un namespace URI particulier et un localName. Le localName fait parti du namespace après le préfixe.

Document.renameNode(n, namespaceURI, name)

Rename the element or attribute node n and return it. namespaceURI is the new namespace URI, or EMPTY_NAMESPACE if the node does not belong to a namespace. name is the new qualified name.

Raise WrongDocumentErr if n was created by another document, and NotSupportedErr if it is neither an element nor an attribute.

Objets Elements

Element est une une sous classe de Node et donc hérite de tout les éléments de cette classe.

Element.tagName

Le nom de l'élément type. Dans un document utilisant des namespace, il pourrait y avoir des : dedans. La valeur est une chaîne.

Element.setIdAttribute(name)

Declare that the attribute name is of type ID, so that the element is found by Document.getElementById(). Raise NotFoundErr if the element has no such attribute.

Element.setIdAttributeNS(namespaceURI, localName)

The same as setIdAttribute(), but for an attribute specified by its namespace URI and local name.

Element.setIdAttributeNode(idAttr)

The same as setIdAttribute(), but for an already retrieved attribute node.

Element.getElementsByTagName(tagName)

Identique à la méthode équivalente de la classe Document.

Element.getElementsByTagNameNS(namespaceURI, localName)

Identique à la méthode équivalente de la classe Document.

Element.hasAttribute(name)

Renvoie True si l'élément a un attribut nommé name.

Element.hasAttributeNS(namespaceURI, localName)

Renvoie True si l'élément a un attribut nommé localName dans l'espace de noms namespaceURI.

Element.getAttribute(name)

Retourne la valeur de l'attribut nommé par name comme une chaîne. Si un tel attribue n'existe pas, une chaîne vide est retournée comme si l'attribut n'avait aucune valeur.

Element.getAttributeNode(attrname)

Retourne le nœud Attr pour l'attribut nommé par attrname.

Element.getAttributeNS(namespaceURI, localName)

Renvoi la valeur de l'attribut nommé par namespaceURI et localName comme une chaîne. Si un tel attribue n'existe pas, une chaîne vide est retournée comme si l'attribut n'avait aucune valeur.

Element.getAttributeNodeNS(namespaceURI, localName)

Renvoi la valeur de l'attribue comme un nœud étant donné namespaceURI et localName.

Element.removeAttribute(name)

Remove an attribute by name.

Element.removeAttributeNode(oldAttr)

Supprime et renvoi oldAttr de la liste des attributs si présent. Si oldAttr n'est pas présent, NotFoundErr est levée.

Element.removeAttributeNS(namespaceURI, localName)

Remove an attribute by name. Note that it uses a localName, not a qname.

Element.setAttribute(name, value)

Assigne la valeur à un attribut pour la chaîne.

Element.setAttributeNode(newAttr)

Add a new attribute node to the element, replacing an existing attribute if necessary if the name attribute matches. If a replacement occurs, the old attribute node will be returned. If newAttr is already in use, InuseAttributeErr will be raised.

Element.setAttributeNodeNS(newAttr)

Add a new attribute node to the element, replacing an existing attribute if necessary if the namespaceURI and localName attributes match. If a replacement occurs, the old attribute node will be returned. If newAttr is already in use, InuseAttributeErr will be raised.

Element.setAttributeNS(namespaceURI, qname, value)

Assigne la valeur d'un attribut depuis une chaîne étant donnée un namespaceURI et un qname. Notez que qname est le nom de l'attribut en entier. Ceci est différent d'au dessus.

Objets Attr

Attr hérite Node et donc hérite de tout ces attributs.

Attribute nodes are not part of the document tree. They are contained in the attributes map of an element, not in its children, and their parentNode, previousSibling and nextSibling are always None.

Attr.name

Le nom de l'attribut. Dans un document utilisant des namespaces, il pourra inclure un :.

Attr.localName

La partie du nom suivant le : s'il y en a un ou le nom entier sinon. Ceci est un attribut en lecture seule.

Attr.prefix

La partie du nom précédent le : s'il y en a un ou une chaîne vide.

Attr.isId

Whether this attribute is of type ID, either because it is declared as such in the DTD or because Element.setIdAttribute() was used. This is a read-only attribute.

Attr.ownerElement

The Element node to which this attribute belongs, or None if it is not used. This is a read-only attribute.

Attr.specified

Whether the value of the attribute was explicitly set in the document, as opposed to being defaulted from the DTD. This is a read-only attribute.

Attr.value

The text value of the attribute. This is a synonym for the nodeValue attribute.

Objets NameNodeMap

NamedNodeMap n'hérite pas de Node.

NamedNodeMap.length

La longueur de la liste d'attributs.

NamedNodeMap.item(index)

Return an attribute with a particular index. The order you get the attributes in is arbitrary but will be consistent for the life of a DOM. Each item is an attribute node. Get its value with the value attribute.

NamedNodeMap.getNamedItem(name)

Return the node with the given name, or None if there is no such node.

NamedNodeMap.getNamedItemNS(namespaceURI, localName)

Return the node with the given namespace URI and local name, or None if there is no such node.

NamedNodeMap.setNamedItem(node)

Add node to the map, using its name as the key. Return the node which it replaces, or None if it replaces no node.

NamedNodeMap.setNamedItemNS(node)

Add node to the map, using its namespace URI and local name as the key. Return the node which it replaces, or None if it replaces no node.

NamedNodeMap.removeNamedItem(name)

Remove and return the node with the given name. Raise NotFoundErr if there is no such node.

NamedNodeMap.removeNamedItemNS(namespaceURI, localName)

Remove and return the node with the given namespace URI and local name. Raise NotFoundErr if there is no such node.

You can also use the standardized getAttribute*() family of methods on the Element objects.

DocumentFragment Objects

DocumentFragment is a lightweight container of nodes. It is a subclass of Node. When it is inserted into the document tree, its children are inserted instead of it, and it becomes empty.

CharacterData Objects

CharacterData represents text-like data in the XML document. It is a subclass of Node, and the base class of Text, CDATASection and Comment. Such nodes cannot have child nodes.

CharacterData.data

The content of the node as a string.

CharacterData.length

The number of characters in data. This is a read-only attribute.

CharacterData.substringData(offset, count)

Return the substring of data of count characters starting at offset.

CharacterData.appendData(arg)

Append the string arg to data.

CharacterData.insertData(offset, arg)

Insert the string arg into data at offset.

CharacterData.deleteData(offset, count)

Remove count characters from data starting at offset.

CharacterData.replaceData(offset, count, arg)

Replace count characters of data starting at offset with the string arg.

Objets Comment

Comment represents a comment in the XML document. It is a subclass of CharacterData.

Comment.data

Le contenu du commentaire comme une chaîne. L'attribut contient tous les caractères entre <!-- et --> mais ne les inclues pas.

Objets Text et CDATASection

The Text interface represents text in the XML document. If the parser and DOM implementation support the DOM's XML extension, portions of the text enclosed in CDATA marked sections are stored in CDATASection objects. These two interfaces are identical, but provide different values for the nodeType attribute.

Text extends the CharacterData interface, and CDATASection extends Text.

Text.data

Le contenu du nœud texte comme une chaîne.

Text.wholeText

The text of all Text nodes logically adjacent to this node, concatenated in document order. This is a read-only attribute.

Text.replaceWholeText(content)

Replace the text of all Text nodes logically adjacent to this node with content, removing the other nodes. Return this node, or None if content is empty.

Text.splitText(offset)

Split this node into two nodes at offset, keeping the first part in this node and returning a new sibling node with the rest.

Note

L'utilisation d'un nœud CDATASection n'indique pas que le nœud représente une section complète marquée CDATA, seulement que le contenu du nœud est le contenu d'une section CDATA. Une seule section CDATA peut représenter plus d'un nœud dans l'arbre du document. Il n'y a aucun moyen de déterminer si deux nœuds CDATASection adjacents représentent différentes sections CDATA.

Objets ProcessingInstruction

Représente une processing instruction dans un document XML. Hérite de l'interface Node et ne peut avoir aucun nœud fils.

ProcessingInstruction.target

Le contenu de la processing instruction jusqu'au premier caractère blanc. Cet attribut est en lecture seule.

ProcessingInstruction.data

Le contenu de la processing instruction après le premier caractère blanc.

Entity Objects

Entity represents a parsed or unparsed entity declared in the DTD. It is a subclass of Node. Entity nodes are contained in DocumentType.entities and cannot be inserted into the document tree. The name of the entity is its nodeName.

Entity.publicId

The public identifier of the entity, or None if it is not specified. This is a read-only attribute.

Entity.systemId

The system identifier of the entity, or None if it is not specified. This is a read-only attribute.

Entity.notationName

The name of the notation for an unparsed entity, or None for a parsed entity. This is a read-only attribute.

Notation Objects

Notation represents a notation declared in the DTD. It is a subclass of Node and cannot have child nodes. Notation nodes are contained in DocumentType.notations and cannot be inserted into the document tree. The name of the notation is its nodeName.

Notation.publicId

The public identifier of the notation, or None if it is not specified. This is a read-only attribute.

Notation.systemId

The system identifier of the notation, or None if it is not specified. This is a read-only attribute.

Exceptions

La recommandation DOM Level 2 définie une seule exception DOMException et un nombre de constantes qui permettent aux applications à déterminer quelle type d'erreur s'est produit. Les instances de DOMException ont un attribut code qui fourni une valeur approprié pour une exception spécifique.

L'interface DOM de Python fournit des constant mais également étends un ensemble d'exception pour qu'il existe une exception spécifique pour chaque code d'exception défini par le DOM. L'implémentation doit lever l'exception spécifique appropriée. Chacune ayant la valeur appropriée pour l'attribut code.

exception xml.dom.DOMException

Exception de base utilisée pour toutes les exceptions spécifiques du DOM. Cette classe ne peut pas être instanciée directement.

exception xml.dom.DomstringSizeErr

Levée quand un intervalle spécifique de texte ne rentre pas dans une chaîne. Cette exception n'est pas réputée être utilisée par les implémentations DOM de Python mais elle peur être levée par des implémentations de DOM qui ne sont pas écrite en Python.

exception xml.dom.HierarchyRequestErr

Levée quand l'insertion d'un nœud est tentée dans un type de nœud incompatible.

exception xml.dom.IndexSizeErr

Levée quand un index ou la taille d'un paramètre d'une méthode est négatif ou excède les valeurs autorisées.

exception xml.dom.InuseAttributeErr

Levée quand l'insertion d'un nœud Attr est tenté alors que ce nœud est déjà présent ailleurs dans le document.

exception xml.dom.InvalidAccessErr

Levée si un paramètre ou une opération n'est pas supporté par l'objet sous-jacent.

exception xml.dom.InvalidCharacterErr

Cette exception est levée quand un paramètre chaîne contient un caractère qui n'est pas autorisé dans le contexte utilisé par la recommandation XML 1.0. Par exemple, lors la tentative de création d'un nœud Element avec un espace dans le nom de l'élément.

exception xml.dom.InvalidModificationErr

Levée lors de la tentative de modifier le type de nœud.

exception xml.dom.InvalidStateErr

Levée quand une tentative est faite d'utiliser un objet non défini ou qui ne sont plus utilisables.

exception xml.dom.NamespaceErr

Si une tentative est faite de changer un objet d'une manière qui n'est pas autorisée selon la recommandation Namespaces in XML , cette exception est levée.

exception xml.dom.NotFoundErr

Exception quand un nœud n'existe pas dans le contexte référencé. Par exemple, NamedNodeMap.removeNamedItem() lèvera cette exception si le nœud passé n'appartient pas à la séquence.

exception xml.dom.NotSupportedErr

Levée si l'implémentation ne supporte pas le type d'objet requis ou l'opération.

exception xml.dom.NoDataAllowedErr

Levée si la donnée spécifiée pour un nœud n'est pas supportée.

exception xml.dom.NoModificationAllowedErr

Levée lors de la tentative de modification sur objet où les modifications ne sont pas autorisées (tels que les nœuds en lecture seule).

exception xml.dom.SyntaxErr

Levée quand une chaîne invalide ou illégale est spécifiée.

exception xml.dom.ValidationErr

Raised when an operation would make the document invalid with respect to partial validity. This is not known to be used in the Python DOM implementations, but may be received from DOM implementations not written in Python.

exception xml.dom.WrongDocumentErr

Levée quand un nœud est inséré dans un document différent de celui auquel il appartient et que l'implémentation ne supporte pas la migration d'un document à un autre.

Les codes d'exceptions définis par la recommandation DOM avec leurs correspondances décrites si dessous selon ce tableau :

Constante	Exception
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

Conformité

Cette section décrit la conformité des pré requis et des relations entre l'API DOM de Python, les recommandations W3C DOM et les correspondances OMG IDL pour Python.

Correspondance des types

Les types IDL utilisés dans la spécification DOM correspondent aux types Python selon le tableau suivant.

Type IDL	Type Python
boolean	bool ou int
int	int
long int	int
unsigned int	int
DOMString	str or bytes
null	None

Méthodes d'accès

Les correspondance de OMG IDL vers Python définissent des fonction d'accès pour les déclarations attribut d'IDL à la manière dont Java le fait. Correspondance des déclarations IDL

readonly attribute string someValue;
         attribute string anotherValue;

yields three accessor functions: a "get" method for someValue (_get_someValue()), and "get" and "set" methods for anotherValue (_get_anotherValue() and _set_anotherValue()). The mapping, in particular, does not require that the IDL attributes are accessible as normal Python attributes: object.someValue is not required to work, and may raise an AttributeError.

Cependant, l'API DOM de Python impose que les accès par attributs classiques fonctionnent. Par conséquent, les substituts générés par le compilateur IDL de Python ne fonctionneront probablement pas, et des objets façade pourraient être nécessaires côté client si les objets DOM sont manipulés via CORBA. Bien qu'utiliser un client DOM CORBA nécessite une bonne réflexion, les développeurs habitués et expérimentés à l'utilisation de CORBA ne considèrent pas que c'est un problème. Les attributs déclarés readonly pourraient ne pas voir leur accès en écriture restreint dans toutes les implémentations du DOM.

Dans l'API DOM de Python, les fonctions d'accès ne sont pas requises. Si elles sont fournies, elles doivent prendre la forme définie par le mapping de Python IDL, mais ces méthodes sont considérées inutiles car les attributs sont directement accessible depuis Python. Les fonctions d'accès "Set" ne devraient jamais être fournies pour les attributs readonly (en lecture seule).

The IDL definitions do not fully embody the requirements of the W3C DOM API, such as the notion of certain objects, such as the return value of getElementsByTagName(), being "live". The Python DOM API does not require implementations to enforce such requirements.