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

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

Пакет 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, полученного в качестве параметра. string должен быть экземпляром str или объектом, подобным bytes.

Изменено в версии 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 должен быть человекочитаемым описанием ошибки. Необязательный параметр исключение, если задан, должен быть 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-приложения и расширения могут использовать этот класс для аналогичных целей.