xml.etree.elementtree.md
1> **Источник:** https://python-all.ru/3.0/library/xml.etree.elementtree.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `xml.etree.ElementTree` – API ElementTree для XML89Тип Element – это гибкий контейнер, предназначенный для хранения иерархических структур данных в памяти. Его можно описать как нечто среднее между списком и словарём.1011У каждого элемента есть несколько связанных с ним свойств:1213- тег – строка, определяющая, какие данные представляет этот элемент (то есть тип элемента).14- набор атрибутов, хранящихся в словаре Python.15- текстовая строка.16- необязательная строка tail.17- набор дочерних элементов, хранящихся в последовательности Python.1819Для создания экземпляра элемента используйте фабричные функции Element или SubElement.2021Класс [`ElementTree`](https://python-all.ru/3.0/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree) используется для обёртки структуры элементов и преобразования её из XML и в XML.2223Реализация этого API на C доступна как `xml.etree.cElementTree`.2425Учебные материалы и ссылки на другие ресурсы см. на [http://effbot.org/zone/element-index.htm](https://python-all.ru/3.0/library/xml.etree.elementtree.html). На странице Фредрика Лунда также находится разрабатываемая версия xml.etree.ElementTree.2627## Функции2829#### `[xml.etree.ElementTree.Comment]xml.etree.ElementTree.Comment([text])`3031Фабрика элементов Comment. Эта фабричная функция создаёт специальный элемент, который будет сериализован как XML-комментарий. Строка комментария может быть объектом3233[`bytes`](https://python-all.ru/3.0/library/functions.html#bytes)3435с символами только ASCII или объектом3637[`str`](https://python-all.ru/3.0/library/functions.html#str)3839.4041*text*4243– это строка, содержащая текст комментария. Возвращает экземпляр элемента, представляющий комментарий.4445#### `[xml.etree.ElementTree.dump]xml.etree.ElementTree.dump(elem)`4647Записывает дерево элементов или структуру элемента в sys.stdout. Эту функцию следует использовать только для отладки.4849Точный формат вывода зависит от реализации. В этой версии он записывается как обычный XML-файл.5051*elem* – это дерево элементов или отдельный элемент.5253#### `[xml.etree.ElementTree.Element]xml.etree.ElementTree.Element(tag[, attrib][, **extra])`5455Фабрика элементов. Эта функция возвращает объект, реализующий стандартный интерфейс Element. Точный класс или тип этого объекта зависит от реализации, но он всегда будет совместим с классом \_ElementInterface в этом модуле.5657Имя элемента, имена атрибутов и значения атрибутов могут быть объектом [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes) только с ASCII или объектом [`str`](https://python-all.ru/3.0/library/functions.html#str). *tag* – это имя элемента. *attrib* – необязательный словарь, содержащий атрибуты элемента. *extra* содержит дополнительные атрибуты, заданные как именованные аргументы. Возвращает экземпляр элемента.5859#### `[xml.etree.ElementTree.fromstring]xml.etree.ElementTree.fromstring(text)`6061Разбирает XML-фрагмент из строковой константы. То же, что и XML.6263*text*6465– это строка, содержащая XML-данные. Возвращает экземпляр Element.6667#### `[xml.etree.ElementTree.iselement]xml.etree.ElementTree.iselement(element)`6869Проверяет, является ли объект корректным элементом.7071*element*7273– это экземпляр элемента. Возвращает истинное значение, если это объект элемента.7475#### `[xml.etree.ElementTree.iterparse]xml.etree.ElementTree.iterparse(source[, events])`7677Разбирает XML-фрагмент в дерево элементов поэтапно и сообщает пользователю о происходящем. *source* – это имя файла или файловый объект, содержащий XML-данные. *events* – это список событий, о которых нужно сообщать. Если не указан, сообщается только о событиях “end”. Возвращает [*итератор*](https://python-all.ru/3.0/glossary.html#term-iterator), предоставляющий пары `(event, elem)`.7879> **Примечание**80>81> [`iterparse()`](https://python-all.ru/3.0/library/xml.etree.elementtree.html#xml.etree.ElementTree.iterparse) гарантирует только то, что при генерации события «start» он уже увидел символ «\>» открывающего тега; поэтому атрибуты определены, но содержимое атрибутов text и tail на этот момент не определено. То же самое относится к дочерним элементам: они могут присутствовать или отсутствовать.82>83> Если нужен полностью заполненный элемент, используйте события "end".8485#### `[xml.etree.ElementTree.parse]xml.etree.ElementTree.parse(source[, parser])`8687Разбирает XML-фрагмент в дерево элементов.8889*source*9091– это имя файла или файловый объект, содержащий XML-данные.9293*parser*9495– необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор XMLTreeBuilder. Возвращает экземпляр ElementTree.9697#### `[xml.etree.ElementTree.ProcessingInstruction]xml.etree.ElementTree.ProcessingInstruction(target[, text])`9899Фабрика элементов PI. Эта фабричная функция создаёт специальный элемент, который будет сериализован как инструкция по обработке XML.100101*target*102103– это строка, содержащая цель PI.104105*text*106107– это строка, содержащая содержимое PI, если задано. Возвращает экземпляр элемента, представляющий инструкцию по обработке.108109#### `[xml.etree.ElementTree.SubElement]xml.etree.ElementTree.SubElement(parent, tag[, attrib[, **extra]])`110111Фабрика подэлементов. Эта функция создаёт экземпляр элемента и добавляет его к существующему элементу.112113Имя элемента, имена атрибутов и значения атрибутов могут быть объектом [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes) только с ASCII или объектом [`str`](https://python-all.ru/3.0/library/functions.html#str). *parent* – это родительский элемент. *tag* – имя подэлемента. *attrib* – необязательный словарь, содержащий атрибуты элемента. *extra* содержит дополнительные атрибуты, заданные как именованные аргументы. Возвращает экземпляр элемента.114115#### `[xml.etree.ElementTree.tostring]xml.etree.ElementTree.tostring(element[, encoding])`116117Генерирует строковое представление XML-элемента, включая все подэлементы.118119*element*120121– это экземпляр Element.122123*encoding*124125– кодировка вывода (по умолчанию US-ASCII). Возвращает закодированную строку, содержащую XML-данные.126127#### `[xml.etree.ElementTree.XML]xml.etree.ElementTree.XML(text)`128129Разбирает XML-фрагмент из строковой константы. Эту функцию можно использовать для встраивания «XML-литералов» в код Python.130131*text*132133– это строка, содержащая XML-данные. Возвращает экземпляр Element.134135#### `[xml.etree.ElementTree.XMLID]xml.etree.ElementTree.XMLID(text)`136137Разбирает XML-фрагмент из строковой константы, а также возвращает словарь, который сопоставляет идентификаторы элементов с элементами.138139*text*140141– это строка, содержащая XML- данные. Возвращает кортеж, содержащий экземпляр Element и словарь.142143## Интерфейс Element144145Объекты Element, возвращаемые функциями Element или SubElement, имеют следующие методы и атрибуты.146147#### `[xml.etree.ElementTree.Element.tag]Element.tag`148149Строка, определяющая, какие данные представляет этот элемент (иными словами, тип элемента).150151#### `[xml.etree.ElementTree.Element.text]Element.text`152153Атрибут154155*text*156157можно использовать для хранения дополнительных данных, связанных с элементом. Как следует из названия, этот атрибут обычно является строкой, но может быть любым объектом, специфичным для приложения. Если элемент создан из XML-файла, атрибут будет содержать любой текст, найденный между тегами элемента.158159#### `[xml.etree.ElementTree.Element.tail]Element.tail`160161Атрибут162163*tail*164165можно использовать для хранения дополнительных данных, связанных с элементом. Обычно этот атрибут представляет собой строку, но может быть любым объектом, специфичным для приложения. Если элемент создан из XML-файла, атрибут будет содержать любой текст, найденный после закрывающего тега элемента и перед следующим тегом.166167#### `[xml.etree.ElementTree.Element.attrib]Element.attrib`168169Словарь, содержащий атрибуты элемента. Обратите внимание: хотя значение170171*attrib*172173всегда является настоящим изменяемым словарём Python, реализация ElementTree может использовать другое внутреннее представление и создавать словарь только по запросу. Чтобы воспользоваться преимуществами таких реализаций, используйте методы словаря, перечисленные ниже, когда это возможно.174175Следующие методы, подобные словарным, работают с атрибутами элемента.176177#### `[xml.etree.ElementTree.Element.clear]Element.clear()`178179Сбрасывает элемент. Эта функция удаляет все подэлементы, очищает все атрибуты и устанавливает атрибуты text и tail в None.180181#### `[xml.etree.ElementTree.Element.get]Element.get(key[, default=None])`182183Возвращает атрибут элемента с именем *key*.184185Возвращает значение атрибута или *default*, если атрибут не найден.186187#### `[xml.etree.ElementTree.Element.items]Element.items()`188189Возвращает атрибуты элемента в виде последовательности пар (имя, значение). Атрибуты возвращаются в произвольном порядке.190191#### `[xml.etree.ElementTree.Element.keys]Element.keys()`192193Возвращает имена атрибутов элемента в виде списка. Имена возвращаются в произвольном порядке.194195#### `[xml.etree.ElementTree.Element.set]Element.set(key, value)`196197Устанавливает атрибут198199*key*200201элемента в202203*value*204205.206207Следующие методы работают с дочерними элементами (подэлементами) текущего элемента.208209#### `[xml.etree.ElementTree.Element.append]Element.append(subelement)`210211Добавляет элемент212213*subelement*214215в конец внутреннего списка подэлементов данного элемента.216217#### `[xml.etree.ElementTree.Element.find]Element.find(match)`218219Находит первый подэлемент, соответствующий220221*match*222223.224225*match*226227может быть именем тега или путём. Возвращает экземпляр элемента или228229`None`230231.232233#### `[xml.etree.ElementTree.Element.findall]Element.findall(match)`234235Находит все подэлементы, соответствующие236237*match*238239.240241*match*242243может быть именем тега или путём. Возвращает итерируемый объект, выдающий все подходящие элементы в порядке документа.244245#### `[xml.etree.ElementTree.Element.findtext]Element.findtext(condition[, default=None])`246247Находит текст первого подэлемента, соответствующего248249*condition*250251.252253*condition*254255может быть именем тега или путём. Возвращает текстовое содержимое первого подходящего элемента или256257*default*258259, если элемент не найден. Обратите внимание: если у подходящего элемента нет текстового содержимого, возвращается пустая строка.260261#### `[xml.etree.ElementTree.Element.getchildren]Element.getchildren()`262263Возвращает все подэлементы. Элементы возвращаются в порядке документа.264265#### `[xml.etree.ElementTree.Element.getiterator]Element.getiterator([tag=None])`266267Создаёт итератор дерева с текущим элементом в качестве корня. Итератор проходит по этому элементу и всем элементам ниже него, соответствующим заданному тегу. Если tag равен268269`None`270271или272273`'*'`274275, то перебираются все элементы. Возвращает итерируемый объект, который предоставляет объекты элементов в порядке документа (в глубину).276277#### `[xml.etree.ElementTree.Element.insert]Element.insert(index, element)`278279Вставляет подэлемент в заданную позицию в данном элементе.280281#### `[xml.etree.ElementTree.Element.makeelement]Element.makeelement(tag, attrib)`282283Создаёт новый объект элемента того же типа, что и данный элемент. Не вызывайте этот метод, используйте вместо него фабричную функцию SubElement.284285#### `[xml.etree.ElementTree.Element.remove]Element.remove(subelement)`286287Удаляет288289*подэлемент*290291из элемента. В отличие от методов findXYZ, этот метод сравнивает элементы на основе идентичности экземпляра, а не по значению тега или содержимому.292293Объекты Element также поддерживают следующие методы последовательностей для работы с подэлементами: [`__delitem__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__delitem__), [`__getitem__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__getitem__), [`__setitem__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__setitem__), [`__len__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__len__).294295Внимание: поскольку объекты Element не определяют метод [`__bool__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__bool__), элементы без подэлементов будут проверяться как `False`.296297```python298element = root.find('foo')299300if not element: # осторожно!301 print("element not found, or element has no subelements")302303if element is None:304 print("element not found")305```306307## Объекты ElementTree308309#### `[xml.etree.ElementTree.ElementTree]class xml.etree.ElementTree.ElementTree([element][, file])`310311Класс-обёртка ElementTree. Этот класс представляет целую иерархию элементов и добавляет дополнительную поддержку для сериализации в стандартный XML и из него.312313*element* – корневой элемент. Дерево инициализируется содержимым XML-*файла*, если он указан.314315#### `[xml.etree.ElementTree.ElementTree._setroot]_setroot(element)`316317Заменяет корневой элемент этого дерева. При этом отбрасывается текущее содержимое дерева и заменяется указанным элементом. Используйте с осторожностью.318319*element*320321– экземпляр элемента.322323#### `[xml.etree.ElementTree.ElementTree.find]find(path)`324325Находит первый элемент верхнего уровня с указанным тегом. То же, что getroot().find(path).326327*path*328329– элемент для поиска. Возвращает первый подходящий элемент или330331`None`332333, если элемент не найден.334335#### `[xml.etree.ElementTree.ElementTree.findall]findall(path)`336337Находит все элементы верхнего уровня с указанным тегом. То же, что getroot().findall(path).338339*path*340341– элемент для поиска. Возвращает список или342343[*итератор*](https://python-all.ru/3.0/glossary.html#term-iterator)344345, содержащий все подходящие элементы, в порядке документа.346347#### `[xml.etree.ElementTree.ElementTree.findtext]findtext(path[, default])`348349Находит текст элемента для первого элемента верхнего уровня с указанным тегом. То же, что getroot().findtext(path).350351*path*352353– элемент верхнего уровня для поиска.354355*default*356357– значение, возвращаемое, если элемент не найден. Возвращает текстовое содержимое первого подходящего элемента или значение по умолчанию, если элемент не найден. Обратите внимание, что если элемент найден, но не имеет текстового содержимого, этот метод возвращает пустую строку.358359#### `[xml.etree.ElementTree.ElementTree.getiterator]getiterator([tag])`360361Создаёт и возвращает итератор дерева для корневого элемента. Итератор перебирает все элементы этого дерева в порядке разделов.362363*tag*364365– тег для поиска (по умолчанию возвращаются все элементы).366367#### `[xml.etree.ElementTree.ElementTree.getroot]getroot()`368369Возвращает корневой элемент этого дерева.370371#### `[xml.etree.ElementTree.ElementTree.parse]parse(source[, parser])`372373Загружает внешний XML-раздел в это дерево элементов.374375*source*376377– это имя файла или файловый объект.378379*parser*380381– необязательный экземпляр парсера. Если не указан, используется стандартный парсер XMLTreeBuilder. Возвращает корневой элемент раздела.382383#### `[xml.etree.ElementTree.ElementTree.write]write(file[, encoding])`384385Записывает дерево элементов в файл в формате XML.386387*file*388389– это имя файла или файловый объект, открытый для записи.390391*encoding*392393[\[1\]](https://python-all.ru/3.0/library/xml.etree.elementtree.html#id2)394395– кодировка вывода (по умолчанию US-ASCII).396397Это XML-файл, который будет обрабатываться:398399```python400<html>401 <head>402 <title>Example page</title>403 </head>404 <body>405 <p>Moved to <a href="http://example.org/">example.org</a>406 or <a href="http://example.com/">example.com</a>.</p>407 </body>408</html>409```410411Пример изменения атрибута «target» каждой ссылки в первом абзаце:412413```python414>>> from xml.etree.ElementTree import ElementTree415>>> tree = ElementTree()416>>> tree.parse("index.xhtml")417<Element html at b7d3f1ec>418>>> p = tree.find("body/p") # Находит первое вхождение тега p в body419>>> p420<Element p at 8416e0c>421>>> links = p.getiterator("a") # Возвращает список всех ссылок422>>> links423[<Element a at b7d4f9ec>, <Element a at b7d4fb0c>]424>>> for i in links: # Перебирает все найденные ссылки425... i.attrib["target"] = "blank"426>>> tree.write("output.xhtml")427```428429## Объекты QName430431#### `[xml.etree.ElementTree.QName]class xml.etree.ElementTree.QName(text_or_uri[, tag])`432433Обёртка QName. Её можно использовать для обёртывания значения атрибута QName, чтобы обеспечить правильную обработку пространств имён на выходе.434435*text\_or\_uri*436437– строка, содержащая значение QName в форме {uri}local, или, если задан аргумент tag, URI-часть QName. Если задан438439*tag*440441, первый аргумент интерпретируется как URI, а этот аргумент – как локальное имя. Экземпляры442443[`QName`](https://python-all.ru/3.0/library/xml.etree.elementtree.html#xml.etree.ElementTree.QName)444445являются непрозрачными.446447## Объекты TreeBuilder448449#### `[xml.etree.ElementTree.TreeBuilder]class xml.etree.ElementTree.TreeBuilder([element_factory])`450451Универсальный построитель структуры элементов. Этот построитель преобразует последовательность вызовов методов start, data и end в правильно сформированную структуру элементов. Вы можете использовать этот класс для построения структуры элементов с помощью пользовательского XML-парсера или парсера для какого-либо другого XML-подобного формата. *element\_factory* вызывается для создания новых экземпляров Element, если он задан.452453#### `[xml.etree.ElementTree.TreeBuilder.close]close()`454455Сбрасывает буферы парсера и возвращает элемент документа верхнего уровня. Возвращает экземпляр Element.456457#### `[xml.etree.ElementTree.TreeBuilder.data]data(data)`458459Добавляет текст в текущий элемент.460461*data*462463– строка. Она должна быть либо объектом464465[`bytes`](https://python-all.ru/3.0/library/functions.html#bytes)466467, содержащим только ASCII, либо объектом468469[`str`](https://python-all.ru/3.0/library/functions.html#str)470471.472473#### `[xml.etree.ElementTree.TreeBuilder.end]end(tag)`474475Закрывает текущий элемент.476477*tag*478479– имя элемента. Возвращает закрытый элемент.480481#### `[xml.etree.ElementTree.TreeBuilder.start]start(tag, attrs)`482483Открывает новый элемент.484485*tag*486487– имя элемента.488489*attrs*490491– словарь, содержащий атрибуты элемента. Возвращает открытый элемент.492493## Объекты XMLTreeBuilder494495#### `[xml.etree.ElementTree.XMLTreeBuilder]class xml.etree.ElementTree.XMLTreeBuilder([html][, target])`496497Построитель структуры элементов для исходных данных XML, основанный на парсере expat. *html* – предопределённые HTML-сущности. Этот флаг не поддерживается текущей реализацией. *target* – целевой объект. Если не указан, построитель использует экземпляр стандартного класса TreeBuilder.498499#### `[xml.etree.ElementTree.XMLTreeBuilder.close]close()`500501Завершает подачу данных парсеру. Возвращает структуру элемента.502503#### `[xml.etree.ElementTree.XMLTreeBuilder.doctype]doctype(name, pubid, system)`504505Обрабатывает объявление doctype.506507*name*508509– имя doctype.510511*pubid*512513– публичный идентификатор.514515*system*516517– системный идентификатор.518519#### `[xml.etree.ElementTree.XMLTreeBuilder.feed]feed(data)`520521Подаёт данные парсеру.522523*data*524525– закодированные данные.526527[`XMLTreeBuilder.feed()`](https://python-all.ru/3.0/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLTreeBuilder.feed) вызывает метод `start()` объекта *target* для каждого открывающего тега, его метод `end()` для каждого закрывающего тега, а данные обрабатываются методом `data()`. [`XMLTreeBuilder.close()`](https://python-all.ru/3.0/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLTreeBuilder.close) вызывает метод `close()` объекта *target*. [`XMLTreeBuilder`](https://python-all.ru/3.0/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLTreeBuilder) может использоваться не только для построения древовидной структуры. Это пример подсчёта максимальной глубины XML-файла:528529```python530>>> from xml.etree.ElementTree import XMLTreeBuilder531>>> class MaxDepth: # Целевой объект парсера532... maxDepth = 0533... depth = 0534... def start(self, tag, attrib): # Вызывается для каждого открывающего тега.535... self.depth += 1536... if self.depth > self.maxDepth:537... self.maxDepth = self.depth538... def end(self, tag): # Вызывается для каждого закрывающего тега.539... self.depth -= 1540... def data(self, data):541... pass # С данными ничего делать не нужно.542... def close(self): # Вызывается, когда все данные проанализированы.543... return self.maxDepth544...545>>> target = MaxDepth()546>>> parser = XMLTreeBuilder(target=target)547>>> exampleXml = """548... <a>549... <b>550... </b>551... <b>552... <c>553... <d>554... </d>555... </c>556... </b>557... </a>"""558>>> parser.feed(exampleXml)559>>> parser.close()5604561```562563Сноски564565| \[1\] | Строка кодировки, включённая в вывод XML, должна соответствовать соответствующим стандартам. Например, «UTF-8» допустимо, а «UTF8» – нет. См. [http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl](https://python-all.ru/3.0/library/xml.etree.elementtree.html) и [http://www.iana.org/assignments/character-sets](https://python-all.ru/3.0/library/xml.etree.elementtree.html) . |566| --- | --- |567