"xml.sax.handler" --- Base classes for SAX handlers
***************************************************

**Code source :** Lib/xml/sax/handler.py

======================================================================

L'API *SAX* définit cinq types de gestionnaires : les gestionnaires de
contenu, les gestionnaires de *DTD*, les gestionnaires d'erreurs, les
résolveurs d'entités et les gestionnaires lexicaux. Les applications
n'ont normalement besoin d'implémenter que les interfaces dont les
événements les intéressent ; elles peuvent implémenter les interfaces
dans un seul objet ou dans plusieurs objets. Les implémentations de
gestionnaires doivent hériter des classes mères fournies dans le
module "xml.sax.handler", afin que toutes les méthodes aient des
implémentations par défaut.

class xml.sax.handler.ContentHandler

   Il s'agit de l'interface de rappel principale de *SAX* et de la
   plus importante pour les applications. L'ordre des événements dans
   cette interface reflète l'ordre des informations dans le document.

class xml.sax.handler.DTDHandler

   Gestionnaires d'évènements *DTD*

   Cette interface concerne uniquement les événements *DTD* requis
   pour une analyse basique (entités et attributs non analysés).

class xml.sax.handler.EntityResolver

   Interface de base pour résoudre les entités. Si vous créez un objet
   implémentant cette interface, puis enregistrez l'objet auprès de
   votre analyseur, l'analyseur appellera la méthode de votre objet
   pour résoudre toutes les entités externes.

class xml.sax.handler.ErrorHandler

   Interface utilisée par l'analyseur pour présenter des messages
   d'erreur et d'avertissement à l'application. Les méthodes de cet
   objet permettent de choisir si les erreurs doivent être
   immédiatement converties en exceptions ou si elles doivent être
   traitées d'une autre manière.

class xml.sax.handler.LexicalHandler

   Interface utilisée par l'analyseur pour représenter des événements
   rares qui n'intéressent que peu d'applications.

En plus de ces classes, "xml.sax.handler" fournit des constantes
symboliques pour les noms de fonctionnalités et de propriétés.

xml.sax.handler.feature_namespaces

      valeur : ""http://xml.org/sax/features/namespaces""
      vrai : effectue le traitement de l'espace de noms.
      faux : n'effectue pas le traitement des espaces de noms (implique *namespace-prefixes* ; valeur par défaut).
      accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture

xml.sax.handler.feature_namespace_prefixes

      valeur : ""http://xml.org/sax/features/namespace-prefixes""
      vrai : renvoie les noms et attributs avec les préfixes originaux utilisés dans les déclarations d'espaces de noms.
      faux : ne renvoie pas les attributs utilisés pour les déclarations d'espaces de noms et, éventuellement, ne signale pas les noms avec les préfixes originaux (par défaut).
      accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture

xml.sax.handler.feature_string_interning

      valeur : ""http://xml.org/sax/features/string-interning""
      vrai : tous les noms d'éléments, préfixes, noms d'attributs, URI d'espace de noms et noms locaux sont rendus internes à l'aide de la fonction native correspondante.
      faux : les noms ne sont pas nécessairement rendus internes, bien qu'ils puissent l'être (par défaut).
      accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture

xml.sax.handler.feature_validation

      valeur : ""http://xml.org/sax/features/validation""
      vrai : signale toutes les erreurs de validation (implique *external-general-entities* et *external-parameter-entities*).
      faux : ne signale pas les erreurs de validation.
      accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture

xml.sax.handler.feature_external_ges

      valeur : ""http://xml.org/sax/features/external-general-entities""
      vrai : Inclut toutes les entités générales (texte) externes.
      faux : n'inclut pas les entités générales externes.
      accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture

xml.sax.handler.feature_external_pes

      valeur : ""http://xml.org/sax/features/external-parameter-entities""
      vrai : Inclut toutes les entités de paramètres externes, y compris les sous-ensembles *DTD* externes.
      faux : n'inclue aucune entité de paramètre externe, même les sous-ensembles *DTD* externes.
      accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture

xml.sax.handler.all_features

   Liste de toutes les fonctionnalités.

xml.sax.handler.property_lexical_handler

      valeur : ""http://xml.org/sax/properties/lexical-handler""
      type de données : "xml.sax.handler.LexicalHandler" (non pris en charge dans Python 2)
      description : gestionnaire d'extension facultatif pour les événements lexicaux tels que les commentaires.
      accès : lecture-écriture

