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

Объекты XMLParser

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

xmlparser.Parse(data[, isfinal])

Парсит содержимое строки data, вызывая соответствующие функции обработчика для обработки обработанных данных. isfinal должно быть истинным при последнем вызове этого метода; это позволяет парсить один файл фрагментами, а не загружать несколько файлов. 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). Возможные значения flag — 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 имеет значение 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 если документ объявлен автономным, 0 если он объявлен не автономным или -1 если оговорка standalone опущена. Доступно только с 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 будет истинно. Требуется Expat версии 1.95.0 или более поздней.

xmlparser.StartElementHandler(name, attributes)

Вызывается для начала каждого элемента. name — строка, содержащая имя элемента, а attributes — атрибуты элемента. Если ordered_attributes истинно, это список (см. 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 будет истинно, если сущность является параметрической сущностью, или ложно для общих сущностей (большинству приложений нужно беспокоиться только о общих сущностях). Доступно начиная с версии 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(). Общедоступные и системные идентификаторы, systemId и publicId, — это строки, если они заданы; если общедоступный идентификатор не задан, 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*.

Постоянные значения ошибок Expat

Следующие константы предоставляются в модуле xml.parsers.expat.errors. Эти константы полезны при интерпретации некоторых атрибутов объектов исключений ExpatError , возникающих при ошибке. По соображениям обратной совместимости, значение констант — это сообщение об ошибке, а не числовой код ошибки. Поэтому сравнивайте атрибут 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. Это никогда не должно сообщаться приложением Python в стандартной сборке модуля 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

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

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.