xml.sax.handler — Classes mères pour les gestionnaires SAX

Code source : Lib/xml/sax/handler.py

L'API SAX définit cinq types de gestionnaires : les gestionnaires de contenu, les gestionnaires de DTD, les gestionnaires d'erreurs, les résolveurs d'entités et les gestionnaires lexicaux. Les applications n'ont normalement besoin d'implémenter que les interfaces dont les événements les intéressent ; elles peuvent implémenter les interfaces dans un seul objet ou dans plusieurs objets. Les implémentations de gestionnaires doivent hériter des classes mères fournies dans le module xml.sax.handler, afin que toutes les méthodes aient des implémentations par défaut.

class xml.sax.handler.ContentHandler

Il s'agit de l'interface de rappel principale de SAX et de la plus importante pour les applications. L'ordre des événements dans cette interface reflète l'ordre des informations dans le document.

class xml.sax.handler.DTDHandler

Gestionnaires d'évènements DTD

Cette interface concerne uniquement les événements DTD requis pour une analyse basique (entités et attributs non analysés).

class xml.sax.handler.EntityResolver

Interface de base pour résoudre les entités. Si vous créez un objet implémentant cette interface, puis enregistrez l'objet auprès de votre analyseur, l'analyseur appellera la méthode de votre objet pour résoudre toutes les entités externes.

class xml.sax.handler.ErrorHandler

Interface utilisée par l'analyseur pour présenter des messages d'erreur et d'avertissement à l'application. Les méthodes de cet objet permettent de choisir si les erreurs doivent être immédiatement converties en exceptions ou si elles doivent être traitées d'une autre manière.

class xml.sax.handler.LexicalHandler

Interface utilisée par l'analyseur pour représenter des événements rares qui n'intéressent que peu d'applications.

En plus de ces classes, xml.sax.handler fournit des constantes symboliques pour les noms de fonctionnalités et de propriétés.

xml.sax.handler.feature_namespaces
valeur : "http://xml.org/sax/features/namespaces"
vrai : effectue le traitement de l'espace de noms.
faux : n'effectue pas le traitement des espaces de noms (implique namespace-prefixes ; valeur par défaut).
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture
xml.sax.handler.feature_namespace_prefixes
valeur : "http://xml.org/sax/features/namespace-prefixes"
vrai : renvoie les noms et attributs avec les préfixes originaux utilisés dans les déclarations d'espaces de noms.
faux : ne renvoie pas les attributs utilisés pour les déclarations d'espaces de noms et, éventuellement, ne signale pas les noms avec les préfixes originaux (par défaut).
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture
xml.sax.handler.feature_string_interning
valeur : "http://xml.org/sax/features/string-interning"
vrai : tous les noms d'éléments, préfixes, noms d'attributs, URI d'espace de noms et noms locaux sont rendus internes à l'aide de la fonction native correspondante.
faux : les noms ne sont pas nécessairement rendus internes, bien qu'ils puissent l'être (par défaut).
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture
xml.sax.handler.feature_validation
valeur : "http://xml.org/sax/features/validation"
vrai : signale toutes les erreurs de validation (implique external-general-entities et external-parameter-entities).
faux : ne signale pas les erreurs de validation.
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture
xml.sax.handler.feature_external_ges
valeur : "http://xml.org/sax/features/external-general-entities"
vrai : Inclut toutes les entités générales (texte) externes.
faux : n'inclut pas les entités générales externes.
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture
xml.sax.handler.feature_external_pes
valeur : "http://xml.org/sax/features/external-parameter-entities"
vrai : Inclut toutes les entités de paramètres externes, y compris les sous-ensembles DTD externes.
faux : n'inclue aucune entité de paramètre externe, même les sous-ensembles DTD externes.
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture
xml.sax.handler.all_features

Liste de toutes les fonctionnalités.

