xml.parsers.expat — Analyse XML rapide utilisant Expat

---

Note

Si vous avez besoin d’analyser des données non sécurisées ou non authentifiées, consultez XML security.

Le module xml.parsers.expat est une interface Python pour l’analyseur XML non validant Expat. Le module fournit une seule classe, xmlparser, qui représente l’état actuel d’un analyseur XML. Après qu’un objet xmlparser a été créé, divers attributs de l’objet peuvent être définis comme fonctions de rappel. Lorsqu’un document XML est ensuite transmis à l’analyseur, les fonctions de rappel sont appelées pour les données textes et le balisage dans le document XML.

Ce module utilise le module pyexpat pour donner accès à l’analyseur Expat. L’utilisation directe du module pyexpat est obsolète.

Ce module fournit une exception et un type :

exception xml.parsers.expat.ExpatError

Exception levée lorsqu’Expat signale une erreur. Voir la section Exceptions ExpatError pour plus d’informations sur l’interprétation des erreurs Expat.

exception xml.parsers.expat.error

Alias pour ExpatError.

xml.parsers.expat.XMLParserType

Type des valeurs renvoyées par la fonction ParserCreate().

Le module xml.parsers.expat contient deux fonctions :

xml.parsers.expat.ErrorString(errno)

Renvoie une chaîne explicative pour le numéro d’erreur errno.

xml.parsers.expat.ParserCreate(encoding=None, namespace_separator=None)

Crée et renvoie un nouvel objet xmlparser. S’il est spécifié, l’argument encoding doit être une chaîne nommant l’encodage utilisé par les données XML. Expat ne prend pas en charge autant d’encodages que Python et il n’est pas possible d’en ajouter ; Expat prend en charge UTF-8, UTF-16, ISO-8859-1 (Latin1) et ASCII. Si encoding [1] est donné, il remplace l’encodage implicite ou explicite du document.

Parsers created through ParserCreate() are called "root" parsers, in the sense that they do not have any parent parser attached. Non-root parsers are created by parser.ExternalEntityParserCreate.

Si vous fournissez une valeur au paramètre namespace_separator Expat gère des espaces de noms XML pour vous. La valeur doit être une chaîne d’un caractère ; une ValueError est levée si la chaîne a une longueur illégale (None est considéré comme une omission). Lorsque la gestion des espaces de noms est activée, les noms de types d’éléments et les noms d’attributs appartenant à un espace de noms sont développés. Le nom de l’élément transmis aux fonctions de rappel StartElementHandler et EndElementHandler est la concaténation de l’URI de l’espace de noms, du caractère séparateur de l’espace de noms et de la partie locale du nom. Si le séparateur d’espace de noms est un octet de valeur zéro (chr(0)), alors l’URI de l’espace de noms et la partie locale sont concaténés sans aucun séparateur.

Par exemple, si namespace_separator est une espace (' ') et que le document suivant est analysé :

<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>

StartElementHandler recevra les chaînes suivantes pour chaque élément :

http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2

En raison des limitations de la bibliothèque Expat utilisée par pyexpat, l’instance xmlparser renvoyée ne peut être utilisée que pour analyser un seul document XML. Appelez ParserCreate pour chaque document afin de fournir des instances d’analyseur uniques.

Voir aussi

L’analyseur XML Expat

Page d’accueil du projet Expat.

Objets XMLParser

Les objets xmlparser ont les méthodes suivantes :

xmlparser.Parse(data[, isfinal])

Analyse le contenu de la chaîne data, en appelant les fonctions de rappel appropriées pour traiter les données analysées. isfinal doit être vrai lors du dernier appel à cette méthode ; elle permet l’analyse d’un seul fichier en fragments mais pas le traitement de plusieurs fichiers. data peut être une chaîne vide à tout moment.

xmlparser.ParseFile(file)

Analyse les données XML lues à partir de l’objet file. file n’a besoin de fournir que la méthode read(nbytes) renvoyant une chaîne vide lorsqu’il n’y a plus de données.

