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 reader всегда производит строки.

Примечание

Ранее 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)

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