Código fuente:Lib / xml / sax / handler.py

La API SAX define cuatro tipos de controladores: controladores de contenido, controladores DTD, controladores de errores y resolutores de entidades. Las aplicaciones normalmente solo necesitan implementar aquellas interfaces cuyos eventos les interesan; pueden implementar las interfaces en un solo objeto o en múltiples objetos. Las implementaciones de manejadores deben heredar de las clases base proporcionadas en el módulo xml.sax.handler, para que todos los métodos obtengan implementaciones predeterminadas.

class xml.sax.handler.ContentHandler

Esta es la interfaz de devolución de llamada principal en 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 DTD.

Esta interfaz especifica solo los eventos DTD necesarios para el análisis básico (entidades no analizadas y attributes).

class xml.sax.handler.EntityResolver

Interfaz básica para la resolución de entidades. Si crea un objeto que implementa esta interfaz, luego registra el objeto con su analizador, el analizador llamará al método en su objeto para resolver todas las entidades externas.

class xml.sax.handler.ErrorHandler

Interfaz utilizada por el analizador 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 características y propiedades.

xml.sax.handler.feature_namespaces
xml.sax.handler.feature_namespace_prefixes
xml.sax.handler.feature_string_interning
xml.sax.handler.feature_validation
xml.sax.handler.feature_external_ges
xml.sax.handler.feature_external_pes
xml.sax.handler.all_features

Lista de todas las funciones.

xml.sax.handler.property_lexical_handler
xml.sax.handler.property_declaration_handler
xml.sax.handler.property_dom_node
xml.sax.handler.property_xml_string
xml.sax.handler.all_properties

Lista de todos los nombres de propiedad conocidos.

Objetos ContentHandler

Se espera que los usuarios subclasifiquen ContentHandler para apoyar su aplicación. El analizador llama a los siguientes métodos en los eventos apropiados en el documento de entrada:

ContentHandler.setDocumentLocator(locator)

Lo llama el analizador para darle a la aplicación un localizador para localizar el origen de los eventos del documento.

Se recomienda encarecidamente a los 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 en la interfaz DocumentHandler.

El localizador permite que la aplicación determine 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 sus propios errores (como el contenido de caracteres que no coincide con las reglas comerciales de una aplicación). La información devuelta por el localizador probablemente no sea suficiente para su uso con un motor de búsqueda.

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

ContentHandler.startDocument()

Reciba notificación del inicio de un documento.

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

ContentHandler.endDocument()

Reciba notificación del final de un documento.

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

ContentHandler.startPrefixMapping(prefix, uri)

Comience el alcance de un prefix-Mapeo del espacio de nombres URI.

La información de este evento no es necesaria para el procesamiento normal del espacio de nombres: el lector de XML SAX reemplazará automáticamente los prefijos para el elemento y attribute nombres cuando el feature_namespaces la función está habilitada (por defecto).

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

Tenga en cuenta que startPrefixMapping() y endPrefixMapping() No se garantiza que los eventos estén correctamente anidados entre sí: todos startPrefixMapping() los eventos ocurrirán antes de la correspondiente startElement() evento, y todo endPrefixMapping() los eventos ocurrirán después de la correspondiente endElement() evento, pero su orden no está garantizada.

ContentHandler.endPrefixMapping(prefix)

Terminar con el alcance de un prefix-Mapeo de URL.

Ver startPrefixMapping() para detalles. Este evento siempre ocurrirá después del correspondiente endElement() evento, pero el orden de endPrefixMapping() Los eventos no están garantizados de otra manera.

ContentHandler.startElement(name, attrs)

Señala el inicio de un elemento en modo sin espacio de nombres.

los nombre El parámetro contiene el nombre XML 1.0 sin formato del tipo de elemento como un string y el attrs El parámetro contiene un objeto del Attributes interfaz (ver La interfaz de atributos) que contiene el attributes del elemento. El objeto pasó como attrs puede ser reutilizado por el analizador; aferrarse a una referencia no es una forma fiable de conservar una copia del attributes. Para guardar una copia del attributes, utilizar el copy() método del attrs objeto.

ContentHandler.endElement(name)

Señala el final de un elemento en modo sin espacio de nombres.

los nombre contiene el nombre del tipo de elemento, al igual que con el startElement() evento.

ContentHandler.startElementNS(name, qname, attrs)

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

