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

Объекты 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 с атрибутами элемента. Парсер может повторно использовать объект, переданный как attrs; поэтому хранение ссылки на него не является надёжным способом сохранить копию атрибутов. Чтобы сохранить копию атрибутов, используйте метод copy() объекта attrs.

ContentHandler.endElement(name)

Сообщает об окончании элемента в режиме без пространств имён.

Параметр name содержит имя типа элемента, как и в событии startElement().

ContentHandler.startElementNS(name, qname, attrs)

Сообщает о начале элемента в режиме пространств имён.

Параметр name содержит имя типа элемента в виде кортежа (uri, localname), параметр qname содержит необработанное имя XML 1.0, использованное в исходном документе, а параметр attrs содержит экземпляр интерфейса AttributesNS с атрибутами элемента. Если элементу не сопоставлено пространство имён, компонент uri значения name будет равен None. Парсер может повторно использовать объект, переданный как attrs; поэтому хранение ссылки на него не является надёжным способом сохранить копию атрибутов. Чтобы сохранить копию атрибутов, используйте метод copy() объекта attrs.

Парсеры могут задать параметру qname значение None, если не включена функция feature_namespace_prefixes.

ContentHandler.endElementNS(name, qname)

Сообщает об окончании элемента в режиме пространств имён.

Параметр name содержит имя типа элемента, как и в методе startElementNS(); то же относится и к параметру qname.

ContentHandler.characters(content)

Получить уведомление о символьных данных.

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

content может быть строкой или экземпляром bytes; модуль чтения 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)

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

Объекты 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.