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

Пакет 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])

Создаёт SAX-парсер и использует его для анализа документа. Документ, переданный как filename_or_stream, может быть именем файла или объектом файла. Параметр handler должен быть экземпляром SAX ContentHandler. Если error_handler задан, он должен быть экземпляром SAX ErrorHandler; если он опущен, будет поднято исключение SAXParseException при всех ошибках. Возвращаемое значение отсутствует; вся работа должна выполняться переданным handler.

xml.sax.parseString(string, handler[, error_handler])

Аналогично 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])

Упаковывает 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])

Подкласс SAXException, поднимаемый, когда SAX XMLReader сталкивается с нераспознанным свойством или функцией. Приложения и расширения SAX могут использовать этот класс для аналогичных целей.

exception xml.sax.SAXNotSupportedException(msg[, exception])

Подкласс SAXException, поднимаемый, когда SAX XMLReader попросили включить функцию, которая не поддерживается, или установить свойство со значением, которое не поддерживается реализацией. Приложения и расширения SAX могут использовать этот класс для аналогичных целей.

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

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

SAXException.getMessage()

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

SAXException.getException()

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