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.

Обработчики ошибок

Объекты с этим интерфейсом используются для получения информации об ошибках и предупреждениях от 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.