xml.sax.handler — Clases base para los handlers SAX

Source code Lib/xml/sax/handler.py

La API de SAX define cuatro tipos de manejadores: manejadores de contenido, manejadores de DTD, manejadores de errores y resolvedores de entidades. Normalmente, las aplicaciones sólo necesitan implementar las interfaces cuyos eventos les interesan; pueden implementar las interfaces en un solo objeto o en múltiples objetos. Las implementaciones de los manejadores deben heredar de las clases base provistas en el módulo xml.sax.handler, de modo que todos los métodos obtengan implementaciones por defecto.

class xml.sax.handler.ContentHandler

Esta es la principal interfaz de devolución de llamada en el SAX, y la más importante para las aplicaciones. El orden de los eventos en esta interfaz refleja el orden de la información en el documento.

class xml.sax.handler.DTDHandler

Manejar eventos de DTD.

Esta interfaz especifica sólo los eventos DTD necesarios para el análisis básico (entidades y atributos no analizados).

class xml.sax.handler.EntityResolver

Interfaz básica para resolver entidades. Si creas un objeto implementando esta interfaz, y luego registras el objeto con tu Parser, el parser (analizador) invocara al método en tu objeto para resolver todas las entidades externas.

class xml.sax.handler.ErrorHandler

Interfaz utilizada por el parser para presentar mensajes de error y advertencia a la aplicación. Los métodos de este objeto controlan si los errores se convierten inmediatamente en excepciones o se manejan de alguna otra manera.

Además de estas clases, xml.sax.handler proporciona constantes simbólicas para los nombres de las características y propiedades.

xml.sax.handler.feature_namespaces
value: "http://xml.org/sax/features/namespaces"
true: Realizar el procesamiento del Namespace (espacio de nombres).
false: Opcionalmente no realizar el procesamiento del Namespace (espacio de nombres) (implica prefijos de espacio de nombres; por defecto).
acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura
xml.sax.handler.feature_namespace_prefixes
value: "http://xml.org/sax/features/namespace-prefixes"
true: Reporte de los nombres prefijados originales y los atributos utilizados para las declaraciones del Namespace (espacio de nombres).
false: No informar de los atributos utilizados para las declaraciones del Namespace (espacio de nombres), y opcionalmente no informar de los nombres prefijados originales (por defecto).
acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura
xml.sax.handler.feature_string_interning
value: "http://xml.org/sax/features/string-interning"
true: Todos los nombres de elementos, prefijos, nombres de atributos, URIs del Namespace (espacio de nombres) y nombres locales son internados usando la función interna incorporada.
false: Los nombres no están necesariamente internados, aunque pueden estarlo (por defecto).
acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura
xml.sax.handler.feature_validation
value: "http://xml.org/sax/features/validation"
true: Reportar de todos los errores de validación (implica entidades generales externas y entidades de parámetros externos).
false: No informe de los errores de validación.
acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura
xml.sax.handler.feature_external_ges
value: "http://xml.org/sax/features/external-parameter-entities"
true: Incluye todas las entidades externas generales de texto (text).
false: No incluya entidades generales externas.
acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura
xml.sax.handler.feature_external_pes
value: "http://xml.org/sax/features/external-parameter-entities"
true: Incluye todas las entidades paramétricas externas, incluyendo el subconjunto DTD externo.
false: No incluya ninguna entidad paramétrica externa, ni siquiera el subconjunto DTD externo.
acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura
xml.sax.handler.all_features

Lista de todas las características.

xml.sax.handler.property_lexical_handler
value: "http://xml.org/sax/properties/lexical-handler"
data type: xml.sax.sax2lib.LexicalHandler (no soportado en Python 2)
descripción: Un handler (manipulador) de extensión opcional para eventos léxicos como los comentarios.
acceso: read/write (leer/escribir)
xml.sax.handler.property_declaration_handler
value: "http://xml.org/sax/properties/declaration-handler"
data type: xml.sax.sax2lib.DeclHandler (no soportado en Python 2)
description: Un gestor de extensión opcional para eventos relacionados con la DTD que no sean anotaciones y entidades no preparadas.
acceso: read/write (leer/escribir)
xml.sax.handler.property_dom_node
value: "http://xml.org/sax/properties/dom-node"
data type: org.w3c.dom.Node (not supported in Python 2)
descripción: Cuando se analiza, el nodo DOM actual que se visita si se trata de un iterador DOM; cuando no se analiza, el nodo DOM raíz para la iteración.
acceso: (parsing) sólo de lectura; (not parsing) lectura/escritura
xml.sax.handler.property_xml_string
value: "http://xml.org/sax/properties/xml-string"
data type: Bytes
description: La cadena literal de caracteres que fue la fuente del evento actual.
acceso: solo-lectura
xml.sax.handler.all_properties