xmlparser.SetBase(base)

Définit la base à utiliser pour résoudre les URI relatifs des identifiants système dans les déclarations. La résolution des identifiants relatifs est laissée à l’application : cette valeur est transmise comme argument base aux fonctions ExternalEntityRefHandler(), NotationDeclHandler() et UnparsedEntityDeclHandler().

xmlparser.GetBase()

Renvoie une chaîne contenant la base définie par un appel précédent à SetBase(), ou None si SetBase() n’a pas été appelée.

xmlparser.GetInputContext()

Renvoie les données d’entrée qui ont généré l’événement en cours sous forme de chaîne. Les données sont dans l’encodage de l’entité qui contient le texte. Lorsqu’elle est appelée alors qu’aucune fonction de rappel n’est active, la valeur renvoyée est None.

xmlparser.ExternalEntityParserCreate(context[, encoding])

Crée un analyseur « enfant » qui peut être utilisé pour analyser une entité externe référencée par le contenu analysé par l’analyseur parent. Le paramètre context doit être la chaîne transmise à la fonction de rappel ExternalEntityRefHandler(), décrite ci-dessous. Les attributs ordered_attributes et specified_attributes sont copiés dans l’analyseur enfant.

xmlparser.SetParamEntityParsing(flag)

Contrôle l’analyse des entités de paramètres (y compris le sous-ensemble DTD externe). Les valeurs possibles pour flag sont XML_PARAM_ENTITY_PARSING_NEVER, XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE et XML_PARAM_ENTITY_PARSING_ALWAYS. Renvoie True si la définition de l’indicateur a réussi.

xmlparser.UseForeignDTD([flag])

Appeler cette fonction avec une valeur vraie pour flag (la valeur par défaut) amènera Expat à appeler le ExternalEntityRefHandler avec None pour tous les arguments afin de permettre le chargement d’une DTD alternative. Si le document ne contient pas de définition de type de document, ExternalEntityRefHandler sera quand même appelée, mais les fonctions StartDoctypeDeclHandler et EndDoctypeDeclHandler ne le seront pas.

Appeler cette fonction avec une valeur fausse pour flag annule un appel précédent qui a transmis une valeur vraie, et n’a aucun autre effet.

Cette méthode ne peut être appelée qu’avant l’appel de Parse() ou de ParseFile() ; l’appeler après que l’un ou l’autre ait été appelé provoque la levée de ExpatError avec l’attribut code valant errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING].

xmlparser.SetReparseDeferralEnabled(enabled)

Avertissement

Les implications en termes de sécurité causées par un appel à SetReparseDeferralEnabled(False) sont détaillées plus bas. Soyez certains de comprendre les conséquences avant d’utiliser la méthode SetReparseDeferralEnabled.

Expat 2.6.0 a introduit un mécanisme de sécurité appelé reparse deferral (réanalyse reportée) permettant d’éviter un déni de service causé par une explosion quadratique du temps d’exécution lors de l’analyse de grands lexèmes, la réanalyse des lexèmes non entièrement analysés est maintenant par défaut reportée jusqu’à ce qu’une quantité suffisante de donnée soit présente en entrée. À cause de ce report les fonctions de rappel peuvent ne pas être appelées immédiatement après avoir envoyé de la donnée à l'analyseur syntaxique (en fonction de la taille des morceaux de données fournis à Expat). Lorsque qu’il est souhaitable d’avoir un retour immédiat, et si vous pouvez prendre la responsabilité de protéger vous-même l'analyseur syntaxique contre cette attaque, vous pouvez appeler SetReparseDeferralEnabled(False) qui désactive le report de réanalyse pour l’instance courante, temporairement ou définitivement. Appeler SetReparseDeferralEnabled(True) active à nouveau le report de réanalyse.

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

Ajouté dans la version 3.13.

xmlparser.GetReparseDeferralEnabled()

Indique si la réanalyse reportée est activée pour l'analyseur syntaxique Expact actuel.

Ajouté dans la version 3.13.

