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.