Lista de todos los nombres de propiedades conocidas.

Objetos ContentHandler

Se espera que los usuarios subclasifiquen ContentHandler para apoyar su aplicación. Los siguientes métodos son llamados por el analizador en los eventos apropiados en el documento de entrada:

ContentHandler.setDocumentLocator(locator)

Invocado por el parser (analizador) para dar a la aplicación un localizador para determinar el origen de los eventos del documento.

Se recomienda encarecidamente a los parsers (analizadores) SAX (aunque no es absolutamente necesario) que proporcionen un localizador: si lo hace, debe proporcionar el localizador a la aplicación invocando este método antes de invocar cualquiera de los otros métodos de la interfaz DocumentHandler.

El localizador permite a la aplicación determinar la posición final de cualquier evento relacionado con el documento, incluso si el analizador no informa de un error. Normalmente, la aplicación utilizará esta información para informar de sus propios errores (como el contenido de los caracteres que no coinciden con las reglas de negocio de la aplicación). Es probable que la información retornada por el localizador no sea suficiente para su uso con un motor de búsqueda.

Tenga en cuenta que el localizador retornará la información correcta sólo durante la invocación de los eventos en esta interfaz. La aplicación no debe intentar utilizarlo en ningún otro momento.

ContentHandler.startDocument()

Recibir la notificación del inicio de un documento.

El parser (analizador) SAX invocará este método sólo una vez, antes que cualquier otro método en esta interfaz o en DTDHandler (excepto setDocumentLocator()).

ContentHandler.endDocument()

Recibir una notificación del final de un documento.

El analizador (parser) SAX invocará este método sólo una vez, y será el último método invocado durante el análisis. El analizador no invocará este método hasta que no haya abandonado el análisis sintáctico (debido a un error irrecuperable) o haya llegado al final de la entrada.

ContentHandler.startPrefixMapping(prefix, uri)

Comienza el alcance de un mapeo del prefijo-URI Namespace.

La información de este evento no es necesaria para el procesamiento normal del Namespace (espacio de nombres): el lector de XML SAX sustituirá automáticamente los prefijos de los nombres de elementos y atributos cuando se active la función feature_namespaces default (el valor por defecto).

Sin embargo, hay casos en que las aplicaciones necesitan utilizar prefijos en los datos de los caracteres o en los valores de los atributos, en los que no se pueden expandir automáticamente de forma segura; los eventos startPrefixMapping() y endPrefixMapping() suministran la información a la aplicación para expandir los prefijos en esos contextos por sí mismos, si es necesario.

Note que los eventos startPrefixMapping() y endPrefixMapping() no están garantizados de estar apropiadamente anidados en relación a cada uno: todos los eventos startPrefixMapping() ocurrirán antes del correspondiente evento startElement(), y todos los eventos endPrefixMapping() ocurrirán después del correspondiente evento endElement(), pero su orden no está garantizado.

ContentHandler.endPrefixMapping(prefix)

Terminar con el alcance de un mapeo de prefijos-URI.

Ver startPrefixMapping() para más detalles. Este evento siempre ocurrirá después del correspondiente evento endElement(), pero el orden de los eventos endPrefixMapping() no está garantizado.

ContentHandler.startElement(name, attrs)

Señala el inicio de un elemento en modo no espacial.

El parámetro name contiene el nombre XML 1.0 en bruto del tipo de elemento como una cadena y el parámetro attrs contiene un objeto de la interfaz Attributes (véase La Interfaz Attributes) que contiene los atributos del elemento. El objeto pasado como attrs puede ser reutilizado por el parser (analizador); mantener una referencia a él no es una forma fiable de conservar una copia de los atributos. Para guardar una copia de los atributos, usa el método copy() del objeto attrs.

ContentHandler.endElement(name)

Señala el final de un elemento en modo no espacial.

El parámetro name contiene el nombre del tipo de elemento, al igual que con el evento startElement().

ContentHandler.startElementNS(name, qname, attrs)

Señala el inicio de un elemento en el modo de Namespace (espacio de nombres).

