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

Объекты ContentHandler

Предполагается, что пользователи будут создавать подклассы ContentHandler для поддержки своих приложений. При соответствующих событиях во входном документе анализатор вызывает следующие методы:

ContentHandler.setDocumentLocator(locator)

Вызывается анализатором, чтобы предоставить приложению локатор для определения источника событий документа.

Настоятельно рекомендуется (хотя и не является обязательным), чтобы анализаторы SAX предоставляли локатор. Если он предоставляется, анализатор должен передать его приложению, вызвав этот метод до вызова любого другого метода интерфейса DocumentHandler.

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

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

ContentHandler.startDocument()

Получает уведомление о начале документа.

Анализатор SAX вызывает этот метод только один раз, до вызова любых других методов этого интерфейса или интерфейса DTDHandler (за исключением setDocumentLocator()).

ContentHandler.endDocument()

Получает уведомление об окончании документа.

Анализатор SAX вызывает этот метод только один раз, и это будет последний метод, вызванный во время разбора. Анализатор не должен вызывать этот метод, пока не прекратит разбор (из-за неисправимой ошибки) или не достигнет конца входных данных.

ContentHandler.startPrefixMapping(prefix, uri)

Начинает область действия сопоставления префикса с URI пространства имён.

Информация об этом событии не нужна для обычной обработки пространств имён: XML-считыватель SAX автоматически заменяет префиксы в именах элементов и атрибутов, если включена функция 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 содержит объект интерфейса Атрибуты с атрибутами элемента. Переданный объект attrs может повторно использоваться анализатором; хранение ссылки на него не является надёжным способом сохранить копию атрибутов. Чтобы сохранить копию атрибутов, используйте метод copy() объекта attrs.

ContentHandler.endElement(name)

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

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

ContentHandler.startElementNS(name, qname, attrs)

Сообщает о начале элемента в режиме пространств имён.

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

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

ContentHandler.endElementNS(name, qname)

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

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

ContentHandler.characters(content)

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

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

content может быть строкой или экземпляром bytes; модуль-считыватель expat всегда возвращает строки.

Примечание

В более раннем интерфейсе SAX 1, предоставленном специальной группой по XML в Python, для этого метода использовался интерфейс, более похожий на Java. Поскольку большинство анализаторов, использовавшихся в Python, не задействовали старый интерфейс, вместо него была выбрана более простая сигнатура. Чтобы преобразовать старый код для нового интерфейса, используйте 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-документе. Лексическая информация включает сведения об использованной кодировке документа и встроенных в документ комментариях 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 передаётся через обработчик characters.

LexicalHandler.endCDATA()

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