xml.parsers.expat – Быстрый разбор XML с помощью Expat¶xml.parsers.expat – Fast XML parsing using Expat

Объекты XMLParser¶XMLParser Objects

Объекты xmlparser имеют следующие методы:

xmlparser.Parse(data[, isfinal])¶

Разбирает содержимое строки data, вызывая соответствующие функции-обработчики для обработки разобранных данных. isfinal должен быть истинным при последнем вызове этого метода. data может быть пустой строкой в любое время.

xmlparser.ParseFile(file)¶

Выполняет синтаксический анализ XML-данных, считывая их из объекта file. Объект file должен предоставлять только метод read(nbytes), который возвращает пустую строку, когда данные закончились.

xmlparser.SetBase(base)¶

Устанавливает базовый URI, используемый для разрешения относительных URI в системных идентификаторах в объявлениях. Разрешение относительных идентификаторов оставлено на усмотрение приложения: это значение будет передаваться в качестве аргумента base функциям ExternalEntityRefHandler(), NotationDeclHandler() и UnparsedEntityDeclHandler().

xmlparser.GetBase()¶

Возвращает строку, содержащую базовый URI, установленный предыдущим вызовом SetBase(), или None, если SetBase() не вызывался.

xmlparser.GetInputContext()¶

Возвращает входные данные, которые породили текущее событие, в виде строки. Данные представлены в кодировке сущности, содержащей текст. Если метод вызван, когда обработчик события не активен, возвращается None.

xmlparser.ExternalEntityParserCreate(context, encodingencoding])¶

Create a “child” parser which can be used to parse an external parsed entity referred to by content parsed by the parent parser. The context parameter should be the string passed to the ExternalEntityRefHandler() handler function, described below. The child parser is created with the ordered_attributes and specified_attributes set to the values of this parser.

xmlparser.UseForeignDTD([flag])¶

Вызов этого с истинным значением для flag (по умолчанию) заставит Expat вызывать ExternalEntityRefHandler с None для всех аргументов, чтобы разрешить загрузку альтернативного DTD. Если документ не содержит объявления типа документа, ExternalEntityRefHandler всё равно будет вызван, но StartDoctypeDeclHandler и EndDoctypeDeclHandler вызываться не будут.

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

Этот метод можно вызывать только до вызова методов Parse() или ParseFile(); вызов после любого из них приводит к возбуждению ExpatError с атрибутом code, установленным в errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING.

Объекты xmlparser имеют следующие атрибуты:

xmlparser.buffer_size¶

Размер буфера, используемого, когда buffer_text имеет значение true. Новый размер буфера можно задать, присвоив этому атрибуту новое целочисленное значение. При изменении размера буфер будет сброшен.

xmlparser.buffer_text¶

Установка этого атрибута в true заставляет объект xmlparser буферизовать текстовое содержимое, возвращаемое Expat, чтобы по возможности избежать множественных вызовов колбэка CharacterDataHandler(). Это может значительно повысить производительность, поскольку Expat обычно разбивает символьные данные на фрагменты на каждом конце строки. По умолчанию этот атрибут имеет значение false, и его можно изменить в любое время.

xmlparser.buffer_used¶

Если buffer_text включён, то это количество байтов, хранящихся в буфере. Эти байты представляют текст в кодировке UTF-8. Этот атрибут не имеет осмысленной интерпретации, когда buffer_text имеет значение false.

xmlparser.ordered_attributes¶

Установка этого атрибута в ненулевое целое число приводит к тому, что атрибуты возвращаются в виде списка, а не словаря. Атрибуты представляются в порядке их появления в тексте документа. Для каждого атрибута возвращаются два элемента списка: имя атрибута и значение атрибута. (Более старые версии этого модуля также использовали этот формат.) По умолчанию этот атрибут равен false; его можно изменить в любое время.

xmlparser.specified_attributes¶

Если установить в ненулевое целое число, парсер будет сообщать только те атрибуты, которые были указаны в экземпляре документа, а не те, которые получены из объявлений атрибутов. Приложения, устанавливающие этот флаг, должны быть особенно внимательны, чтобы использовать дополнительную информацию из объявлений по мере необходимости для соблюдения стандартов поведения XML-процессоров. По умолчанию этот атрибут равен false; его можно изменить в любое время.