xml.sax.handler.property_lexical_handler
valeur : "http://xml.org/sax/properties/lexical-handler"
type de données : xml.sax.handler.LexicalHandler (non pris en charge dans Python 2)
description : gestionnaire d'extension facultatif pour les événements lexicaux tels que les commentaires.
accès : lecture-écriture
xml.sax.handler.property_declaration_handler
valeur : "http://xml.org/sax/properties/declaration-handler"
type de données : xml.sax.sax2lib.DeclHandler (non pris en charge dans Python 2)
description : gestionnaire d'extension facultatif pour les événements liés à la DTD autres que les notations et les entités non analysées.
accès : lecture-écriture
xml.sax.handler.property_dom_node
valeur : "http://xml.org/sax/properties/dom-node"
type de données : org.w3c.dom.Node (non pris en charge dans Python 2)
description : lors de l'analyse, le nœud DOM actuel visité s'il s'agit d'un itérateur DOM ; hors de l'analyse, le nœud racine du DOM pour l'itération.
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture
xml.sax.handler.property_xml_string
valeur : "http://xml.org/sax/properties/xml-string"
type de données : octets
description : chaîne littérale de caractères qui était la source de l'événement en cours.
accès : lecture seule
xml.sax.handler.all_properties

Liste de tous les noms de propriétés connus.

Objets ContentHandler

Les utilisateurs doivent sous-classer ContentHandler dans leur application. Les méthodes suivantes sont appelées par l'analyseur pour notifier les événements appropriés dans le document d'entrée :

ContentHandler.setDocumentLocator(locator)

Appelé par l'analyseur pour donner à l'application un localisateur permettant de localiser l'origine des événements du document.

Les analyseurs SAX sont fortement encouragés (bien que ce ne soit pas absolument obligatoire) à fournir un localisateur : s'ils le font, ils doivent fournir le localisateur à l'application en appelant cette méthode avant d'invoquer l'une des autres méthodes de l'interface DocumentHandler.

Le localisateur permet à l'application de déterminer la position finale de tout événement lié au document, même si l'analyseur ne signale pas d'erreur. En règle générale, l'application utilise ces informations pour signaler ses propres erreurs (telles que le contenu d'un champ texte qui ne correspond pas aux règles métier d'une application). Les informations renvoyées par le localisateur ne sont probablement pas suffisantes pour être utilisées avec un moteur de recherche.

Notez que le localisateur renvoie des informations correctes pendant la durée de l'invocation des événements dans cette interface. L'application ne doit pas tenter de l'utiliser à un autre moment.

ContentHandler.startDocument()

Reçoit la notification correspondant au début du document.

L'analyseur SAX invoque cette méthode une seule fois, avant toute autre méthode dans cette interface ou dans DTDHandler (sauf pour setDocumentLocator()).

ContentHandler.endDocument()

Reçoit la notification correspondant à la fin du document.

L'analyseur SAX n'invoque cette méthode qu'une seule fois et c'est la dernière méthode invoquée lors de l'analyse. L'analyseur ne doit pas invoquer cette méthode tant qu'il n'a pas abandonné l'analyse (en raison d'une erreur irrécupérable) ou atteint la fin de l'entrée.

ContentHandler.startPrefixMapping(prefix, uri)

Commence la portée d’une correspondance d’espace de noms préfixe-URI.

Les informations de cet événement ne sont pas nécessaires au traitement normal des espaces de noms : le lecteur XML SAX remplace automatiquement les préfixes des noms d'éléments et d'attributs lorsque la fonctionnalité feature_namespaces est activée (la valeur par défaut).

Il existe cependant des cas où les applications doivent utiliser des préfixes dans des champs textes ou dans les valeurs d'attribut, où ils ne peuvent pas être développés automatiquement en toute sécurité ; les événements startPrefixMapping() et endPrefixMapping() fournissent les informations à l'application pour développer elle-même les préfixes dans ces contextes, si nécessaire.

Notez qu'il n'est pas garanti que les événements startPrefixMapping() et endPrefixMapping() soient correctement imbriqués les uns par rapport aux autres : tout événement startPrefixMapping() se produit avant l'événement startElement() correspondant, et tout événement endPrefixMapping() se produit après l'événement endElement() correspondant, mais leur ordre n'est pas garanti.

