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