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

Объекты 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): Устанавливает общественный идентификатор этого InputSource.

InputSource.getPublicId(): Возвращает общественный идентификатор этого InputSource.

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

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

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