xml.sax — Поддержка синтаксических анализаторов SAX2¶

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

Пакет xml.sax предоставляет ряд модулей, которые реализуют простой интерфейс API для 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(), но выполняется синтаксический анализ из буфера string, полученного в качестве параметра. string должен быть экземпляром str или bytes-like object.

Изменено в версии 3.5: Добавлена поддержка экземпляров str.

Типичное приложение SAX использует три вида объектов: считыватели, обработчики и источники ввода. «Считыватель» в данном контексте - это еще один термин для синтаксического анализа, т.е. некоторого фрагмента кода, который считывает байты или символы из источника ввода и генерирует последовательность событий. Затем события распределяются по объектам обработчика, т.е. reader вызывает метод в обработчике. Таким образом, приложение SAX должно получить объект reader, создать или открыть источники ввода, обработчики и соединить все эти объекты вместе. На заключительном этапе подготовки вызывается программа чтения для анализа входных данных. Во время синтаксического анализа методы объектов-обработчиков вызываются на основе структурных и синтаксических событий из входных данных.

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