xmlparser objects have the following methods to tune protections against some common XML vulnerabilities.

xmlparser.SetBillionLaughsAttackProtectionActivationThreshold(threshold, /)

Sets the number of output bytes needed to activate protection against billion laughs attacks.

The number of output bytes includes amplification from entity expansion and reading DTD files.

Parser objects usually have a protection activation threshold of 8 MiB, but the actual default value depends on the underlying Expat library.

An ExpatError is raised if this method is called on a non-root parser. The corresponding lineno and offset should not be used as they may have no special meaning.

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

Note

Activation thresholds below 4 MiB are known to break support for DITA 1.3 payload and are hence not recommended.

Ajouté dans la version 3.15.

xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification(max_factor, /)

Sets the maximum tolerated amplification factor for protection against billion laughs attacks.

The amplification factor is calculated as (direct + indirect) / direct while parsing, where direct is the number of bytes read from the primary document in parsing and indirect is the number of bytes added by expanding entities and reading of external DTD files.

The max_factor value must be a non-NaN float value greater than or equal to 1.0. Peak amplifications of factor 15,000 for the entire payload and of factor 30,000 in the middle of parsing have been observed with small benign files in practice. In particular, the activation threshold should be carefully chosen to avoid false positives.

Parser objects usually have a maximum amplification factor of 100, but the actual default value depends on the underlying Expat library.

An ExpatError is raised if this method is called on a non-root parser or if max_factor is outside the valid range. The corresponding lineno and offset should not be used as they may have no special meaning.

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

Note

The maximum amplification factor is only considered if the threshold that can be adjusted by SetBillionLaughsAttackProtectionActivationThreshold() is exceeded.

Ajouté dans la version 3.15.

xmlparser.SetAllocTrackerActivationThreshold(threshold, /)

Sets the number of allocated bytes of dynamic memory needed to activate protection against disproportionate use of RAM.

Parser objects usually have an allocation activation threshold of 64 MiB, but the actual default value depends on the underlying Expat library.

An ExpatError is raised if this method is called on a non-root parser. The corresponding lineno and offset should not be used as they may have no special meaning.

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

Ajouté dans la version 3.15.

xmlparser.SetAllocTrackerMaximumAmplification(max_factor, /)

Sets the maximum amplification factor between direct input and bytes of dynamic memory allocated.

The amplification factor is calculated as allocated / direct while parsing, where direct is the number of bytes read from the primary document in parsing and allocated is the number of bytes of dynamic memory allocated in the parser hierarchy.

The max_factor value must be a non-NaN float value greater than or equal to 1.0. Amplification factors greater than 100.0 can be observed near the start of parsing even with benign files in practice. In particular, the activation threshold should be carefully chosen to avoid false positives.

Parser objects usually have a maximum amplification factor of 100, but the actual default value depends on the underlying Expat library.

An ExpatError is raised if this method is called on a non-root parser or if max_factor is outside the valid range. The corresponding lineno and offset should not be used as they may have no special meaning.

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

Note

The maximum amplification factor is only considered if the threshold that can be adjusted by SetAllocTrackerActivationThreshold() is exceeded.

Ajouté dans la version 3.15.

Les objets xmlparser ont les attributs suivants :

xmlparser.buffer_size

Taille du tampon utilisé lorsque buffer_text est vrai. La taille du tampon peut être modifiée en attribuant une nouvelle valeur entière à cet attribut. Le tampon est vidé lorsque la taille est modifiée.

xmlparser.buffer_text

Lorsque buffer_text est vrai, xmlparser stocke le contenu textuel reçu d’Expat dans une mémoire tampon pour éviter les appels successifs à CharacterDataHandler() lorsque c’est possible. Cela peut améliorer les performances, Expat découpant les données textuelles ligne par ligne. Cet attribut est faux par défaut, et peut être changé à tout moment. Notez que lorsque cet attribut est faux, les données qui ne contiennent pas de retour à la ligne peuvent aussi être découpées.

xmlparser.buffer_used

