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

Nouveau dans la version 2.0.

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.

Les fonctions les plus utiles sont:

xml.sax.make_parser([parser_list])

   Create and return a SAX "XMLReader" object.  The first parser found
   will be used.  If *parser_list* is provided, it must be a list of
   strings which name modules that have a function named
   "create_parser()".  Modules listed in *parser_list* will be used
   before modules in the default list of parsers.

xml.sax.parse(filename_or_stream, handler[, error_handler])

   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])

   Similar to "parse()", but parses from a buffer *string* received as
   a parameter.

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])

   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])

   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])

   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.


19.11.1. 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``.
