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.

The convenience functions and data are:

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, errorHandler=handler.ErrorHandler())

Create a SAX parser and use it to parse a document. The document, passed in as filename_or_stream, can be a system identifier (a string identifying the input source -- typically a file name or a URL), a path-like object, or a file object. A system identifier which does not refer to an existing file is opened with urllib.request.urlopen(). The handler parameter needs to be a SAX ContentHandler instance. If errorHandler is given, it must be a SAX ErrorHandler instance; if omitted, SAXParseException will be raised on all errors. There is no return value; all work must be done by the handler passed in.

xml.sax.parseString(string, handler, errorHandler=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.

xml.sax.default_parser_list

The list of the names of modules which are tried by make_parser() after the modules named in its parser_list argument. It contains 'xml.sax.expatreader', or, if the PY_SAX_PARSER environment variable is set and the environment is not ignored, the comma-separated list of module names taken from it.

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.

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

Subclass of SAXNotSupportedException raised when no parser is available. A parser module raises it when it is imported or during parsing if the parser it provides cannot be used, and make_parser() raises it if no module from the tried ones provides a usable parser.

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.