Si buffer_text est activé, buffer_used donne le nombre d’octets stockés dans le tampon. Ces octets représentent du texte encodé en UTF-8. Cet attribut n’a aucune signification lorsque buffer_text est faux.

xmlparser.ordered_attributes

Lorsque ordered_attributes est un entier supérieur à zéro les attributs sont présentés sous forme de liste (plutôt que de dictionnaire) dans l’ordre indiqué dans le texte du document. Pour chaque attribut, deux entrées de liste sont présentées : le nom de l’attribut et la valeur de l’attribut (les anciennes versions de ce module utilisaient également ce format). Par défaut, cet attribut est faux ; il peut être modifié à tout moment.

xmlparser.specified_attributes

Si la valeur de specified_attributes est différente de zéro, l’analyseur ne présente que les attributs spécifiés dans l’instance du document et non ceux dérivés des déclarations d’attributs. Les applications qui définissent cela doivent être particulièrement prudentes et utiliser les informations supplémentaires disponibles dans les déclarations, selon les besoins, pour se conformer aux normes relatives au comportement des processeurs XML. Par défaut, cet attribut est faux ; il peut être modifié à tout moment.

Les attributs suivants contiennent des valeurs relatives à l’erreur la plus récente rencontrée par un objet xmlparser, et n’ont des valeurs correctes qu’une fois qu’un appel à Parse() ou ParseFile() a déclenché une exception xml.parsers.expat.ExpatError.

xmlparser.ErrorByteIndex

Indice de l’octet où une erreur s’est produite.

xmlparser.ErrorCode

Code numérique précisant le problème. Cette valeur peut être passée à la fonction ErrorString() ou comparée à une des constantes définies dans l’objet errors.

xmlparser.ErrorColumnNumber

Numéro de la colonne où une erreur s’est produite.

xmlparser.ErrorLineNumber

Numéro de la ligne sur laquelle une erreur s’est produite.

Les attributs suivants contiennent des valeurs relatives à l’emplacement d’analyse actuel dans un objet xmlparser. Lors d’un rappel signalant un événement d’analyse, ils indiquent l’emplacement du premier caractère de la séquence qui a généré l’événement. En dehors d’un rappel, la position indiquée est juste après le dernier événement d’analyse (qu’il y ait ou non un rappel associé).

xmlparser.CurrentByteIndex

Indice de l’octet actuel dans l’entrée de l’analyseur.

xmlparser.CurrentColumnNumber

Numéro de colonne actuel dans l’entrée de l’analyseur.

xmlparser.CurrentLineNumber

Numéro de ligne actuel dans l’entrée de l’analyseur.

Voici la liste des fonctions de rappel pouvant être définies. Pour définir une fonction de rappel sur un objet xmlparser o, utilisez o.handlername = func. handlername doit être extrait de la liste suivante et func doit être un objet appelable acceptant le nombre correct d’arguments. Les arguments sont tous des chaînes, sauf indication contraire.

xmlparser.XmlDeclHandler(version, encoding, standalone)

Appelée lorsque la déclaration XML est analysée. La déclaration XML est la déclaration (facultative) de la version applicable de la recommandation XML, l’encodage du texte du document et une déclaration standalone facultative. version et encoding sont des chaînes, et standalone vaut 1 si le document est déclaré autonome, 0 s’il est déclaré non autonome, ou -1 si la clause autonome a été omise. Ceci n’est disponible qu’avec la version Expat 1.95.0 ou plus récente.

xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)

Appelée lorsque Expat commence à analyser la déclaration du type de document (<!DOCTYPE ...). Le doctypeName est fourni exactement tel que présenté. Les paramètres systemId et publicId donnent les identifiants système et public s’ils sont spécifiés, ou None s’ils sont omis. has_internal_subset est vrai si le document contient un sous-ensemble de déclaration de document interne. Cela nécessite Expat version 1.2 ou plus récente.

xmlparser.EndDoctypeDeclHandler()

Appelée lorsque Expat a fini d’analyser la déclaration de type de document. Cela nécessite Expat version 1.2 ou plus récente.