xml.sax.handler.property_declaration_handler

      valeur : ""http://xml.org/sax/properties/declaration-handler""
      type de données : xml.sax.sax2lib.DeclHandler (non pris en charge dans Python 2)
      description : gestionnaire d'extension facultatif pour les événements liés à la *DTD* autres que les notations et les entités non analysées.
      accès : lecture-écriture

xml.sax.handler.property_dom_node

      valeur : ""http://xml.org/sax/properties/dom-node""
      type de données : org.w3c.dom.Node (non pris en charge dans Python 2)
      description : lors de l'analyse, le nœud DOM actuel visité s'il s'agit d'un itérateur DOM ; hors de l'analyse, le nœud racine du DOM pour l'itération.
      accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture

xml.sax.handler.property_xml_string

      valeur : ""http://xml.org/sax/properties/xml-string""
      type de données : octets
      description : chaîne littérale de caractères qui était la source de l'événement en cours.
      accès : lecture seule

xml.sax.handler.all_properties

   Liste de tous les noms de propriétés connus.


Objets *ContentHandler*
=======================

Les utilisateurs doivent sous-classer "ContentHandler" dans leur
application. Les méthodes suivantes sont appelées par l'analyseur pour
notifier les événements appropriés dans le document d'entrée :

ContentHandler.setDocumentLocator(locator)

   Appelé par l'analyseur pour donner à l'application un localisateur
   permettant de localiser l'origine des événements du document.

   Les analyseurs *SAX* sont fortement encouragés (bien que ce ne soit
   pas absolument obligatoire) à fournir un localisateur : s'ils le
   font, ils doivent fournir le localisateur à l'application en
   appelant cette méthode avant d'invoquer l'une des autres méthodes
   de l'interface *DocumentHandler*.

   Le localisateur permet à l'application de déterminer la position
   finale de tout événement lié au document, même si l'analyseur ne
   signale pas d'erreur. En règle générale, l'application utilise ces
   informations pour signaler ses propres erreurs (telles que le
   contenu d'un champ texte qui ne correspond pas aux règles métier
   d'une application). Les informations renvoyées par le localisateur
   ne sont probablement pas suffisantes pour être utilisées avec un
   moteur de recherche.

   Notez que le localisateur renvoie des informations correctes
   pendant la durée de l'invocation des événements dans cette
   interface. L'application ne doit pas tenter de l'utiliser à un
   autre moment.

ContentHandler.startDocument()

   Reçoit la notification correspondant au début du document.

   L'analyseur *SAX* invoque cette méthode une seule fois, avant toute
   autre méthode dans cette interface ou dans *DTDHandler* (sauf pour
   "setDocumentLocator()").

ContentHandler.endDocument()

   Reçoit la notification correspondant à la fin du document.

   L'analyseur *SAX* n'invoque cette méthode qu'une seule fois et
   c'est la dernière méthode invoquée lors de l'analyse. L'analyseur
   ne doit pas invoquer cette méthode tant qu'il n'a pas abandonné
   l'analyse (en raison d'une erreur irrécupérable) ou atteint la fin
   de l'entrée.

ContentHandler.startPrefixMapping(prefix, uri)

   Commence la portée d’une correspondance d’espace de noms préfixe-
   URI.

   Les informations de cet événement ne sont pas nécessaires au
   traitement normal des espaces de noms : le lecteur XML *SAX*
   remplace automatiquement les préfixes des noms d'éléments et
   d'attributs lorsque la fonctionnalité "feature_namespaces" est
   activée (la valeur par défaut).

   Il existe cependant des cas où les applications doivent utiliser
   des préfixes dans des champs textes ou dans les valeurs d'attribut,
   où ils ne peuvent pas être développés automatiquement en toute
   sécurité ; les événements "startPrefixMapping()" et
   "endPrefixMapping()" fournissent les informations à l'application
   pour développer elle-même les préfixes dans ces contextes, si
   nécessaire.

   Notez qu'il n'est pas garanti que les événements
   "startPrefixMapping()" et "endPrefixMapping()" soient correctement
   imbriqués les uns par rapport aux autres : tout événement
   "startPrefixMapping()" se produit avant l'événement
   "startElement()" correspondant, et tout événement
   "endPrefixMapping()" se produit après l'événement "endElement()"
   correspondant, mais leur ordre n'est pas garanti.

