xml.sax.handler — Базовые классы для обработчиков SAX

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

API SAX определяет четыре вида обработчиков: обработчики содержимого, обработчики DTD, обработчики ошибок и обработчики разрешения сущностей. Приложениям обычно требуется реализовать только те интерфейсы, события которых их интересуют; они могут реализовать интерфейсы в одном объекте или в нескольких объектах. Реализации обработчиков должны наследоваться от базовых классов, предоставленных в модуле xml.sax.handler, чтобы все методы получали реализации по умолчанию.

class xml.sax.handler.ContentHandler

Это основной интерфейс обратного вызова в SAX, и самый важный для приложений. Порядок событий в этом интерфейсе отражает порядок информации в документе.

class xml.sax.handler.DTDHandler

Обработка событий DTD.

Этот интерфейс определяет только те события DTD, необходимые для базового разбора (необработанные сущности и атрибуты).

class xml.sax.handler.EntityResolver

Базовый интерфейс для разрешения сущностей. Если вы создаёте объект, реализующий этот интерфейс, и регистрируете его в вашем анализаторе, анализатор будет вызывать метод в вашем объекте для разрешения всех внешних сущностей.

class xml.sax.handler.ErrorHandler

Интерфейс, используемый анализатором для представления сообщений об ошибках и предупреждениях приложению. Методы этого объекта управляют тем, преобразуются ли ошибки немедленно в исключения или обрабатываются каким-то другим способом.

В дополнение к этим классам, xml.sax.handler предоставляет символьные константы для имён функций и свойств.

xml.sax.handler.feature_namespaces

xml.sax.handler.feature_namespace_prefixes

xml.sax.handler.feature_string_interning

xml.sax.handler.feature_validation

xml.sax.handler.feature_external_ges

xml.sax.handler.feature_external_pes

xml.sax.handler.all_features

Список всех функций.

xml.sax.handler.property_lexical_handler

xml.sax.handler.property_declaration_handler

xml.sax.handler.property_dom_node

xml.sax.handler.property_xml_string

xml.sax.handler.all_properties

Список всех известных имён свойств.

1. Объекты ContentHandler

Ожидается, что пользователи будут подклассировать ContentHandler для поддержки своих приложений. Следующие методы вызываются анализатором при соответствующих событиях во входном документе:

ContentHandler.setDocumentLocator(locator)

Вызывается анализатором, чтобы предоставить приложению локатор для определения источника событий документа.

SAX анализаторы настоятельно рекомендуются (хотя и не абсолютно необходимы) предоставить локатор: если он это сделает, он должен предоставить локатор приложению, вызвав этот метод перед вызовом любого из других методов в интерфейсе DocumentHandler.

Локатор позволяет приложению определить конечную позицию любого события, связанного с документом, даже если анализатор не сообщает об ошибке. Как правило, приложение будет использовать эту информацию для сообщения об собственных ошибках (например, контент символов, который не соответствует бизнес-правилам приложения). Информация, возвращаемая локатором, вероятно, недостаточна для использования с поисковой системой.

Обратите внимание, что локатор будет возвращать корректную информацию только во время вызова событий в этом интерфейсе. Приложение не должно пытаться использовать его в другое время.

ContentHandler.startDocument()

Получает уведомление о начале документа.

SAX анализатор вызовет этот метод только один раз, прежде чем вызывать любые другие методы в этом интерфейсе или в DTDHandler (кроме setDocumentLocator()).

ContentHandler.endDocument()

Получает уведомление об окончании документа.

SAX анализатор вызовет этот метод только один раз, и это будет последний метод, вызванный во время разбора. Анализатор не вызовет этот метод, пока не откажется от разбора (из-за неисправимой ошибки) или не достигнет конца входных данных.

ContentHandler.startPrefixMapping(prefix, uri)

Начинает область сопоставления префикс-URI пространства имён.

Информация из этого события не необходима для обычной обработки пространства имён: SAX XML-читатель автоматически заменит префиксы для имён элементов и атрибутов, когда функция feature_namespaces включена (по умолчанию).

Однако есть случаи, когда приложениям нужно использовать префиксы в данных символов или в значениях атрибутов, где их нельзя безопасно автоматически расширить; события startPrefixMapping() и endPrefixMapping() предоставляют приложению информацию для расширения префиксов в этих контекстах самостоятельно, если это необходимо.

Обратите внимание, что события startPrefixMapping() и endPrefixMapping() не гарантируются как правильно вложенные относительно друг друга: все события startPrefixMapping() произойдут до соответствующего события startElement(), а все события endPrefixMapping() произойдут после соответствующего события endElement(), но их порядок не гарантируется.

ContentHandler.endPrefixMapping(prefix)

Заканчивает область сопоставления префикс-URI.

См. startPrefixMapping() для получения подробностей. Это событие всегда будет происходить после соответствующего события endElement(), но порядок событий endPrefixMapping() не гарантируется.

ContentHandler.startElement(name, attrs)

Сигнализирует о начале элемента в режиме без пространства имён.

