# `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=())

  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.

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

### 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`.

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

  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)

  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.

### 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 ie é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__()` .

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

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

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

  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)

  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.

### 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`.

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

There are also experimental methods that give this class more mapping behavior. You can use them or you can use the standardized `getAttribute*()` family of methods on the `Element` objects.

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

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

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

### 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`

## 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;

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.