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

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

Объекты 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.

Объекты DTDHandler

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

DTDHandler.notationDecl(name, publicId, systemId)

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

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

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

Объекты EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

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

Обработчик ошибок SAX

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

ErrorHandler.error(exception)

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

ErrorHandler.fatalError(exception)

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

ErrorHandler.warning(exception)

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