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

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

В дополнение к этим классам 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.

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

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