# `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)

  Avertissement

  Implementing a handler that accesses local files and/or the network may create a vulnerability to external entity attacks if `xmlparser` is used with user-provided XML content. Please reflect on your threat model before implementing this handler.

  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 `&#0;`).

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.