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

The "xml.dom" contains the following functions:

xml.dom.registerDOMImplementation(name, factory)

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

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

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

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

Quelques constantes pratiques sont également fournies :

xml.dom.EMPTY_NAMESPACE

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

xml.dom.XML_NAMESPACE

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

xml.dom.XMLNS_NAMESPACE

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

xml.dom.XHTML_NAMESPACE

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

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


Objets dans le DOM
==================

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

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

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

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

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


Objets DOMImplementation
------------------------

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

DOMImplementation.hasFeature(feature, version)

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

DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)

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

DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)

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


Objets nœuds
------------

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

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

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

"DocumentFragment" and "Element"
   "Element", "Text", "CDATASection", "ProcessingInstruction" and
   "Comment"

"Attr"
   "Text"

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

Node.nodeType

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

Node.ELEMENT_NODE
Node.ATTRIBUTE_NODE
Node.TEXT_NODE
Node.CDATA_SECTION_NODE
Node.ENTITY_REFERENCE_NODE
Node.ENTITY_NODE
Node.PROCESSING_INSTRUCTION_NODE
Node.COMMENT_NODE
Node.DOCUMENT_NODE
Node.DOCUMENT_TYPE_NODE
Node.DOCUMENT_FRAGMENT_NODE
Node.NOTATION_NODE

   Integer constants for the possible values of the "nodeType"
   attribute.

Node.parentNode

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

Node.attributes

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

Node.previousSibling

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

Node.nextSibling

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

Node.childNodes

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

Node.firstChild

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

Node.lastChild

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

Node.localName

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

Node.prefix

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

Node.namespaceURI

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

Node.ownerDocument

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

Node.isSupported(feature, version)

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

Node.setUserData(key, data, handler)

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

Node.getUserData(key)

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

Node.nodeName

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

Node.nodeValue

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

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

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

Node.hasAttributes()

   Renvoie "True" si le nœud a des attributs.

Node.hasChildNodes()

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

Node.isSameNode(other)

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

   Note:

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

Node.appendChild(newChild)

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

Node.insertBefore(newChild, refChild)

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

Node.removeChild(oldChild)

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

Node.replaceChild(newChild, oldChild)

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

Node.normalize()

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

Node.cloneNode(deep)

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


Objet NodeList
--------------

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

"NodeList" does *not* inherit from "Node".

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

NodeList.item(i)

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

NodeList.length

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

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

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


Objets DocumnentType
--------------------

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

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

DocumentType.publicId

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

DocumentType.systemId

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

DocumentType.internalSubset

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

DocumentType.name

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

DocumentType.entities

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

DocumentType.notations

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


Objets Document
---------------

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

Document.documentElement

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

Document.doctype

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

Document.implementation

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

Document.strictErrorChecking

   Whether error checking is enforced.

Document.documentURI

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

Document.createDocumentFragment()

   Create and return an empty "DocumentFragment" node.

Document.createCDATASection(data)

   Create and return a "CDATASection" node containing *data*.

Document.importNode(importedNode, deep)

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

Document.createElement(tagName)

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

Document.createElementNS(namespaceURI, tagName)

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

Document.createTextNode(data)

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

Document.createComment(data)

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

Document.createProcessingInstruction(target, data)

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

Document.createAttribute(name)

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

Document.createAttributeNS(namespaceURI, qualifiedName)

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

Document.getElementById(id)

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

Document.getElementsByTagName(tagName)

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

Document.getElementsByTagNameNS(namespaceURI, localName)

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

Document.renameNode(n, namespaceURI, name)

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

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


Objets Elements
---------------

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

Element.tagName

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

Element.setIdAttribute(name)

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

Element.setIdAttributeNS(namespaceURI, localName)

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

Element.setIdAttributeNode(idAttr)

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

Element.getElementsByTagName(tagName)

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

Element.getElementsByTagNameNS(namespaceURI, localName)

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

Element.hasAttribute(name)

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

Element.hasAttributeNS(namespaceURI, localName)

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

Element.getAttribute(name)

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

Element.getAttributeNode(attrname)

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

Element.getAttributeNS(namespaceURI, localName)

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

Element.getAttributeNodeNS(namespaceURI, localName)

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

Element.removeAttribute(name)

   Remove an attribute by name.

Element.removeAttributeNode(oldAttr)

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

Element.removeAttributeNS(namespaceURI, localName)

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

Element.setAttribute(name, value)

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

Element.setAttributeNode(newAttr)

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

Element.setAttributeNodeNS(newAttr)

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

Element.setAttributeNS(namespaceURI, qname, value)

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


Objets Attr
-----------

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

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

Attr.name

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

Attr.localName

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

Attr.prefix

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

Attr.isId

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

Attr.ownerElement

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

Attr.specified

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

Attr.value

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


Objets NameNodeMap
------------------

"NamedNodeMap" *n'hérite pas* de "Node".

NamedNodeMap.length

   La longueur de la liste d'attributs.

NamedNodeMap.item(index)

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

NamedNodeMap.getNamedItem(name)

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

NamedNodeMap.getNamedItemNS(namespaceURI, localName)

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

NamedNodeMap.setNamedItem(node)

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

NamedNodeMap.setNamedItemNS(node)

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

NamedNodeMap.removeNamedItem(name)

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

