This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `XML.sax`— Soporte para analizadores SAX2

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`.