xml.sax.xmlreader — Interface pour les parseurs XML

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

Les analyseurs SAX implémentent l'interface XMLReader. Ils sont implémentés dans un module Python qui doit fournir une fonction create_parser(). Cette fonction est invoquée par xml.sax.make_parser() sans aucun argument pour créer un nouvel objet analyseur.

class xml.sax.xmlreader.XMLReader

Classe mère qui peut être héritée par les analyseurs SAX.

class xml.sax.xmlreader.IncrementalParser

Dans certains cas, il est souhaitable de ne pas analyser une source d'un coup, mais d'alimenter l'analyseur à partir de morceaux du document dès qu'ils sont disponibles. Notez que le lecteur ne lira normalement pas le fichier en entier, mais le lira également par morceaux ; quoi qu'il en soit parse() ne termine pas tant que l'intégralité du document n'est pas traitée. Ces interfaces doivent donc être utilisées si le comportement bloquant de parse() n’est pas souhaitable.

Lorsque l'analyseur est instancié, il est immédiatement prêt à accepter les données via sa méthode feed. Une fois l'analyse terminée avec un appel à close, la méthode reset doit être appelée pour que l'analyseur soit prêt à accepter de nouvelles données, soit à l'aide de la méthode feed, soit à l'aide de la méthode parse.

Notez que ces méthodes ne doivent pas être appelées pendant l'analyse, c'est-à-dire entre l'appel de la fonction parse et sa sortie.

Par défaut, la classe implémente également la méthode parse de l'interface XMLReader en utilisant les méthodes feed, close et reset de l'interface IncrementalParser pour faciliter la tâche des rédacteurs de pilotes SAX 2.0.

class xml.sax.xmlreader.Locator

Interface permettant d'associer un événement SAX à un emplacement de document. Un objet localisateur renvoie des résultats valides uniquement lors des appels aux méthodes du DocumentHandler ; à tout autre moment, les résultats sont imprévisibles. Si les informations ne sont pas disponibles, les méthodes peuvent renvoyer None.

class xml.sax.xmlreader.InputSource(system_id=None)

Encapsulation des informations nécessaires au XMLReader pour lire les entités.

Cette classe peut inclure des informations sur l'identifiant public, l'identifiant système, le flux d'octets (éventuellement avec des informations d'encodage de caractères) et/ou le flux de caractères d'une entité.

Les applications créeront des objets de cette classe pour les utiliser dans la méthode XMLReader.parse() et en retour de EntityResolver.resolveEntity.

L'InputSource appartient à l'application, le XMLReader n'est pas autorisé à modifier les objets InputSource qui lui sont transmis depuis l'application, cependant il puisse en faire des copies et les modifier.

class xml.sax.xmlreader.AttributesImpl(attrs)

Il s'agit d'une implémentation de l'interface Attributes (voir section L'interface Attributes). Il s'agit d'un objet de type dictionnaire qui représente les attributs de l'élément dans un appel startElement(). En plus des opérations de dictionnaire les plus utiles, il prend en charge un certain nombre d'autres méthodes décrites par l'interface. Les objets de cette classe doivent être instanciés par les lecteurs ; attrs doit être un objet de type dictionnaire contenant une correspondance entre des noms d'attributs et des valeurs d'attributs.

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

Variante de AttributesImpl prenant en charge les espaces de noms, qui est transmise à startElementNS(). Elle est dérivée de AttributesImpl, mais sait gérer les noms d'attributs comme les paires de namespaceURI et localname. De plus, elle fournit un certain nombre de méthodes qui attendent les noms qualifiés tels qu'ils apparaissent dans le document original. Cette classe implémente l'interface AttributesNS (voir section L'interface AttributesNS).

Objets XMLReader

L'interface XMLReader prend en charge les méthodes suivantes :

XMLReader.parse(source)