NamedNodeMap.removeNamedItemNS(namespaceURI, localName)

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

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


DocumentFragment Objects
------------------------

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


CharacterData Objects
---------------------

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

CharacterData.data

   The content of the node as a string.

CharacterData.length

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

CharacterData.substringData(offset, count)

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

CharacterData.appendData(arg)

   Append the string *arg* to "data".

CharacterData.insertData(offset, arg)

   Insert the string *arg* into "data" at *offset*.

CharacterData.deleteData(offset, count)

   Remove *count* characters from "data" starting at *offset*.

CharacterData.replaceData(offset, count, arg)

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


Objets Comment
--------------

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

Comment.data

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


Objets Text et CDATASection
---------------------------

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

"Text" extends the "CharacterData" interface, and "CDATASection"
extends "Text".

Text.data

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

Text.wholeText

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

Text.replaceWholeText(content)

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

Text.splitText(offset)

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

Note:

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


Objets ProcessingInstruction
----------------------------

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

ProcessingInstruction.target

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

ProcessingInstruction.data

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


Entity Objects
--------------

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

Entity.publicId

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

Entity.systemId

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

Entity.notationName

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


Notation Objects
----------------

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

Notation.publicId

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

Notation.systemId

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


Exceptions
----------

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

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

exception xml.dom.DOMException

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

exception xml.dom.DomstringSizeErr

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

exception xml.dom.HierarchyRequestErr

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

exception xml.dom.IndexSizeErr

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

exception xml.dom.InuseAttributeErr

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

exception xml.dom.InvalidAccessErr

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

exception xml.dom.InvalidCharacterErr

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

exception xml.dom.InvalidModificationErr

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

exception xml.dom.InvalidStateErr

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

exception xml.dom.NamespaceErr

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

exception xml.dom.NotFoundErr

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

exception xml.dom.NotSupportedErr

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

exception xml.dom.NoDataAllowedErr

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

exception xml.dom.NoModificationAllowedErr

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

exception xml.dom.SyntaxErr

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

exception xml.dom.ValidationErr

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

exception xml.dom.WrongDocumentErr

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

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

+-----------------------------------------+-----------------------------------+
| Constante                               | Exception                         |
|=========================================|===================================|
| xml.dom.DOMSTRING_SIZE_ERR              | "DomstringSizeErr"                |
+-----------------------------------------+-----------------------------------+
| xml.dom.HIERARCHY_REQUEST_ERR           | "HierarchyRequestErr"             |
+-----------------------------------------+-----------------------------------+
| xml.dom.INDEX_SIZE_ERR                  | "IndexSizeErr"                    |
+-----------------------------------------+-----------------------------------+
| xml.dom.INUSE_ATTRIBUTE_ERR             | "InuseAttributeErr"               |
+-----------------------------------------+-----------------------------------+
| xml.dom.INVALID_ACCESS_ERR              | "InvalidAccessErr"                |
+-----------------------------------------+-----------------------------------+
| xml.dom.INVALID_CHARACTER_ERR           | "InvalidCharacterErr"             |
+-----------------------------------------+-----------------------------------+
| xml.dom.INVALID_MODIFICATION_ERR        | "InvalidModificationErr"          |
+-----------------------------------------+-----------------------------------+
| xml.dom.INVALID_STATE_ERR               | "InvalidStateErr"                 |
+-----------------------------------------+-----------------------------------+
| xml.dom.NAMESPACE_ERR                   | "NamespaceErr"                    |
+-----------------------------------------+-----------------------------------+
| xml.dom.NOT_FOUND_ERR                   | "NotFoundErr"                     |
+-----------------------------------------+-----------------------------------+
| xml.dom.NOT_SUPPORTED_ERR               | "NotSupportedErr"                 |
+-----------------------------------------+-----------------------------------+
| xml.dom.NO_DATA_ALLOWED_ERR             | "NoDataAllowedErr"                |
+-----------------------------------------+-----------------------------------+
| xml.dom.NO_MODIFICATION_ALLOWED_ERR     | "NoModificationAllowedErr"        |
+-----------------------------------------+-----------------------------------+
| xml.dom.SYNTAX_ERR                      | "SyntaxErr"                       |
+-----------------------------------------+-----------------------------------+
| xml.dom.VALIDATION_ERR                  | "ValidationErr"                   |
+-----------------------------------------+-----------------------------------+
| xml.dom.WRONG_DOCUMENT_ERR              | "WrongDocumentErr"                |
+-----------------------------------------+-----------------------------------+


Conformité
==========

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


Correspondance des types
------------------------

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

+--------------------+---------------------------------------------+
| Type IDL           | Type Python                                 |
|====================|=============================================|
| "boolean"          | "bool" ou "int"                             |
+--------------------+---------------------------------------------+
| "int"              | "int"                                       |
+--------------------+---------------------------------------------+
| "long int"         | "int"                                       |
+--------------------+---------------------------------------------+
| "unsigned int"     | "int"                                       |
+--------------------+---------------------------------------------+
| "DOMString"        | "str" or "bytes"                            |
+--------------------+---------------------------------------------+
| "null"             | "None"                                      |
+--------------------+---------------------------------------------+


Méthodes d'accès
----------------

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

   readonly attribute string someValue;
            attribute string anotherValue;

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

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

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

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