xml.sax.handler
— Базовые классы для обработчиков SAX¶
Исходный код: Lib/xml/sax/handler.py
API SAX определяет пять типов обработчиков: обработчики содержимого, обработчики 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¶
Интерфейс, используемый синтаксическим анализатором для отправки приложению сообщений об ошибках и предупреждений. Методы этого объекта определяют, преобразуются ли ошибки немедленно в исключения или обрабатываются каким-либо другим способом.
- class xml.sax.handler.LexicalHandler¶
Интерфейс, используемый синтаксическим анализатором для представления низкочастотных событий, которые могут не представлять интереса для многих приложений.
В дополнение к этим классам, xml.sax.handler
предоставляет символьные константы для имен объектов и свойств.
- xml.sax.handler.feature_namespaces¶
- значение:
"http://xml.org/sax/features/namespaces"
true: Выполнить обработку пространства имен.false: необязательно выполнять обработку пространства имен (подразумеваются префиксы пространства имен; по умолчанию).доступ: (синтаксический) только для чтения; (без синтаксического анализа) для чтения/записи
- xml.sax.handler.feature_namespace_prefixes¶
- значение:
"http://xml.org/sax/features/namespace-prefixes"
true: Укажите исходные имена с префиксами и атрибуты, используемые для объявления пространства имен.false: Не сообщайте об атрибутах, используемых для объявления пространства имен, и, при необходимости, не сообщайте об исходных именах с префиксами (по умолчанию).доступ: (синтаксический) только для чтения; (без синтаксического анализа) для чтения/записи
- xml.sax.handler.feature_string_interning¶
- значение:
"http://xml.org/sax/features/string-interning"
верно: все имена элементов, префиксы, имена атрибутов, URI пространства имен и локальные имена передаются с помощью встроенной функции intern.false: Имена не обязательно являются интернет-именами, хотя они могут быть такими (по умолчанию).доступ: (синтаксический) только для чтения; (без синтаксического анализа) для чтения/записи
- xml.sax.handler.feature_validation¶
- значение:
"http://xml.org/sax/features/validation"
верно: Сообщайте обо всех ошибках проверки (подразумеваются внешние общие объекты и объекты с внешними параметрами).false: Не сообщайте об ошибках проверки.доступ: (синтаксический) только для чтения; (без синтаксического анализа) для чтения/записи
- xml.sax.handler.feature_external_ges¶
- значение:
"http://xml.org/sax/features/external-general-entities"
true: Включает все внешние общие (текстовые) объекты.false: Не включать внешние общие объекты.доступ: (синтаксический) только для чтения; (без синтаксического анализа) для чтения/записи
- xml.sax.handler.feature_external_pes¶
- значение:
"http://xml.org/sax/features/external-parameter-entities"
true: Включить все объекты внешних параметров, включая подмножество внешних DTD.false: Не включайте никаких объектов с внешними параметрами, даже подмножество внешних DTD.доступ: (синтаксический) только для чтения; (без синтаксического анализа) для чтения/записи
- xml.sax.handler.all_features¶
Список всех функций.
- xml.sax.handler.property_lexical_handler¶
- значение:
"http://xml.org/sax/properties/lexical-handler"
тип данных: xml.sax.обработчик.LexicalHandler (не поддерживается в Python 2)описание: Дополнительный обработчик расширения для лексических событий, таких как комментарии.доступ: чтение/запись
- xml.sax.handler.property_declaration_handler¶
- значение:
"http://xml.org/sax/properties/declaration-handler"
тип данных: xml.sax.saxlib.DeclHandler (не поддерживается в Python 2)описание: Дополнительный обработчик расширений для событий, связанных с DTD, отличных от обозначений и неразличимых объектов.доступ: чтение/запись
- xml.sax.handler.property_dom_node¶
- значение:
"http://xml.org/sax/properties/dom-node"
тип данных: org.w3c.dom.Узел (не поддерживается в Python 2)описание: При синтаксическом анализе используется текущий DOM-узел, который посещается, если это DOMiterator; при отсутствии синтаксического анализа - корневой DOM-узел для итерации.доступ: (синтаксический) только для чтения; (без синтаксического анализа) для чтения/записи
- xml.sax.handler.property_xml_string¶
- значение:
"http://xml.org/sax/properties/xml-string"
тип данных: Байтыописание: Буквальная строка символов, которая была источником для текущего события.доступ: только для чтения
- xml.sax.handler.all_properties¶
Список всех известных названий объектов недвижимости.
Объекты обработчика содержимого¶
Ожидается, что пользователи создадут подкласс 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 в имени будетNone
. Объект, переданный как attrs, может быть повторно использован синтаксическим анализатором; сохранение ссылки на него не является надежным способом сохранения копии атрибутов. Чтобы сохранить копию атрибутов, используйте методcopy()
объекта attrs.Анализаторы могут устанавливать для параметра qname значение
None
, если только функцияfeature_namespace_prefixes
не активирована.
- ContentHandler.endElementNS(name, qname)¶
Сигнализирует о завершении элемента в режиме пространства имен.
Параметр name содержит имя типа элемента, как и в случае с методом
startElementNS()
, аналогично параметру qname.
- ContentHandler.characters(content)¶
Получать уведомления о вводе символьных данных.
Синтаксический анализатор вызовет этот метод, чтобы сообщить о каждом фрагменте символьных данных. Синтаксические анализаторы SAX могут возвращать все непрерывные символьные данные в одном фрагменте или могут разбивать их на несколько фрагментов; однако все символы в любом отдельном событии должны поступать из одного и того же внешнего объекта, чтобы локатор предоставлял полезную информацию.
content может быть экземпляром string или bytes; модуль чтения
expat
всегда выдает строки.Примечание
Более ранний интерфейс SAX 1, предоставленный специальной группой по изучению Python XML, использовал для этого метода интерфейс, более похожий на 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.
Объекты обработчика ошибок¶
Объекты с этим интерфейсом используются для получения информации об ошибках и предупреждениях от XMLReader
. Если вы создадите объект, реализующий этот интерфейс, а затем зарегистрируете его с помощью XMLReader
, синтаксический анализатор вызовет методы вашего объекта, чтобы сообщить обо всех предупреждениях и ошибках. Доступны три уровня ошибок: предупреждения, (возможно) исправимые ошибки и неустранимые ошибки. Все методы принимают SAXParseException
в качестве единственного параметра. Ошибки и предупреждения могут быть преобразованы в исключение путем создания переданного объекта exception.
- 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.