Следующие атрибуты содержат значения, относящиеся к самой последней ошибке, возникшей в объекте xmlparser, и будут иметь корректные значения только после того, как вызов Parse() или ParseFile() возбудит исключение xml.parsers.expat.ExpatError.

xmlparser.ErrorByteIndex¶

Индекс байта, на котором произошла ошибка.

xmlparser.ErrorCode¶

Числовой код, указывающий на проблему. Это значение можно передать функции ErrorString() или сравнить с одной из констант, определённых в объекте errors.

xmlparser.ErrorColumnNumber¶

Номер столбца, на котором произошла ошибка.

xmlparser.ErrorLineNumber¶

Номер строки, в которой произошла ошибка.

Следующие атрибуты содержат значения, относящиеся к текущей позиции разбора в объекте xmlparser. Во время колбэка, сообщающего о событии разбора, они указывают местоположение первого символа из последовательности символов, которая породила это событие. При вызове вне колбэка указанная позиция будет находиться сразу после последнего события разбора (независимо от того, был ли связанный с ним колбэк).

xmlparser.CurrentByteIndex¶

Текущий индекс байта во входных данных парсера.

xmlparser.CurrentColumnNumber¶

Текущий номер колонки во входных данных парсера.

xmlparser.CurrentLineNumber¶

Текущий номер строки во входных данных парсера.

Вот список обработчиков, которые можно установить. Чтобы установить обработчик на объект xmlparser o, используйте o.handlername = func. handlername должно быть взято из следующего списка, а func должен быть вызываемым объектом, принимающим правильное количество аргументов. Если не указано иное, все аргументы являются строками.

xmlparser.XmlDeclHandler(version, encoding, standalone)¶

Вызывается при разборе XML-декларации. XML-декларация – это (необязательное) объявление используемой версии рекомендации XML, кодировки текста документа и необязательное объявление «standalone». version и encoding будут строками, а standalone будет 1, если документ объявлен как standalone, 0, если объявлено, что он не является standalone, или -1, если атрибут standalone был опущен. Доступно только в Expat версии 1.95.0 или новее.

xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)¶

Вызывается, когда Expat начинает разбор объявления типа документа (<!DOCTYPE ...). Параметр doctypeName предоставляется точно так, как он представлен. Параметры systemId и publicId задают системный и публичный идентификаторы, если они указаны, или None, если опущены. Параметр has_internal_subset будет иметь значение true, если документ содержит внутреннее подмножество объявления документа. Требуется Expat версии 1.2 или новее.

xmlparser.EndDoctypeDeclHandler()¶

Вызывается, когда Expat завершил разбор объявления типа документа. Требуется Expat версии 1.2 или новее.

xmlparser.ElementDeclHandler(name, model)¶

Вызывается один раз для каждого объявления типа элемента. name – это имя типа элемента, а model – представление модели содержимого.

xmlparser.AttlistDeclHandler(elname, attname, type, default, required)¶

Вызывается для каждого объявленного атрибута типа элемента. Если в объявлении списка атрибутов объявлено три атрибута, этот обработчик вызывается три раза, по одному на каждый атрибут. elname – это имя элемента, к которому относится объявление, а attname – имя объявленного атрибута. Тип атрибута – это строка, передаваемая как type; возможные значения: 'CDATA', 'ID', 'IDREF', ... default задаёт значение по умолчанию для атрибута, используемое, когда атрибут не указан в экземпляре документа, или None, если значения по умолчанию нет (значения #IMPLIED). Если атрибут требуется указывать в экземпляре документа, required будет иметь значение true. Требуется Expat версии 1.95.0 или новее.

xmlparser.StartElementHandler(name, attributes)¶

Вызывается в начале каждого элемента. name – строка, содержащая имя элемента, а attributes – словарь, сопоставляющий имена атрибутов с их значениями.

xmlparser.EndElementHandler(name)¶

Вызывается для конца каждого элемента.

xmlparser.ProcessingInstructionHandler(target, data)¶

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

xmlparser.CharacterDataHandler(data)¶

Вызывается для символьных данных. Будет вызываться для обычных символьных данных, CDATA-разметки и игнорируемых пробелов. Приложения, которые должны различать эти случаи, могут использовать колбэки StartCdataSectionHandler, EndCdataSectionHandler и ElementDeclHandler для сбора необходимой информации.

xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)¶

