20.6. xml.dom — L’API Document Object Model

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

Spécification Level 2 Document Object Model (DOM)

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.

20.6.1. 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=())

Renvoie une implémentation DOM appropriée. Le name est soit connu, soit le nom du module d’une implémentation DOM, soit None. Si ce n’est pas None, le module correspondant est importé et retourne un objet DOMImplementation si l’importation réussit. Si Aucun name n’est donné et que la variable d’environnement PYTHON_DOM est positionnée, cette variable est utilisée pour trouver l’implémentation.

Si name n’est pas donné, la fonction examine les implémentations disponibles pour en trouver une avec l’ensemble des fonctionnalités requises. Si aucune implémentation n’est trouvée, une ImportError est levée. La liste de fonctionnalité doit être une séquence de paires (feature, version) qui est passée à la méthode hasFeature() disponible dans les objets DOMImplementation.

Quelques constantes pratiques sont également fournies :

xml.dom.EMPTY_NAMESPACE

La valeur utilisée pour indiquer qu’aucun espace de noms n’est associé à un nœud dans le DOM. Typiquement, ceci est trouvé comme namespaceURI dans un nœud ou utilisé comme le paramètre namespaceURI dans une méthode spécifique aux espaces de noms.

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).

Par ailleurs, xml.dom contient une classe de base Node et les exceptions de DOM. La classe Node fournie par ce module n’implémente aucune des méthodes ou des attributs définis par les spécifications DOM ; les implémentations concrètes des DOM doivent fournir les informations suivantes. La classe Node fournie part ce modules fournit les constantes utilisées pour l’attribut nodeType pour des objets concrets Node ; ils sont situés dans les classes plutôt qu’au niveau du module en accord avec les spécifications DOM.

20.6.2. Objets dans le DOM

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

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.

20.6.2.1. 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 vrai si la fonctionnalité identifiée par une paire de chaîne 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.

20.6.2.2. Objets nœuds

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

Node.nodeType

Un entier représentant le type de nœud. Pour l’objet Node, les constantes symboliques pour les types sont ELEMENT_NODE, ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, ENTITY_NODE, PROCESSING_INSTRUCTION_NODE, COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE. Ceci est un attribut en lecture seule.

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

Une liste de nœuds contenu dans le nœud courant. Cet attribut est en lecture seule.

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

S’il y a un :, contient la partie suivante de tagName ce : sinon la valeur complète de tagName. Cette valeur est une chaîne.

Node.prefix

La partie de tagName précédent le : s’il y en a un. sinon une chaîne vide. La valeur est une chaîne ou 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.nodeName

L’attribut a un sens différent pour chaque type de nœud ; se reporter à la spécification DOM pour les détails. Vous obtiendrez toujours l’information que vous obtiendrez à l’aide d’une autre propriété comme tagName pour les éléments ou name pour les attributs. Pour tous les types de nœuds, la valeur sera soit une chaîne soit None. Cet attribut est en lecture seule.

Node.nodeValue

L’attribut a un sens différent pour chaque type de nœud ; se reporter à la spécification DOM pour les détails. La situation est similaire à nodeName. La valeur est une chaîne ou None.

Node.hasAttributes()

Renvoi vrai si le nœud a des attributs.

Node.hasChildNodes()

Renvoi vrai si le nœud a des nœuds fils.

Node.isSameNode(other)

Renvoi vrai si other fait référence au même nœud que le nœud courant. Ceci est particulièrement pratique pour implémentation de DOM qui utilise une architecture proxy (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)

Insère un nouveau nœud fils avant un fils existant. Il est impératif que refChild soit un fils du nœud, sinon ValueError sera levée. newChild est renvoyé. Si refChild est None, newChild est inséré à la fin de la liste des fils.

Node.removeChild(oldChild)

Retire un nœud fils. oldChild doit être un fils de ce nœud ; sinon ValueError sera levée. En cas de succès, oldChild est renvoyé. Si oldChild n’est plus utilisé, sa méthode unlink() doit être appelée.

Node.replaceChild(newChild, oldChild)

Remplace un nœud existant avec un nouveau. oldChild doit être un fils de ce nœud ; sinon ValueError sera levée.

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.

20.6.2.3. Objet NodeList

NodeList représente une séquence de nœuds. Ces objets sont utilisés de deux manières dans la recommandation Dom Core : un objet Element fournit en fournis liste des nœud fils et les méthodes getElementsByTagName() et getElementsByTagNameNS() de Node renvoient des objet avec cette interface pour représenter les résultats des requêtes.

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

NodeList.item(i)

Renvoie le i*ème élément de la séquence s’il existe ou ``None``. L’index *i ne peut pas être inférieur à 0 ou supérieur ou égale à la longueur de la séquence.

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__() .

20.6.2.4. Objets DocumnentType

Les objets de type DocumentType fournissent des informations sur les notations et les entités déclarées par un document (incluant les données externes si l’analyseur les utilise et peut les fournir). Le DocumentType d’un Document est accessible via l’attribut doctype. Si le document ne déclare pas de DOCTYPE, l’attribut doctype vaudra None plutôt qu’une instance de cette interface.

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

DocumentType.publicId

L’identifiant publique pour un sous ensemble de la définition type de document (DTD). Cela sera une chaîne ou None.

DocumentType.systemId

