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

Источник: Lib/xml/sax/__init__.py

Пакет xml.sax предоставляет ряд модулей, реализующих интерфейс Simple API for XML (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_или_stream, может быть именем файла или файловым объектом. Параметр handler должен быть экземпляром SAX ContentHandler. Если указан error_handler, то он должен быть экземпляром SAX ErrorHandler; если его не указать, то при всех ошибках будет выдаваться сообщение SAXParseException. Возвращаемого значения нет; вся работа должна выполняться переданным обработчиком.

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

Аналогично parse(), но разбирает из буфера строку, полученную в качестве параметра. Строка должна быть экземпляром str или bytes-like object.

Изменено в версии 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: The Simple API for XML

Этот сайт является координационным центром для определения API SAX. Он предоставляет реализацию на Java и онлайн-документацию. Также имеются ссылки на реализации и историческую информацию.

Модуль xml.sax.handler

Определения интерфейсов для объектов, предоставляемых приложением.

Модуль xml.sax.saxutils

Удобные функции для использования в приложениях SAX.

Модуль xml.sax.xmlreader

Определения интерфейсов для объектов, предоставляемых парсером.

Объекты SAXException

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

SAXException.getMessage()

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

SAXException.getException()

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