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

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

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

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

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

ContentHandler.endPrefixMapping(prefix)

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

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

ContentHandler.startElement(name, attrs)

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

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

ContentHandler.endElement(name)

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

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

ContentHandler.startElementNS(name, qname, attrs)

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

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

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

ContentHandler.endElementNS(name, qname)

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

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

ContentHandler.characters(content)

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

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

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

Примечание

Предыдущий интерфейс 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)

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