Вызывается для объявлений неразобранных (NDATA) сущностей. Доступно только для версии 1.2 библиотеки Expat; для более новых версий используйте EntityDeclHandler. (Соответствующая функция в библиотеке Expat признана устаревшей.)

xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)¶

Вызывается для всех объявлений сущностей. Для параметрических и внутренних сущностей value будет строкой, содержащей объявленное содержимое сущности; для внешних сущностей этот параметр будет равен None. Параметр notationName будет равен None для разобранных сущностей и имени нотации для неразобранных сущностей. Параметр is_parameter_entity будет истинным, если сущность является параметрической, и ложным для общих сущностей (большинству приложений нужно работать только с общими сущностями). Это доступно только начиная с версии 1.95.0 библиотеки Expat.

xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)¶

Вызывается для объявлений нотаций. Параметры notationName, base, systemId и publicId, если заданы, являются строками. Если публичный идентификатор опущен, publicId будет равен None.

xmlparser.StartNamespaceDeclHandler(prefix, uri)¶

Вызывается, когда элемент содержит объявление пространства имён. Объявления пространств имён обрабатываются до вызова StartElementHandler для элемента, в котором эти объявления расположены.

xmlparser.EndNamespaceDeclHandler(prefix)¶

Вызывается при достижении закрывающего тега элемента, содержавшего объявление пространства имён. Этот обработчик вызывается один раз для каждого объявления пространства имён в элементе в порядке, обратном тому, в котором вызывался StartNamespaceDeclHandler для указания начала области действия каждого объявления пространства имён. Вызовы этого обработчика производятся после соответствующего EndElementHandler для окончания элемента.

xmlparser.CommentHandler(data)¶

Вызывается для комментариев. data – это текст комментария, за исключением начального ‘<!--‘ и конечного ‘-->‘.

xmlparser.StartCdataSectionHandler()¶

Вызывается в начале секции CDATA. Этот обработчик и EndCdataSectionHandler необходимы для определения синтаксического начала и конца секций CDATA.

xmlparser.EndCdataSectionHandler()¶

Вызывается в конце секции CDATA.

xmlparser.DefaultHandler(data)¶

Вызывается для любых символов в XML-документе, для которых не был указан подходящий обработчик. Это символы, которые являются частью конструкции, о которой можно было бы сообщить, но для которой не предоставлен обработчик.

xmlparser.DefaultHandlerExpand(data)¶

Это то же самое, что и DefaultHandler(), но не препятствует разворачиванию внутренних сущностей. Ссылка на сущность не будет передана обработчику по умолчанию.

xmlparser.NotStandaloneHandler()¶

Вызывается, если XML-документ не объявлен как отдельный (standalone) документ. Это происходит, когда присутствует внешнее подмножество или ссылка на параметрическую сущность, но в XML-декларации атрибут standalone не установлен в yes. Если этот обработчик возвращает 0, то анализатор вызовет ошибку XML_ERROR_NOT_STANDALONE. Если этот обработчик не установлен, анализатор не генерирует исключение в этом случае.

xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)¶

Вызывается для ссылок на внешние сущности. Параметр base – это текущий базовый URI, установленный предыдущим вызовом SetBase(). Публичный и системный идентификаторы systemId и publicId, если заданы, являются строками; если публичный идентификатор не задан, publicId будет равен None. Значение context является непрозрачным и должно использоваться только так, как описано ниже.

Для разбора внешних сущностей этот обработчик должен быть реализован. Он отвечает за создание под-анализатора с помощью ExternalEntityParserCreate(context), инициализацию его соответствующими колбэками и разбор сущности. Этот обработчик должен возвращать целое число; если он возвращает 0, анализатор вызовет ошибку XML_ERROR_EXTERNAL_ENTITY_HANDLING, иначе разбор продолжится.

Если этот обработчик не предоставлен, внешние сущности сообщаются через колбэк DefaultHandler, если он установлен.

