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

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

Изменено в версии 3.8: Аргумент 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. Возвращаемого значения нет; вся работа должна быть выполнена переданным обработчиком.

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())¶

Аналогичен parse(), но разбирает из буфера строку, полученную в качестве параметра. Строка должна быть экземпляром str или bytes-like object.

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