Содержание страницы

`xml.sax.xmlreader` – Интерфейс для парсеров XML¶xml.sax.xmlreader – Interface for XML parsers

Исходный код: 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 к местоположению в документе. Объект локатора возвращает корректные результаты только во время вызовов методов 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 (см. раздел The Attributes Interface). Это словареподобный объект, который представляет атрибуты элемента в вызове startElement(). В дополнение к наиболее полезным операциям со словарём, он поддерживает ряд других методов, описанных интерфейсом. Объекты этого класса должны создаваться читателями; attrs должен быть словареподобным объектом, содержащим отображение имён атрибутов в значения атрибутов.

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)¶: Вариант AttributesImpl с поддержкой пространств имён, который передаётся в startElementNS(). Он является производным от AttributesImpl, но понимает имена атрибутов как кортежи из двух элементов: namespaceURI и localname. Кроме того, он предоставляет ряд методов, ожидающих квалифицированные имена в том виде, в котором они появляются в исходном документе. Этот класс реализует интерфейс AttributesNS (см. раздел The AttributesNS Interface).

Объекты XMLReader¶XMLReader Objects

Интерфейс 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)¶: Устанавливает propertyname в value. Если свойство не распознано, возбуждается SAXNotRecognizedException. Если свойство или его значение не поддерживаются парсером, возбуждается SAXNotSupportedException.

Объекты IncrementalParser¶IncrementalParser Objects

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

IncrementalParser.feed(data)¶: Обрабатывает фрагмент data.

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

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

Объекты Locator¶Locator Objects

Экземпляры Locator предоставляют следующие методы:

Locator.getColumnNumber()¶: Возвращает номер столбца, с которого начинается текущее событие.

Locator.getLineNumber()¶: Возвращает номер строки, с которой начинается текущее событие.

Locator.getPublicId()¶: Возвращает общедоступный идентификатор текущего события.

Locator.getSystemId()¶: Возвращает системный идентификатор текущего события.

Объекты InputSource¶InputSource Objects

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`¶The Attributes Interface

Объекты Attributes реализуют часть протокола отображения, включая методы copy(), get(), __contains__(), items(), keys() и values(). Также предоставляются следующие методы:

Attributes.getLength()¶: Возвращает количество атрибутов.

Attributes.getNames()¶: Возвращает имена атрибутов.

Attributes.getType(name)¶: Возвращает тип атрибута имя, который обычно равен 'CDATA'.

Attributes.getValue(name)¶: Возвращает значение атрибута имя.

Интерфейс `AttributesNS`¶The AttributesNS Interface

Этот интерфейс является подтипом интерфейса Attributes (см. раздел Интерфейс атрибутов). Все методы, поддерживаемые этим интерфейсом, также доступны для объектов AttributesNS.

Также доступны следующие методы:

AttributesNS.getValueByQName(name)¶: Возвращает значение для полного имени.

AttributesNS.getNameByQName(name)¶: Возвращает пару (namespace, localname) для полного имени.

AttributesNS.getQNameByName(name)¶: Возвращает полное имя для пары (namespace, localname).

AttributesNS.getQNames()¶: Возвращает полные имена всех атрибутов.