Исключения ExpatError¶ExpatError Exceptions

Исключения ExpatError имеют ряд интересных атрибутов:

ExpatError.code¶

Внутренний номер ошибки Expat для конкретной ошибки. Он соответствует одной из констант, определённых в объекте errors из этого модуля.

ExpatError.lineno¶

Номер строки, в которой обнаружена ошибка. Первая строка нумеруется как 1.

ExpatError.offset¶

Смещение символов внутри строки, где произошла ошибка. Первый столбец нумеруется как 0.

Пример¶Example

Следующая программа определяет три обработчика, которые просто выводят свои аргументы.

import xml.parsers.expat

# 3 функции-обработчика
def start_element(name, attrs):
    print('Start element:', name, attrs)
def end_element(name):
    print('End element:', name)
def char_data(data):
    print('Character data:', repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)

Результат работы этой программы:

Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent

Описания моделей содержимого¶Content Model Descriptions

Модули содержимого описываются с помощью вложенных кортежей. Каждый кортеж содержит четыре значения: тип, квантификатор, имя и кортеж дочерних элементов. Дочерние элементы – это просто дополнительные описания модулей содержимого.

Значения первых двух полей – это константы, определённые в объекте model модуля xml.parsers.expat. Эти константы можно разделить на две группы: группа типов моделей и группа квантификаторов.

Константы группы типов моделей:

xml.parsers.expat.XML_CTYPE_ANY

Элемент, названный именем модели, был объявлен с моделью содержимого ANY.

xml.parsers.expat.XML_CTYPE_CHOICE

Именованный элемент допускает выбор из нескольких вариантов; это используется для моделей содержимого, таких как (A | B | C).

xml.parsers.expat.XML_CTYPE_EMPTY

Элементы, объявленные как EMPTY, имеют этот тип модели.

xml.parsers.expat.XML_CTYPE_MIXED

xml.parsers.expat.XML_CTYPE_NAME

xml.parsers.expat.XML_CTYPE_SEQ

Модели, представляющие последовательность моделей, следующих одна за другой, обозначаются этим типом модели. Это используется для моделей, таких как (A, B, C).

Константы группы квантификаторов:

xml.parsers.expat.XML_CQUANT_NONE

Модификатор не указан, поэтому элемент может появиться ровно один раз, как для A.

xml.parsers.expat.XML_CQUANT_OPT

Модель является необязательной: она может появиться один раз или не появиться вовсе, как для A?.

xml.parsers.expat.XML_CQUANT_PLUS

Модель должна встречаться один или более раз (как A+).

xml.parsers.expat.XML_CQUANT_REP

Модель должна встречаться ноль или более раз, как для A*.

Константы ошибок Expat¶Expat error constants

Следующие константы предоставлены в объекте errors модуля xml.parsers.expat. Эти константы полезны для интерпретации некоторых атрибутов объектов исключения ExpatError, которые возбуждаются при возникновении ошибки.

Объект errors имеет следующие атрибуты:

xml.parsers.expat.XML_ERROR_ASYNC_ENTITY

xml.parsers.expat.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

Ссылка на сущность в значении атрибута указывала на внешнюю сущность вместо внутренней.

xml.parsers.expat.XML_ERROR_BAD_CHAR_REF

