# `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.