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

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