Ссылка на символ указала на символ, недопустимый в XML (например, символ 0 или ‘&#0;‘).

xml.parsers.expat.XML_ERROR_BINARY_ENTITY_REF

Ссылка на сущность указывала на сущность, объявленную с помощью нотации, поэтому её невозможно разобрать.

xml.parsers.expat.XML_ERROR_DUPLICATE_ATTRIBUTE

Атрибут был использован более одного раза в одном открывающем теге.

xml.parsers.expat.XML_ERROR_INCORRECT_ENCODING

xml.parsers.expat.XML_ERROR_INVALID_TOKEN

Возникает, когда входной байт не удаётся правильно сопоставить с символом; например, нулевой байт (значение 0) во входном потоке UTF-8.

xml.parsers.expat.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

После корневого элемента встретилось что-то, кроме пробельных символов.

xml.parsers.expat.XML_ERROR_MISPLACED_XML_PI

Объявление XML обнаружено не в начале входных данных.

xml.parsers.expat.XML_ERROR_NO_ELEMENTS

Документ не содержит ни одного элемента (XML требует, чтобы каждый документ содержал ровно один корневой элемент).

xml.parsers.expat.XML_ERROR_NO_MEMORY

Expat не смог выделить память внутри себя.

xml.parsers.expat.XML_ERROR_PARAM_ENTITY_REF

Ссылка на параметрическую сущность обнаружена там, где она не допускается.

xml.parsers.expat.XML_ERROR_PARTIAL_CHAR

Во входных данных обнаружен неполный символ.

xml.parsers.expat.XML_ERROR_RECURSIVE_ENTITY_REF

Ссылка на сущность содержала другую ссылку на ту же самую сущность; возможно, через другое имя, и возможно, косвенную.

xml.parsers.expat.XML_ERROR_SYNTAX

Обнаружена некоторая неопределённая синтаксическая ошибка.

xml.parsers.expat.XML_ERROR_TAG_MISMATCH

Закрывающий тег не соответствует самому внутреннему открытому открывающему тегу.

xml.parsers.expat.XML_ERROR_UNCLOSED_TOKEN

Какой-то токен (например, открывающий тег) не был закрыт до конца потока или до встречи следующего токена.

xml.parsers.expat.XML_ERROR_UNDEFINED_ENTITY

Ссылка на неопределённую сущность.

xml.parsers.expat.XML_ERROR_UNKNOWN_ENCODING

Кодировка документа не поддерживается Expat.

xml.parsers.expat.XML_ERROR_UNCLOSED_CDATA_SECTION

Раздел CDATA не был закрыт.

xml.parsers.expat.XML_ERROR_EXTERNAL_ENTITY_HANDLING

xml.parsers.expat.XML_ERROR_NOT_STANDALONE

Парсер определил, что документ не является “standalone”, хотя в XML-декларации он был объявлен таковым, и обработчик NotStandaloneHandler был установлен и вернул 0.

xml.parsers.expat.XML_ERROR_UNEXPECTED_STATE

xml.parsers.expat.XML_ERROR_ENTITY_DECLARED_IN_PE

xml.parsers.expat.XML_ERROR_FEATURE_REQUIRES_XML_DTD

Была запрошена операция, требующая встроенной поддержки DTD, но Expat был сконфигурирован без поддержки DTD. Это не должно сообщаться стандартной сборкой модуля xml.parsers.expat.

xml.parsers.expat.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

Запрошено изменение поведения после начала синтаксического анализа, хотя его можно изменить только до начала анализа. На данный момент это исключение генерируется только функцией UseForeignDTD().

xml.parsers.expat.XML_ERROR_UNBOUND_PREFIX

При включённой обработке пространств имён обнаружен необъявленный префикс.

xml.parsers.expat.XML_ERROR_UNDECLARING_PREFIX

Документ пытается удалить объявление пространства имён, связанное с префиксом.

xml.parsers.expat.XML_ERROR_INCOMPLETE_PE

Параметрическая сущность содержит неполную разметку.

xml.parsers.expat.XML_ERROR_XML_DECL

В документе отсутствует корневой элемент.

xml.parsers.expat.XML_ERROR_TEXT_DECL

Ошибка при разборе текстовой декларации во внешней сущности.

xml.parsers.expat.XML_ERROR_PUBLICID

В публичном идентификаторе обнаружены недопустимые символы.

xml.parsers.expat.XML_ERROR_SUSPENDED

Запрошенная операция выполнена на приостановленном парсере, но не разрешена. Сюда входят попытки передать дополнительные данные или остановить парсер.

xml.parsers.expat.XML_ERROR_NOT_SUSPENDED

Попытка возобновить работу парсера, когда он не был приостановлен.

xml.parsers.expat.XML_ERROR_ABORTED

Это не должно сообщаться приложениям Python.

xml.parsers.expat.XML_ERROR_FINISHED

Попытка выполнить операцию над парсером, который уже закончил разбор входных данных, но такая операция запрещена. Сюда относятся попытки передать дополнительные данные или остановить парсер.

xml.parsers.expat.XML_ERROR_SUSPEND_PE

Сноски