los nombre El parámetro contiene el nombre del tipo de elemento como un (uri,
localname) tupla, la qname contiene el nombre XML 1.0 sin formato utilizado en el documento de origen, y el attrs El parámetro contiene una instancia del AttributesNS interfaz (ver La interfaz AttributesNS) que contiene el attributes del elemento. Si no hay ningún espacio de nombres asociado con el elemento, el uri componente de nombre estarán None. El objeto pasó como attrs puede ser reutilizado por el analizador; aferrarse a una referencia no es una forma fiable de conservar una copia del attributes. Para guardar una copia del attributes, utilizar el copy() método del attrs objeto.

Los analizadores pueden establecer el qname parámetro a None, a menos que el feature_namespace_prefixes la función está activada.

ContentHandler.endElementNS(name, qname)

Señala el final de un elemento en el modo de espacio de nombres.

los nombre contiene el nombre del tipo de elemento, al igual que con el startElementNS() método, igualmente el qname parámetro.

ContentHandler.characters(content)

Recibe notificaciones de datos de personajes.

El analizador llamará a este método para informar cada fragmento de datos de caracteres. Los analizadores SAX pueden devolver todos los datos de caracteres contiguos en un solo fragmento, o pueden dividirlo en varios fragmentos; sin embargo, todos los personajes de cualquier evento deben provenir de la misma entidad externa para que el localizador proporcione información útil.

contenido tal vez un string o instancia de bytes; los expat El módulo lector siempre produce cadenas.

Nota

La interfaz SAX 1 anterior proporcionada por Python XML Special Interest Group usaba una interfaz más similar a Java para este método. Dado que la mayoría de los analizadores utilizados desde Python no aprovecharon la interfaz anterior, se eligió la firma más simple para reemplazarla. Para convertir el código antiguo a la nueva interfaz, use contenido en lugar de dividir el contenido con el viejo compensar y largo parámetros.

ContentHandler.ignorableWhitespace(whitespace)

Reciba notificaciones de espacios en blanco ignorables en el contenido del elemento.

Los analizadores de validación deben utilizar este método para informar cada fragmento de espacio en blanco ignorable (consulte la recomendación W3C XML 1.0, sección 2.10): los analizadores de validación también pueden utilizar este método si son capaces de analizar y utilizar modelos de contenido.

Los analizadores SAX pueden devolver todos los espacios en blanco contiguos en un solo fragmento, o pueden dividirlo en varios fragmentos; sin embargo, todos los personajes de cualquier evento deben provenir de la misma entidad externa, de modo que el localizador proporcione información útil.

ContentHandler.processingInstruction(target, data)

Reciba notificación de una instrucción de procesamiento.

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

Un analizador SAX nunca debe informar 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)

Reciba notificación de una entidad omitida.

El analizador invocará este método una vez por cada entidad omitida. Los procesadores que no validan pueden omitir entidades si no han visto las declaraciones (porque, por ejemplo, la entidad se declaró en un subconjunto DTD externo). Todos los procesadores pueden omitir entidades externas, dependiendo de los valores del feature_external_ges y el feature_external_pes propiedades.

Objetos DTDHandler

DTDHandler Las instancias proporcionan los siguientes métodos:

DTDHandler.notationDecl(name, publicId, systemId)

Maneja un evento de declaración de notación.

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

Maneja un evento de declaración de entidad sin analizar.

Objetos EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

Resuelva el identificador del sistema de una entidad y devuelva el identificador del sistema para leer como un stringo un InputSource desde el que leer. La implementación predeterminada regresa systemId.

Objetos ErrorHandler

Los objetos con esta interfaz se utilizan para recibir información de error y advertencia del XMLReader. Si crea un objeto que implementa esta interfaz, registre el objeto con su XMLReader, el analizador llamará a los métodos en su objeto para informar todas las advertencias y errores. Hay tres niveles de errores disponibles: advertencias, (posiblemente) errores recuperables y errores irrecuperables. Todos los métodos toman un SAXParseException como único parámetro. Los errores y las advertencias se pueden convertir en una excepción generando el objeto de excepción pasado.

ErrorHandler.error(exception)

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

ErrorHandler.fatalError(exception)

Se llama cuando el analizador encuentra un error del que no puede recuperarse; Se espera que el análisis finalice cuando este método regrese.

ErrorHandler.warning(exception)

Se llama cuando el analizador presenta información de advertencia menor a la aplicación. Se espera que el análisis continúe cuando este método regrese, y la información del documento continuará pasando a la aplicación. Planteando una excepción en este método hará que el análisis finalice.