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.