xml.etree.elementtree.md
1> **Источник:** https://python-all.ru/3.3/library/xml.etree.elementtree.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 20.5. [`xml.etree.ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) – API ElementTree XML89Модуль [`xml.etree.ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) реализует простой и эффективный API для разбора и создания XML-данных.1011Изменено в версии 3.3: Этот модуль будет использовать быструю реализацию, когда это возможно. Модуль `xml.etree.cElementTree` устарел.1213> **Предупреждение**14>15> Модуль [`xml.etree.ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) не защищён от вредоносных данных. Если необходимо разбирать непроверенные или неаутентифицированные данные, см. [*уязвимости XML*](https://python-all.ru/3.3/library/xml.html#xml-vulnerabilities).1617## 20.5.1. Учебное руководство1819Это краткое руководство по использованию [`xml.etree.ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) (сокращённо `ET`). Цель – продемонстрировать некоторые строительные блоки и основные понятия модуля.2021### 20.5.1.1. XML-дерево и элементы2223XML по своей природе иерархический формат данных, и самый естественный способ его представления – дерево. `ET` предоставляет для этого два класса: [`ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree) представляет весь XML-документ как дерево, а [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element) представляет отдельный узел в этом дереве. Взаимодействие со всем документом (чтение и запись в/из файлов) обычно выполняется на уровне [`ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree). Взаимодействие с отдельным XML-элементом и его дочерними элементами выполняется на уровне [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element).2425### 20.5.1.2. Разбор XML2627В этом разделе в качестве примера будет использоваться следующий XML-документ:2829```xml30<?xml version="1.0"?>31<data>32 <country name="Liechtenstein">33 <rank>1</rank>34 <year>2008</year>35 <gdppc>141100</gdppc>36 <neighbor name="Austria" direction="E"/>37 <neighbor name="Switzerland" direction="W"/>38 </country>39 <country name="Singapore">40 <rank>4</rank>41 <year>2011</year>42 <gdppc>59900</gdppc>43 <neighbor name="Malaysia" direction="N"/>44 </country>45 <country name="Panama">46 <rank>68</rank>47 <year>2011</year>48 <gdppc>13600</gdppc>49 <neighbor name="Costa Rica" direction="W"/>50 <neighbor name="Colombia" direction="E"/>51 </country>52</data>53```5455Данные можно импортировать, прочитав файл:5657```python58import xml.etree.ElementTree as ET59tree = ET.parse('country_data.xml')60root = tree.getroot()61```6263Или непосредственно из строки:6465```python66root = ET.fromstring(country_data_as_string)67```6869[`fromstring()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.fromstring) разбирает XML из строки непосредственно в [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element), который является корневым элементом разобранного дерева. Другие функции разбора могут создавать [`ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree). Сверьтесь с документацией, чтобы быть уверенным.7071Будучи [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element), `root` имеет тег и словарь атрибутов:7273```python74>>> root.tag75'data'76>>> root.attrib77{}78```7980У него также есть дочерние узлы, которые можно перебирать:8182```python83>>> for child in root:84... print(child.tag, child.attrib)85...86country {'name': 'Liechtenstein'}87country {'name': 'Singapore'}88country {'name': 'Panama'}89```9091Дочерние узлы вложены, и к конкретным дочерним узлам можно обратиться по индексу:9293```python94>>> root[0][1].text95'2008'96```9798### 20.5.1.3. Поиск интересующих элементов99100[`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element) имеет несколько полезных методов, которые помогают рекурсивно перебирать всё поддерево ниже него (его дочерние элементы, их дочерние и т.д.). Например, [`Element.iter()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.iter):101102```python103>>> for neighbor in root.iter('neighbor'):104... print(neighbor.attrib)105...106{'name': 'Austria', 'direction': 'E'}107{'name': 'Switzerland', 'direction': 'W'}108{'name': 'Malaysia', 'direction': 'N'}109{'name': 'Costa Rica', 'direction': 'W'}110{'name': 'Colombia', 'direction': 'E'}111```112113[`Element.findall()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.findall) находит только элементы с тегом, которые являются прямыми дочерними элементами текущего элемента. [`Element.find()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.find) находит *первый* дочерний элемент с определённым тегом, а [`Element.text`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.text) даёт доступ к текстовому содержимому элемента. [`Element.get()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.get) даёт доступ к атрибутам элемента:114115```python116>>> for country in root.findall('country'):117... rank = country.find('rank').text118... name = country.get('name')119... print(name, rank)120...121Liechtenstein 1122Singapore 4123Panama 68124```125126Более сложное задание критериев поиска элементов возможно с помощью [*XPath*](https://python-all.ru/3.3/library/xml.etree.elementtree.html#elementtree-xpath).127128### 20.5.1.4. Изменение XML-файла129130[`ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree) предоставляет простой способ построения XML-документов и записи их в файлы. Метод [`ElementTree.write()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree.write) служит этой цели.131132После создания объект [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element) можно изменять, напрямую меняя его поля (например, [`Element.text`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.text)), добавляя и изменяя атрибуты (метод [`Element.set()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.set)), а также добавляя новые дочерние элементы (например, с помощью [`Element.append()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.append)).133134Допустим, мы хотим увеличить на единицу ранг каждой страны и добавить атрибут `updated` элементу rank:135136```python137>>> for rank in root.iter('rank'):138... new_rank = int(rank.text) + 1139... rank.text = str(new_rank)140... rank.set('updated', 'yes')141...142>>> tree.write('output.xml')143```144145Теперь наш XML выглядит так:146147```xml148<?xml version="1.0"?>149<data>150 <country name="Liechtenstein">151 <rank updated="yes">2</rank>152 <year>2008</year>153 <gdppc>141100</gdppc>154 <neighbor name="Austria" direction="E"/>155 <neighbor name="Switzerland" direction="W"/>156 </country>157 <country name="Singapore">158 <rank updated="yes">5</rank>159 <year>2011</year>160 <gdppc>59900</gdppc>161 <neighbor name="Malaysia" direction="N"/>162 </country>163 <country name="Panama">164 <rank updated="yes">69</rank>165 <year>2011</year>166 <gdppc>13600</gdppc>167 <neighbor name="Costa Rica" direction="W"/>168 <neighbor name="Colombia" direction="E"/>169 </country>170</data>171```172173Элементы можно удалять с помощью [`Element.remove()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.remove). Допустим, мы хотим удалить все страны с рангом выше 50:174175```python176>>> for country in root.findall('country'):177... rank = int(country.find('rank').text)178... if rank > 50:179... root.remove(country)180...181>>> tree.write('output.xml')182```183184Теперь наш XML выглядит так:185186```xml187<?xml version="1.0"?>188<data>189 <country name="Liechtenstein">190 <rank updated="yes">2</rank>191 <year>2008</year>192 <gdppc>141100</gdppc>193 <neighbor name="Austria" direction="E"/>194 <neighbor name="Switzerland" direction="W"/>195 </country>196 <country name="Singapore">197 <rank updated="yes">5</rank>198 <year>2011</year>199 <gdppc>59900</gdppc>200 <neighbor name="Malaysia" direction="N"/>201 </country>202</data>203```204205### 20.5.1.5. Создание XML-документов206207Функция [`SubElement()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.SubElement) также предоставляет удобный способ создания новых дочерних элементов для заданного элемента:208209```python210>>> a = ET.Element('a')211>>> b = ET.SubElement(a, 'b')212>>> c = ET.SubElement(a, 'c')213>>> d = ET.SubElement(c, 'd')214>>> ET.dump(a)215<a><b /><c><d /></c></a>216```217218### 20.5.1.6. Дополнительные ресурсы219220Смотрите [http://effbot.org/zone/element-index.htm](https://python-all.ru/3.3/library/xml.etree.elementtree.html) для обучающих материалов и ссылок на другую документацию.221222## 20.5.2. Поддержка XPath223224Этот модуль предоставляет ограниченную поддержку [XPath-выражений](https://python-all.ru/3.3/library/xml.etree.elementtree.html) для поиска элементов в дереве. Цель – поддержать небольшое подмножество сокращённого синтаксиса; полноценный движок XPath выходит за рамки модуля.225226### 20.5.2.1. Пример227228Вот пример, демонстрирующий некоторые возможности XPath модуля. Мы будем использовать XML-документ `countrydata` из раздела [*Разбор XML*](https://python-all.ru/3.3/library/xml.etree.elementtree.html#elementtree-parsing-xml):229230```python231import xml.etree.ElementTree as ET232233root = ET.fromstring(countrydata)234235# Элементы верхнего уровня236root.findall(".")237238# Все элементы 'neighbor', являющиеся внуками дочерних элементов 'country' верхнего уровня239# элементы240root.findall("./country/neighbor")241242# Узлы с name='Singapore', имеющие дочерний элемент 'year'243root.findall(".//year/..[@name='Singapore']")244245# Элементы 'year', являющиеся дочерними для узлов с name='Singapore'246root.findall(".//*[@name='Singapore']/year")247248# Все элементы 'neighbor', являющиеся вторым дочерним элементом своего родителя249root.findall(".//neighbor[2]")250```251252### 20.5.2.2. Поддерживаемый синтаксис XPath253254| Синтаксис | Значение |255| --- | --- |256| `тег` | Выбирает все дочерние элементы с указанным тегом. Например, `spam` выбирает все дочерние элементы с именем `spam`; `spam/egg` выбирает всех потомков с именем `egg` среди всех дочерних элементов с именем `spam`. |257| `*` | Выбирает все дочерние элементы. Например, `*/egg` выбирает все внучатые элементы с именем `egg`. |258| `.` | Выбирает текущий узел. Это особенно полезно в начале пути, чтобы указать, что это относительный путь. |259| `//` | Выбирает все подэлементы на всех уровнях ниже текущего элемента. Например, `.//egg` выбирает все элементы `egg` во всём дереве. |260| `..` | Выбирает родительский элемент. Возвращает `None`, если путь пытается достичь предков начального элемента (элемента, для которого была вызвана функция `find`). |261| `[@attrib]` | Выбирает все элементы, у которых есть указанный атрибут. |262| `[@attrib='value']` | Выбирает все элементы, у которых указанный атрибут имеет заданное значение. Значение не может содержать кавычки. |263| `[tag]` | Выбирает все элементы, у которых есть дочерний элемент с именем `тег`. Поддерживаются только непосредственные дочерние элементы. |264| `[position]` | Выбирает все элементы, находящиеся на заданной позиции. Позицией может быть целое число (1 – это первая позиция), выражение `last()` (для последней позиции) или позиция относительно последней позиции (например, `last()-1`). |265266Предикаты (выражения в квадратных скобках) должны предваряться именем тега, звёздочкой или другим предикатом. Предикаты `position` должны предваряться именем тега.267268## 20.5.3. Справочник269270### 20.5.3.1. Функции271272#### `xml.etree.ElementTree.Comment(text=None)`273274Фабрика элементов Comment. Эта фабричная функция создаёт специальный элемент, который будет сериализован как XML-комментарий стандартным сериализатором. Строка комментария может быть как байтовой строкой, так и строкой Unicode. *text* – это строка, содержащая текст комментария. Возвращает экземпляр элемента, представляющий комментарий.275276#### `xml.etree.ElementTree.dump(elem)`277278Записывает дерево элементов или структуру элементов в sys.stdout. Эту функцию следует использовать только для отладки.279280Точный формат вывода зависит от реализации. В этой версии он записывается как обычный XML-файл.281282*elem* – это дерево элементов или отдельный элемент.283284#### `xml.etree.ElementTree.fromstring(text)`285286Разбирает XML-фрагмент из строковой константы. То же, что и [`XML()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XML). *text* – это строка, содержащая XML-данные. Возвращает экземпляр [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element).287288#### `xml.etree.ElementTree.fromstringlist(sequence, parser=None)`289290Разбирает XML-документ из последовательности строковых фрагментов. *sequence* – это список или другая последовательность, содержащая фрагменты XML-данных. *parser* – это необязательный экземпляр анализатора. Если он не указан, используется стандартный анализатор [`XMLParser`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser). Возвращает экземпляр [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element).291292Новое в версии 3.2.293294#### `xml.etree.ElementTree.iselement(element)`295296Проверяет, является ли объект корректным элементом. *element* – это экземпляр элемента. Возвращает истинное значение, если это объект элемента.297298#### `xml.etree.ElementTree.iterparse(source, events=None, parser=None)`299300Разбирает XML-фрагмент в дерево элементов инкрементально и сообщает пользователю о происходящем. *source* – это имя файла или [*файловый объект*](https://python-all.ru/3.3/glossary.html#term-file-object), содержащий XML-данные. *events* – это кортеж событий, о которых нужно сообщать. Поддерживаемые события – строки `"start"`, `"end"`, `"start-ns"` и `"end-ns"` (события “ns” используются для получения подробной информации о пространствах имён). Если *events* опущен, сообщается только о событиях `"end"`. *parser* – это необязательный экземпляр парсера. Если он не указан, используется стандартный парсер [`XMLParser`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser). *parser* может использовать только стандартный [`TreeBuilder`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.TreeBuilder) в качестве цели. Возвращает [*итератор*](https://python-all.ru/3.3/glossary.html#term-iterator), предоставляющий пары `(event, elem)`.301302> **Примечание**303>304> [`iterparse()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.iterparse) гарантирует только то, что при генерации события «start» он уже увидел символ «\>» открывающего тега; поэтому атрибуты определены, но содержимое атрибутов text и tail на этот момент не определено. То же самое относится к дочерним элементам: они могут присутствовать или отсутствовать.305>306> Если нужен полностью заполненный элемент, используйте события "end".307308#### `xml.etree.ElementTree.parse(source, parser=None)`309310Разбирает XML-фрагмент в дерево элементов. *source* – это имя файла или файловый объект, содержащий XML-данные. *parser* – необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор [`XMLParser`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser). Возвращает экземпляр [`ElementTree`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree).311312#### `xml.etree.ElementTree.ProcessingInstruction(target, text=None)`313314Фабрика PI-элементов. Эта фабричная функция создаёт специальный элемент, который будет сериализован как инструкция обработки XML. *target* – строка, содержащая цель PI. *text* – строка, содержащая содержимое PI, если задано. Возвращает экземпляр элемента, представляющий инструкцию обработки.315316#### `xml.etree.ElementTree.register_namespace(prefix, uri)`317318Регистрирует префикс пространства имён. Реестр является глобальным, и любое существующее сопоставление для данного префикса или URI пространства имён будет удалено. *prefix* – префикс пространства имён. *uri* – URI пространства имён. Теги и атрибуты в этом пространстве имён будут сериализованы с указанным префиксом, если это возможно.319320Новое в версии 3.2.321322#### `xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)`323324Фабрика подэлементов. Эта функция создаёт экземпляр элемента и добавляет его к существующему элементу.325326Имя элемента, имена атрибутов и значения атрибутов могут быть как байтовыми строками, так и строками Unicode. *parent* – родительский элемент. *tag* – имя подэлемента. *attrib* – необязательный словарь, содержащий атрибуты элемента. *extra* содержит дополнительные атрибуты, заданные как именованные аргументы. Возвращает экземпляр элемента.327328#### `xml.etree.ElementTree.tostring(element, encoding="us-ascii", method="xml")`329330Генерирует строковое представление XML-элемента, включая все подэлементы. *element* – это экземпляр [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element). *encoding* [\[1\]](https://python-all.ru/3.3/library/xml.etree.elementtree.html#id5) – это кодировка вывода (по умолчанию US-ASCII). Используйте `encoding="unicode"` для генерации строки Unicode (в противном случае генерируется байтовая строка). *method* может быть `"xml"`, `"html"` или `"text"` (по умолчанию `"xml"`). Возвращает (опционально) закодированную строку, содержащую XML-данные.331332#### `xml.etree.ElementTree.tostringlist(element, encoding="us-ascii", method="xml")`333334Генерирует строковое представление XML-элемента, включая все подэлементы. *element* – это экземпляр [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element). *encoding* [\[1\]](https://python-all.ru/3.3/library/xml.etree.elementtree.html#id5) – это кодировка вывода (по умолчанию US-ASCII). Используйте `encoding="unicode"` для генерации строки Unicode (в противном случае генерируется байтовая строка). *method* может быть `"xml"`, `"html"` или `"text"` (по умолчанию `"xml"`). Возвращает список (опционально) закодированных строк, содержащих XML-данные. Не гарантируется какой-либо определённый порядок, за исключением того, что `b"".join(tostringlist(element)) == tostring(element)`.335336Новое в версии 3.2.337338#### `xml.etree.ElementTree.XML(text, parser=None)`339340Разбирает XML-фрагмент из строковой константы. Эту функцию можно использовать для встраивания «XML-литералов» в код Python. *text* – это строка, содержащая XML-данные. *parser* – необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор [`XMLParser`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser). Возвращает экземпляр [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element).341342#### `xml.etree.ElementTree.XMLID(text, parser=None)`343344Разбирает XML-фрагмент из строковой константы, а также возвращает словарь, который сопоставляет идентификаторы элементов с элементами. *text* – это строка, содержащая XML-данные. *parser* – необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор [`XMLParser`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser). Возвращает кортеж, содержащий экземпляр [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element) и словарь.345346### 20.5.3.2. Объекты Element347348#### `class xml.etree.ElementTree.Element(tag, attrib={}, **extra)`349350Класс Element. Этот класс определяет интерфейс Element и предоставляет эталонную реализацию этого интерфейса.351352Имя элемента, имена атрибутов и значения атрибутов могут быть либо байтовыми строками, либо строками Unicode. *tag* – имя элемента. *attrib* – необязательный словарь, содержащий атрибуты элемента. *extra* содержит дополнительные атрибуты, заданные как именованные аргументы.353354#### `tag`355356Строка, определяющая, какие данные представляет этот элемент (иначе говоря, тип элемента).357358#### `text`359360Атрибут *text* можно использовать для хранения дополнительных данных, связанных с элементом. Как следует из названия, этот атрибут обычно является строкой, но может быть любым объектом, зависящим от приложения. Если элемент создаётся из XML-файла, атрибут будет содержать любой текст, найденный между тегами элемента.361362#### `tail`363364Атрибут *tail* можно использовать для хранения дополнительных данных, связанных с элементом. Обычно этот атрибут является строкой, но может быть любым объектом, зависящим от приложения. Если элемент создан из XML-файла, атрибут будет содержать любой текст, найденный после закрывающего тега элемента и до следующего тега.365366#### `attrib`367368Словарь, содержащий атрибуты элемента. Обратите внимание, что хотя значение *attrib* всегда является настоящим изменяемым словарём Python, реализация ElementTree может использовать другое внутреннее представление и создавать словарь только по запросу. Чтобы воспользоваться преимуществами таких реализаций, по возможности используйте приведённые ниже методы словаря.369370Следующие методы, подобные словарным, работают с атрибутами элемента.371372#### `clear()`373374Сбрасывает элемент. Эта функция удаляет все дочерние элементы, очищает все атрибуты и устанавливает атрибуты text и tail в `None`.375376#### `get(key, default=None)`377378Возвращает атрибут элемента с именем *key*.379380Возвращает значение атрибута или *default*, если атрибут не найден.381382#### `items()`383384Возвращает атрибуты элемента в виде последовательности пар (имя, значение). Атрибуты возвращаются в произвольном порядке.385386#### `keys()`387388Возвращает имена атрибутов элемента в виде списка. Имена возвращаются в произвольном порядке.389390#### `set(key, value)`391392Устанавливает атрибут *key* элемента в *value*.393394Следующие методы работают с дочерними элементами (подэлементами) текущего элемента.395396#### `append(subelement)`397398Добавляет элемент *subelement* в конец внутреннего списка дочерних элементов этого элемента. Возбуждает [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError), если *subelement* не является [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element).399400#### `extend(subelements)`401402Добавляет *subelements* из объекта-последовательности с нулем или более элементов. Возбуждает [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError), если дочерний элемент не является [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element).403404Новое в версии 3.2.405406#### `find(match, namespaces=None)`407408Находит первый дочерний элемент, соответствующий *match*. *match* может быть именем тега или [*путем*](https://python-all.ru/3.3/library/xml.etree.elementtree.html#elementtree-xpath). Возвращает экземпляр элемента или `None`. *namespaces* – необязательное отображение префикса пространства имен на полное имя.409410#### `findall(match, namespaces=None)`411412Находит все соответствующие подэлементы по имени тега или [*пути*](https://python-all.ru/3.3/library/xml.etree.elementtree.html#elementtree-xpath). Возвращает список, содержащий все подходящие элементы в порядке документа. *namespaces* – необязательное отображение префикса пространства имён в полное имя.413414#### `findtext(match, default=None, namespaces=None)`415416Находит текст для первого подэлемента, соответствующего *match*. *match* может быть именем тега или [*путём*](https://python-all.ru/3.3/library/xml.etree.elementtree.html#elementtree-xpath). Возвращает текстовое содержимое первого подходящего элемента или *default*, если элемент не найден. Обратите внимание: если у подходящего элемента нет текстового содержимого, возвращается пустая строка. *namespaces* – необязательное отображение префикса пространства имён в полное имя.417418#### `getchildren()`419420Устарело с версии 3.2: Используйте `list(elem)` или итерацию.421422#### `getiterator(tag=None)`423424Устарело с версии 3.2: Вместо этого используйте метод [`Element.iter()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.iter).425426#### `insert(index, subelement)`427428Вставляет *subelement* в заданную позицию в этом элементе. Возбуждает [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError), если *subelement* не является [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element).429430#### `iter(tag=None)`431432Создает древесный [*итератор*](https://python-all.ru/3.3/glossary.html#term-iterator) с текущим элементом в качестве корня. Итератор обходит этот элемент и все элементы ниже него в порядке документа (сначала вглубь). Если *tag* не равен `None` или `'*'`, из итератора возвращаются только элементы, чей тег равен *tag*. Если структура дерева изменяется во время итерации, результат не определен.433434Новое в версии 3.2.435436#### `iterfind(match, namespaces=None)`437438Находит все подходящие подэлементы по имени тега или [*path*](https://python-all.ru/3.3/library/xml.etree.elementtree.html#elementtree-xpath). Возвращает итерируемый объект, выдающий все подходящие элементы в порядке документа. *namespaces* – необязательное отображение префикса пространства имён на полное имя.439440Новое в версии 3.2.441442#### `itertext()`443444Создаёт текстовый итератор. Итератор перебирает этот элемент и все подэлементы в порядке документа и возвращает весь внутренний текст.445446Новое в версии 3.2.447448#### `makeelement(tag, attrib)`449450Создает новый объект элемента того же типа, что и этот элемент. Не вызывайте этот метод, вместо этого используйте фабричную функцию [`SubElement()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.SubElement).451452#### `remove(subelement)`453454Удаляет *subelement* из элемента. В отличие от методов find\*, этот метод сравнивает элементы по идентичности экземпляра, а не по значению тега или содержимому.455456[`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element) объекты также поддерживают следующие методы последовательностного типа для работы с подэлементами: [`__delitem__()`](https://python-all.ru/3.3/reference/datamodel.html#object.__delitem__), [`__getitem__()`](https://python-all.ru/3.3/reference/datamodel.html#object.__getitem__), [`__setitem__()`](https://python-all.ru/3.3/reference/datamodel.html#object.__setitem__), [`__len__()`](https://python-all.ru/3.3/reference/datamodel.html#object.__len__).457458Внимание: элементы без подэлементов будут иметь значение `False` при проверке. Это поведение изменится в будущих версиях. Вместо этого используйте проверку `len(elem)` или `elem is None`.459460```python461element = root.find('foo')462463if not element: # осторожно!464 print("element not found, or element has no subelements")465466if element is None:467 print("element not found")468```469470### 20.5.3.3. Объекты ElementTree471472#### `class xml.etree.ElementTree.ElementTree(element=None, file=None)`473474Класс-обёртка ElementTree. Этот класс представляет целую иерархию элементов и добавляет дополнительную поддержку сериализации в стандартный XML и из него.475476*element* – корневой элемент. Дерево инициализируется содержимым XML-*файла*, если он указан.477478#### `_setroot(element)`479480Заменяет корневой элемент этого дерева. При этом текущее содержимое дерева отбрасывается и заменяется указанным элементом. Используйте с осторожностью. *element* – экземпляр элемента.481482#### `find(match, namespaces=None)`483484То же, что и [`Element.find()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.find), начиная с корня дерева.485486#### `findall(match, namespaces=None)`487488То же, что и [`Element.findall()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.findall), начиная с корня дерева.489490#### `findtext(match, default=None, namespaces=None)`491492То же, что и [`Element.findtext()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.findtext), начиная с корня дерева.493494#### `getiterator(tag=None)`495496Устарело с версии 3.2: Вместо этого используйте метод [`ElementTree.iter()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree.iter).497498#### `getroot()`499500Возвращает корневой элемент этого дерева.501502#### `iter(tag=None)`503504Создаёт и возвращает итератор дерева для корневого элемента. Итератор перебирает все элементы в этом дереве в порядке следования разделов. *tag* – это тег, который нужно найти (по умолчанию возвращаются все элементы).505506#### `iterfind(match, namespaces=None)`507508То же, что и [`Element.iterfind()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element.iterfind), начиная с корня дерева.509510Новое в версии 3.2.511512#### `parse(source, parser=None)`513514Загружает внешний XML-раздел в это дерево элементов. *source* – это имя файла или [*файловый объект*](https://python-all.ru/3.3/glossary.html#term-file-object). *parser* – необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор [`XMLParser`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser). Возвращает корневой элемент раздела.515516#### `write(file, encoding="us-ascii", xml_declaration=None, default_namespace=None, method="xml")`517518Записывает дерево элементов в файл в формате XML. *file* – это имя файла или [*файловый объект*](https://python-all.ru/3.3/glossary.html#term-file-object), открытый для записи. *encoding* [\[1\]](https://python-all.ru/3.3/library/xml.etree.elementtree.html#id5) – это кодировка вывода (по умолчанию US-ASCII). *xml\_declaration* управляет, нужно ли добавлять XML-декларацию в файл. Используйте `False`, чтобы никогда не добавлять, `True` – чтобы добавлять всегда, `None` – чтобы добавлять, только если кодировка не US-ASCII, UTF-8 или Unicode (по умолчанию `None`). *default\_namespace* задаёт пространство имён XML по умолчанию (для “xmlns”). *method* может быть `"xml"`, `"html"` или `"text"` (по умолчанию `"xml"`).519520Результат может быть строкой ([`str`](https://python-all.ru/3.3/library/stdtypes.html#str)) или двоичными данными ([`bytes`](https://python-all.ru/3.3/library/functions.html#bytes)). Это управляется аргументом *encoding*. Если *encoding* равно `"unicode"`, результат – строка; в противном случае – двоичные данные. Обратите внимание, что это может конфликтовать с типом *file*, если это открытый [*файловый объект*](https://python-all.ru/3.3/glossary.html#term-file-object); убедитесь, что не пытаетесь записать строку в двоичный поток и наоборот.521522Это XML-файл, который будет обрабатываться:523524```python525<html>526 <head>527 <title>Example page</title>528 </head>529 <body>530 <p>Moved to <a href="http://example.org/">example.org</a>531 or <a href="http://example.com/">example.com</a>.</p>532 </body>533</html>534```535536Пример изменения атрибута «target» каждой ссылки в первом абзаце:537538```python539>>> from xml.etree.ElementTree import ElementTree540>>> tree = ElementTree()541>>> tree.parse("index.xhtml")542<Element 'html' at 0xb77e6fac>543>>> p = tree.find("body/p") # Находит первое вхождение тега p в body544>>> p545<Element 'p' at 0xb77ec26c>546>>> links = list(p.iter("a")) # Возвращает список всех ссылок547>>> links548[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]549>>> for i in links: # Перебирает все найденные ссылки550... i.attrib["target"] = "blank"551>>> tree.write("output.xhtml")552```553554### 20.5.3.4. Объекты QName555556#### `class xml.etree.ElementTree.QName(text_or_uri, tag=None)`557558Обёртка QName. Её можно использовать для обёртки значения атрибута QName, чтобы обеспечить правильную обработку пространств имён при выводе. *text\_or\_uri* – это строка, содержащая значение QName в формате {uri}local, или, если задан аргумент tag, часть URI QName. Если *tag* задан, первый аргумент интерпретируется как URI, а этот аргумент – как локальное имя. Экземпляры [`QName`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.QName) непрозрачны.559560### 20.5.3.5. Объекты TreeBuilder561562#### `class xml.etree.ElementTree.TreeBuilder(element_factory=None)`563564Универсальный построитель структуры элементов. Этот построитель преобразует последовательность вызовов методов start, data и end в правильно сформированную структуру элементов. Этот класс можно использовать для построения структуры элементов с помощью пользовательского анализатора XML или анализатора для другого XML-подобного формата. *element\_factory*, если задан, должен быть вызываемым объектом, принимающим два позиционных аргумента: тег и словарь атрибутов. Ожидается, что он возвращает новый экземпляр элемента.565566#### `close()`567568Сбрасывает буферы построителя и возвращает корневой элемент документа. Возвращает экземпляр [`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element).569570#### `data(data)`571572Добавляет текст в текущий элемент. *data* является строкой. Это должна быть либо байтовая строка, либо строка Unicode.573574#### `end(tag)`575576Закрывает текущий элемент. *tag* – имя элемента. Возвращает закрытый элемент.577578#### `start(tag, attrs)`579580Открывает новый элемент. *tag* – имя элемента. *attrs* – словарь, содержащий атрибуты элемента. Возвращает открытый элемент.581582Кроме того, пользовательский объект [`TreeBuilder`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.TreeBuilder) может предоставлять следующий метод:583584#### `doctype(name, pubid, system)`585586Обрабатывает объявление типа документа. *name* – это имя типа документа. *pubid* – публичный идентификатор. *system* – системный идентификатор. Этот метод не существует в классе [`TreeBuilder`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.TreeBuilder) по умолчанию.587588Новое в версии 3.2.589590### 20.5.3.6. Объекты XMLParser591592#### `class xml.etree.ElementTree.XMLParser(html=0, target=None, encoding=None)`593594[`Element`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element) построитель структуры для исходных данных XML, основанный на парсере expat. *html* – предопределённые HTML-сущности. Этот флаг не поддерживается текущей реализацией. *target* – целевой объект. Если опущен, построитель использует экземпляр стандартного класса [`TreeBuilder`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.TreeBuilder). *encoding* [\[1\]](https://python-all.ru/3.3/library/xml.etree.elementtree.html#id5) необязателен. Если задан, значение переопределяет кодировку, указанную в XML-файле.595596#### `close()`597598Завершает передачу данных анализатору. Возвращает результат вызова метода `close()` объекта *target*, переданного при создании; по умолчанию это корневой элемент документа.599600#### `doctype(name, pubid, system)`601602Устарело с версии 3.2: Определите метод [`TreeBuilder.doctype()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.TreeBuilder.doctype) в собственном целевом объекте TreeBuilder.603604#### `feed(data)`605606Передает данные парсеру. *data* – это закодированные данные.607608[`XMLParser.feed()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser.feed) вызывает метод *target* `start()` для каждого открывающего тега, его метод `end()` для каждого закрывающего тега, а данные обрабатываются методом `data()`. [`XMLParser.close()`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser.close) вызывает метод *target* `close()`. [`XMLParser`](https://python-all.ru/3.3/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLParser) может использоваться не только для построения дерева. Это пример подсчёта максимальной глубины XML-файла:609610```python611>>> from xml.etree.ElementTree import XMLParser612>>> class MaxDepth: # Целевой объект парсера613... maxDepth = 0614... depth = 0615... def start(self, tag, attrib): # Вызывается для каждого открывающего тега.616... self.depth += 1617... if self.depth > self.maxDepth:618... self.maxDepth = self.depth619... def end(self, tag): # Вызывается для каждого закрывающего тега.620... self.depth -= 1621... def data(self, data):622... pass # С данными ничего делать не нужно.623... def close(self): # Вызывается, когда все данные проанализированы.624... return self.maxDepth625...626>>> target = MaxDepth()627>>> parser = XMLParser(target=target)628>>> exampleXml = """629... <a>630... <b>631... </b>632... <b>633... <c>634... <d>635... </d>636... </c>637... </b>638... </a>"""639>>> parser.feed(exampleXml)640>>> parser.close()6414642```643644### 20.5.3.7. Исключения645646#### `class xml.etree.ElementTree.ParseError`647648Ошибка разбора XML, возникающая при сбое разбора в различных методах разбора этого модуля. Строковое представление экземпляра этого исключения будет содержать понятное пользователю сообщение об ошибке. Кроме того, будут доступны следующие атрибуты:649650#### `code`651652Числовой код ошибки от анализатора expat. См. документацию [`xml.parsers.expat`](https://python-all.ru/3.3/library/pyexpat.html#module-xml.parsers.expat) для получения списка кодов ошибок и их значений.653654#### `position`655656Кортеж из номеров строки *line* и столбца *column*, указывающий, где произошла ошибка.657658Сноски659660| \[1\] | Строка кодировки, включённая в вывод XML, должна соответствовать соответствующим стандартам. Например, «UTF-8» допустимо, а «UTF8» – нет. См. [http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl](https://python-all.ru/3.3/library/xml.etree.elementtree.html) и [http://www.iana.org/assignments/character-sets](https://python-all.ru/3.3/library/xml.etree.elementtree.html). |661| --- | --- |662