xml.sax.xmlreader — Интерфейс для парсеров XML

Исходный код: Lib/xml/sax/xmlreader.py

Парсеры SAX реализуют интерфейс XMLReader. Они реализованы в модуле Python, который должен предоставить функцию create_parser(). Эта функция вызывается xml.sax.make_parser() без аргументов для создания нового объекта парсера.

class xml.sax.xmlreader.XMLReader

Базовый класс, который может быть унаследован парсерами SAX.

class xml.sax.xmlreader.IncrementalParser

В некоторых случаях желательно не парсить исходный источник сразу, а подавать фрагменты документа по мере их появления. Обратите внимание, что читатель обычно не читает весь файл, а читает его частями; тем не менее parse() не вернётся, пока весь документ не будет обработан. Поэтому эти интерфейсы следует использовать, если блокирующее поведение parse() нежелательно.

При создании парсер готов сразу принимать данные из метода feed. После завершения парсинга вызовом метода close, необходимо вызвать метод reset, чтобы подготовить парсер к приёму новых данных, либо с помощью метода feed, либо с помощью метода parse.

Обратите внимание, что эти методы не должны вызываться во время парсинга, то есть после вызова parse и до его возвращения.

По умолчанию класс также реализует метод parse интерфейса XMLReader, используя методы feed, close и reset интерфейса IncrementalParser в качестве удобства для разработчиков драйверов SAX 2.0.

class xml.sax.xmlreader.Locator

Интерфейс для связывания события SAX с местоположением в документе. Объект locator будет возвращать корректные результаты только во время вызовов методов DocumentHandler; в любое другое время результаты непредсказуемы. Если информация недоступна, методы могут возвращать None.

class xml.sax.xmlreader.InputSource(system_id=None)

Инкапсуляция информации, необходимой XMLReader для чтения сущностей.

Этот класс может содержать информацию о публичном идентификаторе, системном идентификаторе, потоке байтов (возможно, с информацией о кодировке символов) и/или потоке символов сущности.

Приложения будут создавать объекты этого класса для использования в методе XMLReader.parse() и для возврата из EntityResolver.resolveEntity.

Объект InputSource принадлежит приложению, XMLReader не имеет права изменять объекты InputSource, переданные ему приложением, хотя он может создавать копии и изменять их.

class xml.sax.xmlreader.AttributesImpl(attrs)

Это реализация интерфейса Attributes (см. раздел Интерфейс Attributes). Это объект, похожий на словарь, который представляет атрибуты элемента в вызове startElement(). В дополнение к наиболее полезным операциям со словарями, он поддерживает ряд других методов, как описано в интерфейсе. Объекты этого класса должны создаваться читателями; attrs должен быть объектом, похожим на словарь, содержащим отображение имен атрибутов на значения атрибутов.

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

Пространственно-именной вариант AttributesImpl, который будет передан в startElementNS(). Он происходит от AttributesImpl, но понимает имена атрибутов как пары кортежей namespaceURI и localname. Кроме того, он предоставляет ряд методов, ожидающих квалифицированные имена, как они появляются в исходном документе. Этот класс реализует интерфейс AttributesNS (см. раздел Интерфейс AttributesNS).

Объекты XMLReader

Интерфейс XMLReader поддерживает следующие методы:

XMLReader.parse(source)

Обработка исходного источника, генерирующая события SAX. Объект source может быть системным идентификатором (строкой, определяющей исходный источник — обычно имя файла или URL), объектом типа «подобный файлу» или объектом InputSource. Когда parse() возвращается, вход полностью обработан, и объект парсера может быть удалён или сброшен.

Изменено в версии 3.5: Добавлена поддержка потоков символов.

XMLReader.getContentHandler()

Возвращает текущий ContentHandler.

XMLReader.setContentHandler(handler)

Устанавливает текущий ContentHandler. Если ContentHandler не установлен, события контента будут игнорироваться.

XMLReader.getDTDHandler()

Возвращает текущий DTDHandler.

XMLReader.setDTDHandler(handler)

Устанавливает текущий DTDHandler. Если DTDHandler не установлен, события DTD будут игнорироваться.

XMLReader.getEntityResolver()

Возвращает текущий EntityResolver.

XMLReader.setEntityResolver(handler)

Устанавливает текущий EntityResolver. Если EntityResolver не установлен, попытки разрешить внешнюю сущность приведут к открытию системного идентификатора для сущности и завершатся ошибкой, если он недоступен.

XMLReader.getErrorHandler()

Возвращает текущий ErrorHandler.

XMLReader.setErrorHandler(handler)

Устанавливает текущего обработчика ошибок. Если ErrorHandler не установлен, ошибки будут подниматься как исключения, а предупреждения будут выводиться на печать.

