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

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

Объекты исключений SAX

Класс исключений SAXException поддерживает следующие методы:

SAXException.getMessage()

Возвращает удобочитаемое сообщение, описывающее состояние ошибки.

SAXException.getException()

Возвращает инкапсулированный объект исключения или None.