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

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

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)

   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)

   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. This requires Expat version
   1.2 or newer.

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.

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

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
=========================

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

   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

   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

   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.
