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"
true: Все имена элементов, префиксы, имена атрибутов, URI пространства имен и локальные имена интернируются с помощью встроенной функции intern.
false: Имена не обязательно интернируются, хотя могут быть интернированы (по умолчанию).
доступ: (разбор) только для чтения; (не разбор) чтение/запись
xml.sax.handler.feature_validation
значение: "http://xml.org/sax/features/validation"
true: Сообщать обо всех ошибках валидации (подразумевает external-general-entities и external-parameter-entities).
false: Не сообщать об ошибках валидации.
доступ: (разбор) только для чтения; (не разбор) чтение/запись
xml.sax.handler.feature_external_ges
значение: "http://xml.org/sax/features/external-general-entities"
true: Включить все внешние общие (текстовые) сущности.
ложные: Не включать внешние общие сущности.
доступ: (разбор) только для чтения; (не разбор) чтение/запись
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.handler.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)

Парсер SAX вызывает этот метод только один раз, и это будет последний метод, вызываемый во время разбора. Парсер не должен вызывать этот метод до тех пор, пока он не прекратит разбор (из-за неустранимой ошибки) или не достигнет конца ввода.

Информация из этого события не нужна для обычной обработки пространства имен: SAX XML reader будет автоматически заменять префиксы для имен элементов и атрибутов, если включена функция 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.

Объекты обработчиков ошибок

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

xml.sax — Поддержка парсеров SAX2
xml.sax.saxutils — Утилиты SAX
Вернуться на верх