xml.sax — Поддержка парсеров SAX2

Исходный код: Lib/xml/sax/__init__.py

Пакет xml.sax предоставляет ряд модулей, которые реализуют интерфейс Simple API for XML (SAX) для Python. Сам пакет предоставляет исключения SAX и удобные функции, которые будут наиболее часто использоваться пользователями API SAX.

Удобные функции:

xml.sax.make_parser(parser_list=[])

Создайте и верните объект SAX XMLReader. Будет использован первый найденный парсер. Если parser_list задан, он должен быть последовательностью строк, которые задают имена модулей, содержащих функцию create_parser(). Модули, перечисленные в parser_list, будут использоваться перед модулями в стандартном списке парсеров.

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

Создайте парсер SAX и используйте его для анализа документа. Документ, переданный в качестве filename_or_stream, может быть именем файла или объектом файла. Параметр handler должен быть экземпляром SAX ContentHandler. Если задан error_handler, он должен быть экземпляром SAX ErrorHandler; если он опущен, SAXParseException будет поднят при всех ошибках. Значение возврата отсутствует; вся работа должна выполняться переданным handler.

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

Аналогично parse(), но анализирует данные из буфера string, полученного в качестве параметра. string должен быть экземпляром str или объектом-последовательностью байтов.

Изменено в версии 3.5: Добавлена поддержка экземпляров str.

Типичное приложение SAX использует три вида объектов: читатели, обработчики и источники входных данных. «Читатель» в данном контексте — это другое название парсера, т. е. какой-либо фрагмент кода, который считывает байты или символы из источника входных данных и генерирует последовательность событий. Затем события распределяются по объектам-обработчикам, т. е. читатель вызывает метод в объекте-обработчике. Приложение SAX должно, следовательно, получить объект-читатель, создать или открыть источники входных данных, создать обработчики и соединить эти объекты вместе. В качестве последнего шага подготовки читатель вызывается для анализа входных данных. Во время анализа на основе структурных и синтаксических событий входных данных вызываются методы объектов-обработчиков.

Для этих объектов важны только интерфейсы; они обычно не создаются самим приложением. Поскольку у Python нет явного понятия интерфейса, они формально вводятся как классы, но приложения могут использовать реализации, которые не наследуются от предоставленных классов. Интерфейсы InputSource, Locator, Attributes, AttributesNS, и XMLReader определены в модуле xml.sax.xmlreader. Интерфейсы обработчиков определены в xml.sax.handler. Для удобства, InputSource (который часто создаётся непосредственно) и классы обработчиков также доступны из xml.sax. Эти интерфейсы описаны ниже.

В дополнение к этим классам, xml.sax предоставляет следующие классы исключений.

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

Захватывает XML ошибку или предупреждение. Этот класс может содержать основную информацию об ошибке или предупреждении от XML парсера или приложения: он может быть переопределён для предоставления дополнительной функциональности или добавления локализации. Обратите внимание, что хотя обработчики, определённые в интерфейсе ErrorHandler получают экземпляры этого исключения, это не обязательно для поднятия исключения — это также полезно в качестве контейнера для информации.

При создании msg должен быть удобочитаемым описанием ошибки. Необязательный параметр exception, если задан, должен быть None или исключением, которое было перехвачено кодом парсинга и передаётся как информация.

Это базовый класс для других классов исключений SAX.

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

Подкласс SAXException, поднимаемый при ошибках парсинга. Экземпляры этого класса передаются методам интерфейса SAX ErrorHandler для предоставления информации об ошибке парсинга. Этот класс поддерживает интерфейс SAX Locator, а также интерфейс SAXException.

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

Подкласс SAXException, поднимаемый, когда SAX XMLReader сталкивается с нераспознанным свойством или функцией. Приложения и расширения SAX могут использовать этот класс для аналогичных целей.

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

Подкласс SAXException, поднимаемый, когда SAX XMLReader запрошен для включения функции, которая не поддерживается, или для установки свойства в значение, которое реализация не поддерживает. Приложения и расширения SAX могут использовать этот класс для аналогичных целей.

1. Объекты исключений SAX

Класс исключений SAXException поддерживает следующие методы:

SAXException.getMessage()

Возвращает удобочитаемое сообщение, описывающее условие ошибки.

SAXException.getException()

Возвращает объект перехваченного исключения или None.