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

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

20.10.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.

20.10.2. Объекты DTDHandler

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

DTDHandler.notationDecl(name, publicId, systemId)

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

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

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

20.10.3. Объекты EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

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

20.10.4. Обработчики ошибок

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

ErrorHandler.error(exception)

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

ErrorHandler.fatalError(exception)

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

ErrorHandler.warning(exception)

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