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 или объектом типа байт.

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