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

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

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

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

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

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

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

См.также

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

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

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

SAXException.getMessage()

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

SAXException.getException()

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