xmlparser.ElementDeclHandler(name, model)

Appelée une fois pour chaque déclaration de type d’élément. name est le nom du type d’élément et model est une représentation du modèle de contenu.

xmlparser.AttlistDeclHandler(elname, attname, type, default, required)

Appelée pour chaque attribut déclaré pour un type d’élément. Si une déclaration de liste d’attributs déclare trois attributs, cette fonction de rappel est appelée trois fois, une fois pour chaque attribut. elname est le nom de l’élément auquel la déclaration s’applique et attname est le nom de l’attribut déclaré. Le type d’attribut est une chaîne passée à type ; les valeurs possibles sont 'CDATA', 'ID', 'IDREF' … default donne la valeur par défaut de l’attribut utilisé lorsque l’attribut n’est pas spécifié par l’instance de document, ou None s’il n’y a pas de valeur par défaut (valeurs #IMPLIED). Si l’attribut doit être donné dans l’instance du document, required sera vrai. Cela nécessite Expat version 1.95.0 ou plus récente.

xmlparser.StartElementHandler(name, attributes)

Appelée pour le début de chaque élément. name est une chaîne contenant le nom de l’élément et attributes sont les attributs de l’élément. Si ordered_attributes est vrai, il s’agit d’une liste (voir ordered_attributes pour une description complète). Sinon, c’est un dictionnaire faisant correspondre les noms aux valeurs.

xmlparser.EndElementHandler(name)

Appelée à la fin de chaque élément.

xmlparser.ProcessingInstructionHandler(target, data)

Appelée pour chaque instruction de traitement.

xmlparser.CharacterDataHandler(data)

Appelée pour des données textuelles. Elle sera appelée pour des données textuelles normales, du contenu CDATA, et des blancs ignorables. Les programmes qui doivent distinguer ces cas peuvent utiliser les fonctions de rappel StartCdataSectionHandler, EndCdataSectionHandler, et ElementDeclHandler pour collecter les informations requises. Notez que les données peuvent être découpées, même si elles sont courtes, ainsi votre application peut recevoir plusieurs appels à CharacterDataHandler(). Utilisez l’attribut buffer_text pour éviter ça.

xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)

Appelée pour les déclarations d’entité non analysées (NDATA). Ceci n’est présent que pour la version 1.2 de la bibliothèque Expat ; pour les versions plus récentes, utilisez plutôt EntityDeclHandler (la fonction sous-jacente de la bibliothèque Expat a été déclarée obsolète).

xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

Appelée pour toutes les déclarations d’entité. Pour les paramètres et les entités internes, value est une chaîne donnant le contenu déclaré de l’entité ; c’est None pour les entités externes. Le paramètre notationName est None pour les entités analysées, et le nom de la notation pour les entités non analysées. is_parameter_entity est vrai si l’entité est une entité paramètre ou faux pour les entités générales (la plupart des applications ne doivent se soucier que des entités générales). Ceci n’est disponible qu’à partir de la version 1.95.0 de la bibliothèque Expat.

xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)

Appelée pour les déclarations de notation. notationName, base, systemId et publicId sont des chaînes si elles sont données. Si l’identifiant public est omis, publicId est None.

xmlparser.StartNamespaceDeclHandler(prefix, uri)

Appelée lorsqu’un élément contient une déclaration d’espace de noms. Les déclarations d’espace de noms sont traitées avant que StartElementHandler soit appelée pour l’élément sur lequel les déclarations sont placées.

xmlparser.EndNamespaceDeclHandler(prefix)

Appelée lorsque la balise de fermeture est atteinte pour un élément contenant une déclaration d’espace de noms. Elle est appelée une fois pour chaque déclaration d’espace de noms sur l’élément dans l’ordre inverse de l’ordre pour lequel StartNamespaceDeclHandler a été appelé pour indiquer le début de la portée de chaque déclaration d’espace de noms. Les appels à cette fonction sont effectués après le EndElementHandler correspondant pour la fin de l’élément.

