`xml.etree.ElementTree` --- The ElementTree XML API¶

Code Source: Lib/xml/etree/ElementTree.py

Le module xml.etree.ElementTree implémente une API simple et efficace pour analyser et créer des données XML.

Modifié dans la version 3.3: ce module utilise une implémentation rapide chaque fois que c'est possible.

Obsolète depuis la version 3.3: The xml.etree.cElementTree module is deprecated.

Avertissement

le module xml.sax n'est pas sécurisé contre les données construites de façon malveillante. Si vous avez besoin d'analyser des données non sécurisées ou non authentifiées, référez-vous à Vulnérabilités XML.

Tutoriel¶

Ceci est un petit tutoriel pour utiliser xml.etree.ElementTree (ET). Le but est de montrer quelques composants et les concepts basiques du module.

Arborescence et éléments XML¶

XML est un format de données fondamentalement hiérarchique et la façon la plus naturelle de le représenter est avec un arbre. ET a deux classes pour ce but : ElementTree représente l'ensemble du document XML comme un arbre et Element représente un simple nœud dans cet arbre. Les interactions (lire et écrire vers et depuis des fichiers) sur le document sont habituellement effectuées au niveau de ElementTree. Les interactions sur un seul élément XML et ses sous-éléments sont effectuées au niveau de Element.

Analyse XML¶

We'll be using the fictive country_data.xml XML document as the sample data for this section:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank>1</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank>4</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank>68</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Nous pouvons importer ces données en lisant un fichier :

import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()

Ou depuis une chaîne de caractères :

root = ET.fromstring(country_data_as_string)

fromstring() analyse les données XML depuis une chaîne de caractères et produit un Element, qui est l'élément racine de l'arbre analysé. D'autres fonctions d'analyse peuvent créer un ElementTree. Vérifiez la documentation pour en être sûr.

En tant qu'Element, root a une balise (tag) et un dictionnaire d'attributs :

>>> root.tag
'data'
>>> root.attrib
{}

Il contient aussi des nœuds enfants sur lesquels nous pouvons itérer :

>>> for child in root:
...     print(child.tag, child.attrib)
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}

Les enfants sont imbriqués et nous pouvons accéder aux nœuds enfants spécifiques via un indice :

>>> root[0][1].text
'2008'

Note

les éléments du XML d'entrée ne sont pas tous considérés comme des éléments de l'arborescence. Actuellement, le module ignore les commentaires XML, les instructions de traitements et la déclaration du type de document dans l'entrée. Néanmoins, les arborescences construites en utilisant l'API du module plutôt que par l'analyse du texte XML peuvent contenir des commentaires et des instructions de traitement ; ils seront inclus lors de la génération du XML de sortie. La DTD du document est accessible en passant une instance de TreeBuilder au constructeur de XMLParser.

API à flux tiré¶

La plupart des fonctions d'analyse fournies par ce module nécessitent que le document entier soit lu en même temps avant de renvoyer un résultat. Il est possible d'utiliser un XMLParser et d'y introduire des données de manière incrémentielle, mais il s'agit d'une API à flux poussé qui appelle des méthodes par rappel automatique, ce qui est de trop bas niveau et peu pratique pour la plupart des besoins. Parfois, ce que l'utilisateur souhaite réellement, c'est pouvoir analyser du XML de manière incrémentielle, sans bloquer les opérations, tout en bénéficiant de la commodité des objets Element entièrement construits.

L'outil le plus puissant pour ce faire est XMLPullParser. Il ne nécessite pas de lecture bloquante pour obtenir les données XML et est plutôt alimenté en données de manière incrémentielle avec des appels à XMLPullParser.feed(). Pour obtenir les éléments XML analysés, appelez XMLPullParser.read_events(). Voici un exemple :

>>> parser = ET.XMLPullParser(['start', 'end'])
>>> parser.feed('<mytag>sometext')
>>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> parser.feed(' more text</mytag>')
>>> for event, elem in parser.read_events():
...     print(event)
...     print(elem.tag, 'text=', elem.text)
...
end
mytag text= sometext more text

Le cas d'utilisation évident concerne les applications qui fonctionnent de manière non bloquante dans lesquelles les données XML sont reçues à partir d'un connecteur réseau ou lues de manière incrémentielle à partir d'un périphérique de stockage. Dans de tels cas, le blocage des lectures est inacceptable.

Parce qu'il est très flexible, XMLPullParser peut être peu pratique à utiliser pour des cas d'utilisation plus simples. Si cela ne vous dérange pas que votre application se bloque pendant la lecture de données XML mais que vous souhaitez tout de même disposer de capacités d'analyse incrémentielle, jetez un œil à iterparse(). Cela peut être utile lorsque vous lisez un document XML volumineux et que vous ne souhaitez pas le conserver entièrement en mémoire.

Where immediate feedback through events is wanted, calling method XMLPullParser.flush() can help reduce delay; please make sure to study the related security notes.

Atteinte d'éléments d'intérêt¶

Element a quelques méthodes très utiles qui aident à parcourir récursivement tous les sous-arbres (ses enfants, leurs enfants et ainsi de suite). Par exemple, Element.iter() :

>>> for neighbor in root.iter('neighbor'):
...     print(neighbor.attrib)
...
{'name': 'Austria', 'direction': 'E'}
{'name': 'Switzerland', 'direction': 'W'}
{'name': 'Malaysia', 'direction': 'N'}
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}

Element.findall() récupère seulement les éléments avec une balise qui sont les descendants directs de l'élément courant. Element.find() récupère le premier élément avec une balise particulière et Element.text accède au contenu textuel de l'élément. Element.get() accède aux attributs de l'élément :

>>> for country in root.findall('country'):
...     rank = country.find('rank').text
...     name = country.get('name')
...     print(name, rank)
...
Liechtenstein 1
Singapore 4
Panama 68

Une caractérisation plus sophistiquée des éléments à rechercher est possible en utilisant XPath.

Modification d'un fichier XML¶

ElementTree fournit un moyen simple de créer des documents XML et de les écrire dans des fichiers. La méthode ElementTree.write() sert à cet effet.

Une fois créé, un objet Element peut être manipulé en changeant directement ses champs (tels que Element.text), en ajoutant et en modifiant des attributs (méthode Element.set()), ou en ajoutant de nouveaux enfants (par exemple avec Element.append()).

