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

Объекты 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 (см. Интерфейс атрибутовNS) содержащий атрибуты элемента. Если элементу не ассоциировано пространство имён, компонент 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 Special Interest Group, использовал более похожий на 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.

Объекты ErrorHandler

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

ErrorHandler.error(exception)

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

ErrorHandler.fatalError(exception)

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

ErrorHandler.warning(exception)

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

Объекты LexicalHandler

Необязательный обработчик SAX2 для лексических событий.

Этот обработчик используется для получения лексической информации об XML-документе. Лексическая информация включает информацию, описывающую кодировку документа, используемую в документе, а также границы разделов для DTD и для любых разделов CDATA. Лексические обработчики используются аналогично обработчикам содержимого.

Установите LexicalHandler XMLReader, используя метод setProperty с идентификатором свойства 'http://xml.org/sax/properties/lexical-handler'.

LexicalHandler.comment(content)

Сообщает о комментарии где угодно в документе (включая DTD и вне элемента документа).

LexicalHandler.startDTD(name, public_id, system_id)

Сообщает о начале объявления DTD, если у документа есть связанный DTD.

LexicalHandler.endDTD()

Сообщает об окончании объявления DTD.

LexicalHandler.startCDATA()

Сообщает о начале раздела, помеченного CDATA.

Содержимое раздела, помеченного CDATA, будет сообщено через обработчик символов.

LexicalHandler.endCDATA()

Сообщает об окончании раздела, помеченного CDATA.