20.9. xml.sax – Поддержка парсеров SAX2¶xml.sax – Support for SAX2 parsers

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

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

xml.sax.make_parser(parser_list=[])¶

Создаёт и возвращает объект SAX XMLReader. Будет использован первый найденный парсер. Если указан параметр parser_list, он должен быть последовательностью строк, которые называют модули, содержащие функцию create_parser(). Модули из 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, переданного в качестве параметра.

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