Disons que nous voulons en ajouter un au classement de chaque pays, et ajouter un attribut updated (« mis à jour ») à l'élément de classement :

>>> for rank in root.iter('rank'):
...     new_rank = int(rank.text) + 1
...     rank.text = str(new_rank)
...     rank.set('updated', 'yes')
...
>>> tree.write('output.xml')

Maintenant, notre XML ressemble à ceci :

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank updated="yes">69</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Nous pouvons supprimer des éléments en utilisant Element.remove(). Supposons que nous souhaitions supprimer tous les pays dont le classement est supérieur à 50 :

>>> for country in root.findall('country'):
...     # using root.findall() to avoid removal during traversal
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

Notez que les modifications simultanées lors de l'itération peuvent entraîner des problèmes, tout comme lors de l'itération et de la modification de listes ou de dictionnaires Python. Par conséquent, l'exemple collecte d'abord tous les éléments correspondants avec root.findall(), et après seulement parcourt la liste des correspondances.

Maintenant, notre XML ressemble à ceci :

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
</data>

Création de documents XML¶

La fonction SubElement() fournit également un moyen pratique de créer de nouveaux sous-éléments pour un élément donné :

>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>

Analyse d'un XML avec des espaces de noms¶

Si l'entrée XML a des espaces de noms, les balises et les attributs avec des préfixes sous la forme préfixe:unebalise sont étendus à {uri}unebalise où le préfixe est remplacé par l'URI complet. De plus, s'il existe un espace de noms par défaut, cet URI complet est ajouté au début de toutes les balises non préfixées.

Voici un exemple XML qui intègre deux espaces de noms, l'un avec le préfixe fictional et l'autre servant d'espace de noms par défaut :

<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
        xmlns="http://people.example.com">
    <actor>
        <name>John Cleese</name>
        <fictional:character>Lancelot</fictional:character>
        <fictional:character>Archie Leach</fictional:character>
    </actor>
    <actor>
        <name>Eric Idle</name>
        <fictional:character>Sir Robin</fictional:character>
        <fictional:character>Gunther</fictional:character>
        <fictional:character>Commander Clement</fictional:character>
    </actor>
</actors>

Une façon de rechercher et d'explorer cet exemple XML consiste à ajouter manuellement l'URI à chaque balise ou attribut dans le xpath d'une recherche find() ou findall() :

root = fromstring(xml_text)
for actor in root.findall('{http://people.example.com}actor'):
    name = actor.find('{http://people.example.com}name')
    print(name.text)
    for char in actor.findall('{http://characters.example.com}character'):
        print(' |-->', char.text)

Une meilleure façon de rechercher dans l'exemple XML avec espace de noms consiste à créer un dictionnaire avec vos propres préfixes et à les utiliser dans les fonctions de recherche :

ns = {'real_person': 'http://people.example.com',
      'role': 'http://characters.example.com'}

for actor in root.findall('real_person:actor', ns):
    name = actor.find('real_person:name', ns)
    print(name.text)
    for char in actor.findall('role:character', ns):
        print(' |-->', char.text)

Ces deux approches donnent le même résultat :

John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement

Prise en charge de XPath¶

Ce module fournit une prise en charge limitée des expressions XPath pour localiser des éléments dans une arborescence. L'objectif est de prendre en charge un petit sous-ensemble de la syntaxe abrégée ; un moteur XPath complet sort du cadre du module.

Exemple¶

Voici un exemple qui démontre certaines des fonctionnalités XPath du module. Nous utilisons le document XML countrydata de la section Parsing XML :

import xml.etree.ElementTree as ET

root = ET.fromstring(countrydata)

# Top-level elements
root.findall(".")

# All 'neighbor' grand-children of 'country' children of the top-level
# elements
root.findall("./country/neighbor")

# Nodes with name='Singapore' that have a 'year' child
root.findall(".//year/..[@name='Singapore']")

# 'year' nodes that are children of nodes with name='Singapore'
root.findall(".//*[@name='Singapore']/year")

# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")

Pour du XML avec des espaces de noms, utilisez la notation qualifiée habituelle {namespace}tag :

# All dublin-core "title" tags in the document
root.findall(".//{http://purl.org/dc/elements/1.1/}title")

Prise en charge de la syntaxe XPath¶

Syntaxe	Signification
`tag`	Sélectionne tous les éléments enfants avec une balise donnée. Par exemple, `spam` sélectionne tous les éléments enfants nommés `spam` et `spam/egg` sélectionne tous les petits-enfants nommés `egg` dans les enfants nommés `spam`. `{namespace}` sélectionne toutes les balises dans l'espace de noms donné, `{}spam` sélectionne les balises nommées `spam` dans n'importe quel (ou aucun) espace de noms et `{}*` sélectionne seulement les balises qui ne sont pas dans un espace de noms. Modifié dans la version 3.8: la prise en charge des caractères génériques étoiles a été ajoutée.
`*`	Sélectionne tous les éléments enfants, y compris les commentaires et les instructions de traitement. Par exemple, `*/egg` sélectionne tous les petits-enfants nommés `egg`.
`.`	Sélectionne le nœud actuel. C'est surtout utile au début du chemin, pour indiquer qu'il s'agit d'un chemin relatif.
`//`	Sélectionne tous les sous-éléments, à tous les niveaux situés sous l'élément actuel. Par exemple, `.//egg` sélectionne tous les éléments `egg` dans l'arborescence entière.
`..`	Sélectionne l'élément parent. Renvoie `None` si le chemin tente d'atteindre les ancêtres de l'élément de départ (l'élément sur lequel `find` a été appelé).
`[@attrib]`	Sélectionne tous les éléments qui ont l'attribut donné.
`[@attrib='value']`	Sélectionne tous les éléments pour lesquels l'attribut donné a la valeur donnée. La valeur ne peut pas contenir de guillemet simple (`'`).
`[@attrib!='value']`	Sélectionne tous les éléments pour lesquels l'attribut donné n'a pas la valeur donnée. La valeur ne peut pas contenir de guillemet simple (`'`). Ajouté dans la version 3.10.
`[tag]`	Sélectionne tous les éléments qui ont un enfant nommé `tag`. Seuls les enfants immédiats sont pris en charge.
`[.='text']`	Sélectionne tous les éléments dont le contenu textuel complet, y compris les descendants, est égal au `text` donné. Ajouté dans la version 3.7.
`[.!='text']`	Sélectionne tous les éléments dont le contenu textuel complet, y compris les descendants, n'est pas égal au `text` donné. Ajouté dans la version 3.10.
`[tag='text']`	Sélectionne tous les éléments qui ont un enfant nommé `tag` dont le contenu textuel complet, y compris les descendants, est égal au `text` donné.
`[tag!='text']`	Sélectionne tous les éléments qui ont un enfant nommé `tag` dont le contenu textuel complet, y compris les descendants, n'est pas égal au `text` donné. Ajouté dans la version 3.10.
`[position]`	Sélectionne tous les éléments situés à la position donnée. La position peut être soit un entier (1 est la première position), l'expression `last()` (pour la dernière position), ou une position relative à la dernière position (par exemple `last()-1`).

