"xml.sax.xmlreader" --- Interfaz para analizadores XML
******************************************************

**Código fuente:** Lib/xml/sax/xmlreader.py

======================================================================

Los analizadores SAX implementan la interfaz "XMLReader". Están
implementados en un módulo Python, que debe proveer una función
"create_parser()". Esta función es invocada por
"xml.sax.make_parser()" sin argumentos para crear un nuevo objeto
analizador.

class xml.sax.xmlreader.XMLReader

   Clase base que puede ser heredada por analizadores SAX.

class xml.sax.xmlreader.IncrementalParser

   En algunos casos, es deseable no analizar una fuente de entrada a
   la vez, si no alimentar partes del documento a medida que estén
   disponibles. Tenga en cuenta que el lector normalmente no leerá el
   fichero completo, si no que también lo leerá por partes, aún así
   "parse()" no retornará hasta que el documento por completo es
   procesado. Por lo tanto, estas interfaces deben utilizarse si el
   comportamiento de bloqueo "parse()" no es deseable.

   Cuando se crea una instancia del analizador, está listo para
   comenzar a aceptar información desde el método de alimentación
   inmediatamente. Después de que el análisis ha finalizado con una
   llamada para cerrar, se debe llamar al método de reinicio para que
   el analizador esté listo para aceptar información nueva, ya sea de
   la fuente o utilizando el método de análisis.

   Tenga en cuenta que estos métodos *no* deben ser llamados durante
   el análisis, es decir, después de que el análisis ha sido llamado y
   antes de que regrese.

   Por defecto, la clase también implementa el método de análisis de
   la interfaz XMLReader utilizando los métodos de alimentación,
   cierre y reinicio de la interfaz IncrementalParser en conveniencia
   a los escritores de controlador SAX 2.0.

class xml.sax.xmlreader.Locator

   La interfaz para asociar un evento SAX con una ubicación del
   documento. Un objecto localizador retornará resultados válidos sólo
   durante llamadas a métodos DocumentHandler; en cualquier otro
   momento, los resultados son impredecibles. Si la información no
   está disponible, los métodos pueden retornar "None".

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

   La encapsulación de la información necesaria por el "XMLReader"
   para leer entidades.

   Esta clase puede incluir información sobre el identificador
   público, identificador del sistema, flujo de bytes (posiblemente
   con la información de codificación de caracteres) y/o el flujo de
   caracteres de una entidad.

   Las aplicaciones crearán objetos de esta clase para uso en el
   método "XMLReader.parse()" y para retornar desde
   EntityResolver.resolveEntity.

   Una "InputSource" pertenece a la aplicación, el "XMLReader" no
   tiene permitido modificar objetos "InputSource" pasados desde la
   aplicación, a pesar de que puede hacer copias y modificarlas.

class xml.sax.xmlreader.AttributesImpl(attrs)

   Esta es una implementación de la interfaz "Attributes" (vea la
   sección La Interfaz Attributes). Este es un objeto de tipo
   diccionario que representa los atributos de elemento en una llamada
   "startElement()". En adición a las operaciones de diccionario más
   útiles, soporta una serie de otros métodos como se describe en la
   interfaz. Los lectores deben crear una instancia de los objetos de
   esta clase; *attrs* debe ser un objeto de tipo diccionario que
   contenga un mapeo de nombres de atributo a valores de atributo.

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

   Variante consciente del espacio de nombres de "AttributesImpl", que
   se pasará a "startElementNS()". Es derivada de "AttributesImpl",
   pero entiende nombres de atributo como dos tuplas de *namespaceURI*
   y *localname*. En adición, provee una serie de métodos esperando
   nombres calificados como aparecen en el documento original. Esta
   clase implementa la interfaz "AttributesNS" (vea la sección La
   Interfaz AttributesNS).


Objetos XMLReader
=================

La interfaz "XMLReader" soporta los siguientes métodos:

XMLReader.parse(source)

   Procesa una fuente de entrada, produciendo eventos SAX. El objeto
   *source* puede ser un identificador de sistema (una cadena
   identificando la fuente de entrada -- típicamente un nombre de
   fichero o una URL), un "pathlib.Path" o un objeto *path-like*, o un
   objeto "InputSource". Cuando "parse()" retorna, la entrada es
   procesada completamente, y el objeto analizador puede ser
   descartado o reiniciado.

   Distinto en la versión 3.5: Agregado soporte de flujo de
   caracteres.

   Distinto en la versión 3.8: Agregado soporte de objetos path-like.

XMLReader.getContentHandler()

   Retorna el "ContentHandler" actual.

XMLReader.setContentHandler(handler)

   Establece el "ContentHandler" actual. Si ningún "ContentHandler" es
   establecido, los eventos de contenido serán descartados.

XMLReader.getDTDHandler()

   Retorna el "DTDHandler" actual.

XMLReader.setDTDHandler(handler)

   Establece el "DTDHandler" actual. Si ningún "DTDHandler" es
   establecido, los eventos DTD serán descartados.

XMLReader.getEntityResolver()

   Retorna el "EntityResolver" actual.

XMLReader.setEntityResolver(handler)

   Establece el "EntityResolver" actual. Si ningún "EntityResolver" es
   establecido, los intentos de resolver una entidad externa
   resultarán en la apertura del identificador de sistema para la
   entidad, y un error si no está disponible.

XMLReader.getErrorHandler()

   Retorna el "ErrorHandler" actual.

XMLReader.setErrorHandler(handler)

   Establece el manejador de errores actual. Si ningún "ErrorHandler"
   es establecido, se lanzarán errores como excepciones, y se
   imprimirán alertas.

