xml.sax.xmlreader — Интерфейс для парсеров XML

Парсеры 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 с местоположением в документе. Объект локатора вернёт корректные результаты только во время вызовов методов обработчика документа; в любое другое время результаты непредсказуемы. Если информация недоступна, методы могут вернуть None.

class xml.sax.xmlreader.InputSource([systemId])

Инкапсуляция информации, необходимой 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).

1. Объекты XMLReader

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

XMLReader.parse(source)

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

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.

2. Объекты IncrementalParser

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

IncrementalParser.feed(data)

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

IncrementalParser.close()

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

IncrementalParser.reset()

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

3. Объекты Locator

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

Locator.getColumnNumber()

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

Locator.getLineNumber()

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

Locator.getPublicId()

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

Locator.getSystemId()

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

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)

Установить байтовый поток (объект Python, подобный файлу, который не выполняет преобразование байтов в символы) для этого источника ввода.

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

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

InputSource.getByteStream()

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

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

InputSource.setCharacterStream(charfile)

Установить символьный поток для этого источника ввода. (Поток должен быть объектом Python 1.6 Unicode-оборачивающим файлоподобным, который выполняет преобразование в строки Unicode.)

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

InputSource.getCharacterStream()

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

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

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

Attributes.getLength()

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

Attributes.getNames()

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

Attributes.getType(name)

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

Attributes.getValue(name)

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

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

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

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

AttributesNS.getValueByQName(name)

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

AttributesNS.getNameByQName(name)

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

AttributesNS.getQNameByName(name)

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

AttributesNS.getQNames()

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