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, будут использоваться перед модулями в списке парсеров по умолчанию.

Изменено в версии 3.8: Аргумент 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 или объекта типа bytes.

Изменено в версии 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 могут использовать этот класс для аналогичных целей.