xmlparser.CommentHandler(data)

Appelée lorsqu'un commentaire est trouvé. data est le texte du commentaire, à l’exclusion de son marqueur de début '<!--' et de son marqueur de fin '-->'.

xmlparser.StartCdataSectionHandler()

Appelée au début d’une section CDATA. Elle et EndCdataSectionHandler sont nécessaires pour pouvoir identifier le début et la fin syntaxique des sections CDATA.

xmlparser.EndCdataSectionHandler()

Appelée à la fin d’une section CDATA.

xmlparser.DefaultHandler(data)

Appelée pour tous les caractères du document XML pour lesquels aucune fonction de rappel applicable n’a été spécifiée. Cela signifie des caractères qui font partie d’une construction qui pourrait être signalée, mais pour laquelle aucune fonction de rappel n’a été fournie.

xmlparser.DefaultHandlerExpand(data)

C’est la même chose que DefaultHandler(), mais n’empêche pas l’expansion des entités internes. La référence d’entité n’est pas transmise à la fonction de rappel par défaut.

xmlparser.NotStandaloneHandler()

Appelée si le document XML n’a pas été déclaré comme étant un document autonome. Cela se produit lorsqu’il existe un sous-ensemble externe ou une référence à une entité paramètre, mais que la déclaration XML ne définit pas standalone sur yes dans une déclaration XML. Si cette fonction de rappel renvoie 0, alors l’analyseur génère une erreur XML_ERROR_NOT_STANDALONE. Si cette fonction de rappel n’est pas définie, aucune exception n’est levée par l’analyseur pour cette condition.

xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)

Appelée pour des références à des entités externes. base est la base actuelle, telle que définie par un appel précédent à SetBase(). Les identifiants publics et système, systemId et publicId, sont des chaînes s’ils sont fournis ; si l’identifiant public n’est pas donné, publicId est None. La valeur context est opaque et ne doit être utilisée que comme décrit ci-dessous.

Pour que les entités externes soient analysées, cette fonction de rappel doit être implémentée. Elle est responsable de la création du sous-analyseur en utilisant ExternalEntityParserCreate(context), de son initialisation avec les fonctions de rappels appropriées et de l’analyse de l’entité. Cette fonction de rappel doit renvoyer un entier ; si elle renvoie 0, l’analyseur génère une erreur XML_ERROR_EXTERNAL_ENTITY_HANDLING, sinon l’analyse continue.

Si cette fonction de rappel n’est pas fournie, les entités externes sont signalées à la fonction DefaultHandler (si elle est fournie).

Exceptions ExpatError

Les exceptions ExpatError ont un certain nombre d’attributs intéressants :

ExpatError.code

Numéro d’erreur interne d’Expat pour l’erreur spécifique. Le dictionnaire errors.messages fait correspondre ces numéros d’erreur aux messages d’erreur d’Expat. Par exemple :

from xml.parsers.expat import ParserCreate, ExpatError, errors

p = ParserCreate()
try:
    p.Parse(some_xml_document)
except ExpatError as err:
    print("Error:", errors.messages[err.code])

Le module errors fournit également des constantes de message d’erreur et un dictionnaire codes faisant correspondre ces messages aux codes d’erreur, voir ci-dessous.

ExpatError.lineno

Numéro de ligne sur laquelle l’erreur a été détectée. La première ligne est numérotée 1.

ExpatError.offset

Colonne du caractère dans la ligne où l’erreur s’est produite. La première colonne est numérotée 0.

Exemple

Le programme suivant définit trois fonctions de rappel qui affichent simplement leurs arguments.

import xml.parsers.expat

# 3 handler functions
def start_element(name, attrs):
    print('Start element:', name, attrs)
def end_element(name):
    print('End element:', name)
def char_data(data):
    print('Character data:', repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)

Le résultat de ce programme est :

Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent

Descriptions des modèles de contenu

