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

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

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

InputSource.setByteStream(bytefile)

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

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

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

InputSource.getByteStream()

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

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

InputSource.setCharacterStream(charfile)

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

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

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–2024 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.13/library/xml.sax.reader.html