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

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, lisez 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 `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 --- il 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`.