ContentHandler.endPrefixMapping(prefix)

Termine la portée d’une correspondance préfixe-URI.

Voir startPrefixMapping() pour plus de détails. Cet événement se produit toujours après l'événement endElement() correspondant, mais l'ordre des événements endPrefixMapping() n'est pas garanti entre eux.

ContentHandler.startElement(name, attrs)

Signale le début d’un élément en mode sans espaces de noms.

Le paramètre name contient le nom brut XML 1.0 du type d'élément sous forme de chaîne et le paramètre attrs contient un objet de l'interface Attributes (voir The Attributes Interface) contenant les attributs de l'élément. L'objet passé comme attrs peut être réutilisé par l'analyseur ; conserver une référence à celui-ci n’est pas un moyen fiable de conserver une copie des attributs. Pour conserver une copie des attributs, utilisez la méthode copy() de l'objet attrs.

ContentHandler.endElement(name)

Signale la fin d'un élément en mode sans espaces de noms.

Le paramètre name contient le nom du type d'élément, tout comme pour l'événement startElement().

ContentHandler.startElementNS(name, qname, attrs)

Signale le début d’un élément en mode avec espaces de noms.

Le paramètre name contient le nom du type d'élément sous forme de n-uplet (uri, localname), le paramètre qname contient le nom XML 1.0 brut utilisé dans le document source et le paramètre attrs contient une instance de l'interface AttributesNS (voir The AttributesNS Interface) contenant les attributs de l'élément. Si aucun espace de noms n'est associé à l'élément, le composant uri de name est None. L'objet passé comme attrs peut être réutilisé par l'analyseur ; conserver une référence à celui-ci n’est pas un moyen fiable de conserver une copie des attributs. Pour conserver une copie des attributs, utilisez la méthode copy() de l'objet attrs.

Les analyseurs peuvent définir le paramètre qname à None, à moins que la fonctionnalité feature_namespace_prefixes ne soit activée.

ContentHandler.endElementNS(name, qname)

Signale la fin d'un élément en mode avec espaces de noms.

Le paramètre name contient le nom du type d'élément, tout comme avec la méthode startElementNS(), de même que le paramètre qname.

ContentHandler.characters(content)

Reçoit une notification correspondant à des données de type caractère.

L'analyseur appelle cette méthode pour signaler chaque morceau de données de caractères. Les analyseurs SAX peuvent renvoyer toutes les données de caractères contiguës en un seul morceau ou ils peuvent les diviser en plusieurs morceaux ; cependant, tous les caractères d'un événement doivent provenir de la même entité externe afin que le localisateur fournisse des informations utiles.

content peut être une instance de chaîne ou d'octets ; le module lecteur expat produit toujours des chaînes.

Note

l'interface SAX 1 précédente fournie par Python XML utilisait une interface plus proche de Java pour cette méthode. Étant donné que la plupart des analyseurs utilisés à partir de Python ne tiraient pas parti de l’ancienne interface, la signature la plus simple a été choisie pour la remplacer. Pour convertir l'ancien code vers la nouvelle interface, utilisez content au lieu de découper le contenu avec les anciens paramètres offset et length.

ContentHandler.ignorableWhitespace(whitespace)

Reçoit une notification en cas d'espaces pouvant être ignorées dans le contenu de l'élément.

Les analyseurs validateurs doivent utiliser cette méthode pour signaler chaque morceau d'espaces pouvant être ignorées (voir la recommandation W3C XML 1.0, section 2.10) : les analyseurs non validateurs peuvent également utiliser cette méthode s'ils sont capables d'analyser et d'utiliser des modèles de contenu.

Les analyseurs SAX peuvent renvoyer tous les espaces contigües en un seul morceau ou ils peuvent le diviser en plusieurs morceaux ; cependant, tous les caractères d'un événement doivent provenir de la même entité externe, afin que le localisateur fournisse des informations utiles.

