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 |
---|---|
|
Sélectionne tous les éléments enfants avec une balise donnée. Par exemple, 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, |
|
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, |
|
Sélectionne l'élément parent. Renvoie |
|
Sélectionne tous les éléments qui ont l'attribut donné. |
|
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 ( |
|
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. |
|
Sélectionne tous les éléments qui ont un enfant nommé |
|
Sélectionne tous les éléments dont le contenu textuel complet, y compris les descendants, est égal au Ajouté dans la version 3.7. |
|
Sélectionne tous les éléments dont le contenu textuel complet, y compris les descendants, n'est pas égal au Ajouté dans la version 3.10. |
|
Sélectionne tous les éléments qui ont un enfant nommé |
|
Sélectionne tous les éléments qui ont un enfant nommé Ajouté dans la version 3.10. |
|
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 |
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. UnElementTree
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 standardXMLParser
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 standardXMLParser
parser is used. parser must be a subclass ofXMLParser
and can only use the defaultTreeBuilder
as a target. Returns an iterator providing(event, elem)
pairs; it has aroot
attribute that references the root element of the resulting XML tree once source is fully read. The iterator has theclose()
method that closes the internal file object if source is a filename.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, voirXMLPullParser
.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
etpi
ont été ajoutés.Modifié dans la version 3.13: Added the
close()
method.
- 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. AnElementTree
will only contain processing instruction nodes if they have been inserted into to the tree using one of theElement
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). Utilisezencoding="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 dansElementTree.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). Utilisezencoding="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 dansElementTree.write()
. Renvoie une liste de chaînes codées (éventuellement) contenant les données XML. Elle ne garantit aucune séquence spécifique, seulementb"".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 anElement
instance. If the parse mode is"text"
, this is a string. If the loader fails, it can returnNone
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 anElementTree
instance to find such element. loader is an optional resource loader. If omitted, it defaults todefault_loader()
. If given, it should be a callable that implements the same interface asdefault_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. PassNone
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, soitNone
. 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 vautNone
, et l'attribut text de l'élément d vautNone
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 unElement
.
- extend(subelements)¶
Appends subelements from an iterable of elements. Raises
TypeError
if a subelement is not anElement
.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 unElement
.
- 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 asTrue
regardless of whether subelements exist. Instead, prefer explicitlen(elem)
orelem 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 estNone
). 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'estTrue
(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()
etProcessingInstruction()
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éthodefeed()
, 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, leTreeBuilder
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 seexml.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 offlush()
usinghasattr()
if used in code running across a variety of Python versions.Ajouté dans la version 3.13.
XMLParser.feed()
appelle la méthodestart(tag, attrs_dict)
de target pour chaque balise d'ouverture, sa méthodeend(tag)
pour chaque balise de fermeture, et les données sont traitées par la méthodedata(data)
. Pour d'autres méthodes de rappel prises en charge, consultez la classeTreeBuilder
.XMLParser.close()
appelle la méthodeclose()
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 seexml.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 offlush()
usinghasattr()
if used in code running across a variety of Python versions.Ajouté dans la version 3.13.
- close()¶
Signale à l'analyseur que le flux de données est terminé. Contrairement à
XMLParser.close()
, cette méthode renvoie toujoursNone
. Tous les événements non encore récupérés lorsque l'analyseur est fermé peuvent toujours être lus avecread_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'objetElement
rencontré, ou une autre valeur de contexte comme suit.start
,end
: l'élément actuel.comment
,pi
: le commentaire ou l'instruction de traitement actuelstart-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 deread_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
etpi
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