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 namedcreate_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 SAXErrorHandler
; 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 SAXErrorHandler
pour fournir des informations sur l’erreur d’analyse. Cette classe supporte aussi l’interface SAXLocator
comme l’interfaceSAXException
.
-
exception
xml.sax.
SAXNotRecognizedException
(msg[, exception])¶ Sous-classe de
SAXException
levée quand un SAXXMLReader
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 SAXXMLReader
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``.