"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.