ContentHandler.endPrefixMapping(prefix)

   Termine la portée d’une correspondance préfixe-URI.

   Voir "startPrefixMapping()" pour plus de détails. Cet événement se
   produit toujours après l'événement "endElement()" correspondant,
   mais l'ordre des événements "endPrefixMapping()" n'est pas garanti
   entre eux.

ContentHandler.startElement(name, attrs)

   Signale le début d’un élément en mode sans espaces de noms.

   Le paramètre *name* contient le nom brut XML 1.0 du type d'élément
   sous forme de chaîne et le paramètre *attrs* contient un objet de
   l'interface "Attributes" (voir The Attributes Interface) contenant
   les attributs de l'élément. L'objet passé comme *attrs* peut être
   réutilisé par l'analyseur ; conserver une référence à celui-ci
   n’est pas un moyen fiable de conserver une copie des attributs.
   Pour conserver une copie des attributs, utilisez la méthode
   "copy()" de l'objet *attrs*.

ContentHandler.endElement(name)

   Signale la fin d'un élément en mode sans espaces de noms.

   Le paramètre *name* contient le nom du type d'élément, tout comme
   pour l'événement "startElement()".

ContentHandler.startElementNS(name, qname, attrs)

   Signale le début d’un élément en mode avec espaces de noms.

   Le paramètre *name* contient le nom du type d'élément sous forme de
   *n*-uplet "(uri, localname)", le paramètre *qname* contient le nom
   XML 1.0 brut utilisé dans le document source et le paramètre
   *attrs* contient une instance de l'interface "AttributesNS" (voir
   The AttributesNS Interface) contenant les attributs de l'élément.
   Si aucun espace de noms n'est associé à l'élément, le composant
   *uri* de *name* est "None". L'objet passé comme *attrs* peut être
   réutilisé par l'analyseur ; conserver une référence à celui-ci
   n’est pas un moyen fiable de conserver une copie des attributs.
   Pour conserver une copie des attributs, utilisez la méthode
   "copy()" de l'objet *attrs*.

   Les analyseurs peuvent définir le paramètre *qname* à "None", à
   moins que la fonctionnalité "feature_namespace_prefixes" ne soit
   activée.

ContentHandler.endElementNS(name, qname)

   Signale la fin d'un élément en mode avec espaces de noms.

   Le paramètre *name* contient le nom du type d'élément, tout comme
   avec la méthode "startElementNS()", de même que le paramètre
   *qname*.

ContentHandler.characters(content)

   Reçoit une notification correspondant à des données de type
   caractère.

   L'analyseur appelle cette méthode pour signaler chaque morceau de
   données de caractères. Les analyseurs *SAX* peuvent renvoyer toutes
   les données de caractères contiguës en un seul morceau ou ils
   peuvent les diviser en plusieurs morceaux ; cependant, tous les
   caractères d'un événement doivent provenir de la même entité
   externe afin que le localisateur fournisse des informations utiles.

   *content* peut être une instance de chaîne ou d'octets ; le module
   lecteur "expat" produit toujours des chaînes.

   Note:

     l'interface *SAX 1* précédente fournie par Python XML utilisait
     une interface plus proche de Java pour cette méthode. Étant donné
     que la plupart des analyseurs utilisés à partir de Python ne
     tiraient pas parti de l’ancienne interface, la signature la plus
     simple a été choisie pour la remplacer. Pour convertir l'ancien
     code vers la nouvelle interface, utilisez *content* au lieu de
     découper le contenu avec les anciens paramètres *offset* et
     *length*.

ContentHandler.ignorableWhitespace(whitespace)

   Reçoit une notification en cas d'espaces pouvant être ignorées dans
   le contenu de l'élément.

   Les analyseurs validateurs doivent utiliser cette méthode pour
   signaler chaque morceau d'espaces pouvant être ignorées (voir la
   recommandation W3C XML 1.0, section 2.10) : les analyseurs non
   validateurs peuvent également utiliser cette méthode s'ils sont
   capables d'analyser et d'utiliser des modèles de contenu.

   Les analyseurs *SAX* peuvent renvoyer tous les espaces contigües en
   un seul morceau ou ils peuvent le diviser en plusieurs morceaux ;
   cependant, tous les caractères d'un événement doivent provenir de
   la même entité externe, afin que le localisateur fournisse des
   informations utiles.

