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.

The xml.parsers.expat module is a Python interface to the Expat non-validating XML parser. The module provides a single extension type, xmlparser, that represents the current state of an XML parser. After an xmlparser object has been created, various attributes of the object can be set to handler functions. When an XML document is then fed to the parser, the handler functions are called for the character data and markup in the XML document.

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

This module provides the following exception, type object and data items:

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().

xml.parsers.expat.EXPAT_VERSION

The version string of the Expat library loaded by the interpreter, like 'expat_2.8.4'.

xml.parsers.expat.version_info

The version of the Expat library loaded by the interpreter, as a tuple of three integers: major, minor and micro version.

xml.parsers.expat.features

The list of the features with which the loaded Expat library was compiled, as (name, value) pairs. The value is only meaningful for features which have one, like 'XML_CONTEXT_BYTES' or the default protection limits 'XML_BLAP_ACT_THRES' and 'XML_AT_MAX_AMP'; for other features, like 'XML_DTD' and 'XML_NS', the value is 0 and only the presence of the name is significant.

The xml.parsers.expat module contains two functions:

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, intern=None)

Creates and returns a new xmlparser object. encoding [1], if specified, must be a string naming the encoding used by the XML data. If it is given it will override the implicit or explicit encoding of the document.

Particularité de l'implémentation CPython : Expat natively understands and processes UTF-8, UTF-16, UTF-16BE, UTF-16LE, ISO-8859-1, and US-ASCII. For other encodings (including aliases like Latin1 and ASCII) it falls back to Python. It supports most of 8-bit encodings and many multi-byte encodings like Shift_JIS, although only BMP characters (U+0000-U+FFFF) are supported with non-native encodings (this restriction is also applied to aliases like UTF8). These restrictions only apply if encoding is not given.

Modifié dans la version 3.16.0a0 (unreleased): Added support for multi-byte encodings.

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

intern, if given, must be a dictionary. It is used to intern the names of elements and attributes, and is available as the intern attribute. By default a new empty dictionary is created for every parser.

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])

Parses the contents of data, calling the appropriate handler functions to process the parsed data. data can be a bytes-like object or a string. If it is a string, the encoding declaration in the XML data is ignored, and the data is parsed as already decoded text. isfinal must be true on the final call to this method; it allows the parsing of a single file in fragments, not the submission of multiple files. data can be empty at any time.

xmlparser.ParseFile(file)

Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, which returns bytes, and an empty bytes object when there's no more data. Text files are not supported; use Parse() for data which is already decoded.

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.GetSpecifiedAttributeCount()

Return the index just past the attributes given in the start tag. Attributes defaulted from the DTD follow the specified ones, so attributes at lower indices in the list passed to StartElementHandler were given in the start tag. Each attribute takes two items in that list, its name and its value. Only meaningful inside a StartElementHandler call, and only if ordered_attributes is true.

Ajouté dans la version 3.16.0a0 (unreleased).

xmlparser.GetInputContext()

Returns the input data which generated the current event as a bytes object. The data is in the encoding of the entity which contains the text. It extends to the end of the currently buffered input, therefore it can contain also the data of the following events, and if the event was generated by a large amount of text, not all of it may be available. When called while an event handler is not active, the return value is 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.

xmlparser.intern

The dictionary used to intern the names of elements and attributes. It is either the dictionary passed as the intern argument of ParserCreate(), or a new dictionary created for this parser.

xmlparser.namespace_prefixes

If set to a true value, and namespace processing is enabled, the namespace prefix is reported as the third part of the expanded name, separated by the namespace separator. Names which have no prefix are not affected. By default, this attribute is false; it may be changed at any time.

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)

Called when the XML declaration is parsed. The XML declaration is the (optional) declaration of the applicable version of the XML recommendation, the encoding of the document text, and an optional "standalone" declaration. version and encoding will be strings, and standalone will be 1 if the document is declared standalone, 0 if it is declared not to be standalone, or -1 if the standalone clause was omitted.

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

Called when Expat begins parsing the document type declaration (<!DOCTYPE ...). The doctypeName is provided exactly as presented. The systemId and publicId parameters give the system and public identifiers if specified, or None if omitted. has_internal_subset will be true if the document contains an internal document declaration subset.

xmlparser.EndDoctypeDeclHandler()

Called when Expat is done parsing the document type declaration.

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)

Called for each declared attribute for an element type. If an attribute list declaration declares three attributes, this handler is called three times, once for each attribute. elname is the name of the element to which the declaration applies and attname is the name of the attribute declared. The The attribute type is a string passed as type: 'CDATA', 'ID', 'IDREF', 'IDREFS', 'ENTITY', 'ENTITIES', 'NMTOKEN' or 'NMTOKENS', an enumeration like '(x|y)', or a notation list like 'NOTATION(n1|n2)'. default gives the default value for the attribute used when the attribute is not specified by the document instance, or None if there is no default value (#IMPLIED values). If the attribute is required to be given in the document instance, required will be true.

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)

Called for unparsed (NDATA) entity declarations. If this handler is not set, such declarations are reported by EntityDeclHandler, which is preferred for new code. (The underlying function in the Expat library has been declared obsolete.)

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

Called for all entity declarations. For parameter and internal entities, value will be a string giving the declared contents of the entity; this will be None for external entities. The notationName parameter will be None for parsed entities, and the name of the notation for unparsed entities. is_parameter_entity will be true if the entity is a parameter entity or false for general entities (most applications only need to be concerned with general entities).

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)

This is the same as the DefaultHandler, but doesn't inhibit expansion of internal entities. The entity reference will not be passed to the default handler.

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).

xmlparser.SkippedEntityHandler(entityName, is_parameter_entity)

Called for entity references which are not expanded, because the parser did not read the declaration of the entity. This happens when the external DTD subset or an external parameter entity is not parsed. is_parameter_entity is true for a parameter entity and false for a general entity.

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.

The values of the first two fields are constants defined in the xml.parsers.expat.model module. These constants can be collected in two groups: the model type group and the quantifier group.

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

The named element allows character data, optionally interspersed with the named children; this is used for content models such as (#PCDATA) and (#PCDATA | A | B)*.

xml.parsers.expat.model.XML_CTYPE_NAME

The model names a single element, as for A.

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

The following constants are provided in the xml.parsers.expat.errors module. These constants are useful in interpreting some of the attributes of the ExpatError exception objects raised when an error has occurred. Since for backwards compatibility reasons, the constants' value is the error message and not the numeric error code, you do this by comparing its code attribute with 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

The document contains no elements (XML requires all documents to contain exactly one top-level element).

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

An operation was requested that requires DTD support to be compiled in, but Expat was configured without DTD support. This should never be reported by a standard build of the xml.parsers.expat module.

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

There was an error parsing the XML declaration.

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]

The encoding string included in XML output should conform to the appropriate standards. For example, "UTF-8" is valid, but "UTF8" is not valid in an XML document's declaration, even though Python accepts it as an encoding name. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and https://www.iana.org/assignments/character-sets/character-sets.xhtml.