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

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

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

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

2. Объекты IncrementalParser

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

IncrementalParser.feed(data)

Обработать фрагмент данных.

IncrementalParser.close()

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

IncrementalParser.reset()

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

3. Объекты Locator

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

Locator.getColumnNumber()

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

Locator.getLineNumber()

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

Locator.getPublicId()

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

Locator.getSystemId()

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

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

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

5. Интерфейс Attributes

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

Attributes.getLength()

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

Attributes.getNames()

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

Attributes.getType(name)

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

Attributes.getValue(name)

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

6. Интерфейс AttributesNS

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

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

AttributesNS.getValueByQName(name)

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

AttributesNS.getNameByQName(name)

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

AttributesNS.getQNameByName(name)

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

AttributesNS.getQNames()

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