ContentHandler.processingInstruction(target, data)

   Reçoit une notification correspondant à une instruction de
   traitement.

   L'analyseur invoque cette méthode une fois pour chaque instruction
   de traitement trouvée : notez que les instructions de traitement
   peuvent survenir avant ou après l'élément principal du document.

   Un analyseur *SAX* ne doit jamais rapporter une déclaration XML
   (XML 1.0, section 2.8) ou une déclaration texte (XML 1.0, section
   4.3.1) en utilisant cette méthode.

ContentHandler.skippedEntity(name)

   Reçoit une notification correspondant à une entité ignorée.

   L'analyseur invoque cette méthode une fois pour chaque entité
   ignorée. Les processeurs non validateurs peuvent ignorer les
   entités s'ils n'ont pas vu les déclarations (parce que, par
   exemple, l'entité a été déclarée dans un sous-ensemble *DTD*
   externe). Tous les processeurs peuvent ignorer les entités
   externes, en fonction des valeurs des propriétés
   "feature_external_ges" et "feature_external_pes".


Objets *DTDHandler*
===================

Les instances "DTDHandler" fournissent les méthodes suivantes :

DTDHandler.notationDecl(name, publicId, systemId)

   Gère un événement de déclaration de notation.

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

   Gère un événement de déclaration d'entité non analysé.


Objets *EntityResolver*
=======================

EntityResolver.resolveEntity(publicId, systemId)

   Résout l'identifiant système d'une entité et renvoie soit
   l'identifiant système à partir duquel lire sous forme de chaîne,
   soit un *InputSource* à partir duquel lire. L'implémentation par
   défaut renvoie *systemId*.


Objets *ErrorHandler*
=====================

Objects with this interface are used to receive error and warning
information from the "XMLReader".  If you create an object that
implements this interface, then register the object with your
"XMLReader", the parser will call the methods in your object to report
all warnings and errors. There are three levels of errors available:
warnings, (possibly) recoverable errors, and unrecoverable errors.
All methods take a "SAXParseException" as the only parameter.  Errors
and warnings may be converted to an exception by raising the passed-in
exception object.

ErrorHandler.error(exception)

   Appelée lorsque l'analyseur rencontre une erreur récupérable. Si
   cette méthode ne génère pas d'exception, l'analyse peut continuer,
   mais l'application ne doit pas attendre d'autres informations
   concernant le document. Autoriser l'analyseur à continuer peut
   permettre de découvrir des erreurs supplémentaires dans le document
   d'entrée.

ErrorHandler.fatalError(exception)

   Appelée lorsque l'analyseur rencontre une erreur irrécupérable ;
   l'analyse devrait se terminer au retour de cette méthode.

ErrorHandler.warning(exception)

   Appelée lorsque l'analyseur présente des informations
   d'avertissement mineures à l'application. L'analyse devrait se
   poursuivre lorsque cette méthode termine et les informations du
   document continueront d'être transmises à l'application. La levée
   d’une exception dans cette méthode entraîne la fin de l’analyse.


Objets *LexicalHandler*
=======================

Gestionnaire *SAX2* facultatif pour les événements lexicaux.

Ce gestionnaire est utilisé pour obtenir des informations lexicales
relatives à un document XML. Les informations lexicales incluent des
informations décrivant le codage du document utilisé et les
commentaires XML intégrés dans le document, ainsi que les limites des
sections pour la *DTD* et pour toutes les sections *CDATA*. Les
gestionnaires lexicaux sont utilisés de la même manière que les
gestionnaires de contenu.

Définissez le *LexicalHandler* d'un *XMLReader* en utilisant la
méthode *setProperty* avec l'identifiant de propriété
"'http://xml.org/sax/properties/lexical-handler'".

LexicalHandler.comment(content)

   Signale un commentaire n'importe où dans le document (y compris la
   *DTD* et en dehors de l'élément de document).

LexicalHandler.startDTD(name, public_id, system_id)

   Signale le début des déclarations *DTD* si le document a une *DTD*
   associée.

LexicalHandler.endDTD()

   Signale la fin de la déclaration de la *DTD*.

LexicalHandler.startCDATA()

   Signale le début d’une section marquée *CDATA*.

   Le contenu de la section marquée *CDATA* est signalé via le
   gestionnaire de données de type caractère.

LexicalHandler.endCDATA()

   Signale la fin d’une section marquée *CDATA*.