XMLReader.setLocale(locale)

Позволяет приложению установить локаль для ошибок и предупреждений.

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

XMLReader.getFeature(featurename)

Возвращает текущее значение параметра featurename. Если параметр не распознан, SAXNotRecognizedException поднимается. Известные имена параметров перечислены в модуле xml.sax.handler.

XMLReader.setFeature(featurename, value)

Устанавливает параметр featurename в значение value. Если параметр не распознан, SAXNotRecognizedException поднимается. Если параметр или его значение не поддерживается парсером, поднимается SAXNotSupportedException.

XMLReader.getProperty(propertyname)

Возвращает текущее значение свойства propertyname. Если свойство не распознано, SAXNotRecognizedException поднимается. Известные имена свойств перечислены в модуле xml.sax.handler.

XMLReader.setProperty(propertyname, value)

Устанавливает свойство propertyname в значение value. Если свойство не распознано, SAXNotRecognizedException поднимается. Если свойство или его значение не поддерживается парсером, поднимается SAXNotSupportedException.

Объекты IncrementalParser

Экземпляры IncrementalParser предлагают следующие дополнительные методы:

IncrementalParser.feed(data)

Обработать фрагмент data.

IncrementalParser.close()

Предположите конец документа. Это проверит условия корректности, которые могут быть проверены только в конце, вызовет обработчики и может очистить ресурсы, выделенные во время разбора.

IncrementalParser.reset()

Этот метод вызывается после вызова close для сброса парсера, чтобы он был готов к разбору новых документов. Результаты вызова parse или feed после close без вызова reset не определены.

Объекты Locator

Экземпляры Locator предоставляют эти методы:

Locator.getColumnNumber()

Возвращает номер столбца, в котором начинается текущее событие.

Locator.getLineNumber()

Возвращает номер строки, в которой начинается текущее событие.

Locator.getPublicId()

Возвращает общедоступный идентификатор для текущего события.

Locator.getSystemId()

Возвращает системный идентификатор для текущего события.

Объекты InputSource

InputSource.setPublicId(id)

Устанавливает общедоступный идентификатор этого InputSource.

InputSource.getPublicId()

Возвращает общедоступный идентификатор этого InputSource.

InputSource.setSystemId(id)

Устанавливает системный идентификатор этого InputSource.

InputSource.getSystemId()

Возвращает системный идентификатор этого InputSource.

InputSource.setEncoding(encoding)

Устанавливает кодировку символов этого InputSource.

Кодировка должна быть строкой, приемлемой для объявления кодировки XML (см. раздел 4.3.3 рекомендации XML).

Атрибут encoding объекта InputSource игнорируется, если объект InputSource также содержит символьный поток.

InputSource.getEncoding()

Получить кодировку символов этого InputSource.

InputSource.setByteStream(bytefile)

Установить бинарный поток (бинарный файл) для этого источника ввода.

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

Если приложение знает кодировку символов бинарного потока, оно должно установить её с помощью метода setEncoding.

InputSource.getByteStream()

Получить бинарный поток для этого источника ввода.

Метод getEncoding вернёт кодировку символов для этого бинарного потока или None если она неизвестна.

InputSource.setCharacterStream(charfile)

Установить символьный поток (текстовый файл) для этого источника ввода.

Если указан символьный поток, парсер SAX проигнорирует любой бинарный поток и не попытается открыть соединение с URI по системному идентификатору.

InputSource.getCharacterStream()

Получить символьный поток для этого источника ввода.

Интерфейс Attributes

Attributes объекты реализуют часть протокола отображения отображения, включая методы copy(), get(), __contains__(), items(), keys(), и values(). Также предоставляются следующие методы:

Attributes.getLength()

Возвращает количество атрибутов.

Attributes.getNames()

Возвращает имена атрибутов.

Attributes.getType(name)

Возвращает тип атрибута name, который обычно 'CDATA'.

Attributes.getValue(name)

Возвращает значение атрибута name.

Интерфейс AttributesNS

Этот интерфейс является подтипом интерфейса Attributes (см. раздел Интерфейс Attributes). Все методы, поддерживаемые этим интерфейсом, также доступны для объектов AttributesNS.

Также доступны следующие методы:

AttributesNS.getValueByQName(name)

Возвращает значение для квалифицированного имени.

AttributesNS.getNameByQName(name)

Возвращает (namespace, localname) пару для квалифицированного name.

AttributesNS.getQNameByName(name)

Возвращает квалифицированное имя для (namespace, localname) пары.

AttributesNS.getQNames()

Возвращает квалифицированные имена всех атрибутов.