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).

END_OF_DOCUMENT_MARKER

Объекты XMLReader

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

XMLReader.parse(source): Обрабатывает источник ввода, генерируя события SAX. Объект source может быть идентификатором системы (строка, определяющая источник ввода — обычно имя файла или URL), объектом pathlib.Path или объектом path-like, или объектом InputSource. Когда parse() возвращается, ввод полностью обработан, и объект парсера можно удалить или сбросить.

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

Изменено в версии 3.8: Добавлена поддержка path-like объектов.

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(): Возвращает системный идентификатор текущего события.

END_OF_DOCUMENT_MARKER

Объекты InputSource

InputSource.setPublicId(id): Устанавливает идентификатор public данного InputSource.

InputSource.getPublicId(): Возвращает идентификатор public данного InputSource.

InputSource.setSystemId(id): Устанавливает идентификатор system данного InputSource.

InputSource.getSystemId(): Возвращает идентификатор system данного 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) пару для квалифицированного имени.

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

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

© 2001–2022 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.8/library/xml.sax.reader.html