Les prédicats (expressions entre crochets) doivent être précédés d'un nom de balise, d'un astérisque ou d'un autre prédicat. Les prédicats position doivent être précédés d'un nom de balise.

Référence¶

Fonctions¶

xml.etree.ElementTree.canonicalize(xml_data=None, *, out=None, from_file=None, **options)¶

Fonction de transformation C14N 2.0.

Canonicalization is a way to normalise XML output in a way that allows byte-by-byte comparisons and digital signatures. It reduces the freedom that XML serializers have and instead generates a more constrained XML representation. The main restrictions regard the placement of namespace declarations, the ordering of attributes, and ignorable whitespace.

Cette fonction prend une chaîne de données XML (xml_data) ou un chemin de fichier ou un objet de type fichier (from_file) en entrée, la convertit sous la forme canonique et l'écrit à l'aide de l'objet simili-fichier out, s'il est fourni, ou le renvoie sous forme de chaîne de texte sinon. Le fichier de sortie reçoit du texte, pas des octets. Il doit donc être ouvert en mode texte avec l'encodage utf-8.

Utilisation typique :

xml_data = "<root>...</root>"
print(canonicalize(xml_data))

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(xml_data, out=out_file)

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(from_file="inputfile.xml", out=out_file)

Les options de configuration sont les suivantes :

with_comments : définissez cet attribut à vrai pour inclure les commentaires (par défaut : faux)
strip_text : définissez à vrai pour supprimer les espaces avant et après le contenu du texte
(par défaut : faux)
rewrite_prefixes : définissez à vrai pour remplacer les préfixes d'espace de noms par « n{nombre} »
(par défaut : faux)
qname_aware_tags : ensemble de noms de balises prenant en charge les noms qualifiés dans lesquels les préfixes
doivent être remplacés dans le contenu du texte (par défaut : vide)
qname_aware_attrs : ensemble de noms d'attributs prenant en charge les noms qualifiés dans lesquels les préfixes
doivent être remplacés dans le contenu du texte (par défaut : vide)
exclude_attrs : ensemble de noms d'attributs qui ne doivent pas être sérialisés
exclude_tags : ensemble de noms de balises qui ne doivent pas être sérialisés

Dans la liste d'options ci-dessus, un « ensemble » fait référence à toute collection ou itérable de chaînes, aucun ordre n'est attendu.

Ajouté dans la version 3.8.

xml.etree.ElementTree.Comment(text=None)¶

Fabrique d’éléments de commentaire. Cette fonction crée un élément spécial qui sera sérialisé sous forme de commentaire XML par le sérialiseur standard. La chaîne de commentaire peut être une chaîne d'octets ou une chaîne Unicode. text est une chaîne contenant la chaîne de commentaire. Renvoie une instance d'élément représentant un commentaire.

Notez que XMLParser ignore les commentaires dans l'entrée au lieu de créer des objets de commentaire pour eux. Un ElementTree ne contiendra que des nœuds de commentaires qui ont été insérés dans l'arborescence à l'aide de l'une des méthodes d'Element.

xml.etree.ElementTree.dump(elem)¶

Écrit une arborescence d'éléments ou une structure d'éléments dans sys.stdout. Cette fonction doit être utilisée uniquement pour le débogage.

Le format de sortie exact dépend de l’implémentation. Dans cette version, il est écrit sous la forme d'un fichier XML ordinaire.

elem est un élément de l'arborescence ou un élément individuel.

Modifié dans la version 3.8: la fonction dump() préserve désormais l'ordre des attributs spécifié par l'utilisateur.

xml.etree.ElementTree.fromstring(text, parser=None)¶: Analyse une section XML à partir d'une constante de chaîne. Identique à XML(). text est une chaîne contenant des données XML. parser est une instance d'analyseur facultative. S'il n'est pas fourni, l'analyseur standard XMLParser est utilisé. Renvoie une instance d'Element.

xml.etree.ElementTree.fromstringlist(sequence, parser=None)¶: Analyse un document XML à partir d'une séquence de fragments de chaîne. séquence est une liste ou une autre séquence contenant des fragments de données XML. parser est une instance d'analyseur facultative. S'il n'est pas fourni, l'analyseur standard XMLParser est utilisé. Renvoie une instance d'Element.

Ajouté dans la version 3.2.

xml.etree.ElementTree.indent(tree, space=' ', level=0)¶: Ajoute des espaces au sous-arbre pour indenter visuellement l'arborescence. Cela peut être utilisé pour générer une sortie XML avec une mise en forme agréable. tree peut être un élément ou un ElementTree. espace est la chaîne d'espaces qui est insérée pour chaque niveau d'indentation, deux caractères d'espace par défaut. Pour indenter des sous-arbres partiels à l'intérieur d'un arbre déjà indenté, transmettez le niveau d'indentation initial dans level.

Ajouté dans la version 3.9.

xml.etree.ElementTree.iselement(element)¶: Vérifie si un objet semble être un objet élément valide. element est une instance d'élément. Renvoie True s'il s'agit d'un objet élément.

xml.etree.ElementTree.iterparse(source, events=None, parser=None)¶

Parses an XML section into an element tree incrementally, and reports what's going on to the user. source is a filename or file object containing XML data. events is a sequence of events to report back. The supported events are the strings "start", "end", "comment", "pi", "start-ns" and "end-ns" (the "ns" events are used to get detailed namespace information). If events is omitted, only "end" events are reported. parser is an optional parser instance. If not given, the standard XMLParser parser is used. parser must be a subclass of XMLParser and can only use the default TreeBuilder as a target. Returns an iterator providing (event, elem) pairs; it has a root attribute that references the root element of the resulting XML tree once source is fully read.

