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