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

END_OF_DOCUMENT_MARKER

Объекты XMLReader

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

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

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

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

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.9/library/xml.sax.reader.html