`pyexpat.md`

661 строк · 61.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/library/pyexpat.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `xml.parsers.expat` – Быстрый разбор XML с помощью Expat89---1011> **Примечание**12>13> Если требуется разобрать непроверенные или неаутентифицированные данные, см. [Безопасность XML](https://python-all.ru/3.16/library/xml.html#xml-security).1415Модуль `xml.parsers.expat` представляет собой интерфейс Python к непроверяющему XML-парсеру Expat. Модуль предоставляет один тип расширения, `xmlparser`, который представляет текущее состояние XML-парсера. После создания объекта `xmlparser` различные атрибуты объекта можно установить в функции-обработчики. Когда XML-документ затем передается парсеру, функции-обработчики вызываются для символьных данных и разметки в XML-документе.1617Этот модуль использует модуль `pyexpat` для доступа к парсеру Expat. Прямое использование модуля `pyexpat` устарело.1819Этот модуль предоставляет одно исключение и один объект типа:2021#### `exception xml.parsers.expat.ExpatError`2223Исключение, возникающее, когда Expat сообщает об ошибке. См. раздел [Исключения ExpatError](https://python-all.ru/3.16/library/pyexpat.html#expaterror-objects) для получения дополнительной информации об интерпретации ошибок Expat.2425#### `exception xml.parsers.expat.error`2627Псевдоним для [`ExpatError`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError).2829#### `xml.parsers.expat.XMLParserType`3031Тип возвращаемых значений функции [`ParserCreate()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ParserCreate).3233Модуль `xml.parsers.expat` содержит две функции:3435#### `xml.parsers.expat.ErrorString(errno)`3637Возвращает пояснительную строку для заданного номера ошибки *errno*.3839#### `xml.parsers.expat.ParserCreate(encoding=None, namespace_separator=None)`4041Создаёт и возвращает новый объект `xmlparser`. *encoding* [\[1\]](https://python-all.ru/3.16/library/pyexpat.html#id3), если указан, должен быть строкой, задающей кодировку, используемую в XML-данных. Если он передан, он переопределит неявную или явную кодировку документа.4243**Особенность реализации CPython:** Expat изначально понимает и обрабатывает UTF-8, UTF-16, UTF-16BE, UTF-16LE, ISO-8859-1 и US-ASCII. Для других кодировок (включая псевдонимы вроде Latin1 и ASCII) он переключается на Python. Поддерживаются большинство 8-битных кодировок и многие многобайтовые кодировки, такие как Shift\_JIS, хотя для неродных кодировок поддерживаются только символы из базовой многоязычной плоскости (`U+0000-U+FFFF`) (это ограничение также распространяется на псевдонимы, например UTF8). Эти ограничения действуют, только если *encoding* не указан.4445Изменено в версии 3.16.0a0 (не выпущена): Добавлена поддержка многобайтовых кодировок.4647Парсеры, созданные через `ParserCreate()`, называются «корневыми» парсерами в том смысле, что к ним не прикреплен родительский парсер. Некорневые парсеры создаются с помощью [`parser.ExternalEntityParserCreate`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.ExternalEntityParserCreate).4849Expat может опционально выполнять обработку пространств имен XML, что включается предоставлением значения для *namespace\_separator*. Значение должно быть строкой из одного символа; будет возбуждено [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError), если строка имеет недопустимую длину (`None` считается эквивалентом отсутствия). Когда обработка пространств имен включена, имена типов элементов и имена атрибутов, принадлежащие пространству имен, будут расширены. Имя элемента, передаваемое обработчикам элементов `StartElementHandler` и `EndElementHandler`, будет конкатенацией URI пространства имен, символа-разделителя пространства имен и локальной части имени. Если разделитель пространства имен является нулевым байтом (`chr(0)`), то URI пространства имен и локальная часть будут объединены без разделителя.5051Например, если *namespace\_separator* установлен в пробел (`' '`) и разбирается следующий документ:5253```xml54<?xml version="1.0"?>55<root xmlns    = "http://default-namespace.org/"56      xmlns:py = "http://www.python.org/ns/">57  <py:elem1 />58  <elem2 xmlns="" />59</root>60```6162`StartElementHandler` получит следующие строки для каждого элемента:6364```python65http://default-namespace.org/ root66http://www.python.org/ns/ elem167elem268```6970Из-за ограничений в библиотеке `Expat`, используемой `pyexpat`, возвращаемый экземпляр `xmlparser` может использоваться только для разбора одного XML-документа. Вызывайте `ParserCreate` для каждого документа, чтобы получить уникальные экземпляры парсера.7172> **См. также**73>74> **[XML-парсер Expat](https://python-all.ru/3.16/library/pyexpat.html)**75>76> Домашняя страница проекта Expat.7778## Объекты XMLParser7980Объекты `xmlparser` имеют следующие методы:8182#### `xmlparser.Parse(data[, isfinal])`8384Разбирает содержимое строки *data*, вызывая соответствующие функции-обработчики для обработки разобранных данных. *isfinal* должен быть истинным при последнем вызове этого метода; это позволяет разбирать один файл по частям, а не передавать несколько файлов. *data* может быть пустой строкой в любой момент.8586#### `xmlparser.ParseFile(file)`8788Разбирает XML-данные, читая из объекта *file*. *file* должен предоставлять только метод `read(nbytes)`, возвращающий пустую строку, когда данных больше нет.8990#### `xmlparser.SetBase(base)`9192Устанавливает базовый URI, используемый для разрешения относительных URI в системных идентификаторах в объявлениях. Разрешение относительных идентификаторов оставлено на усмотрение приложения: это значение будет передано как аргумент *base* в функции [`ExternalEntityRefHandler()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.ExternalEntityRefHandler), [`NotationDeclHandler()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.NotationDeclHandler) и [`UnparsedEntityDeclHandler()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.UnparsedEntityDeclHandler).9394#### `xmlparser.GetBase()`9596Возвращает строку, содержащую базовый URI, установленный предыдущим вызовом [`SetBase()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.SetBase), или `None`, если `SetBase()` не вызывался.9798#### `xmlparser.GetInputContext()`99100Возвращает входные данные, которые породили текущее событие, в виде строки. Данные находятся в кодировке сущности, содержащей текст. Если этот метод вызван, когда обработчик события не активен, возвращается значение `None`.101102#### `xmlparser.ExternalEntityParserCreate(context[, encoding])`103104Создаёт «дочерний» анализатор, который можно использовать для разбора внешней разобранной сущности, на которую ссылается содержимое, разобранное родительским анализатором. Параметр *контекст* должен быть строкой, переданной в функцию-обработчик [`ExternalEntityRefHandler()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.ExternalEntityRefHandler), описанную ниже. Дочерний анализатор создаётся с [`ordered_attributes`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.ordered_attributes) и [`specified_attributes`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.specified_attributes), установленными в значения этого анализатора.105106#### `xmlparser.SetParamEntityParsing(flag)`107108Управляет разбором сущностей-параметров (включая внешнее подмножество DTD). Возможные значения *флаг*: `XML_PARAM_ENTITY_PARSING_NEVER`, `XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE` и `XML_PARAM_ENTITY_PARSING_ALWAYS`. Возвращает true, если установка флага прошла успешно.109110#### `xmlparser.UseForeignDTD([flag])`111112Вызов этого метода с истинным значением для *флаг* (по умолчанию) приведёт к тому, что Expat вызовет [`ExternalEntityRefHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.ExternalEntityRefHandler) с [`None`](https://python-all.ru/3.16/library/constants.html#None) для всех аргументов, чтобы разрешить загрузку альтернативной DTD. Если документ не содержит объявления типа документа, `ExternalEntityRefHandler` всё равно будет вызван, но [`StartDoctypeDeclHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.StartDoctypeDeclHandler) и [`EndDoctypeDeclHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.EndDoctypeDeclHandler) вызваны не будут.113114Передача ложного значения для *флаг* отменяет предыдущий вызов, в котором передавалось истинное значение, но в остальном не имеет эффекта.115116Этот метод можно вызывать только до вызова методов [`Parse()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.Parse) или [`ParseFile()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.ParseFile); если вызвать его после любого из них, будет возбуждено [`ExpatError`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError) с атрибутом [`code`](https://python-all.ru/3.16/library/code.html#module-code), установленным в `errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING]`.117118#### `xmlparser.SetReparseDeferralEnabled(enabled)`119120> **Предупреждение**121>122> Вызов `SetReparseDeferralEnabled(False)` может иметь последствия для безопасности, как описано ниже; убедитесь, что вы понимаете эти последствия, прежде чем использовать метод `SetReparseDeferralEnabled`.123124Expat 2.6.0 ввёл механизм безопасности под названием «отложенное перевыделение» (reparse deferral), при котором вместо того, чтобы вызывать отказ в обслуживании из-за квадратичного времени выполнения при повторном разборе больших токенов, повторный разбор незавершённых токенов теперь по умолчанию откладывается до тех пор, пока не будет получено достаточное количество входных данных. Из-за этой задержки зарегистрированные обработчики могут – в зависимости от размера входных фрагментов, передаваемых Expat – больше не вызываться сразу после передачи новых данных анализатору. Если необходимо как немедленное реагирование, так и взятие на себя ответственности за защиту от отказа в обслуживании из-за больших токенов, вызов `SetReparseDeferralEnabled(False)` отключает отложенное перевыделение для текущего экземпляра экспатовского анализатора (временно или полностью). Вызов `SetReparseDeferralEnabled(True)` позволяет снова включить отложенное перевыделение.125126`SetReparseDeferralEnabled()` была перенесена в некоторые предыдущие выпуски CPython как исправление безопасности. Проверьте доступность с помощью [`hasattr()`](https://python-all.ru/3.16/library/functions.html#hasattr), если код работает на разных версиях Python.127128Добавлено в версии 3.13.129130#### `xmlparser.GetReparseDeferralEnabled()`131132Возвращает, включено ли в данный момент отложенное перевыделение для данного экземпляра анализатора Expat.133134Добавлено в версии 3.13.135136Объекты `xmlparser` имеют следующие методы для настройки защиты от некоторых распространённых уязвимостей XML.137138#### `xmlparser.SetBillionLaughsAttackProtectionActivationThreshold(threshold, /)`139140Устанавливает количество выходных байтов, необходимое для активации защиты от атак [«миллиард смеха»](https://python-all.ru/3.16/library/pyexpat.html).141142Количество выходных байтов включает усиление от расширения сущностей и чтения файлов DTD.143144Объекты-анализаторы обычно имеют порог активации защиты 8 МиБ, но фактическое значение по умолчанию зависит от базовой библиотеки Expat.145146Исключение [`ExpatError`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError) возникает, если этот метод вызывается для [некорневого](https://python-all.ru/3.16/library/pyexpat.html#xmlparser-non-root) парсера. Соответствующие [`lineno`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError.lineno) и [`offset`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError.offset) не следует использовать, так как они могут не иметь специального значения.147148`SetBillionLaughsAttackProtectionActivationThreshold()` была перенесена в некоторые предыдущие выпуски CPython как исправление безопасности. Проверьте доступность с помощью [`hasattr()`](https://python-all.ru/3.16/library/functions.html#hasattr), если код работает на разных версиях Python.149150> **Примечание**151>152> Пороги активации ниже 4 МиБ, как известно, нарушают поддержку полезной нагрузки DITA 1.3, поэтому их не рекомендуется использовать.153154Добавлено в версии 3.15.155156#### `xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification(max_factor, /)`157158Устанавливает максимально допустимый коэффициент усиления для защиты от атак [«миллиард смеха»](https://python-all.ru/3.16/library/pyexpat.html).159160Коэффициент усиления вычисляется как `(direct + indirect) / direct` во время разбора, где `direct` – количество байтов, прочитанных из основного документа при разборе, а `indirect` – количество байтов, добавленных за счёт расширения сущностей и чтения внешних файлов DTD.161162Значение *макс\_фактор* должно быть не-NaN [`float`](https://python-all.ru/3.16/library/functions.html#float) значением, большим или равным 1.0. На практике наблюдались пиковые усиления в 15 000 раз для всей полезной нагрузки и в 30 000 раз в середине разбора для небольших безвредных файлов. В частности, порог активации следует тщательно выбирать, чтобы избежать ложных срабатываний.163164Объекты парсера обычно имеют максимальный коэффициент усиления 100, но фактическое значение по умолчанию зависит от используемой библиотеки Expat.165166Исключение [`ExpatError`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError) возникает, если этот метод вызывается для [некорневого](https://python-all.ru/3.16/library/pyexpat.html#xmlparser-non-root) парсера или если *max\_factor* находится за пределами допустимого диапазона. Соответствующие [`lineno`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError.lineno) и [`offset`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError.offset) не следует использовать, так как они могут не иметь специального значения.167168`SetBillionLaughsAttackProtectionMaximumAmplification()` была перенесена в некоторые предыдущие выпуски CPython как исправление безопасности. Проверьте доступность с помощью [`hasattr()`](https://python-all.ru/3.16/library/functions.html#hasattr), если код работает на разных версиях Python.169170> **Примечание**171>172> Максимальный коэффициент усиления учитывается только в том случае, если превышен порог, который можно настроить с помощью [`SetBillionLaughsAttackProtectionActivationThreshold()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.SetBillionLaughsAttackProtectionActivationThreshold).173174Добавлено в версии 3.15.175176#### `xmlparser.SetAllocTrackerActivationThreshold(threshold, /)`177178Устанавливает количество байт динамической памяти, необходимых для активации защиты от непропорционального использования оперативной памяти.179180Объекты парсера обычно имеют порог активации выделения памяти 64 МиБ, но фактическое значение по умолчанию зависит от используемой библиотеки Expat.181182Исключение [`ExpatError`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError) возникает, если этот метод вызывается для [некорневого](https://python-all.ru/3.16/library/pyexpat.html#xmlparser-non-root) парсера. Соответствующие [`lineno`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError.lineno) и [`offset`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError.offset) не следует использовать, так как они могут не иметь специального значения.183184`SetAllocTrackerActivationThreshold()` была перенесена в некоторые предыдущие выпуски CPython как исправление безопасности. Проверьте доступность с помощью [`hasattr()`](https://python-all.ru/3.16/library/functions.html#hasattr), если код работает на разных версиях Python.185186Добавлено в версии 3.15.187188#### `xmlparser.SetAllocTrackerMaximumAmplification(max_factor, /)`189190Устанавливает максимальный коэффициент усиления между прямым вводом и байтами выделенной динамической памяти.191192Коэффициент усиления вычисляется как `allocated / direct` во время разбора, где `direct` – число байт, прочитанных из основного документа при разборе, а `allocated` – число байт динамической памяти, выделенной в иерархии парсера.193194Значение *max\_factor* должно быть не NaN [`float`](https://python-all.ru/3.16/library/functions.html#float) значением больше или равным 1.0. На практике коэффициенты усиления больше 100.0 могут наблюдаться вблизи начала разбора даже для безвредных файлов. В частности, порог активации следует тщательно выбирать, чтобы избежать ложных срабатываний.195196Объекты парсера обычно имеют максимальный коэффициент усиления 100, но фактическое значение по умолчанию зависит от используемой библиотеки Expat.197198Исключение [`ExpatError`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError) возникает, если этот метод вызывается для [некорневого](https://python-all.ru/3.16/library/pyexpat.html#xmlparser-non-root) парсера или если *max\_factor* находится за пределами допустимого диапазона. Соответствующие [`lineno`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError.lineno) и [`offset`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError.offset) не следует использовать, так как они могут не иметь специального значения.199200`SetAllocTrackerMaximumAmplification()` была перенесена в некоторые предыдущие выпуски CPython как исправление безопасности. Проверьте доступность с помощью [`hasattr()`](https://python-all.ru/3.16/library/functions.html#hasattr), если код работает на разных версиях Python.201202> **Примечание**203>204> Максимальный коэффициент усиления учитывается только в том случае, если превышен порог, который можно настроить с помощью [`SetAllocTrackerActivationThreshold()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.SetAllocTrackerActivationThreshold).205206Добавлено в версии 3.15.207208Объекты `xmlparser` имеют следующие атрибуты:209210#### `xmlparser.buffer_size`211212Размер буфера, используемого, когда [`buffer_text`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.buffer_text) истинно. Новый размер буфера можно установить, присвоив новое целое значение этому атрибуту. При изменении размера буфер будет сброшен.213214#### `xmlparser.buffer_text`215216Установка этого атрибута в true заставляет объект `xmlparser` буферизировать текстовое содержимое, возвращаемое Expat, чтобы по возможности избежать множественных вызовов колбэка [`CharacterDataHandler()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.CharacterDataHandler). Это может существенно повысить производительность, поскольку Expat обычно разбивает символьные данные на фрагменты на каждом конце строки. По умолчанию этот атрибут равен false, и его можно изменить в любое время. Обратите внимание: когда он равен false, данные, не содержащие переводов строк, также могут быть разбиты на фрагменты.217218#### `xmlparser.buffer_used`219220Если [`buffer_text`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.buffer_text) включено, количество байт, хранящихся в буфере. Эти байты представляют текст в кодировке UTF-8. Этот атрибут не имеет осмысленной интерпретации, когда `buffer_text` равно false.221222#### `xmlparser.ordered_attributes`223224Установка этого атрибута в ненулевое целое число приводит к тому, что атрибуты возвращаются в виде списка, а не словаря. Атрибуты представляются в порядке их появления в тексте документа. Для каждого атрибута возвращаются два элемента списка: имя атрибута и значение атрибута. (Более старые версии этого модуля также использовали этот формат.) По умолчанию этот атрибут равен false; его можно изменить в любое время.225226#### `xmlparser.specified_attributes`227228Если установить в ненулевое целое число, парсер будет сообщать только те атрибуты, которые были указаны в экземпляре документа, а не те, которые получены из объявлений атрибутов. Приложения, устанавливающие этот флаг, должны быть особенно внимательны, чтобы использовать дополнительную информацию из объявлений по мере необходимости для соблюдения стандартов поведения XML-процессоров. По умолчанию этот атрибут равен false; его можно изменить в любое время.229230Следующие атрибуты содержат значения, относящиеся к последней ошибке, возникшей в объекте `xmlparser`, и будут иметь корректные значения только после того, как вызов `Parse()` или `ParseFile()` вызвал исключение [`xml.parsers.expat.ExpatError`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError).231232#### `xmlparser.ErrorByteIndex`233234Индекс байта, на котором произошла ошибка.235236#### `xmlparser.ErrorCode`237238Числовой код, определяющий проблему. Это значение можно передать в функцию [`ErrorString()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ErrorString) или сравнить с одной из констант, определенных в объекте `errors`.239240#### `xmlparser.ErrorColumnNumber`241242Номер столбца, на котором произошла ошибка.243244#### `xmlparser.ErrorLineNumber`245246Номер строки, в которой произошла ошибка.247248Следующие атрибуты содержат значения, относящиеся к текущей позиции разбора в объекте `xmlparser`. Во время колбэка, сообщающего о событии разбора, они указывают местоположение первого символа из последовательности, которая породила это событие. При вызове вне колбэка указанная позиция будет находиться сразу после последнего события разбора (независимо от того, был ли связанный с ним колбэк).249250#### `xmlparser.CurrentByteIndex`251252Текущий индекс байта во входных данных парсера.253254#### `xmlparser.CurrentColumnNumber`255256Текущий номер колонки во входных данных парсера.257258#### `xmlparser.CurrentLineNumber`259260Текущий номер строки во входных данных парсера.261262Вот список обработчиков, которые можно установить. Чтобы установить обработчик на объект `xmlparser` *o*, используйте `o.handlername = func`. *handlername* должен быть взят из следующего списка, а *func* должен быть вызываемым объектом, принимающим правильное количество аргументов. Все аргументы являются строками, если не указано иное.263264#### `xmlparser.XmlDeclHandler(version, encoding, standalone)`265266Вызывается при разборе XML-декларации. XML-декларация – это (необязательное) объявление используемой версии рекомендации XML, кодировки текста документа и необязательное объявление «standalone». *version* и *encoding* будут строками, а *standalone* будет `1`, если документ объявлен как standalone, `0`, если объявлено, что он не является standalone, или `-1`, если атрибут standalone был опущен. Доступно только в Expat версии 1.95.0 или новее.267268#### `xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)`269270Вызывается, когда Expat начинает разбирать объявление типа документа (`<!DOCTYPE ...`). *doctypeName* передаётся в точности как представлено. Параметры *systemId* и *publicId* содержат системный и публичный идентификаторы, если они указаны, или `None`, если опущены. *has\_internal\_subset* будет true, если документ содержит внутреннее подмножество объявления документа. Требуется Expat версии 1.2 или новее.271272#### `xmlparser.EndDoctypeDeclHandler()`273274Вызывается, когда Expat завершил разбор объявления типа документа. Требуется Expat версии 1.2 или новее.275276#### `xmlparser.ElementDeclHandler(name, model)`277278Вызывается один раз для каждого объявления типа элемента. *name* – это имя типа элемента, а *model* – представление модели содержимого.279280#### `xmlparser.AttlistDeclHandler(elname, attname, type, default, required)`281282Вызывается для каждого объявленного атрибута типа элемента. Если в объявлении списка атрибутов объявлено три атрибута, этот обработчик вызывается три раза – по одному на каждый атрибут. *elname* – это имя элемента, к которому относится объявление, а *attname* – имя объявленного атрибута. Тип атрибута – строка, передаваемая как *type*; возможные значения: `'CDATA'`, `'ID'`, `'IDREF'`, … *default* задаёт значение по умолчанию для атрибута, используемое, когда атрибут не указан в экземпляре документа, или `None`, если значение по умолчанию отсутствует (значения `#IMPLIED`). Если атрибут обязателен для указания в экземпляре документа, *required* будет true. Требуется Expat версии 1.95.0 или новее.283284#### `xmlparser.StartElementHandler(name, attributes)`285286Вызывается для начала каждого элемента. *name* – строка, содержащая имя элемента, а *attributes* – атрибуты элемента. Если [`ordered_attributes`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.ordered_attributes) равно true, это список (см. `ordered_attributes` для полного описания). В противном случае это словарь, отображающий имена в значения.287288#### `xmlparser.EndElementHandler(name)`289290Вызывается для конца каждого элемента.291292#### `xmlparser.ProcessingInstructionHandler(target, data)`293294Вызывается для каждой инструкции по обработке.295296#### `xmlparser.CharacterDataHandler(data)`297298Вызывается для символьных данных. Вызывается для обычных символьных данных, содержимого, помеченного CDATA, и игнорируемых пробелов. Приложения, которым необходимо различать эти случаи, могут использовать колбэки [`StartCdataSectionHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.StartCdataSectionHandler), [`EndCdataSectionHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.EndCdataSectionHandler) и [`ElementDeclHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.ElementDeclHandler) для сбора необходимой информации. Обратите внимание, что символьные данные могут быть разбиты на фрагменты, даже если они короткие, поэтому вы можете получить несколько вызовов `CharacterDataHandler()`. Чтобы избежать этого, установите атрибут экземпляра [`buffer_text`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.buffer_text) в `True`.299300#### `xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)`301302Вызывается для объявлений неразобранных (NDATA) сущностей. Присутствует только для версии 1.2 библиотеки Expat; для более новых версий используйте [`EntityDeclHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.EntityDeclHandler). (Базовая функция в библиотеке Expat объявлена устаревшей.)303304#### `xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)`305306Вызывается для всех объявлений сущностей. Для параметрических и внутренних сущностей *value* будет строкой, содержащей объявленное содержимое сущности; для внешних сущностей это будет `None`. Параметр *notationName* будет `None` для разобранных сущностей и именем нотации для неразобранных сущностей. *is\_parameter\_entity* будет true, если сущность является параметрической, и false для общих сущностей (большинству приложений нужно иметь дело только с общими сущностями). Доступно начиная с версии 1.95.0 библиотеки Expat.307308#### `xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)`309310Вызывается для объявлений нотации. *notationName*, *base*, *systemId* и *publicId* являются строками, если заданы. Если public identifier опущен, *publicId* будет `None`.311312#### `xmlparser.StartNamespaceDeclHandler(prefix, uri)`313314Вызывается, когда элемент содержит объявление пространства имён. Объявления пространств имён обрабатываются до вызова [`StartElementHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.StartElementHandler) для элемента, на котором эти объявления находятся.315316#### `xmlparser.EndNamespaceDeclHandler(prefix)`317318Вызывается, когда для элемента, содержащего объявление пространства имён, достигнут закрывающий тег. Этот вызов производится один раз для каждого объявления пространства имён в элементе, в порядке, обратном тому, в котором [`StartNamespaceDeclHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.StartNamespaceDeclHandler) вызывался для обозначения начала области видимости каждого объявления. Вызовы этого обработчика происходят после соответствующего [`EndElementHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.EndElementHandler) для конца элемента.319320#### `xmlparser.CommentHandler(data)`321322Вызывается для комментариев. *data* – текст комментария, без начальных `'<!-``-'` и конечных `'-``->'`.323324#### `xmlparser.StartCdataSectionHandler()`325326Вызывается в начале секции CDATA. Этот обработчик и [`EndCdataSectionHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.EndCdataSectionHandler) нужны, чтобы можно было определить синтаксическое начало и конец секций CDATA.327328#### `xmlparser.EndCdataSectionHandler()`329330Вызывается в конце секции CDATA.331332#### `xmlparser.DefaultHandler(data)`333334Вызывается для любых символов в XML-документе, для которых не был указан подходящий обработчик. Это символы, которые являются частью конструкции, о которой можно было бы сообщить, но для которой не предоставлен обработчик.335336#### `xmlparser.DefaultHandlerExpand(data)`337338То же, что и [`DefaultHandler()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.DefaultHandler), но не подавляет раскрытие внутренних сущностей. Ссылка на сущность не будет передана обработчику по умолчанию.339340#### `xmlparser.NotStandaloneHandler()`341342Вызывается, если XML-документ не был объявлен как самостоятельный (standalone). Это происходит, когда присутствует внешнее подмножество или ссылка на параметрическую сущность, но объявление XML не устанавливает standalone равным `yes`. Если этот обработчик возвращает `0`, то синтаксический анализатор вызовет ошибку `XML_ERROR_NOT_STANDALONE`. Если обработчик не задан, в этом случае анализатор не генерирует исключение.343344#### `xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)`345346> **Предупреждение**347>348> Реализация обработчика, который обращается к локальным файлам и/или сети, может создать уязвимость для [атак с использованием внешних сущностей](https://python-all.ru/3.16/library/pyexpat.html), если `xmlparser` используется с пользовательским содержимым XML. Пожалуйста, продумайте [модель угроз](https://python-all.ru/3.16/library/pyexpat.html) перед реализацией этого обработчика.349350Вызывается для ссылок на внешние сущности. *base* – текущий базовый адрес, заданный предыдущим вызовом [`SetBase()`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.SetBase). Публичный и системный идентификаторы, *systemId* и *publicId*, являются строками, если заданы; если публичный идентификатор не задан, *publicId* будет `None`. Значение *context* непрозрачно и должно использоваться только так, как описано ниже.351352Чтобы внешние сущности были разобраны, этот обработчик должен быть реализован. Он отвечает за создание подчиненного анализатора с помощью `ExternalEntityParserCreate(context)`, его инициализацию соответствующими колбэками и разбор сущности. Обработчик должен возвращать целое число; если возвращается `0`, анализатор вызовет ошибку `XML_ERROR_EXTERNAL_ENTITY_HANDLING`, в противном случае разбор продолжится.353354Если этот обработчик не предоставлен, внешние сущности сообщаются через колбэк [`DefaultHandler`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.xmlparser.DefaultHandler), если он задан.355356## Исключения ExpatError357358Исключения [`ExpatError`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.ExpatError) имеют несколько интересных атрибутов:359360#### `ExpatError.code`361362Внутренний номер ошибки Expat для данной ошибки. Словарь [`errors.messages`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.errors.messages) сопоставляет эти номера с сообщениями об ошибках Expat. Например:363364```python365from xml.parsers.expat import ParserCreate, ExpatError, errors366367p = ParserCreate()368try:369    p.Parse(some_xml_document)370except ExpatError as err:371    print("Error:", errors.messages[err.code])372```373374Модуль [`errors`](https://python-all.ru/3.16/library/pyexpat.html#module-xml.parsers.expat.errors) также предоставляет константы сообщений об ошибках и словарь [`codes`](https://python-all.ru/3.16/library/pyexpat.html#xml.parsers.expat.errors.codes), сопоставляющий эти сообщения обратно с кодами ошибок; см. ниже.375376#### `ExpatError.lineno`377378Номер строки, в которой обнаружена ошибка. Первая строка нумеруется как `1`.379380#### `ExpatError.offset`381382Смещение символов внутри строки, где произошла ошибка. Первый столбец нумеруется как `0`.383384## Пример385386Следующая программа определяет три обработчика, которые просто выводят свои аргументы.387388```python389import xml.parsers.expat390391# 3 функции-обработчика392def start_element(name, attrs):393    print('Start element:', name, attrs)394def end_element(name):395    print('End element:', name)396def char_data(data):397    print('Character data:', repr(data))398399p = xml.parsers.expat.ParserCreate()400401p.StartElementHandler = start_element402p.EndElementHandler = end_element403p.CharacterDataHandler = char_data404405p.Parse("""<?xml version="1.0"?>406<parent id="top"><child1 name="paul">Text goes here</child1>407<child2 name="fred">More text</child2>408</parent>""", 1)409```410411Результат работы этой программы:412413```python414Start element: parent {'id': 'top'}415Start element: child1 {'name': 'paul'}416Character data: 'Text goes here'417End element: child1418Character data: '\n'419Start element: child2 {'name': 'fred'}420Character data: 'More text'421End element: child2422Character data: '\n'423End element: parent424```425426## Описания моделей содержимого427428Модели содержимого описываются с помощью вложенных кортежей. Каждый кортеж содержит четыре значения: тип, квантификатор, имя и кортеж дочерних элементов. Дочерние элементы – это просто дополнительные описания моделей содержимого.429430Значения первых двух полей – это константы, определённые в модуле `xml.parsers.expat.model`. Эти константы можно разделить на две группы: группа типов моделей и группа квантификаторов.431432Константы группы типов моделей:433434#### `xml.parsers.expat.model.XML_CTYPE_ANY`435436Элемент, названный именем модели, был объявлен как имеющий модель содержимого `ANY`.437438#### `xml.parsers.expat.model.XML_CTYPE_CHOICE`439440Именованный элемент допускает выбор из нескольких вариантов; это используется для моделей содержимого, таких как `(A | B | C)`.441442#### `xml.parsers.expat.model.XML_CTYPE_EMPTY`443444Элементы, объявленные как `EMPTY`, имеют этот тип модели.445446#### `xml.parsers.expat.model.XML_CTYPE_MIXED`447448#### `xml.parsers.expat.model.XML_CTYPE_NAME`449450#### `xml.parsers.expat.model.XML_CTYPE_SEQ`451452Модели, представляющие последовательность моделей, следующих одна за другой, обозначаются этим типом. Это используется для моделей, таких как `(A, B, C)`.453454Константы группы квантификаторов:455456#### `xml.parsers.expat.model.XML_CQUANT_NONE`457458Модификатор не указан, поэтому элемент может появиться ровно один раз, как в `A`.459460#### `xml.parsers.expat.model.XML_CQUANT_OPT`461462Модель необязательна: может появиться один раз или не появиться вовсе, как в `A?`.463464#### `xml.parsers.expat.model.XML_CQUANT_PLUS`465466Модель должна встречаться один или более раз (как `A+`).467468#### `xml.parsers.expat.model.XML_CQUANT_REP`469470Модель должна встречаться ноль или более раз, как в `A*`.471472## Константы ошибок Expat473474Следующие константы предоставлены в модуле `xml.parsers.expat.errors`. Эти константы полезны для интерпретации некоторых атрибутов объектов исключений `ExpatError`, возникающих при ошибке. Поскольку из соображений обратной совместимости значением констант является *сообщение* об ошибке, а не числовой *код* ошибки, это делается путём сравнения атрибута [`code`](https://python-all.ru/3.16/library/code.html#module-code) с `errors.codes[errors.XML_ERROR_CONSTANT_NAME]`.475476Модуль `errors` имеет следующие атрибуты:477478#### `xml.parsers.expat.errors.codes`479480Словарь, сопоставляющий строковые описания их кодам ошибок.481482Добавлено в версии 3.2.483484#### `xml.parsers.expat.errors.messages`485486Словарь, сопоставляющий числовые коды ошибок их строковым описаниям.487488Добавлено в версии 3.2.489490#### `xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY`491492#### `xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF`493494Ссылка на сущность в значении атрибута указывала на внешнюю сущность вместо внутренней.495496#### `xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF`497498Ссылка на символ указывала на символ, недопустимый в XML (например, символ `0` или ‘`&#0;`’).499500#### `xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF`501502Ссылка на сущность указывала на сущность, объявленную с помощью нотации, поэтому её невозможно разобрать.503504#### `xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE`505506Атрибут был использован более одного раза в одном открывающем теге.507508#### `xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING`509510#### `xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN`511512Возникает, когда входной байт не удаётся правильно сопоставить с символом; например, нулевой байт (значение `0`) во входном потоке UTF-8.513514#### `xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT`515516После корневого элемента встретилось что-то, кроме пробельных символов.517518#### `xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI`519520Объявление XML обнаружено не в начале входных данных.521522#### `xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS`523524Документ не содержит ни одного элемента (XML требует, чтобы каждый документ содержал ровно один корневой элемент).525526#### `xml.parsers.expat.errors.XML_ERROR_NO_MEMORY`527528Expat не смог выделить память внутри себя.529530#### `xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF`531532Ссылка на параметрическую сущность обнаружена там, где она не допускается.533534#### `xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR`535536Во входных данных обнаружен неполный символ.537538#### `xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF`539540Ссылка на сущность содержала другую ссылку на ту же самую сущность; возможно, через другое имя, и возможно, косвенную.541542#### `xml.parsers.expat.errors.XML_ERROR_SYNTAX`543544Обнаружена некоторая неопределённая синтаксическая ошибка.545546#### `xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH`547548Закрывающий тег не соответствует самому внутреннему открытому открывающему тегу.549550#### `xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN`551552Какой-то токен (например, открывающий тег) не был закрыт до конца потока или до встречи следующего токена.553554#### `xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY`555556Ссылка на неопределённую сущность.557558#### `xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING`559560Кодировка документа не поддерживается Expat.561562#### `xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION`563564Раздел CDATA не был закрыт.565566#### `xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING`567568#### `xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE`569570Парсер определил, что документ не является «standalone», хотя в XML-декларации он объявлен таковым, и `NotStandaloneHandler` был установлен и вернул `0`.571572#### `xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE`573574#### `xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE`575576#### `xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD`577578Запрошена операция, требующая встроенной поддержки DTD, но Expat скомпилирован без неё. Стандартная сборка модуля `xml.parsers.expat` никогда не должна выдавать эту ошибку.579580#### `xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING`581582После начала разбора была запрошена смена поведения, которая возможна только до его начала. В настоящее время это возбуждается только `UseForeignDTD()`.583584#### `xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX`585586При включённой обработке пространств имён обнаружен необъявленный префикс.587588#### `xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX`589590Документ пытается удалить объявление пространства имён, связанное с префиксом.591592#### `xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE`593594Параметрическая сущность содержит неполную разметку.595596#### `xml.parsers.expat.errors.XML_ERROR_XML_DECL`597598В документе отсутствует корневой элемент.599600#### `xml.parsers.expat.errors.XML_ERROR_TEXT_DECL`601602Ошибка при разборе текстовой декларации во внешней сущности.603604#### `xml.parsers.expat.errors.XML_ERROR_PUBLICID`605606В публичном идентификаторе обнаружены недопустимые символы.607608#### `xml.parsers.expat.errors.XML_ERROR_SUSPENDED`609610Запрошенная операция выполнена на приостановленном парсере, но не разрешена. Сюда входят попытки передать дополнительные данные или остановить парсер.611612#### `xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED`613614Попытка возобновить работу парсера, когда он не был приостановлен.615616#### `xml.parsers.expat.errors.XML_ERROR_ABORTED`617618Это не должно сообщаться приложениям Python.619620#### `xml.parsers.expat.errors.XML_ERROR_FINISHED`621622Попытка выполнить операцию над парсером, который уже закончил разбор входных данных, но такая операция запрещена. Сюда относятся попытки передать дополнительные данные или остановить парсер.623624#### `xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE`625626#### `xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML`627628Была предпринята попытка отменить объявление зарезервированного префикса пространства имён `xml` или привязать его к другому URI пространства имён.629630#### `xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS`631632Была предпринята попытка объявить или отменить объявление зарезервированного префикса пространства имён `xmlns`.633634#### `xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI`635636Была предпринята попытка привязать URI одного из зарезервированных префиксов пространства имён `xml` и `xmlns` к другому префиксу пространства имён.637638#### `xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT`639640Это не должно сообщаться приложениям Python.641642#### `xml.parsers.expat.errors.XML_ERROR_NO_BUFFER`643644Это не должно сообщаться приложениям Python.645646#### `xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH`647648Превышен лимит коэффициента усиления входных данных (от DTD и сущностей).649650#### `xml.parsers.expat.errors.XML_ERROR_NOT_STARTED`651652Была предпринята попытка остановить или приостановить парсер до его запуска.653654Добавлено в версии 3.14.655656Сноски657658\[[1](https://python-all.ru/3.16/library/pyexpat.html#id1)\]659660Строка кодировки, включаемая в вывод XML, должна соответствовать соответствующим стандартам. Например, «UTF-8» допустима, а «UTF8» недопустима в объявлении XML-документа, хотя Python принимает её как имя кодировки. См. [https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl](https://python-all.ru/3.16/library/pyexpat.html) и [https://www.iana.org/assignments/character-sets/character-sets.xhtml](https://python-all.ru/3.16/library/pyexpat.html).661