XMLReader.setLocale(locale)

   Permite a una aplicación establecer la configuración local para
   errores y alertas.

   Analizadores SAX no son requeridos para proveer localización para
   errores y alertas; si no pueden soportar la configuración local
   solicitada, de cualquier forma, lanzarán una excepción SAX. Las
   aplicaciones pueden solicitar un cambio local en medio del
   análisis.

XMLReader.getFeature(featurename)

   Retorna la configuración actual para la característica
   *featurename*. Si la característica no es reconocida,
   "SAXNotRecognizedException" es lanzada. Los bien conocidos
   featurenames son listados en el módulo "xml.sax.handler".

XMLReader.setFeature(featurename, value)

   Establece el *featurename* a *value*. Si la característica no es
   reconocida, "SAXNotRecognizedException" es lanzada. Si la
   característica o su configuración no es soportada por el
   analizador, *SAXNotSupportedException* es lanzada.

XMLReader.getProperty(propertyname)

   Retorna la configuración actual para la propiedad *propertyname*.
   Si la configuración no es reconocida, una
   "SAXNotRecognizedException" es lanzada. Las bien conocidas
   propertynames son listadas en el módulo  "xml.sax.handler".

XMLReader.setProperty(propertyname, value)

   Establece el *propertyname* a *value*. Si la propiedad no es
   reconocida, "SAXNotRecognizedException" es lanzada. Si la propiedad
   o su configuración no es soportada por el analizador,
   *SAXNotSupportedException* es lanzada.


Objetos IncrementalParser
=========================

Las instancias de "IncrementalParser" ofrecen los siguientes métodos
adicionales:

IncrementalParser.feed(data)

   Procesa una parte de *data*.

IncrementalParser.close()

   Asume el fin del documento. Eso verificará las condiciones bien
   formadas que pueden ser verificadas sólo al final, invocar
   manejadores, y puede limpiar los recursos asignados durante el
   análisis.

IncrementalParser.reset()

   Este método es llamado después de que el cierre ha sido llamado
   para restablecer el analizador, de forma que esté listo para
   analizar nuevos documentos. Los resultados de llamar parse o feed
   después del cierre sin llamar a reset son indefinidos.


Objetos localizadores
=====================

Las instancias de "Locator" proveen estos métodos:

Locator.getColumnNumber()

   Retorna el número de columna donde el evento actual comienza.

Locator.getLineNumber()

   Retorna el número de línea donde el evento actual comienza.

Locator.getPublicId()

   Retorna el identificador público para el evento actual.

Locator.getSystemId()

   Retorna el identificador de sistema para el evento actual.


Objetos InputSource
===================

InputSource.setPublicId(id)

   Establece el identificador público de esta "InputSource".

InputSource.getPublicId()

   Retorna el identificador público para esta "InputSource".

InputSource.setSystemId(id)

   Establece el identificador de sistema de esta "InputSource".

InputSource.getSystemId()

   Retorna el identificador de sistema para esta "InputSource".

InputSource.setEncoding(encoding)

   Establece la codificación de caracteres para esta "InputSource".

   La codificación debe ser una cadena aceptable para una declaración
   de codificación XML (vea la sección 4.3.3 de la recomendación XML).

   El atributo de codificación de la "InputSource" es ignorado si la
   "InputSource" contiene también un flujo de caracteres.

InputSource.getEncoding()

   Obtiene la codificación de caracteres de esta InputSource.

InputSource.setByteStream(bytefile)

   Establece el flujo de bytes (un *binary file*) para esta fuente de
   entrada.

   El analizador SAX ignorará esto si existe también un flujo de
   caracteres especificado, pero utilizará un flujo de bytes en
   preferencia para abrir una conexión URI en sí.

   Si la aplicación conoce la codificación de caracteres del flujo de
   bytes, debería establecerla con el método setEncoding.

InputSource.getByteStream()

   Obtiene el flujo de bytes para esta fuente de entrada.

   El método getEncoding retornará la codificación de caracteres para
   este flujo de bytes, o "None" si se desconoce.

InputSource.setCharacterStream(charfile)

   Establece el flujo de caracteres (un *text file*) para esta fuente
   de entrada.

   Si existe un flujo de caracteres especificado, el analizador SAX
   ignorará cualquier flujo de bytes y no intentará abrir una conexión
   URI al identificador de sistema.

InputSource.getCharacterStream()

   Obtiene el flujo de caracteres para esta fuente de entrada.


La Interfaz "Attributes"
========================

Los objetos "Attributes" implementa una porción del *mapping
protocol*, incluyendo los métodos "copy()", "get()", "__contains__()",
"items()", "keys()", y "values()".  Los siguientes métodos también son
provistos:

Attributes.getLength()

   Retorna el número de atributos.

Attributes.getNames()

   Retorna los nombres de los atributos.

Attributes.getType(name)

   Retorna el tipo del atributo *name*, que es normalmente "'CDATA'".

Attributes.getValue(name)

   Retorna el valor del atributo *name*.


La Interfaz "AttributesNS"
==========================

Esta interfaz es un subtipo de la interfaz "Attributes" (vea la
sección La Interfaz Attributes). Todos los métodos soportados por la
interfaz están también disponibles en los objetos "AttributesNS".

Los siguientes métodos están también disponibles:

AttributesNS.getValueByQName(name)

   Retorna el valor para un nombre cualificado.

AttributesNS.getNameByQName(name)

   Retorna el par "(namespace, localname)" para un *name* cualificado.

AttributesNS.getQNameByName(name)

   Retorna el nombre cualificado para un par "(namespace, localname)".

AttributesNS.getQNames()

   Retorna los nombres cualificados para todos los atributos.