L’identifiant système pour un sous ensemble du document de définition type (DTD). Cela sera une URI sous la forme d’une chaîne ou None.

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

Ceci est un NamedNodeMap donnant les définitions des entités externes. Pour les entités définies plusieurs fois seule la première définition est fournie (les suivantes sont ignorées comme requis par la recommandation XML). Ceci peut retourner None si l’information n’est pas fournie à l’analyseur ou si aucune entités n’est définis.

DocumentType.notations

Ceci est un NamedNodeMap donnant la définition des notations. Pour les notations définies plus d’une fois, seule la première est fournie (les suivante sont ignorées comme requis par la recommandation XML). Ceci peut retourner None si l’information n’est pas fournie à l’analyseur ou si aucune entités n’est définis.

20.6.2.5. 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.createElement(tagName)

Créé et renvoi un nouveau nœud élément. Ce n’est pas inséré dans le document quand il est créé. Vous avez besoin de l’insérer explicitement avec l’une des autres méthodes comme insertBefore() ou appendChild().

Document.createElementNS(namespaceURI, tagName)

Créé et renvoi un nouvel élément avec un namespace. Le tagName peut avoir un préfixe. L’élément ne sera pas insérer dans le document quand il est créé. Vous avez besoin de l’insérer explicitement avec l’une des autres méthodes comme insertBefore() ou 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)

Créé et renvoi un nœud attribut. Cette méthode n’associe le nœud attribut aucun nœud en particulier. Vous devez utiliser la méthode setAttributeNode() sur un objet Element approprié pour utiliser une instance d’attribut nouvellement créé.

Document.createAttributeNS(namespaceURI, qualifiedName)

Créé et renvoi un nœud attribut avec un namespace. Le tagName peut avoir un préfixe. Cette méthode n’associe le nœud attribut à aucun nœud en particulier. Vous devez utiliser la méthode setAttributeNode() sur un objet Element approprié pour utiliser une instance d’attribut nouvellement créé.

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.

20.6.2.6. 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.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)

Renvoi vrai si l’élément a un attribut nommé name.

Element.hasAttributeNS(namespaceURI, localName)

Renvoi vrai si l’élément a un nommé par namespaceURI et localName.

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)

Retire un attribut nommé name. S’il n’y a aucun attribut correspondant une NotFoundErr est levée.

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)

Retire un attribut selon son nom. Notez qu’il utilise un localName et nom un qname. Aucune exception n’est levée s’il n’y a pas d’attribut correspondant.

Element.setAttribute(name, value)

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

Element.setAttributeNode(newAttr)

Ajoute un nouveau nœud attribut à l’élément, remplaçant un attribut existant si nécessaire si name corresponds à un attribut. Si l’attribut en remplace un précédent, l’ancien attribut sera retourné. Si newAttr est déjà utilisé, InuseAttributeErr sera levée.

Element.setAttributeNodeNS(newAttr)

Ajoute un nouveau nœud attribut, remplaçant un attribut existant si namespaceURI et localName corresponds à un attribut. S’il y a remplacement, l’ancien nœud sera renvoyé. Si newAttr est déjà utilisé, InuseAttributeErr sera levée.

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.

20.6.2.7. Objets Attr

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

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.value

La valeur texte de l’attribut. C’est un synonyme de l’attribut nodeValue.

20.6.2.8. Objets NameNodeMap

NamedNodeMap n’hérite pas de Node.

NamedNodeMap.length

La longueur de la liste d’attributs.

NamedNodeMap.item(index)

Renvoi un attribut à un index particulier. L’ordre des attribut est arbitraire mais sera constant durant toute la vie du DOM. Chacun des item sera un nœud attribut. Obtenez sa valeur avec value de l’attribut.

Il y existe également des méthodes expérimentales qui donne à cette classe un comportement plus mappable. Vous pouvez les utiliser ou utiliser la famille de méthode standardisés getAttribute*() des objets Element.

20.6.2.9. Objets Comment

Comment représente un commentaire dans le document XML. C’est une sous classe Node mais n’a aucune nœuds fils.

Comment.data

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

20.6.2.10. Objets Text et CDATASection

L’interface Text représente le texte dans un document XML. Si l’analyseur et l’implémentation DOM supporte les extensions XML du DOM, les portion de texte encapsulées dans des section marquées CDATA seront stockées dans des objets CDATASection. Ces deux interfaces sont identiques mais fournissent des valeurs différentes pour l’attribut nodeType.

Ces interfaces étendent l’interface Node. Elles ne peuvent pas avoir de nœuds fils.

Text.data

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

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.

20.6.2.11. 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.

20.6.2.12. 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.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
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

20.6.3. 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.

20.6.3.1. 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

20.6.3.2. 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;

Donne trois fonctions d’accès : une méthode get pour someValue (_get_someValue()) et des méthodes get et set pour anotherValue (_get_anotherValue() et _set_anotherValue()). Le mapping, en particulier, ne requiert pas que les attributs IDL soient accessible comme des attributs Python normaux : object.someValue n’est pas requis de fonctionner et peut lever une 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).

Les définitions IDL n’embarquent pas entièrement les pré-requis de l’API de DOM API telle que la notion de objets ou que la valeur de retour de getElementsByTagName() est dynamique. L’API DOM de Python ne requiert pas des implémentations d’avoir de tel pré-requis.