Les modèles de contenu sont décrits à l’aide de quadruplets imbriqués. Chaque quadruplet contient : le type, le quantificateur, le nom et un n-uplet d’enfants. Les enfants sont simplement des descriptions de modèles de contenu supplémentaires.

Les valeurs des deux premiers champs sont des constantes définies dans le module xml.parsers.expat.model. Ces constantes peuvent être collectées en deux groupes : le groupe de types de modèles et le groupe de quantificateurs.

Les constantes du groupe de types de modèle sont :

xml.parsers.expat.model.XML_CTYPE_ANY

L’élément nommé par le nom du modèle a été déclaré comme ayant un modèle de contenu de ANY.

xml.parsers.expat.model.XML_CTYPE_CHOICE

L’élément nommé permet un choix parmi un certain nombre d’options ; ceci est utilisé pour les modèles de contenu tels que (A | B | C).

xml.parsers.expat.model.XML_CTYPE_EMPTY

Les éléments déclarés EMPTY ont ce type de modèle.

xml.parsers.expat.model.XML_CTYPE_MIXED

xml.parsers.expat.model.XML_CTYPE_NAME

xml.parsers.expat.model.XML_CTYPE_SEQ

Les modèles qui représentent une série de modèles qui se succèdent sont signalés par ce type de modèle. C’est utilisé pour des modèles tels que (A, B, C).

Les constantes du groupe des quantificateurs sont :

xml.parsers.expat.model.XML_CQUANT_NONE

Aucun modificateur n’est donné, il ne doit apparaître qu’une fois et une seule, comme pour A.

xml.parsers.expat.model.XML_CQUANT_OPT

Le modèle est facultatif : il peut apparaître une fois ou pas du tout, comme pour A?.

xml.parsers.expat.model.XML_CQUANT_PLUS

Le modèle doit apparaître une ou plusieurs fois (comme A+).

xml.parsers.expat.model.XML_CQUANT_REP

Le modèle doit apparaître zéro ou plusieurs fois, comme pour A*.

Constantes d’erreur Expat

Les constantes suivantes sont fournies dans le module xml.parsers.expat.errors. Ces constantes sont utiles pour interpréter certains des attributs des exceptions ExpatError levées lorsqu’une erreur s’est produite. Puisque pour des raisons de compatibilité descendante, la valeur des constantes est l’erreur message et non l’erreur numérique code, vous faites cela en comparant son attribut code avec errors.codes[errors.XML_ERROR_ CONSTANT_NAME].

Le module erreurs a les attributs suivants :

xml.parsers.expat.errors.codes

Dictionnaire faisant correspondre les descriptions de chaînes à leurs codes d’erreur.

Ajouté dans la version 3.2.

xml.parsers.expat.errors.messages

Dictionnaire faisant correspondre les codes d’erreur numériques à leurs descriptions de chaîne.

Ajouté dans la version 3.2.

xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY

xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

Une référence d’entité dans une valeur d’attribut fait référence à une entité externe au lieu d’une entité interne.

xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF

Une référence de caractère fait référence à un caractère illégal en XML (par exemple, le caractère 0 ou �).

xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF

Une référence d’entité fait référence à une entité qui a été déclarée avec une notation et ne peut donc pas être analysée.

xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE

Un attribut a été utilisé plusieurs fois dans une balise de début.

xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING

xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN

Levée lorsqu’un octet d’entrée n’a pas pu être correctement attribué à un caractère ; par exemple, un octet NUL (valeur 0) dans un flux d’entrée UTF-8.

xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Quelque chose d’autre qu’une espace est apparu après l’élément de document.

xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI

Une déclaration XML a été trouvée ailleurs qu’au début des données d’entrée.

xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS

Le document ne contient aucun élément (XML exige que tous les documents contiennent exactement un élément de niveau supérieur).

xml.parsers.expat.errors.XML_ERROR_NO_MEMORY

Expat n’a pas pu allouer de la mémoire en interne.

xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF

Une référence d’entité de paramètre a été trouvée là où elle n’était pas autorisée.

xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR

Un caractère incomplet a été trouvé dans l’entrée.

xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF

Une référence d’entité contenait une autre référence à la même entité ; éventuellement via un nom différent, et éventuellement indirectement.

xml.parsers.expat.errors.XML_ERROR_SYNTAX

Une erreur de syntaxe non spécifiée a été rencontrée.

xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH

Une balise fermante ne correspond pas à la balise attendue.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN

Certains lexèmes (tels qu’une balise de début) n’ont pas été fermés avant la fin du flux ou le lexème suivant a été rencontré.

xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY

Une référence a été faite à une entité qui n’a pas été définie.

xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING

L’encodage du document n’est pas pris en charge par Expat.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION

Une section marquée CDATA n’a pas été fermée.

xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING

xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE

L’analyseur a déterminé que le document n’était pas « autonome » bien qu’il se soit déclaré tel dans la déclaration XML, et le NotStandaloneHandler a été défini et a renvoyé 0.

xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE

xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE

xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD

Une opération nécessite la gestion des DTD, mais Expat a été compilé sans gestion de DTD. Cela ne devrait jamais être signalé par une version standard du module xml.parsers.expat.

xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

Un changement de comportement ne pouvant être modifié qu’avant le début de l’analyse a été demandé après le début de l’analyse. Ceci n’est (actuellement) levé que par UseForeignDTD().

xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX

Un préfixe non déclaré a été trouvé lorsque le traitement de l’espace de noms a été activé.

xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX

Le document a tenté de supprimer la déclaration d’espace de noms associée à un préfixe.

xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE

Une entité paramètre contenait un balisage incomplet.

xml.parsers.expat.errors.XML_ERROR_XML_DECL

Le document ne contenait aucun élément.

xml.parsers.expat.errors.XML_ERROR_TEXT_DECL

Une erreur s’est produite lors de l’analyse d’une déclaration de texte dans une entité externe.

xml.parsers.expat.errors.XML_ERROR_PUBLICID

Des caractères non autorisés ont été trouvés dans l’identifiant public.

xml.parsers.expat.errors.XML_ERROR_SUSPENDED

L’opération demandée a été effectuée sur un analyseur suspendu, alors qu’elle n’est pas applicable sur un analyseur suspendu. Cela inclut les tentatives visant à fournir des entrées supplémentaires ou à arrêter l’analyseur.

xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED

Une tentative de reprise de l’analyseur a été effectuée alors que l’analyseur n’avait pas été suspendu.

xml.parsers.expat.errors.XML_ERROR_ABORTED

Cela ne doit pas être signalé aux applications Python.

xml.parsers.expat.errors.XML_ERROR_FINISHED

L’opération demandée a été effectuée sur un analyseur qui a fini d’analyser l’entrée, mais n’est pas autorisée. Cela inclut les tentatives visant à fournir des entrées supplémentaires ou à arrêter l’analyseur.

xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE

xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML

Tentative d’annuler la déclaration du préfixe d’espace de noms réservé xml ou de le lier à un autre URI d’espace de noms.

xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS

Tentative de déclarer ou annuler la déclaration du préfixe d’espace de noms réservé xmlns.

xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI

Tentative de lier l’URI de l’un des préfixes d’espace de noms réservés xml et xmlns à un autre préfixe d’espace de noms.

xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT

Cela ne doit pas être signalé aux applications Python.

xml.parsers.expat.errors.XML_ERROR_NO_BUFFER

Cela ne doit pas être signalé aux applications Python.

xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH

La limite du facteur d’amplification d’entrée (de la DTD et des entités) a été dépassée.

xml.parsers.expat.errors.XML_ERROR_NOT_STARTED

L’analyseur a été stoppé ou suspendu avant d’être démarré.

Ajouté dans la version 3.14.

Notes

[1]

La chaîne indiquant l’encodage dans la sortie XML doit être conforme aux normes appropriées. Par exemple, "UTF-8" est valide, mais "UTF8" ne l’est pas. Voir https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl et https://www.iana.org/assignments/character-sets/character-sets.xhtml.