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 и до его возврата.

Для удобства разработчиков драйверов SAX 2.0 этот класс по умолчанию также реализует метод parse интерфейса XMLReader с помощью методов feed, close и reset интерфейса IncrementalParser.

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

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

Объекты 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(): Получить символьный поток для этого источника ввода.

Интерфейс `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) для квалифицированного имени name.

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

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

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