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