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