19.8. "xml.dom" — L’API Document Object Model
*********************************************

Nouveau dans la version 2.0.

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.


19.8.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[, 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’import réussit. Si Aucun
   *name* n’est donné et que la variable d’environnement "PYTHON_DOM"
   est positionnée, cette variable est utilisé 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 nom 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 nom.

   Nouveau dans la version 2.2.

xml.dom.XML_NAMESPACE

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

   Nouveau dans la version 2.2.

xml.dom.XMLNS_NAMESPACE

   L’URI de l’espace de nom 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).

   Nouveau dans la version 2.2.

xml.dom.XHTML_NAMESPACE

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

   Nouveau dans la version 2.2.

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.


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


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


19.8.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 nom associé (*namespace*) au nom de l’élément. Cette
   valeur sera 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.

   Nouveau dans la version 2.1.

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.


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


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


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


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


19.8.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".


19.8.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".


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


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


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


19.8.2.12. Exceptions
---------------------

Nouveau dans la version 2.1.

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"                |
+----------------------------------------+-----------------------------------+


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


19.8.3.1. Correspondance des types
----------------------------------

The primitive IDL types used in the DOM specification are mapped to
Python types according to the following table.

+--------------------+---------------------------------------------+
| Type IDL           | Type Python                                 |
+====================+=============================================+
| "boolean"          | "IntegerType" (with a value of "0" or "1")  |
+--------------------+---------------------------------------------+
| "int"              | "IntegerType"                               |
+--------------------+---------------------------------------------+
| "long int"         | "IntegerType"                               |
+--------------------+---------------------------------------------+
| "unsigned int"     | "IntegerType"                               |
+--------------------+---------------------------------------------+

Additionally, the "DOMString" defined in the recommendation is mapped
to a Python string or Unicode string.  Applications should be able to
handle Unicode whenever a string is returned from the DOM.

The IDL "null" value is mapped to "None", which may be accepted or
provided by the implementation whenever "null" is allowed by the API.


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