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