"xml.sax" --- Support for SAX2 parsers
**************************************

**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 sont le plus
utilisées par les utilisateurs de l'API *SAX*.

Note:

  If you need to parse untrusted or unauthenticated data, see XML
  security.

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 "XMLReader" *SAX*. Le premier analyseur
   trouvé est 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* sont 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 "ContentHandler" *SAX*. Si un *error_handler* est donné,
   il doit être un "ErrorHandler" *SAX* ; s'il est omis, une
   "SAXParseException" est levée 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 analyse à partir d'un espace mémoire
   *string* reçu en tant que paramètre. *string* doit être une
   instance "str" ou un objet *octet-compatible*.

   Modifié dans la version 3.5: ajout de la gestion 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 « 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ée
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
   de l'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, elle est
   également utile en tant que conteneur pour l'information.

   Quand elle est instanciée, *msg* doit être une description
   intelligible de l'erreur. Le paramètre optionnel *exception*, s'il
   est donné, doit ê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
   "ErrorHandler" *SAX* pour fournir des informations sur l'erreur
   d'analyse. Cette classe prend aussi en charge l'interface *SAX*
   "Locator" comme l'interface "SAXException".

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

   Sous-classe de "SAXException" levée quand un " XMLReader" *SAX* 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 "XMLReader" *SAX* est
   demandé pour activer une fonctionnalité qui n'est pas prise en
   charge, 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" gère les méthodes suivantes :

SAXException.getMessage()

   Renvoie un message intelligible décrivant la condition d'erreur.

SAXException.getException()

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