El parámetro name contiene el nombre del tipo de elemento como una tupla (uri, localname), el parámetro qname contiene el nombre XML 1.0 en bruto usado en el documento fuente, y el parámetro attrs contiene una instancia de la interfaz AttributesNS (ver La Interfaz AttributesNS) que contiene los atributos del elemento. Si no hay ningún Namespace (espacio de nombres) asociado al elemento, el componente uri de name será Ninguno. El objeto pasado como attrs puede ser reutilizado por el analizador; mantener una referencia a él no es una forma fiable de conservar una copia de los atributos. Para guardar una copia de los atributos, usa el método copy`() del objeto attrs.

Los parsers (analizadores) pueden establecer el parámetro qname como None, a menos que se active la función feature_namespace_prefixes.

ContentHandler.endElementNS(name, qname)

Señala el final de un elemento en el modo de namespace.

El parámetro name contiene el nombre del tipo de elemento, al igual que con el método startElementNS(), así como el parámetro qname.

ContentHandler.characters(content)

Recibir la notificación de los datos de los caracteres.

El Parser (analizador) llamará a este método para informar de cada dato de carácter. Los parsers (analizadores) SAX pueden retornar todos los datos de caracteres contiguos en un solo trozo, o pueden dividirlos en varios trozos; sin embargo, todos los caracteres de un mismo evento deben provenir de la misma entidad externa para que el Localizador proporcione información útil.

content puede ser una cadena o una instancia de bytes; el módulo lector de «Expat» siempre produce cadenas.

Nota

La anterior interfaz SAX 1 proporcionada por el Grupo de Interés Especial de Python XML utilizaba una interfaz más parecida a Java para este método. Dado que la mayoría de los parsers (analizadores) utilizados de Python no aprovecharon la interfaz más antigua, se eligió la firma más simple para reemplazarla. Para convertir el código antiguo en la nueva interfaz, se utilizó content en lugar de cortar el contenido con los antiguos parámetros offset y length.

ContentHandler.ignorableWhitespace(whitespace)

Recibir notificación de espacios en blanco ignorables en el contenido de los elementos.

Los parsers validadores deben utilizar este método para informar de cada trozo de espacio en blanco desconocido (véase la recomendación W3C XML 1.0, sección 2.10): los analizadores no validadores también pueden utilizar este método si son capaces de analizar y utilizar modelos de contenido.

Los parsers (analizadores) SAX pueden retornar todos los espacios blancos contiguos en un solo trozo, o pueden dividirlo en varios trozos; sin embargo, todos los caracteres de un mismo evento deben provenir de la misma entidad externa, para que el Localizador proporcione información útil.

ContentHandler.processingInstruction(target, data)

Recibir la notificación de una instrucción de procesamiento.

El Parser (analizador) invocará este método una vez por cada instrucción de procesamiento encontrada: nótese que las instrucciones de procesamiento pueden ocurrir antes o después del elemento principal del documento.

Un parser (analizador) SAX nunca debe informar de una declaración XML (XML 1.0, sección 2.8) o una declaración de texto (XML 1.0, sección 4.3.1) utilizando este método.

ContentHandler.skippedEntity(name)

Recibir la notificación de una entidad salteada.

El Parser invocará este método una vez por cada entidad omitida. Los procesos no validadores pueden omitir entidades si no han visto las declaraciones (porque, por ejemplo, la entidad fue declarada en un subconjunto DTD externo). Todos los procesos pueden omitir entidades externas, dependiendo de los valores de las propiedades feature_external_ges y feature_external_pes.

Objetos DTDHandler

DTDHandler instancias proporcionan los siguientes métodos:

DTDHandler.notationDecl(name, publicId, systemId)

Manejar un evento de declaración de anotación.

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

Manejar un evento de declaración de entidad no preparada.

Objetos EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

Resolver el identificador de sistema de una entidad y retornar ya sea el identificador de sistema para leerlo como una cadena, o una fuente de entrada para leerlo. La implementación por defecto retorna systemId.

Objetos ErrorHandler

Los objetos con esta interfaz se usan para recibir información de error y advertencia del XMLReader. Si creas un objeto que implemente esta interfaz, y luego registras el objeto con tu XMLReader, el parser (analizador) invocará a los métodos de tu objeto para informar de todas las advertencias y errores. Hay tres niveles de errores disponibles: advertencias, (posiblemente) errores recuperables y errores no recuperables. Todos los métodos toman un SAXParseException como único parámetro. Los errores y advertencias pueden ser convertidos en una excepción lanzando el objeto de excepción pasado.

ErrorHandler.error(exception)

Invocación cuando el parser (analizador) encuentra un error recuperable. Si este método no lanza una excepción, el análisis sintáctico puede continuar, pero la aplicación no debe esperar más información del documento. Permitir que el parser (analizador) continúe puede permitir que se descubran errores adicionales en el documento de entrada.

ErrorHandler.fatalError(exception)

Invocación cuando el parser (analizador) encuentra un error del que no puede recuperarse; se espera que el análisis sintáctico termine cuando vuelva este método.

ErrorHandler.warning(exception)

Invocación cuando el parser (analizador) presenta información de advertencia menor a la aplicación. Se espera que el análisis sintáctico continúe cuando vuelva este método, y la información del documento seguirá pasando a la aplicación. Si se lanza una excepción con este método, el análisis sintáctico terminará.