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 (см. Интерфейс 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 могут возвращать все непрерывные символьные данные одним фрагментом или разбивать их на несколько фрагментов; однако все символы в одном событии должны происходить из одной и той же внешней сущности, чтобы Locator предоставлял полезную информацию.

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

Примечание

В более раннем интерфейсе SAX 1, предоставленном специальной группой Python XML, для этого метода использовался интерфейс, более похожий на Java. Поскольку большинство анализаторов, используемых в Python, не задействовали старый интерфейс, вместо него была выбрана более простая сигнатура. Чтобы преобразовать старый код для работы с новым интерфейсом, используйте content вместо выделения части содержимого с помощью старых параметров offset и length.

ContentHandler.ignorableWhitespace(whitespace)

Получает уведомление о незначащих пробельных символах в содержимом элемента.

Проверяющие анализаторы должны использовать этот метод для передачи каждого фрагмента незначащих пробельных символов (см. рекомендацию W3C XML 1.0, раздел 2.10); непроверяющие анализаторы также могут использовать этот метод, если способны разбирать и использовать модели содержимого.

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

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.