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

Объекты XMLParser¶

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

xmlparser.Parse(data[, isfinal])¶

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

xmlparser.ParseFile(file)¶

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

xmlparser.SetBase(base)¶

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

xmlparser.GetBase()¶

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

xmlparser.GetInputContext()¶

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

xmlparser.ExternalEntityParserCreate(context[, encoding])¶

Создайте «дочерний» парсер, который можно использовать для разбора внешнего парсируемого объекта, на который ссылается содержимое, разобранное родительским парсером. Параметр context должен быть строкой, переданной в функцию обработчика ExternalEntityRefHandler(), описанную ниже. Дочерний парсер создается с параметрами ordered_attributes и specified_attributes, установленными в значения этого парсера.

xmlparser.SetParamEntityParsing(flag)¶

Управление разбором сущностей параметров (включая внешнее подмножество DTD). Возможные значения флага: XML_PARAM_ENTITY_PARSING_NEVER, XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE и XML_PARAM_ENTITY_PARSING_ALWAYS. Возвращает true, если установка флага была успешной.

xmlparser.UseForeignDTD([flag])¶

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

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

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

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

xmlparser.buffer_size¶

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

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. Имя обработчика должно быть взято из следующего списка, а func должен быть вызываемым объектом, принимающим нужное количество аргументов. Все аргументы являются строками, если не указано иное.

xmlparser.XmlDeclHandler(version, encoding, standalone)¶

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

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

Вызывается, когда Expat начинает разбор объявления типа документа (<!DOCTYPE ...). Параметр doctypeName передается в том виде, в котором он представлен. Параметры systemId и publicId задают системный и публичный идентификаторы, если они указаны, или None, если опущены. has_internal_subset будет истиной, если документ содержит внутреннее подмножество декларации документа. Для этого требуется 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 - атрибуты элемента. Если ordered_attributes true, то это список (см. ordered_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 будет true, если сущность является параметрической сущностью, или false для общих сущностей (большинству приложений нужны только общие сущности). Это доступно только начиная с версии 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-документ не был объявлен как автономный. Это происходит, когда имеется внешнее подмножество или ссылка на сущность с параметрами, но в XML объявлении не установлено значение standalone yes в XML объявлении. Если этот обработчик возвращает значение 0, то синтаксический анализатор выдаст ошибку XML_ERROR_NOT_STANDALONE. Если этот обработчик не установлен, то синтаксический анализатор не выдает исключение для этого условия.

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

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

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

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

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

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

ExpatError.code¶

Номер внутренней ошибки Expat для конкретной ошибки. Словарь errors.messages сопоставляет эти номера ошибок с сообщениями об ошибках Expat. Например:

from xml.parsers.expat import ParserCreate, ExpatError, errors

p = ParserCreate()
try:
    p.Parse(some_xml_document)
except ExpatError as err:
    print("Error:", errors.messages[err.code])

Модуль errors также предоставляет константы сообщений об ошибках и словарь codes, отображающий эти сообщения на коды ошибок, см. ниже.

ExpatError.lineno¶

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

ExpatError.offset¶

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

Пример¶

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

import xml.parsers.expat

# 3 handler functions
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

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

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

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

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

xml.parsers.expat.model.XML_CTYPE_ANY

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

xml.parsers.expat.model.XML_CTYPE_CHOICE

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

xml.parsers.expat.model.XML_CTYPE_EMPTY

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

xml.parsers.expat.model.XML_CTYPE_MIXED

xml.parsers.expat.model.XML_CTYPE_NAME

xml.parsers.expat.model.XML_CTYPE_SEQ

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

Константами в группе квантификаторов являются:

xml.parsers.expat.model.XML_CQUANT_NONE

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

xml.parsers.expat.model.XML_CQUANT_OPT

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

xml.parsers.expat.model.XML_CQUANT_PLUS

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

xml.parsers.expat.model.XML_CQUANT_REP

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

Константы ошибок экспатов¶

В модуле xml.parsers.expat.errors предусмотрены следующие константы. Эти константы полезны для интерпретации некоторых атрибутов объектов исключений ExpatError, поднимаемых при возникновении ошибки. Поскольку по соображениям обратной совместимости значением констант является сообщение об ошибке message, а не числовой код ошибки code, вы делаете это, сравнивая атрибут code с errors.codes[errors.XML_ERROR_CONSTANT_NAME].

Модуль errors имеет следующие атрибуты:

xml.parsers.expat.errors.codes¶

Словарь, отображающий описания строк на их коды ошибок.

Добавлено в версии 3.2.

xml.parsers.expat.errors.messages¶

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

Добавлено в версии 3.2.

xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY¶

xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF¶

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

xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF¶

Символьная ссылка ссылается на символ, который является недопустимым в XML (например, символ 0 или „�“).

xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF¶

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

xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE¶

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

xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING¶

xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN¶

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

xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT¶

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

xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI¶

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

xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS¶

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

xml.parsers.expat.errors.XML_ERROR_NO_MEMORY¶

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

xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF¶

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

xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR¶

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

xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF¶

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

xml.parsers.expat.errors.XML_ERROR_SYNTAX¶

Возникла неопределенная синтаксическая ошибка.

xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH¶

Конечный тег не совпал с самым внутренним открытым начальным тегом.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN¶

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

xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY¶

Была сделана ссылка на сущность, которая не была определена.

xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING¶

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

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION¶

Раздел, помеченный CDATA, не был закрыт.

xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING¶

xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE¶

Парсер определил, что документ не является «автономным», хотя он объявил себя таковым в декларации XML, и NotStandaloneHandler был установлен и возвращен 0.

xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE¶

xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE¶

xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD¶

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

xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING¶

После начала разбора было запрошено изменение поведения, которое может быть изменено только до начала разбора. Это (в настоящее время) вызывается только командой UseForeignDTD().

xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX¶

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

xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX¶

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

xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE¶

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

xml.parsers.expat.errors.XML_ERROR_XML_DECL¶

Документ не содержал ни одного элемента документа.

xml.parsers.expat.errors.XML_ERROR_TEXT_DECL¶

Произошла ошибка при разборе текстового объявления во внешней сущности.

xml.parsers.expat.errors.XML_ERROR_PUBLICID¶

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

xml.parsers.expat.errors.XML_ERROR_SUSPENDED¶

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

xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED¶

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

xml.parsers.expat.errors.XML_ERROR_ABORTED¶

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

xml.parsers.expat.errors.XML_ERROR_FINISHED¶

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

xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE¶

Сноски

1

Строка кодировки, включенная в вывод XML, должна соответствовать соответствующим стандартам. Например, «UTF-8» является допустимым, а «UTF8» - нет. См. https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl и https://www.iana.org/assignments/character-sets/character-sets.xhtml.