Параметр name содержит исходное имя элемента типа XML 1.0 в виде строки, а параметр attrs содержит объект интерфейса Attributes (см. Интерфейс атрибутов), содержащий атрибуты элемента. Объект, переданный как attrs, может быть повторно использован анализатором; удержание ссылки на него не является надёжным способом сохранить копию атрибутов. Для сохранения копии атрибутов используйте метод copy() объекта attrs.

ContentHandler.endElement(name)

Сигнализирует об окончании элемента в режиме без пространства имён.

Параметр name содержит имя типа элемента, так же как и в событии startElement().

ContentHandler.startElementNS(name, qname, attrs)

Сигнализирует о начале элемента в режиме пространства имён.

Параметр name содержит имя типа элемента как (uri, localname) кортеж, параметр qname содержит исходное имя XML 1.0, используемое в исходном документе, а параметр attrs содержит экземпляр интерфейса AttributesNS (см. Интерфейс AttributesNS), содержащий атрибуты элемента. Если элементу не присвоено пространство имён, компонента uri в name будет None. Объект, переданный как attrs, может быть повторно использован анализатором; удержание ссылки на него не является надёжным способом сохранить копию атрибутов. Для сохранения копии атрибутов используйте метод copy() объекта attrs.

Анализаторы могут установить параметр qname в None, если не активирована функция feature_namespace_prefixes.

ContentHandler.endElementNS(name, qname)

Сигнализирует об окончании элемента в режиме именованных пространств.

Параметр name содержит имя типа элемента, как и в методе startElementNS(), аналогично параметру qname.

ContentHandler.characters(content)

Получение уведомления о данных символов.

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

content может быть строкой или экземпляром байтов; модуль чтения expat всегда производит строки.

Примечание

Предыдущий интерфейс SAX 1, предоставленный группой по интересам Python XML, использовал более похожий на Java интерфейс для этого метода. Поскольку большинство парсеров, используемых из Python, не использовали старый интерфейс, было выбрано более простое сигнатуру для его замены. Для преобразования старого кода в новый интерфейс используйте content вместо среза content с параметрами offset и length в старой версии.

ContentHandler.ignorableWhitespace(whitespace)

Получение уведомления о пропускаемых пробелах в содержимом элемента.

Валидирующие парсеры должны использовать этот метод для отчёта о каждом фрагменте пропускаемых пробелов (см. рекомендацию W3C XML 1.0, раздел 2.10): невалидирующие парсеры также могут использовать этот метод, если они способны анализировать и использовать модели содержимого.

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

ContentHandler.processingInstruction(target, data)

Получение уведомления об обработке инструкции.

Парсер вызовет этот метод один раз для каждой найденной инструкции обработки: обратите внимание, что инструкции обработки могут появляться до или после основного элемента документа.

Парсер SAX никогда не должен сообщать об XML-декларации (XML 1.0, раздел 2.8) или декларации текста (XML 1.0, раздел 4.3.1) с помощью этого метода.

ContentHandler.skippedEntity(name)

Получение уведомления о пропущенной сущности.

Парсер вызовет этот метод один раз для каждой пропущенной сущности. Невалидирующие процессоры могут пропускать сущности, если они не видели деклараций (например, потому что сущность была объявлена во внешнем DTD подмножестве). Все процессоры могут пропускать внешние сущности, в зависимости от значений feature_external_ges и feature_external_pes свойств.

2. Объекты DTDHandler

DTDHandler экземпляры предоставляют следующие методы:

DTDHandler.notationDecl(name, publicId, systemId)

Обработка события объявления нотации.

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

Обработка события объявления необработанной сущности.

3. Объекты EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

Разрешить системный идентификатор сущности и вернуть либо системный идентификатор для чтения в виде строки, либо InputSource для чтения. Стандартная реализация возвращает systemId.

4. Объекты ErrorHandler

Объекты с этим интерфейсом используются для получения информации об ошибках и предупреждениях от XMLReader. Если вы создаёте объект, реализующий этот интерфейс, и регистрируете его в вашем XMLReader, парсер вызовет методы в вашем объекте, чтобы сообщить обо всех предупреждениях и ошибках. Существуют три уровня ошибок: предупреждения, (возможно) исправимые ошибки и неисправимые ошибки. Все методы принимают SAXParseException в качестве единственного параметра. Ошибки и предупреждения могут быть преобразованы в исключение путём поднятия переданного исключения.

ErrorHandler.error(exception)

Вызывается, когда парсер сталкивается с исправимой ошибкой. Если этот метод не вызывает исключение, анализ может продолжиться, но дальнейшая информация о документе не должна ожидаться приложением. Разрешение парсеру продолжить может позволить обнаружить дополнительные ошибки в документе.

ErrorHandler.fatalError(exception)

Вызывается, когда парсер сталкивается с ошибкой, от которой он не может восстановиться; ожидается, что анализ завершится, когда этот метод вернётся.

ErrorHandler.warning(exception)

Вызывается, когда парсер предоставляет приложению незначительную предупреждающую информацию. Ожидается, что анализ продолжится, когда этот метод вернётся, и информация о документе будет продолжать передаваться приложению. Вызов исключения в этом методе приведёт к завершению анализа.