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