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_or_stream, может быть именем файла или файловым объектом. Параметр handler должен быть экземпляром SAX
ContentHandler
. Если указан error_handler, то он должен быть экземпляром SAXErrorHandler
; если он опущен, то при всех ошибках будет выдаваться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
, возникающий при ошибках разбора. Экземпляры этого класса передаются методам интерфейса SAXErrorHandler
для предоставления информации об ошибке разбора. Этот класс поддерживает интерфейс SAXLocator
, а также интерфейсSAXException
.
-
exception
xml.sax.
SAXNotRecognizedException
(msg, exception=None)¶ Подкласс
SAXException
, возникающий, когда SAXXMLReader
сталкивается с нераспознанной функцией или свойством. Приложения и расширения SAX могут использовать этот класс для аналогичных целей.
-
exception
xml.sax.
SAXNotSupportedException
(msg, exception=None)¶ Подкласс
SAXException
, возникающий, когда SAXXMLReader
просят включить функцию, которая не поддерживается, или установить свойство в значение, которое реализация не поддерживает. Приложения и расширения 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
.