Notez que même si iterparse() construit l'arborescence de manière incrémentielle, il bloque pendant les lectures sur source. En tant que tel, il ne convient pas aux applications dans lesquelles le blocage pendant les lectures ne peut pas être effectué. Pour une analyse entièrement non bloquante, voir XMLPullParser.

Note

iterparse() garantit uniquement qu'il a vu le caractère ">" d'une balise de début lorsqu'il émet un événement "start", donc les attributs sont définis mais le contenu des attributs text et tail n'est pas défini à ce stade. La même chose s'applique aux nœuds enfants de l'élément ; ils peuvent être présents ou non.

Si vous avez besoin d'un élément entièrement rempli, recherchez plutôt les événements "end".

Obsolète depuis la version 3.4: l'argument parser.

Modifié dans la version 3.8: les évènements comment et pi ont été ajoutés.

xml.etree.ElementTree.parse(source, parser=None)¶: Analyse une section XML dans une arborescence d'éléments. source est un nom de fichier ou un objet fichier contenant des données XML. parser (facultatif) est une instance d'analyseur. S'il n'est pas fourni, l'analyseur standard XMLParser est utilisé. Renvoie une instance d'ElementTree.

xml.etree.ElementTree.ProcessingInstruction(target, text=None)¶

Fabrique d’éléments Processing Instruction (PI). Cette fonction crée un élément spécial qui sera sérialisé en tant qu'instruction de traitement XML. target est une chaîne contenant la cible PI. text est une chaîne contenant le contenu de l'instruction de traitement (ou PI), s'il est fourni. Renvoie une instance d'élément, représentant l'instruction de traitement.

Note that XMLParser skips over processing instructions in the input instead of creating PI objects for them. An ElementTree will only contain processing instruction nodes if they have been inserted into to the tree using one of the Element methods.

xml.etree.ElementTree.register_namespace(prefix, uri)¶: Enregistre un préfixe d'espace de noms. Le registre est global et toute correspondance existante pour le préfixe donné ainsi que l'URI de l'espace de noms sera supprimé. prefix est un préfixe d'espace de noms. uri est un URI d'espace de noms. Les balises et les attributs de cet espace de noms seront sérialisés avec le préfixe donné, si possible.

Ajouté dans la version 3.2.

xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)¶

Fabrique de sous-élément. Cette fonction crée une instance d'élément et l'ajoute à un élément existant.

Le nom de l'élément, les noms d'attributs et les valeurs d'attributs peuvent être des chaînes d'octets ou des chaînes Unicode. parent est l'élément parent. tag est le nom du sous-élément. attrib est un dictionnaire facultatif contenant les attributs de l'élément. extra contient des attributs supplémentaires, donnés sous forme d'arguments nommés. Renvoie une instance d'élément.

