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

   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

   *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.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 "&#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

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