Traite une source d'entrée, produisant des événements SAX. L'objet source peut être un identifiant système (une chaîne identifiant la source d'entrée – généralement un nom de fichier ou une URL), un chemin, un simili-chemin, ou un objet InputSource. À la sortie de parse(), l'entrée est complètement traitée et l'objet analyseur peut être supprimé ou réinitialisé.

Modifié dans la version 3.5: ajout de la prise en charge des flux de caractères.

Modifié dans la version 3.8: ajout de la prise en charge des objets simili-chemin.

XMLReader.getContentHandler()

Renvoie le ContentHandler actuel.

XMLReader.setContentHandler(handler)

Définit le ContentHandler actuel. Si aucun ContentHandler n'est défini, les événements de contenu sont ignorés.

XMLReader.getDTDHandler()

Renvoie le DTDHandler actuel.

XMLReader.setDTDHandler(handler)

Définit le DTDHandler actuel. Si aucun DTDHandler n'est défini, les événements DTD sont ignorés.

XMLReader.getEntityResolver()

Renvoie le EntityResolver actuel.

XMLReader.setEntityResolver(handler)

Définit le EntityResolver actuel. Si aucun EntityResolver n'est défini, les tentatives de résolution d'une entité externe entraînent l'ouverture de l'identifiant système de l'entité et échouent s'il n'est pas disponible.

XMLReader.getErrorHandler()

Renvoie le ErrorHandler actuel.

XMLReader.setErrorHandler(handler)

Définit le gestionnaire d'erreurs actuel. Si aucun ErrorHandler n'est défini, les erreurs sont générées comme exceptions et des avertissements sont affichés.

XMLReader.setLocale(locale)

Permet à l'application de définir les paramètres régionaux pour les erreurs et les avertissements.

Les analyseurs SAX ne sont pas tenus de gérer les paramètre régionaux pour les erreurs et les avertissements ; s'ils ne peuvent pas prendre en charge les paramètres régionaux demandés, ils doivent déclencher une exception SAX. Les applications peuvent demander un changement de paramètres régionaux au milieu d'une analyse.

XMLReader.getFeature(featurename)

Renvoie le paramètre actuel pour la fonctionnalité featurename. Si la fonctionnalité n'est pas reconnue, une SAXNotRecognizedException est levée. Les noms de fonctionnalités bien connues sont répertoriés dans le module xml.sax.handler.

XMLReader.setFeature(featurename, value)

Définit featurename à value. Si la fonctionnalité n'est pas reconnue, une SAXNotRecognizedException est levée. Si la fonctionnalité ou son paramètre n'est pas pris en charge par l'analyseur, une SAXNotSupportedException est levée.

XMLReader.getProperty(propertyname)

Renvoie la valeur actuelle de la propriété propertyname. Si la propriété n'est pas reconnue, une SAXNotRecognizedException est levée. Les noms de propriétés bien connues sont répertoriés dans le module xml.sax.handler.

XMLReader.setProperty(propertyname, value)

Définit propertyname à value. Si la propriété n'est pas reconnue, une SAXNotRecognizedException est levée. Si la propriété ou son paramètre n'est pas pris en charge par l'analyseur, une SAXNotSupportedException est levée.

Objets IncrementalParser

Les instances de IncrementalParser offrent les méthodes supplémentaires suivantes :

IncrementalParser.feed(data)

Traite un morceau de data.

IncrementalParser.close()

Considérer que l'on est arrivé à la fin du document. Cela vérifie les conditions de bonne formation qui ne peuvent être vérifiées qu'à la fin, invoque des fonctions de rappel et peut nettoyer les ressources allouées lors de l'analyse.

IncrementalParser.reset()

Cette méthode est appelée après l'appel de close pour réinitialiser l'analyseur afin qu'il soit prêt à analyser de nouveaux documents. Les résultats de l'appel de parse ou feed après la fermeture sans appeler reset ne sont pas définis.

Objets de localisation

Les instances de Locator fournissent ces méthodes :

Locator.getColumnNumber()

Renvoie le numéro de colonne où commence l'événement en cours.

Locator.getLineNumber()

Renvoie le numéro de ligne où commence l'événement en cours.

Locator.getPublicId()

Renvoie l'identifiant public de l'événement en cours.

Locator.getSystemId()

Renvoie l'identifiant système de l'événement en cours.

Objets InputSource

InputSource.setPublicId(id)

Définit l'identifiant public de cet InputSource.

InputSource.getPublicId()

Renvoie l'identifiant public de cet InputSource.

InputSource.setSystemId(id)

Définit l'identifiant système de cet InputSource.

InputSource.getSystemId()

Renvoie l'identifiant système de cet InputSource.

InputSource.setEncoding(encoding)

Définit l'encodage des caractères de cet InputSource.

L'encodage doit être une chaîne acceptable pour une déclaration d'encodage XML (voir section 4.3.3 de la recommandation XML).

L'attribut d'encodage de InputSource est ignoré si le InputSource contient également un flux de caractères.

InputSource.getEncoding()

Récupère l'encodage des caractères de cet InputSource.

InputSource.setByteStream(bytefile)

Définit le flux d'octets (un fichier binaire) pour cette source d'entrée.

L'analyseur SAX ignore cela si un flux de caractères est également spécifié, il préfère utiliser un flux d'octets à l'ouverture d'une connexion URI.

Si l'application connaît l'encodage des caractères du flux d'octets, elle doit le définir avec la méthode setEncoding.

InputSource.getByteStream()

Récupère le flux d'octets pour cette source d'entrée.

La méthode getEncoding renvoie l'encodage des caractères pour ce flux d'octets, ou None s'il est inconnu.

InputSource.setCharacterStream(charfile)

Définit le flux de caractères (un fichier texte) pour cette source d'entrée.

Si un flux de caractères est spécifié, l'analyseur SAX ignore tout flux d'octets et ne tente pas d'ouvrir une connexion URI à l'identifiant système.

InputSource.getCharacterStream()

Récupère le flux de caractères pour cette source d'entrée.

L'interface Attributes

Les objets Attributes implémentent une partie du protocole de tableau de correspondances, y compris les méthodes copy(), get(), __contains__(), items(), keys() et values(). Les méthodes suivantes sont également fournies :

Attributes.getLength()

Renvoie le nombre d'attributs.

Attributes.getNames()

Renvoie les noms des attributs.

Attributes.getType(name)

Renvoie le type de l'attribut name, qui est normalement 'CDATA'.

Attributes.getValue(name)

Renvoie la valeur de l'attribut name.

L'interface AttributesNS

Cette interface est un sous-type de l'interface Attributes (voir section L'interface Attributes). Toutes les méthodes prises en charge par cette interface sont également disponibles sur les objets AttributesNS.

Les méthodes suivantes sont également disponibles :

AttributesNS.getValueByQName(name)

Renvoie la valeur d'un nom qualifié.

AttributesNS.getNameByQName(name)

Renvoie la paire (namespace, localname) pour le nom name qualifié.

AttributesNS.getQNameByName(name)

Renvoie le nom qualifié pour une paire (namespace, localname).

AttributesNS.getQNames()

Renvoie les noms qualifiés de tous les attributs.