ContentHandler.processingInstruction(target, data)

Reçoit une notification correspondant à une instruction de traitement.

L'analyseur invoque cette méthode une fois pour chaque instruction de traitement trouvée : notez que les instructions de traitement peuvent survenir avant ou après l'élément principal du document.

Un analyseur SAX ne doit jamais rapporter une déclaration XML (XML 1.0, section 2.8) ou une déclaration texte (XML 1.0, section 4.3.1) en utilisant cette méthode.

ContentHandler.skippedEntity(name)

Reçoit une notification correspondant à une entité ignorée.

L'analyseur invoque cette méthode une fois pour chaque entité ignorée. Les processeurs non validateurs peuvent ignorer les entités s'ils n'ont pas vu les déclarations (parce que, par exemple, l'entité a été déclarée dans un sous-ensemble DTD externe). Tous les processeurs peuvent ignorer les entités externes, en fonction des valeurs des propriétés feature_external_ges et feature_external_pes.

Objets DTDHandler

Les instances DTDHandler fournissent les méthodes suivantes :

DTDHandler.notationDecl(name, publicId, systemId)

Gère un événement de déclaration de notation.

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

Gère un événement de déclaration d'entité non analysé.

Objets EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

Résout l'identifiant système d'une entité et renvoie soit l'identifiant système à partir duquel lire sous forme de chaîne, soit un InputSource à partir duquel lire. L'implémentation par défaut renvoie systemId.

Objets ErrorHandler

Objects with this interface are used to receive error and warning information from the XMLReader. If you create an object that implements this interface, then register the object with your XMLReader, the parser will call the methods in your object to report all warnings and errors. There are three levels of errors available: warnings, (possibly) recoverable errors, and unrecoverable errors. All methods take a SAXParseException as the only parameter. Errors and warnings may be converted to an exception by raising the passed-in exception object.

ErrorHandler.error(exception)

Appelée lorsque l'analyseur rencontre une erreur récupérable. Si cette méthode ne génère pas d'exception, l'analyse peut continuer, mais l'application ne doit pas attendre d'autres informations concernant le document. Autoriser l'analyseur à continuer peut permettre de découvrir des erreurs supplémentaires dans le document d'entrée.

ErrorHandler.fatalError(exception)

Appelée lorsque l'analyseur rencontre une erreur irrécupérable ; l'analyse devrait se terminer au retour de cette méthode.

ErrorHandler.warning(exception)

Appelée lorsque l'analyseur présente des informations d'avertissement mineures à l'application. L'analyse devrait se poursuivre lorsque cette méthode termine et les informations du document continueront d'être transmises à l'application. La levée d’une exception dans cette méthode entraîne la fin de l’analyse.

Objets LexicalHandler

Gestionnaire SAX2 facultatif pour les événements lexicaux.

Ce gestionnaire est utilisé pour obtenir des informations lexicales relatives à un document XML. Les informations lexicales incluent des informations décrivant le codage du document utilisé et les commentaires XML intégrés dans le document, ainsi que les limites des sections pour la DTD et pour toutes les sections CDATA. Les gestionnaires lexicaux sont utilisés de la même manière que les gestionnaires de contenu.

Définissez le LexicalHandler d'un XMLReader en utilisant la méthode setProperty avec l'identifiant de propriété 'http://xml.org/sax/properties/lexical-handler'.

LexicalHandler.comment(content)

Signale un commentaire n'importe où dans le document (y compris la DTD et en dehors de l'élément de document).

LexicalHandler.startDTD(name, public_id, system_id)

Signale le début des déclarations DTD si le document a une DTD associée.

LexicalHandler.endDTD()

Signale la fin de la déclaration de la DTD.

LexicalHandler.startCDATA()

Signale le début d’une section marquée CDATA.

Le contenu de la section marquée CDATA est signalé via le gestionnaire de données de type caractère.

LexicalHandler.endCDATA()

Signale la fin d’une section marquée CDATA.