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

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

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

The "xml.sax" package provides a number of modules which implement the
Simple API for XML (SAX) interface for Python.  The package itself
provides the SAX exceptions and the convenience functions which will
be most used by users of the SAX API.

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.

For these objects, only the interfaces are relevant; they are normally
not instantiated by the application itself.  Since Python does not
have an explicit notion of interface, they are formally introduced as
classes, but applications may use implementations which do not inherit
from the provided classes.  The "InputSource", "Locator",
"Attributes", "AttributesNS", and "XMLReader" interfaces are defined
in the module "xml.sax.xmlreader".  The handler interfaces are defined
in "xml.sax.handler".  For convenience, "InputSource" (which is often
instantiated directly) and the handler classes are also available from
"xml.sax".  These interfaces are described below.

In addition to these classes, "xml.sax" provides the following
exception classes.

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