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

SAX API определяет четыре типа обработчиков: обработчики содержимого, обработчики DTD, обработчики ошибок и преобразователи сущностей. Обычно приложениям нужно реализовывать только те интерфейсы, события которых их интересуют; они могут реализовать интерфейсы в одном объекте или в нескольких объектах. Реализации обработчиков должны наследоваться от базовых классов, представленных в модуле xml.sax.handler, чтобы все методы получали реализации по умолчанию.

class xml.sax.handler.ContentHandler

Это основной интерфейс обратного вызова в SAX и наиболее важный для приложений. Порядок событий в этом интерфейсе отражает порядок информации в документе.

class xml.sax.handler.DTDHandler

Обработка DTD событий.

Данный интерфейс определяет только те события DTD, которые необходимы для базового парсера (неанализируемые сущности и атрибуты).

class xml.sax.handler.EntityResolver

Базовый интерфейс для разрешения сущностей. Если вы создадите объект, реализующий данный интерфейс, а затем зарегистрируете объект в своём парсере, парсер вызовет метод в вашем объекте для разрешения всех внешних сущностей.

class xml.sax.handler.ErrorHandler

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

В дополнение к данным классам xml.sax.handler предоставляет символические константы для имён функций и свойств.

xml.sax.handler.feature_namespaces
значение: "http://xml.org/sax/features/namespaces"
истина: Выполнить обработку пространства имен.
ложь: Необязательно не выполнять обработку пространства имён (подразумеваются префиксы пространства имён; по умолчанию).
доступ: (парсинг) только для чтения; (не парсинг) чтение/запись
xml.sax.handler.feature_namespace_prefixes
значение: "http://xml.org/sax/features/namespace-prefixes"
истина: Сообщить исходные префиксные имена и атрибуты используемые для объявлений пространства имён.
ложь: не сообщать атрибуты используемые для объявлений пространства имён, и необязательно не сообщать исходные префиксные имена (по умолчанию).
доступ: (парсинг) только для чтения; (не парсинг) чтение/запись
xml.sax.handler.feature_string_interning
значение: "http://xml.org/sax/features/string-interning"
истина: Все имена элементов, префиксы, имена атрибутов, URI пространства имен и локальные имена интернируются с помощью встроенной внутренней функции.
ложь: Имена не обязательно интернируются, хотя могут (по умолчанию).
доступ: (парсинг) только для чтения; (не парсинг) чтение/запись
xml.sax.handler.feature_validation
значение: "http://xml.org/sax/features/validation"
истина: Сообщить обо всех ошибках проверки (подразумевает внешние-общие-сущности и внешние-параметры-сущности).
ложь: Не сообщать об ошибках проверки.
доступ: (парсинг) только для чтения; (не парсинг) чтение/запись
xml.sax.handler.feature_external_ges
значение: "http://xml.org/sax/features/external-general-entities"
истина: Включить все внешние общие (текстовые) объекты.
ложь: Не включать внешние общие объекты.
доступ: (парсинг) только для чтения; (не парсинг) чтение/запись
xml.sax.handler.feature_external_pes
значение: "http://xml.org/sax/features/external-parameter-entities"
истина: Включить все внешние объекты параметров, включая внешнее подмножество DTD.
ложь: Не включать внешние объекты параметров, даже внешнее подмножество DTD.
доступ: (парсинг) только для чтения; (не парсинг) чтение/запись
xml.sax.handler.all_features

Список всех функций.

xml.sax.handler.property_lexical_handler
значение: "http://xml.org/sax/properties/lexical-handler"
тип данных: xml.sax.sax2lib.LexicalHandler (не поддерживается в Python 2)
описание: Дополнительный обработчик расширения для лексических событий, таких как комментарии.
доступ: чтение/запись
xml.sax.handler.property_declaration_handler
значение: "http://xml.org/sax/properties/declaration-handler"
тип данных: xml.sax.sax2lib.DeclHandler (не поддерживается в Python 2)
описание: Необязательное расширение, обработчик для событий, связанных с DTD, кроме обозначений и необработанных сущностей.
доступ: чтение/запись
xml.sax.handler.property_dom_node
значение: "http://xml.org/sax/properties/dom-node"
тип данных: org.w3c.dom.Node (не поддерживается в Python 2)
описание: При парсинге текущего посещаемого узела DOM, если это итератор DOM; если не парсинг, корневого узела DOM для итерации.
доступ: (парсинг) только для чтения; (не парсинг) чтение/запись
xml.sax.handler.property_xml_string
значение: "http://xml.org/sax/properties/xml-string"
тип данных: Строка
описание: Литеральная строка символов, которая была источником для текущего события.
доступ: только для чтения
xml.sax.handler.all_properties

Список всех известных имён свойств.

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

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

Примечание

Более ранний интерфейс SAX 1, предоставленный Python XML Special Interest Group, использовал для этого метода более похожий на 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)

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