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

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

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

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

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