xml.sax — Поддержка SAX2 парсеров

Исходный код: Lib/xml/sax/__init__.py

Пакет xml.sax содержит ряд модулей, реализующих интерфейс Простого (Simple) API для XML (SAX) для Python. Пакет предоставляет исключения SAX и удобные функции, которые будут наиболее востребованы пользователями SAX API.

Предупреждение

Модуль xml.sax не защищен от вредоносно созданных данных. Если требуется проанализировать ненадежные или неаутентифицированные данные, см. раздел Уязвимости XML.

Изменено в версии 3.7.1: SAX парсер больше не обрабатывает общие внешние объекты по умолчанию для повышения безопасности. Прежде парсер создавал сетевые соединения для извлечения удаленных файлов или загружал локальная файлы из файловой системы для DTD и объектов. Функция может быть снова включена с помощью метода, setFeature() на объекте парсер и feature_external_ges аргумента.

Удобные функции:

xml.sax.make_parser(parser_list=[])

Создание и возвращает объекта XMLReader SAX. Первый найденный парсер будет используемый. Если 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 использует три вида объектов: считыватели, обработчики и источники ввода. «Считыватель» в данном контекстt - это еще один термин для парсера, то есть часть кода, которая считывает байты или символы из входного источника и производит последовательность событий. Затем события распределяются по обработчик объектам, т.е. считыватель вызывает метод на обработчик. Поэтому приложение SAX должно получить объект reader, создать или открыть источники ввода, создать обработчики и связать все эти объекты вместе. В качестве последнего этапа подготовки вызывается считыватель для разбора входных данных. При парсинг методы на обработчик объектах вызываются на основе структурных и синтаксических событий из входных данных.

Для этих объектов релевантны только интерфейсы; они обычно не создаются самим приложением. Поскольку 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, вызванный ошибками синтаксического анализа. Сущности этого класса передаются методам ErrorHandler интерфейса SAX для предоставления информации об ошибке синтаксического анализа. Класс поддерживает интерфейс SAX Locator, а также интерфейс SAXException.

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

Подкласс SAXException, возникающий, когда XMLReader SAX сталкивается с нераспознанным элементом или свойством. Приложения и расширения SAX могут использовать этот класс для аналогичных целей.

exception xml.sax.SAXNotSupportedException(msg, exception=None)

Подкласс SAXException возникает, когда XMLReader SAX просят включить функцию, которая не поддерживается, или установить свойство на значение, который не поддерживается реализацией. Приложения и расширения SAX могут использовать этот класс для аналогичных целей.

См.также

SAX: Простой API для XML
Этот сайт является координационным центром для определения SAX API. В нем содержится Java информация о внедрении и онлайновая документация. Также доступны ссылки на реализации и историческую информацию.
Модуль xml.sax.handler
Определения интерфейсов для объектов, предоставляемых приложением.
Модуль xml.sax.saxutils
Функции удобства для использования в приложениях SAX.
Модуль xml.sax.xmlreader
Определения интерфейсов для объектов, предоставляемых парсером.

Объекты SAXException

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

SAXException.getMessage()

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

SAXException.getException()

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