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

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

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

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

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 или объекта типа байтов.

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

20.9.1. Объекты исключений SAX

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

SAXException.getMessage()

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

SAXException.getException()

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