"xml.sax.handler" --- Base classes for SAX handlers
***************************************************

**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 solo 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 solo 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.

class xml.sax.handler.LexicalHandler

   Interface usada por el parser para representar eventos de baja
   frecuencia que pueden no ser de interés para muchas aplicaciones.

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) solo 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) solo 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) solo 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) solo 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) solo 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) solo 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) solo 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 solo 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 solo 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 solo 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" la instancia provee 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á.


Objetos DTDHandler
==================

Handler (manipulador) de extensión opcional para eventos léxicos SAX2.

Este handler se usa para obtener información léxica de un documento
XML. La información léxica incluye información que describe la
codificación del documento usado u los comentarios XML embebidos en el
documento, como también una sección para el DTD y para cada sección
CDTA. Estos manipuladores léxicos son usado de la misma forma que los
manipuladores de contenido (content handlers).

Configurar el LexicalHandlerde un XMLReader usando el método
setProperty con la propiedad identificadora
"'http://xml.org/sax/properties/lexical-handler'".

LexicalHandler.comment(content)

   Reporta un comentario en cualquier lugar en el documento
   (incluyendo el DTD y elementos por fuera del documento).

LexicalHandler.startDTD(name, public_id, system_id)

   Reporta el estado de las declaraciones del DTD en caso de tenga
   asociado un DTD.

LexicalHandler.endDTD()

   Reporta el fin de la declaración del DTD.

LexicalHandler.startCDATA()

   Reporta el inicio de la sección CDATA marcada.

   El contenido de la sección marcada del CDATA se reportará a través
   de manipulador de caracteres.

LexicalHandler.endCDATA()

   Reporta el final de la sección marcada del CDATA.
