"xml.sax" — Prise en charge des analyseurs SAX2
***********************************************

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

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

Le paquet "xml.sax" fournit des modules qui implémentent l'interface
*Simple API for XML (SAX)* pour Python. Le paquet en lui même fournit
les exceptions SAX et les fonctions les plus utiles qui seront le plus
utilisées par les utilisateurs de SAX API.

Avertissement:

  Le module "xml.sax" n'est pas sécurisé contre les données
  construites de façon malveillante. Si vous avez besoin d'analyser
  des données non sécurisées ou non authentifiées, voir Vulnérabilités
  XML.

Modifié dans la version 3.7.1: L'analyseur SAX ne traite plus les
entités externes générales par défaut pour augmenter la sécurité.
Auparavant, l'analyseur créait des connexions réseau pour extraire des
fichiers distants ou des fichiers locaux chargés à partir du système
de fichiers pour les DTD et les entités. La fonctionnalité peut être
activée à nouveau avec la méthode "setFeature()" sur l'objet analyseur
et l'argument "feature_external_ges".

Les fonctions les plus utiles sont:

xml.sax.make_parser(parser_list=[])

   Crée et renvoie un objet SAX "XMLReader". Le premier analyseur
   trouvé sera utilisé. Si *parser_list* est fourni, il doit être un
   itérable de chaînes de caractères qui nomme des modules qui ont une
   fonction nommée "create_parser()". Les modules listés dans
   *parser_list* seront utilisés avant les modules dans la liste par
   défaut des analyseurs.

   Modifié dans la version 3.8: L'argument *parser_list* peut être
   n'importe quel itérable, pas seulement une liste.

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

   Crée un analyseur SAX et l'utilise pour analyser un document. Le
   document transmis comme *filename_or_stream*, peut être un nom de
   fichier ou un objet fichier. Le paramètre *handler* doit être une
   instance SAX "ContentHandler". Si un *error_handler* est donné, il
   doit être un SAX "ErrorHandler" ; si omis, "SAXParseException" sera
   levé sur toutes les erreurs. Il n'y a pas de valeur de retour, tout
   le travail doit être fait par le *handler* transmis.

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

   Similaire à "parse()", mais qui analyse à partir d'un espace
   mémoire *string* reçu en tant que paramètre. *string* doit être une
   instance "str" ou un objet *bytes-like object*.

   Modifié dans la version 3.5: Ajout du support des instances "str".

Une application SAX typique utilise trois types d'objets: les
*readers*, les *handlers* et les sources d'entrée.  "Reader" dans ce
contexte est un autre terme pour le analyseur, c'est-à-dire un morceau
de code qui lit les octets ou les caractères de la source d'entrée et
qui produit une séquence d'événements. Les événements sont ensuite
distribués aux objets du *handler*, c'est-à-dire que le lecteur
appelle une méthode sur le *handler*. L'application doit donc obtenir
un objet *reader*, créer ou ouvrir les sources d'entrée, créer les
*handlers* et connecter ces objets tous ensemble. La dernière étape de
la préparation, le *reader* est appelé à analyser l'entrée. Pendant
l'analyse, les méthodes sur les objets du *handler* sont appelées en
fonction d'événements structurels et syntaxiques à partir des données
d'entrée.

Pour ces objets, seules les interfaces sont pertinentes; elles ne sont
pas normalement instanciées par l'application elle-même. Puisque
Python n'a pas de notion explicite d'interface, elles sont
formellement introduites en tant que classes, mais les applications
peuvent utiliser des implémentations qui n'héritent pas des classes
fournies. Les interfaces "InputSource", "Locator", "Attributes",
"AttributesNS", et "XMLReader" sont définies dans le module
"xml.sax.xmlreader". Les interfaces du *handler* sont définies dans
"xml.sax.handler". Pour plus de commodité,
"xml.sax.xmlreader.InputSource" (qui est souvent instancié
directement) et les classes du *handler* sont également disponibles à
partir de "xml.sax". Ces interfaces sont décrites ci-dessous.

En plus de ces classes, "xml.sax" fournit les classes d'exceptions
suivantes.

exception xml.sax.SAXException(msg, exception=None)

   Encapsule une erreur ou un avertissement XML. Cette classe peut
   contenir une erreur de base ou une information d'avertissement soit
   du analyseur XML ou de l'application: elle peut être sous-classée
   pour fournir des fonctionnalités supplémentaires ou pour ajouter
   une localisation. Noter que même si les *handlers* définis dans
   l'interface  "ErrorHandler" reçoivent des instances de cette
   exception, ce n'est pas nécessaire de lever l'exception --- il est
   également utile en tant que conteneur pour l'information.

   Quand instancié, *msg* devrait être une description lisible par
   l'homme de l'erreur. Le paramètre optionnel *exception*, s'il est
   donné, devrait être "None" ou une exception qui a été interceptée
   par le code d'analyse et qui est transmise comme information.

   Ceci est la classe de base pour les autres classes d'exception SAX.

exception xml.sax.SAXParseException(msg, exception, locator)

   Sous-classe de "SAXException" élevée sur les erreurs d'analyse. Les
   instances de cette classe sont passées aux méthodes de l'interface
   SAX "ErrorHandler" pour fournir des informations sur l'erreur
   d'analyse. Cette classe supporte aussi l'interface SAX "Locator"
   comme l'interface "SAXException".

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

   Sous-classe de "SAXException" levée quand un SAX " XMLReader" est
   confronté à une caractéristique ou à une propriété non reconnue.
   Les applications et les extensions SAX peuvent utiliser cette
   classe à des fins similaires.

exception xml.sax.SAXNotSupportedException(msg, exception=None)

   Sous-classe de "SAXException" levée quand un SAX "XMLReader" est
   demandé pour activer une fonctionnalité qui n'est pas supportée, ou
   pour définir une propriété à une valeur que l'implémentation ne
   prend pas en charge. Les applications et les extensions SAX peuvent
   utiliser cette classe à des fins similaires.

Voir aussi:

  SAX: L'API simple pour XML
     Ce site est le point focal pour la définition de l'API SAX. Il
     offre une implémentation Java et une documentation en ligne. Des
     liens pour l'implémentation et des informations historiques sont
     également disponibles.

  Module "xml.sax.handler"
     Définitions des interfaces pour les objets fournis par
     l'application.

  Module "xml.sax.saxutils"
     Fonctions pratiques pour une utilisation dans les applications
     SAX.

  Module "xml.sax.xmlreader"
     Définitions des interfaces pour les objets fournis par
     l'analyseur.


Les objets SAXException
=======================

La classe d'exception "SAXException" supporte les méthodes suivantes :

SAXException.getMessage()

   Renvoyer un message lisible par l'homme  décrivant la condition
   d'erreur.

SAXException.getException()

   Renvoie un objet d'exception encapsulé, ou "None".
