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

20.12.1. Объекты XMLReader

Интерфейс XMLReader поддерживает следующие методы:

XMLReader.parse(source)

Обрабатывает источник ввода, генерируя события SAX. Объект source может быть системным идентификатором (строкой, идентифицирующей источник ввода — обычно имя файла или URL), объектом, похожим на файл, или объектом InputSource. Когда parse() возвращается, ввод полностью обработан, и объект парсера можно выбросить или сбросить.

Изменено в версии 3.5: Добавлена поддержка потоков символов.

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.

20.12.2. Объекты IncrementalParser

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

IncrementalParser.feed(data)

Обработать блок данных.

IncrementalParser.close()

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

IncrementalParser.reset()

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

20.12.3. Объекты Locator

Примеры Locator предоставляют эти методы:

Locator.getColumnNumber()

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

Locator.getLineNumber()

Возвращает номер строки, в которой начинается текущее событие.

Locator.getPublicId()

Возвращает общественный идентификатор текущего события.

Locator.getSystemId()

Возвращает системный идентификатор текущего события.

20.12.4. Объекты 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()

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

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

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

Attributes.getLength()

Возвращает количество атрибутов.

Attributes.getNames()

Возвращает имена атрибутов.

Attributes.getType(name)

Возвращает тип атрибута name, который обычно равен 'CDATA'.

Attributes.getValue(name)

Возвращает значение атрибута name.

20.12.6. Интерфейс AttributesNS

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

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

AttributesNS.getValueByQName(name)

Возвращает значение для квалифицированного имени.

AttributesNS.getNameByQName(name)

Возвращает пару (namespace, localname) для квалифицированного имени.

AttributesNS.getQNameByName(name)

Возвращает квалифицированное имя для пары (namespace, localname).

AttributesNS.getQNames()

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