xml.sax.handler
--- Base classes for SAX handlers¶
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 : octetsdescription : 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()
etendPrefixMapping()
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()
etendPrefixMapping()
soient correctement imbriqués les uns par rapport aux autres : tout événementstartPrefixMapping()
se produit avant l'événementstartElement()
correspondant, et tout événementendPrefixMapping()
se produit après l'événementendElement()
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énementendElement()
correspondant, mais l'ordre des événementsendPrefixMapping()
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éthodecopy()
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'interfaceAttributesNS
(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 estNone
. 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éthodecopy()
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
etfeature_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.