xml.etree.ElementTree.tostring(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)¶: Génère une représentation sous forme de chaîne d'un élément XML, y compris tous les sous-éléments. element est une instance de Element. encoding [1] est l'encodage de sortie (la valeur par défaut est US-ASCII). Utilisez encoding="unicode" pour générer une chaîne Unicode (sinon, une chaîne d'octets est générée). method vaut "xml", "html" ou "text" (la valeur par défaut est "xml"). xml_declaration, default_namespace et short_empty_elements ont la même signification que dans ElementTree.write(). Renvoie une chaîne codée (éventuellement) contenant les données XML.

Modifié dans la version 3.4: Added the short_empty_elements parameter.

Modifié dans la version 3.8: Added the xml_declaration and default_namespace parameters.

Modifié dans la version 3.8: la fonction tostring() préserve désormais l'ordre des attributs spécifié par l'utilisateur.

xml.etree.ElementTree.tostringlist(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)¶: Génère une représentation sous forme de chaîne d'un élément XML, y compris tous les sous-éléments. element est une instance de Element. encoding [1] est l'encodage de sortie (la valeur par défaut est US-ASCII). Utilisez encoding="unicode" pour générer une chaîne Unicode (sinon, une chaîne d'octets est générée). method vaut "xml", "html" ou "text" (la valeur par défaut est "xml"). xml_declaration, default_namespace et short_empty_elements ont la même signification que dans ElementTree.write(). Renvoie une liste de chaînes codées (éventuellement) contenant les données XML. Elle ne garantit aucune séquence spécifique, seulement b"".join(tostringlist(element)) == tostring(element).

Ajouté dans la version 3.2.

Modifié dans la version 3.4: Added the short_empty_elements parameter.

Modifié dans la version 3.8: Added the xml_declaration and default_namespace parameters.

Modifié dans la version 3.8: la fonction tostringlist() préserve désormais l'ordre des attributs spécifié par l'utilisateur.

xml.etree.ElementTree.XML(text, parser=None)¶: Analyse une section XML à partir d'une constante de chaîne. Cette fonction peut être utilisée pour intégrer des « littéraux XML » dans du code Python. text est une chaîne contenant des données XML. parser, facultatif, est une instance d'analyseur. S'il n'est pas fourni, l'analyseur standard XMLParser est utilisé. Renvoie une instance d'Element.

xml.etree.ElementTree.XMLID(text, parser=None)¶: Analyse une section XML à partir d'une constante de chaîne et renvoie également un dictionnaire qui fait correspondre les identifiants d'éléments aux éléments. text est une chaîne contenant des données XML. parser, facultatif, est une instance d'analyseur. S'il n'est pas fourni, l'analyseur standard XMLParser est utilisé. Renvoie un n-uplet contenant une instance d'Element et un dictionnaire.

Prise en charge de XInclude¶

Ce module fournit une prise en charge limitée des directives XInclude, via le module d'assistance xml.etree.ElementInclude. Ce module peut être utilisé pour insérer des sous-arbres et des chaînes de texte dans des arborescences d'éléments, en fonction des informations contenues dans l'arborescence.

Exemple¶

Voici un exemple qui montre l'utilisation du module XInclude. Pour inclure un document XML dans le document actuel, utilisez l'élément {http://www.w3.org/2001/XInclude}include, définissez l'attribut parse sur "xml" et utilisez l'attribut href pour spécifier le document à inclure.

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>

Par défaut, l'attribut href est traité comme un nom de fichier. Vous pouvez utiliser des chargeurs personnalisés pour remplacer ce comportement. Notez également que l'assistant standard ne prend pas en charge la syntaxe XPointer.

Pour traiter ce fichier, chargez-le comme d'habitude et passez l'élément racine au module xml.etree.ElementTree :

from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)

Le module ElementInclude remplace l'élément {http://www.w3.org/2001/XInclude}include par l'élément racine du document source.xml. Le résultat pourrait ressembler à ceci :

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>This is a paragraph.</para>
</document>

Si l'attribut parse est omis, sa valeur par défaut est "xml". L'attribut href est obligatoire.

Pour inclure un document texte, utilisez l'élément {http://www.w3.org/2001/XInclude}include et définissez l'attribut parse sur "text" :

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>

Le résultat pourrait ressembler à ceci :

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) 2003.
</document>

Référence¶

Fonctions¶

xml.etree.ElementInclude.default_loader(href, parse, encoding=None)¶: Default loader. This default loader reads an included resource from disk. href is a URL. parse is for parse mode either "xml" or "text". encoding is an optional text encoding. If not given, encoding is utf-8. Returns the expanded resource. If the parse mode is "xml", this is an Element instance. If the parse mode is "text", this is a string. If the loader fails, it can return None or raise an exception.

xml.etree.ElementInclude.include(elem, loader=None, base_url=None, max_depth=6)¶: This function expands XInclude directives in-place in tree pointed by elem. elem is either the root Element or an ElementTree instance to find such element. loader is an optional resource loader. If omitted, it defaults to default_loader(). If given, it should be a callable that implements the same interface as default_loader(). base_url is base URL of the original file, to resolve relative include file references. max_depth is the maximum number of recursive inclusions. Limited to reduce the risk of malicious content explosion. Pass None to disable the limitation.

Modifié dans la version 3.9: Added the base_url and max_depth parameters.

Objets Element¶

class xml.etree.ElementTree.Element(tag, attrib={}, **extra)¶

Classe Element. Cette classe définit l'interface Element et fournit une implémentation de référence de cette interface.

Le nom de l'élément, les noms d'attributs et les valeurs d'attributs peuvent être des chaînes d'octets ou des chaînes Unicode. tag est le nom de l'élément. attrib est un dictionnaire facultatif contenant les attributs des éléments. extra contient des attributs supplémentaires, donnés sous forme d'arguments nommés.

tag¶: Chaîne identifiant le type de données que cet élément représente (en d'autres termes, le type d'élément).

text¶

tail¶

Ces attributs peuvent être utilisés pour contenir des données supplémentaires associées à l'élément. Leurs valeurs sont généralement des chaînes mais peuvent être n'importe quel objet spécifique à une application. Si l'élément est créé à partir d'un fichier XML, l'attribut text contient soit le texte entre la balise de début de l'élément et sa première balise enfant ou de fin, soit None ; l'attribut tail contient soit le texte entre la balise de fin de l'élément et la balise suivante, soit None. Pour les données XML

<a><b>1<c>2<d/>3</c></b>4</a>

les attributs text et tail de l'élément a valent None, l'attribut text de l'élément b vaut "1" et tail vaut "4", l'attribut text de l'élément c vaut "2" et tail vaut None, et l'attribut text de l'élément d vaut None et tail vaut "3".

Pour récupérer le texte interne d'un élément, voir itertext(), par exemple "".join(element.itertext()).

Les applications peuvent stocker des objets arbitraires dans ces attributs.

attrib¶: Dictionnaire contenant les attributs de l'élément. Notez que même si la valeur attrib est toujours un véritable dictionnaire Python mutable, une implémentation d'ElementTree peut choisir d'utiliser une autre représentation interne et de créer le dictionnaire uniquement si quelqu'un le demande. Pour profiter de telles implémentations, utilisez les méthodes de dictionnaire ci-dessous autant que possible.

Les méthodes dictionnaire-compatibles suivantes traitent les attributs de l'élément.

clear()¶: Réinitialise un élément. Cette fonction supprime tous les sous-éléments, efface tous les attributs et définit les attributs text et tail sur None.

get(key, default=None)¶

Accède à l'attribut de l'élément nommé key.

Renvoie la valeur de l'attribut ou default si l'attribut n'a pas été trouvé.

items()¶: Renvoie les attributs de l'élément comme une séquence de paire (nom, valeur). Les attributs sont renvoyés dans un ordre arbitraire.

keys()¶: Renvoie les noms d'attributs des éléments sous forme de liste. Les noms sont renvoyés dans un ordre arbitraire.

set(key, value)¶: Change l'attribut key à l'élément value.

Les méthodes suivantes traitent les éléments enfants (sous-éléments).

append(subelement)¶: Ajoute l'élément subelement à la fin de la liste interne des sous-éléments de cet élément. Lève une TypeError si subelement n'est pas un Element.

extend(subelements)¶: Appends subelements from an iterable of elements. Raises TypeError if a subelement is not an Element.

Ajouté dans la version 3.2.

find(match, namespaces=None)¶: Recherche le premier sous-élément correspondant à match. match peut être un nom de balise ou un path. Renvoie une instance d'élément ou None. namespaces est un tableau de correspondances facultatif de préfixes d'espaces de noms vers des noms complets. Passez '' comme préfixe pour déplacer tous les noms de balises sans préfixe dans l'expression dans l'espace de noms donné.

findall(match, namespaces=None)¶: Recherche tous les sous-éléments correspondants, par nom de balise ou path. Renvoie une liste contenant tous les éléments correspondants dans l'ordre du document. namespaces est un tableau de correspondances facultatif de préfixes d'espaces de noms vers des noms complets. Passez '' comme préfixe pour déplacer tous les noms de balises sans préfixe dans l'expression dans l'espace de noms donné.

findtext(match, default=None, namespaces=None)¶: Recherche le texte du premier sous-élément correspondant à match. match peut être un nom de balise ou un path. Renvoie le contenu textuel du premier élément correspondant, ou default si aucun élément n'a été trouvé. Notez que si l'élément correspondant n'a pas de contenu textuel, une chaîne vide est renvoyée. namespaces est un tableau de correspondances facultatif de préfixes d'espaces de noms vers des noms complets. Passez '' comme préfixe pour déplacer tous les noms de balises sans préfixe dans l'expression dans l'espace de noms donné.

insert(index, subelement)¶: Insère le subelement à la position donnée dans cet élément. Lève une TypeError si subelement n'est pas un Element.

iter(tag=None)¶: Crée un itérateur sur l'arbre avec l'élément actuel comme racine. L'itérateur parcourt cet élément et tous les éléments situés en dessous, dans l'ordre du document (profondeur en premier). Si tag n'est pas None ou '*', seuls les éléments dont la balise est égale à tag sont renvoyés par l'itérateur. Si l'arborescence est modifiée au cours de l'itération, le résultat est indéfini.

Ajouté dans la version 3.2.

iterfind(match, namespaces=None)¶: Recherche tous les sous-éléments correspondants, par nom de balise ou path. Renvoie un itérable donnant tous les éléments correspondants dans l'ordre du document. namespaces est un tableau de correspondances facultatif de préfixes d'espaces de noms vers des noms complets.

Ajouté dans la version 3.2.

itertext()¶: Crée un itérateur de texte. L'itérateur parcourt cet élément et tous les sous-éléments, dans l'ordre du document, et renvoie tout le texte interne.

Ajouté dans la version 3.2.

makeelement(tag, attrib)¶: Crée un nouvel objet élément du même type que cet élément. N'appelez pas cette méthode, utilisez plutôt la fonction de fabrique SubElement().

remove(subelement)¶: Supprime le subelement de l'élément. Contrairement aux méthodes find*, cette méthode compare les éléments en fonction de l'identité de l'instance, et non de la valeur ou du contenu de la balise.

Les objets Element prennent également en charge les méthodes de type séquence suivantes pour travailler avec des sous éléments : __delitem__(), __getitem__(), __setitem__(), __len__().

Caution: Elements with no subelements will test as False. In a future release of Python, all elements will test as True regardless of whether subelements exist. Instead, prefer explicit len(elem) or elem is not None tests.:

element = root.find('foo')

if not element:  # careful!
    print("element not found, or element has no subelements")

if element is None:
    print("element not found")

Modifié dans la version 3.12: Testing the truth value of an Element emits DeprecationWarning.

Avant Python 3.8, l'ordre de sérialisation des attributs XML des éléments était artificiellement rendu prévisible en classant les attributs par leur nom. Sur la base de l'ordre désormais garanti des dictionnaires, cette réorganisation arbitraire a été supprimée dans Python 3.8 pour préserver l'ordre dans lequel les attributs ont été initialement analysés ou créés par le code utilisateur.

En général, le code utilisateur doit essayer de ne pas dépendre d'un ordre spécifique des attributs, étant donné que la documentation de référence XML exclut explicitement que l'ordre des attributs soit porteur d'information. Le code doit être prêt à gérer tout ordre en entrée. Dans les cas où une sortie XML déterministe est requise, par exemple pour la signature cryptographique ou les ensembles de données de test, la sérialisation canonique est disponible avec la fonction canonicalize().

Dans les cas où la sortie canonique n'est pas applicable mais où un ordre d'attributs spécifique est quand même souhaitable en sortie, le code doit viser à créer les attributs directement dans l'ordre souhaité, afin d'éviter des inadéquations de perception pour les lecteurs du code. Dans les cas où cela est difficile à réaliser, une recette comme ci-dessous peut être appliquée avant la sérialisation pour appliquer un ordre indépendant de la création de l'élément :

def reorder_attributes(root):
    for el in root.iter():
        attrib = el.attrib
        if len(attrib) > 1:
            # adjust attribute order, e.g. by sorting
            attribs = sorted(attrib.items())
            attrib.clear()
            attrib.update(attribs)

Objets ElementTree¶

class xml.etree.ElementTree.ElementTree(element=None, file=None)¶

Classe enveloppant ElementTree. Cette classe représente une hiérarchie d'éléments entière et ajoute une prise en charge supplémentaire pour la sérialisation vers et depuis le XML standard.

element est l'élément racine. L'arborescence est initialisée avec le contenu du fichier XML file s'il est fourni.

_setroot(element)¶: Remplace l'élément racine de cette arborescence. Cela supprime le contenu actuel de l'arborescence et le remplace par l'élément donné. À utiliser avec précaution. element est une instance d'élément.

find(match, namespaces=None)¶: Comme Element.find(), commence à la racine de l'arbre.

findall(match, namespaces=None)¶: Identique à Element.findall(), en commençant à la racine de l'arborescence.

findtext(match, default=None, namespaces=None)¶: Identique à Element.findtext(), en commençant à la racine de l'arborescence.

getroot()¶: Renvoie l'élément racine de l'arbre.

iter(tag=None)¶: Crée et renvoie un itérateur d'arborescence pour l'élément racine. L'itérateur parcourt tous les éléments de cette arborescence, dans l'ordre des sections. tag est la balise à rechercher (la valeur par défaut est de renvoyer tous les éléments).

iterfind(match, namespaces=None)¶: Identique à Element.iterfind(), en commençant à la racine de l'arborescence.

Ajouté dans la version 3.2.

parse(source, parser=None)¶: Charge une section XML externe dans cette arborescence d'éléments. source est un nom de fichier ou un objet fichier. parser, facultatif, est une instance d'analyseur. S'il n'est pas fourni, l'analyseur standard XMLParser est utilisé. Renvoie l'élément racine de la section.

write(file, encoding='us-ascii', xml_declaration=None, default_namespace=None, method='xml', *, short_empty_elements=True)¶

Écrit l'arborescence des éléments dans un fichier, au format XML. file est un nom de fichier ou un objet fichier ouvert en écriture. encoding [1] est l'encodage de sortie (la valeur par défaut est US-ASCII). xml_declaration contrôle si une déclaration XML doit être ajoutée au fichier. Utilisez False pour jamais, True pour toujours, None pour seulement si ce n'est pas de l'US-ASCII ou de l'UTF-8 ou de l'Unicode (la valeur par défaut est None). default_namespace définit l'espace de noms XML par défaut (pour "xmlns"). method vaut "xml", "html" ou "text" (la valeur par défaut est "xml"). Le paramètre nommé (uniquement) short_empty_elements contrôle le formatage des éléments qui ne contiennent aucun contenu. Si c'est True (valeur par défaut), ils sont écrits sous la forme d'une seule balise auto-fermée, sinon ils sont écrits sous la forme d'une paire de balises de début-fin.

La sortie est une chaîne (str) ou du binaire (bytes). C'est contrôlé par l'argument encoding. Si encoding est "unicode", la sortie est une chaîne ; sinon, c'est binaire. Notez que cela peut entrer en conflit avec le type de fichier s'il s'agit d'un objet fichier déjà ouvert ; assurez-vous de ne pas essayer d'écrire une chaîne dans un flux binaire et vice versa.

Modifié dans la version 3.4: Added the short_empty_elements parameter.

Modifié dans la version 3.8: la méthode write() préserve désormais l'ordre des attributs spécifié par l'utilisateur.

Voici le fichier XML à manipuler :

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>Moved to <a href="http://example.org/">example.org</a>
        or <a href="http://example.com/">example.com</a>.</p>
    </body>
</html>

Exemple de modification de l'attribut target de chaque lien dans le premier paragraphe :

>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a"))   # Returns list of all links
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links:             # Iterates through all found links
...     i.attrib["target"] = "blank"
...
>>> tree.write("output.xhtml")

Objets QName¶

class xml.etree.ElementTree.QName(text_or_uri, tag=None)¶: Surcouche à QName. Cela peut être utilisé pour envelopper une valeur d'attribut QName, afin d'obtenir une gestion appropriée de l'espace de noms en sortie. text_or_uri est une chaîne contenant la valeur QName, sous la forme {uri}local ou, si l'argument tag est donné, la partie URI d'un QName. Si tag est donné, le premier argument est interprété comme un URI et cet argument est interprété comme un nom local. Les instances QName sont opaques.

Objets TreeBuilder¶

class xml.etree.ElementTree.TreeBuilder(element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)¶

Générateur de structure d'éléments générique. Ce constructeur convertit une séquence d'appels de méthode start, data, end, comment et pi en une structure d'éléments bien formée. Vous pouvez utiliser cette classe pour créer une structure d'éléments à l'aide d'un analyseur XML personnalisé ou d'un analyseur pour un autre type de format XML.

element_factory, lorsqu'il est donné, doit être un appelable acceptant deux arguments positionnels : une balise et un dictionnaire d'attributs. Elle est censée renvoyer une nouvelle instance d'élément.

Les fonctions comment_factory et pi_factory, lorsqu'elles sont données, doivent se comporter comme les fonctions Comment() et ProcessingInstruction() pour créer des commentaires et des instructions de traitement. Lorsqu’elles ne sont pas fournies, les fabriques par défaut sont utilisées. Lorsque insert_comments ou insert_pis sont vraies, les commentaires et instructions de traitement sont insérés dans l'arborescence s'ils apparaissent dans l'élément racine (mais pas à l'extérieur de celui-ci).

close()¶: Vide les tampons du générateur et renvoie l'élément de document de niveau supérieur. Renvoie une instance d'Element.

data(data)¶: Ajoute du texte à l'élément courant. data est une chaîne de caractères. Cela peut être une chaîne d'octets ou une chaîne Unicode.

end(tag)¶: Ferme l'élément courant. tag est le nom de l'élément. Renvoie l'élément fermé.

start(tag, attrs)¶: Ouvre un nouvel élément. tag est le nom de l'élément. attrs est un dictionnaire contenant les attributs de l'élément. Renvoie l'élément ouvert.

comment(text)¶: Crée un commentaire avec le text donné. Si insert_comments est vrai, cela l'ajoute également à l'arborescence.

Ajouté dans la version 3.8.

pi(target, text)¶: Creates a process instruction with the given target name and text. If insert_pis is true, this will also add it to the tree.

Ajouté dans la version 3.8.

De plus, un objet TreeBuilder personnalisé peut fournir les méthodes suivantes :

doctype(name, pubid, system)¶: Gère une déclaration doctype. name est le nom du type de document. pubid est l'identifiant public. system est l'identifiant du système. Cette méthode n'existe pas sur la classe par défaut TreeBuilder.

Ajouté dans la version 3.2.

start_ns(prefix, uri)¶: Est appelée chaque fois que l'analyseur rencontre une nouvelle déclaration d'espace de noms, avant le rappel start() pour l'élément d'ouverture qui le définit. prefix est '' pour l'espace de noms par défaut et le nom du préfixe d'espace de noms déclaré dans le cas contraire. uri est l'URI de l'espace de noms.

Ajouté dans la version 3.8.

end_ns(prefix)¶: Est appelée après le rappel end() d'un élément qui a déclaré une correspondance de préfixe d'espace de noms, avec le nom du prefix qui passe hors de portée.

Ajouté dans la version 3.8.

class xml.etree.ElementTree.C14NWriterTarget(write, *, with_comments=False, strip_text=False, rewrite_prefixes=False, qname_aware_tags=None, qname_aware_attrs=None, exclude_attrs=None, exclude_tags=None)¶: Écrivain C14N 2.0. Les arguments sont les mêmes que pour la fonction canonicalize(). Cette classe ne construit pas d'arborescence mais traduit les événements de rappel directement sous une forme sérialisée à l'aide de la fonction write.

Ajouté dans la version 3.8.

Objets XMLParser¶

class xml.etree.ElementTree.XMLParser(*, target=None, encoding=None)¶

Cette classe est l’élément de base du module. Elle utilise xml.parsers.expat pour une analyse efficace du XML et fonctionne à base d'événements. Elle peut être alimentée en données XML de manière incrémentielle avec la méthode feed(), et les événements d'analyse sont traduits en une API à flux poussé – en appelant les méthodes de rappel de l'objet target. Si target est omis, le TreeBuilder standard est utilisé. Si encoding [1] est donné, la valeur remplace l'encodage spécifié dans le fichier XML.

Modifié dans la version 3.8: Parameters are now keyword-only. The html argument is no longer supported.

close()¶: Termine l'envoi des données à l'analyseur. Renvoie le résultat de l'appel de la méthode close() de la target passée lors de la construction ; par défaut, il s'agit de l'élément de plus haut niveau du document.

feed(data)¶: Fournit des données à l’analyseur. data est une donnée encodée.

flush()¶

Triggers parsing of any previously fed unparsed data, which can be used to ensure more immediate feedback, in particular with Expat >=2.6.0. The implementation of flush() temporarily disables reparse deferral with Expat (if currently enabled) and triggers a reparse. Disabling reparse deferral has security consequences; please see xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() for details.

Note that flush() has been backported to some prior releases of CPython as a security fix. Check for availability of flush() using hasattr() if used in code running across a variety of Python versions.

Ajouté dans la version 3.12.3.

XMLParser.feed() appelle la méthode start(tag, attrs_dict) de target pour chaque balise d'ouverture, sa méthode end(tag) pour chaque balise de fermeture, et les données sont traitées par la méthode data(data). Pour d'autres méthodes de rappel prises en charge, consultez la classe TreeBuilder. XMLParser.close() appelle la méthode close() de target. XMLParser peut être utilisée pour autre chose que seulement construire une structure arborescente. Voici un exemple de comptage de la profondeur maximale d'un fichier XML :

>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth:                     # The target object of the parser
...     maxDepth = 0
...     depth = 0
...     def start(self, tag, attrib):   # Called for each opening tag.
...         self.depth += 1
...         if self.depth > self.maxDepth:
...             self.maxDepth = self.depth
...     def end(self, tag):             # Called for each closing tag.
...         self.depth -= 1
...     def data(self, data):
...         pass            # We do not need to do anything with data.
...     def close(self):    # Called when all data has been parsed.
...         return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
...   <b>
...   </b>
...   <b>
...     <c>
...       <d>
...       </d>
...     </c>
...   </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4

Objets XMLPullParser¶

class xml.etree.ElementTree.XMLPullParser(events=None)¶

Analyseur à flux tiré adapté aux applications non bloquantes. Son API côté entrée est similaire à celle de XMLParser, mais au lieu de pousser les appels vers une cible de rappel, XMLPullParser collecte une liste interne d'événements d'analyse et permet à l'utilisateur de la lire. events est une séquence d'événements à signaler. Les événements pris en charge sont les chaînes "start", "end", "comment", "pi", "start-ns" et "end-ns" (les événements "ns" sont utilisés pour obtenir des informations détaillées sur les espaces de noms). Si events est omis, seuls les événements "end" sont rapportés.

feed(data)¶: Transmet les données d’octets à l’analyseur.

flush()¶

Triggers parsing of any previously fed unparsed data, which can be used to ensure more immediate feedback, in particular with Expat >=2.6.0. The implementation of flush() temporarily disables reparse deferral with Expat (if currently enabled) and triggers a reparse. Disabling reparse deferral has security consequences; please see xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() for details.

Note that flush() has been backported to some prior releases of CPython as a security fix. Check for availability of flush() using hasattr() if used in code running across a variety of Python versions.

Ajouté dans la version 3.12.3.

close()¶: Signale à l'analyseur que le flux de données est terminé. Contrairement à XMLParser.close(), cette méthode renvoie toujours None. Tous les événements non encore récupérés lorsque l'analyseur est fermé peuvent toujours être lus avec read_events().

read_events()¶

Renvoie un itérateur sur les événements qui ont été rencontrés dans les données fournies à l'analyseur. L'itérateur génère des paires (event, elem), où event est une chaîne représentant le type d'événement (par exemple "end") et elem est l'objet Element rencontré, ou une autre valeur de contexte comme suit.

start, end : l'élément actuel.
comment, pi : le commentaire ou l'instruction de traitement actuel
start-ns : couple (prefix, uri) nommant la correspondance d'espace de noms déclarée.
end-ns : None (cela peut changer dans une version future)

Les événements fournis lors d'un appel précédent à read_events() ne seront plus renvoyés. Les événements sont consommés à partir de la file d'attente interne uniquement lorsqu'ils sont récupérés de l'itérateur, donc plusieurs lecteurs itérant en parallèle sur les itérateurs obtenus à partir de read_events() auront des résultats imprévisibles.

Note

XMLPullParser garantit uniquement qu'il a vu le caractère ">" d'une balise de début lorsqu'il émet un événement "start", donc les attributs sont définis, mais le contenu des attributs text et tail n'est pas défini à ce stade. La même chose s'applique aux nœuds enfants de l'élément ; ils peuvent être présents ou non.

Si vous avez besoin d'un élément entièrement rempli, recherchez plutôt les événements "end".

Ajouté dans la version 3.4.

Modifié dans la version 3.8: les évènements comment et pi ont été ajoutés.

Exceptions¶

class xml.etree.ElementTree.ParseError¶

Erreur d'analyse XML, générée par les différentes méthodes d'analyse de ce module lorsque l'analyse échoue. La représentation sous forme de chaîne d'une instance de cette exception contient un message d'erreur convivial. De plus, elle possède les attributs suivants :

code¶: Code d'erreur numérique de l'analyseur expat. Voir la documentation de xml.parsers.expat pour la liste des codes d'erreur et leur signification.

position¶: Un n-uplet de numéros de ligne et colonne indiquant le lieu d'apparition de l'erreur.

Notes

`xml.etree.ElementTree` --- The ElementTree XML API¶

Tutoriel¶

Arborescence et éléments XML¶

Analyse XML¶

API à flux tiré¶

Atteinte d'éléments d'intérêt¶

Modification d'un fichier XML¶

Création de documents XML¶

Analyse d'un XML avec des espaces de noms¶

Prise en charge de XPath¶

Exemple¶

Prise en charge de la syntaxe XPath¶

Référence¶

Fonctions¶

Prise en charge de XInclude¶

Exemple¶

Référence¶

Fonctions¶

Objets Element¶

Objets ElementTree¶

Objets QName¶

Objets TreeBuilder¶

Objets XMLParser¶

Objets XMLPullParser¶

Exceptions¶

Table des matières

Sujet précédent

Sujet suivant

Cette page

xml.etree.ElementTree --- The ElementTree XML API¶

Tutoriel¶

Arborescence et éléments XML¶

Analyse XML¶

API à flux tiré¶

Atteinte d'éléments d'intérêt¶

Modification d'un fichier XML¶

Création de documents XML¶

Analyse d'un XML avec des espaces de noms¶

Prise en charge de XPath¶

Exemple¶

Prise en charge de la syntaxe XPath¶

Référence¶

Fonctions¶

Prise en charge de XInclude¶

Exemple¶

Référence¶

Fonctions¶

Objets Element¶

Objets ElementTree¶

Objets QName¶

Objets TreeBuilder¶

Objets XMLParser¶

Objets XMLPullParser¶

Exceptions¶

`xml.etree.ElementTree` --- The ElementTree XML API¶