"xml.sax" --- Support for SAX2 parsers
**************************************

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

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

El paquete "xml.sax" provee un número de módulos que implementan la
API Simple para la interfaz XML (SAX) para Python.  El paquete mismo
provee las excepciones SAX y las funciones de conveniencia que serán
las más usadas por los usuarios de la API SAX.

Advertencia:

  El módulo "XML.sax" no es seguro contra datos construidos
  maliciosamente.  Si necesita analizar datos no autenticados o no
  confiables, mirar Vulnerabilidades XML.

Distinto en la versión 3.7.1: El analizador SAX ya no procesa
entidades generales externas por defecto para incrementar seguridad.
Antes, el analizador creaba conexiones de red para buscar archivos
remotos o archivos locales cargados del sistema de archivos para DTD y
entidades. La característica puede ser activadas de nuevo con el
método "setFeature()" en el objeto analizador y el argumento
"feature_external_ges".

Las funciones de conveniencia son:

xml.sax.make_parser(parser_list=[])

   Crea y retorna un objeto SAX "XMLReader".  El primer analizador
   encontrado será el que se use.  Si se provee *parser_list*, debe
   ser un iterable de cadenas de caracteres el cual nombra módulos que
   tienen una función llamada "créate_parser()".  Los módulos listados
   en *parser_list* serán usados antes de los módulos en la lista de
   analizadores por defecto.

   Distinto en la versión 3.8: El argumento *parser_list* puede ser
   cualquier iterable, no sólo una lista.

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

   Crea un analizador SAD y úsalo para analizar un documento.  El
   documento, aprobado como *filename_or_steam*, puede ser un nombre
   de archivo o un objeto de archivo.  El parámetro *handler* necesita
   ser una instancia SAX "ContentHandler".  Si se da *error_handler*,
   debe ser una instancia "ErrorHandler" SAX; si es omitido, se
   lanzará "SAXParseException" en todos los errores. No hay valor
   retornado; toda tarea debe ser realizada por el *handler* aprobado.

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

   Similar a "parser()", pero analiza desde un búfer *string* recibido
   como un parámetro.  *string* debe ser una instancia "str" o un
   *bytes-like object*.

   Distinto en la versión 3.5: Agregado soporte de instancias "str".

Una aplicación SAX típica usa tres tipos de objetos: lectores,
gestores y fuentes de entrada.  "Lector" en este contexto es otro
término para analizador, por ejemplo, alguna pieza de código que lee
los bytes o caracteres de la fuente de entrada, y produce una
secuencia de eventos. Los eventos luego se distribuyen a los objetos
gestores, por ejemplo el lector invoca un método en el gestor.  Una
aplicación SAX debe por tanto obtener un objeto lector, crear o abrir
una fuente de entrada, crear los gestores, y conectar esos objetos
juntos.  Como paso final de preparación, el lector es llamado para
analizar la entrada. Durante el análisis, los métodos en los objetos
gestores son llamados basados en eventos estructurales y sintácticos
de los datos introducidos.

Para estos objetos, sólo las interfaces son relevantes; éstos
normalmente no son instanciados por la aplicación misma.  Ya que
Python no tiene una noción explícita de interfaz, éstas son
introducidas formalmente como clases, pero las aplicaciones suelen
usar implementaciones que no heredan de las clases provistas.  Las
interfaces "InputSource", "Locator", "Attributes", "AttributesNS", y
"XMLReader" son definidas en el módulo "xml.sax.xmlreader".  Las
interfaces de gestión son definidas en "xml.sax.handler".  Por
conveniencia, "InputSource" (el cual suele ser instanciado
directamente) y el gestor de clases están también disponibles desde
"xml.sax"  Estas interfaces son descritas a continuación.

En adición a esas clases, "xml.sax" provee las siguientes clases de
excepción.

exception xml.sax.SAXException(msg, exception=None)

   Encapsula un error XML o advertencia.  Esta clase puede contener
   errores básicos o información de advertencias ya sea para el
   analizador XML o la aplicación: esto puede ser heredado para
   proveer funcionalidad adicionar o para agregar localización.  Nota
   que a pesar de los analizadores definidos en la interfaz
   "ErrorHandler" recibe instancias de esta excepción, no es requerido
   para lanzar la excepción --- esto es algo útil como un contenedor
   para información.

   Cuando es instanciado, *msg* debería ser una descripción del error
   legible para humanos. El parámetro opcional *exception*, si es
   dado, debería ser "None" o una excepción que fue atrapada por el
   código analizador y se transmite como información.

   Esta es la clase base para las otras clases excepción SAX.

exception xml.sax.SAXParseException(msg, exception, locator)

   Subclase de "SAXException" levantada en errores de análisis. Las
   instancias de esta clase son pasadas a los métodos de las
   interfaces SAX "ErrorHandler" para proveer información sobre el
   error de análisis.  Esta clase soporta la interfaz SAX "Locator"
   así como la interfaz "SAXException".

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

   Subclase de "SAXException" lanzada cuando una SAX "XMLReader" es
   confrontada con una propiedad o característica no reconocida.  Las
   aplicaciones SAX y extensiones pueden usar esta clase para
   propósitos similares.

exception xml.sax.SAXNotSupportedException(msg, exception=None)

   Las subclases de "SAXException" se lanzan cuando un SAX "sax" se
   pregunta para habilitar una característica que no tiene soporte, o
   para establecer una propiedad a un valor que la implementación no
   da soporte.  Las aplicaciones sAX y las extensiones pueden usar
   esta clase para propósitos similares.

Ver también:

  SAX: The Simple API for XML
     Este sitio es el punto focal para la definición de la API SAX.
     Provee una implementación Java y documentación en línea.  Los
     enlaces para implementaciones e información histórica también
     están disponibles.

  Módulo "xml.sax.handler"
     Definiciones de las interfaces para objetos proporcionados por
     aplicaciones.

  Módulo "xml.sax.saxutils"
     Funciones de conveniencia para usar en aplicaciones SAX.

  Módulo "xml.sax.xmlreader"
     Definiciones de las interfaces para objetos que proveen
     analizadores.


Objetos SAXException
====================

La clase de excepción "SAXException" da soporte a los siguientes
métodos:

SAXException.getMessage()

   Retorna un mensaje legible para humanos describiendo la condición
   de error.

SAXException.getException()

   Retorna un objeto excepción encapsulado, o "None".
