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

По умолчанию класс также реализует метод разбора интерфейса 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 (см. раздел Интерфейс 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 или path-like, или объектом 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)

Установите имя свойства в значение. Если свойство не распознано, будет вызвано сообщение SAXNotRecognizedException. Если свойство или его настройка не поддерживается парсером, будет вызвано исключение SAXNotSupportedException.

Объекты IncrementalParser

Экземпляры IncrementalParser предлагают следующие дополнительные методы:

IncrementalParser.feed(data)

Обработка фрагмента данных.

IncrementalParser.close()

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

IncrementalParser.reset()

Этот метод вызывается после вызова close для сброса парсера, чтобы он был готов к разбору новых документов. Результаты вызова parse или feed после close без вызова reset не определены.

Объекты локатора

Экземпляры 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).

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

InputSource.getEncoding()

Получение кодировки символов этого InputSource.

InputSource.setByteStream(bytefile)

Установите поток байтов (a binary file) для этого источника входного сигнала.

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

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

InputSource.getByteStream()

Получение потока байтов для данного источника ввода.

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

InputSource.setCharacterStream(charfile)

Установите поток символов (a text file) для этого источника ввода.

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

InputSource.getCharacterStream()

Получение потока символов для данного источника ввода.

Интерфейс Attributes Интерфейс

Объекты Attributes реализуют часть mapping protocol, включая методы 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()

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