`xml.etree.elementtree.md`

583 строк · 28.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/xml.etree.elementtree.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 19.11. `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.1/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.1/library/xml.etree.elementtree.html). На странице Фредрика Лунда также находится разрабатываемая версия xml.etree.ElementTree.2627## 19.11.1. Функции2829#### `xml.etree.ElementTree.Comment(text=None)`3031Фабрика элементов Comment. Эта фабричная функция создаёт специальный элемент, который будет сериализован как XML-комментарий. Строка комментария может быть объектом3233[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)3435с символами только ASCII или объектом3637[`str`](https://python-all.ru/3.1/library/functions.html#str)3839.4041*text*4243– это строка, содержащая текст комментария. Возвращает экземпляр элемента, представляющий комментарий.4445#### `xml.etree.ElementTree.dump(elem)`4647Записывает дерево элементов или структуру элемента в sys.stdout. Эту функцию следует использовать только для отладки.4849Точный формат вывода зависит от реализации. В этой версии он записывается как обычный XML-файл.5051*elem* – это дерево элементов или отдельный элемент.5253#### `xml.etree.ElementTree.Element(tag, attrib={}, **extra)`5455Фабрика элементов. Эта функция возвращает объект, реализующий стандартный интерфейс Element. Точный класс или тип этого объекта зависит от реализации, но он всегда будет совместим с классом \_ElementInterface в этом модуле.5657Имя элемента, имена атрибутов и значения атрибутов могут быть объектом [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) только с ASCII или объектом [`str`](https://python-all.ru/3.1/library/functions.html#str). *tag* – это имя элемента. *attrib* – необязательный словарь, содержащий атрибуты элемента. *extra* содержит дополнительные атрибуты, заданные как именованные аргументы. Возвращает экземпляр элемента.5859#### `xml.etree.ElementTree.fromstring(text)`6061Разбирает XML-фрагмент из строковой константы. То же, что и XML.6263*text*6465– это строка, содержащая XML-данные. Возвращает экземпляр Element.6667#### `xml.etree.ElementTree.iselement(element)`6869Проверяет, является ли объект корректным элементом.7071*element*7273– это экземпляр элемента. Возвращает истинное значение, если это объект элемента.7475#### `xml.etree.ElementTree.iterparse(source, events=None)`7677Разбирает XML-фрагмент в дерево элементов инкрементально, сообщая пользователю о происходящем. *source* – это имя файла или [*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object), содержащий XML-данные. *events* – это список событий для отчёта. Если опущен, сообщаются только события “end”. Возвращает [*итератор*](https://python-all.ru/3.1/glossary.html#term-iterator), предоставляющий пары `(event, elem)`.7879> **Примечание**80>81> [`iterparse()`](https://python-all.ru/3.1/library/xml.etree.elementtree.html#xml.etree.ElementTree.iterparse) гарантирует только то, что при генерации события «start» он уже увидел символ «\>» открывающего тега; поэтому атрибуты определены, но содержимое атрибутов text и tail на этот момент не определено. То же самое относится к дочерним элементам: они могут присутствовать или отсутствовать.82>83> Если нужен полностью заполненный элемент, используйте события "end".8485#### `xml.etree.ElementTree.parse(source, parser=None)`8687Разбирает XML-фрагмент в дерево элементов.8889*source*9091– это имя файла или файловый объект, содержащий XML-данные.9293*parser*9495– необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор XMLTreeBuilder. Возвращает экземпляр ElementTree.9697#### `xml.etree.ElementTree.ProcessingInstruction(target, text=None)`9899Фабрика элементов PI. Эта фабричная функция создаёт специальный элемент, который будет сериализован как инструкция по обработке XML.100101*target*102103– это строка, содержащая цель PI.104105*text*106107– это строка, содержащая содержимое PI, если задано. Возвращает экземпляр элемента, представляющий инструкцию по обработке.108109#### `xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)`110111Фабрика подэлементов. Эта функция создаёт экземпляр элемента и добавляет его к существующему элементу.112113Имя элемента, имена атрибутов и значения атрибутов могут быть объектом [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) только с ASCII или объектом [`str`](https://python-all.ru/3.1/library/functions.html#str). *parent* – это родительский элемент. *tag* – имя подэлемента. *attrib* – необязательный словарь, содержащий атрибуты элемента. *extra* содержит дополнительные атрибуты, заданные как именованные аргументы. Возвращает экземпляр элемента.114115#### `xml.etree.ElementTree.tostring(element, encoding=None)`116117Генерирует строковое представление XML-элемента, включая все подэлементы.118119*element*120121– это экземпляр Element.122123*encoding*124125– кодировка вывода (по умолчанию US-ASCII). Возвращает закодированную строку, содержащую XML-данные.126127#### `xml.etree.ElementTree.XML(text)`128129Разбирает XML-фрагмент из строковой константы. Эту функцию можно использовать для встраивания «XML-литералов» в код Python.130131*text*132133– это строка, содержащая XML-данные. Возвращает экземпляр Element.134135#### `xml.etree.ElementTree.XMLID(text)`136137Разбирает XML-фрагмент из строковой константы, а также возвращает словарь, который сопоставляет идентификаторы элементов с элементами.138139*text*140141– это строка, содержащая XML- данные. Возвращает кортеж, содержащий экземпляр Element и словарь.142143## 19.11.2. Интерфейс Element144145Объекты Element, возвращаемые функциями Element или SubElement, имеют следующие методы и атрибуты.146147#### `Element.tag`148149Строка, определяющая, какие данные представляет этот элемент (иными словами, тип элемента).150151#### `Element.text`152153Атрибут154155*text*156157можно использовать для хранения дополнительных данных, связанных с элементом. Как следует из названия, этот атрибут обычно является строкой, но может быть любым объектом, специфичным для приложения. Если элемент создан из XML-файла, атрибут будет содержать любой текст, найденный между тегами элемента.158159#### `Element.tail`160161Атрибут162163*tail*164165можно использовать для хранения дополнительных данных, связанных с элементом. Обычно этот атрибут представляет собой строку, но может быть любым объектом, специфичным для приложения. Если элемент создан из XML-файла, атрибут будет содержать любой текст, найденный после закрывающего тега элемента и перед следующим тегом.166167#### `Element.attrib`168169Словарь, содержащий атрибуты элемента. Обратите внимание: хотя значение170171*attrib*172173всегда является настоящим изменяемым словарём Python, реализация ElementTree может использовать другое внутреннее представление и создавать словарь только по запросу. Чтобы воспользоваться преимуществами таких реализаций, используйте методы словаря, перечисленные ниже, когда это возможно.174175Следующие методы, подобные словарным, работают с атрибутами элемента.176177#### `Element.clear()`178179Сбрасывает элемент. Эта функция удаляет все подэлементы, очищает все атрибуты и устанавливает атрибуты text и tail в None.180181#### `Element.get(key, default=None)`182183Возвращает атрибут элемента с именем *key*.184185Возвращает значение атрибута или *default*, если атрибут не найден.186187#### `Element.items()`188189Возвращает атрибуты элемента в виде последовательности пар (имя, значение). Атрибуты возвращаются в произвольном порядке.190191#### `Element.keys()`192193Возвращает имена атрибутов элемента в виде списка. Имена возвращаются в произвольном порядке.194195#### `Element.set(key, value)`196197Устанавливает атрибут198199*key*200201элемента в202203*value*204205.206207Следующие методы работают с дочерними элементами (подэлементами) текущего элемента.208209#### `Element.append(subelement)`210211Добавляет элемент212213*subelement*214215в конец внутреннего списка подэлементов данного элемента.216217#### `Element.find(match)`218219Находит первый подэлемент, соответствующий220221*match*222223.224225*match*226227может быть именем тега или путём. Возвращает экземпляр элемента или228229`None`230231.232233#### `Element.findall(match)`234235Находит все подэлементы, соответствующие236237*match*238239.240241*match*242243может быть именем тега или путём. Возвращает итерируемый объект, выдающий все подходящие элементы в порядке документа.244245#### `Element.findtext(condition, default=None)`246247Находит текст первого подэлемента, соответствующего248249*condition*250251.252253*condition*254255может быть именем тега или путём. Возвращает текстовое содержимое первого подходящего элемента или256257*default*258259, если элемент не найден. Обратите внимание: если у подходящего элемента нет текстового содержимого, возвращается пустая строка.260261#### `Element.getchildren()`262263Возвращает все подэлементы. Элементы возвращаются в порядке документа.264265#### `Element.getiterator(tag=None)`266267Создаёт итератор по дереву с текущим элементом в качестве корня. Итератор обходит этот элемент и все элементы ниже него в порядке документа (в глубину). Если268269*tag*270271не равен272273`None`274275или276277`'*'`278279, из итератора возвращаются только элементы, тег которых равен280281*tag*282283.284285#### `Element.insert(index, element)`286287Вставляет подэлемент в заданную позицию в данном элементе.288289#### `Element.makeelement(tag, attrib)`290291Создаёт новый объект элемента того же типа, что и данный элемент. Не вызывайте этот метод, используйте вместо него фабричную функцию SubElement.292293#### `Element.remove(subelement)`294295Удаляет296297*подэлемент*298299из элемента. В отличие от методов findXYZ, этот метод сравнивает элементы на основе идентичности экземпляра, а не по значению тега или содержимому.300301Объекты Element также поддерживают следующие методы последовательностей для работы с подэлементами: [`__delitem__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__delitem__), [`__getitem__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__getitem__), [`__setitem__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__setitem__), [`__len__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__len__).302303Внимание: поскольку объекты Element не определяют метод [`__bool__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__bool__), элементы без подэлементов будут проверяться как `False`.304305```python306element = root.find('foo')307308if not element: # осторожно!309    print("element not found, or element has no subelements")310311if element is None:312    print("element not found")313```314315## 19.11.3. Объекты ElementTree316317#### `class xml.etree.ElementTree.ElementTree(element=None, file=None)`318319Класс-обёртка ElementTree. Этот класс представляет целую иерархию элементов и добавляет дополнительную поддержку для сериализации в стандартный XML и из него.320321*element* – корневой элемент. Дерево инициализируется содержимым XML-*файла*, если он указан.322323#### `_setroot(element)`324325Заменяет корневой элемент этого дерева. При этом отбрасывается текущее содержимое дерева и заменяется указанным элементом. Используйте с осторожностью.326327*element*328329– экземпляр элемента.330331#### `find(path)`332333Находит первый элемент верхнего уровня с указанным тегом. То же, что getroot().find(path).334335*path*336337– элемент для поиска. Возвращает первый подходящий элемент или338339`None`340341, если элемент не найден.342343#### `findall(path)`344345Находит все элементы верхнего уровня с указанным тегом. То же, что getroot().findall(path).346347*path*348349– элемент для поиска. Возвращает список или350351[*итератор*](https://python-all.ru/3.1/glossary.html#term-iterator)352353, содержащий все подходящие элементы, в порядке документа.354355#### `findtext(path, default=None)`356357Находит текст элемента для первого элемента верхнего уровня с указанным тегом. То же, что getroot().findtext(path).358359*path*360361– элемент верхнего уровня для поиска.362363*default*364365– значение, возвращаемое, если элемент не найден. Возвращает текстовое содержимое первого подходящего элемента или значение по умолчанию, если элемент не найден. Обратите внимание, что если элемент найден, но не имеет текстового содержимого, этот метод возвращает пустую строку.366367#### `getiterator(tag=None)`368369Создаёт и возвращает итератор дерева для корневого элемента. Итератор перебирает все элементы этого дерева в порядке разделов.370371*tag*372373– тег для поиска (по умолчанию возвращаются все элементы).374375#### `getroot()`376377Возвращает корневой элемент этого дерева.378379#### `parse(source, parser=None)`380381Загружает внешний XML-раздел в это дерево элементов.382383*source*384385– имя файла или386387[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)388389.390391*parser*392393– необязательный экземпляр парсера. Если не указан, используется стандартный парсер XMLTreeBuilder. Возвращает корневой элемент раздела.394395#### `write(file, encoding=None)`396397Записывает дерево элементов в файл в формате XML.398399*file*400401– имя файла или402403[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)404405, открытый для записи.406407*encoding*408409[\[1\]](https://python-all.ru/3.1/library/xml.etree.elementtree.html#id2)410411– кодировка вывода (по умолчанию US-ASCII).412413Это XML-файл, который будет обрабатываться:414415```python416<html>417    <head>418        <title>Example page</title>419    </head>420    <body>421        <p>Moved to <a href="http://example.org/">example.org</a>422        or <a href="http://example.com/">example.com</a>.</p>423    </body>424</html>425```426427Пример изменения атрибута «target» каждой ссылки в первом абзаце:428429```python430>>> from xml.etree.ElementTree import ElementTree431>>> tree = ElementTree()432>>> tree.parse("index.xhtml")433<Element html at b7d3f1ec>434>>> p = tree.find("body/p")     # Находит первое вхождение тега p в body435>>> p436<Element p at 8416e0c>437>>> links = p.getiterator("a")  # Возвращает список всех ссылок438>>> links439[<Element a at b7d4f9ec>, <Element a at b7d4fb0c>]440>>> for i in links:             # Перебирает все найденные ссылки441...     i.attrib["target"] = "blank"442>>> tree.write("output.xhtml")443```444445## 19.11.4. Объекты QName446447#### `class xml.etree.ElementTree.QName(text_or_uri, tag=None)`448449Обёртка QName. Её можно использовать для обёртывания значения атрибута QName, чтобы обеспечить правильную обработку пространств имён на выходе.450451*text\_or\_uri*452453– строка, содержащая значение QName в форме {uri}local, или, если задан аргумент tag, URI-часть QName. Если задан454455*tag*456457, первый аргумент интерпретируется как URI, а этот аргумент – как локальное имя. Экземпляры458459[`QName`](https://python-all.ru/3.1/library/xml.etree.elementtree.html#xml.etree.ElementTree.QName)460461являются непрозрачными.462463## 19.11.5. Объекты TreeBuilder464465#### `class xml.etree.ElementTree.TreeBuilder(element_factory=None)`466467Универсальный построитель структуры элементов. Этот построитель преобразует последовательность вызовов методов start, data и end в правильно сформированную структуру элементов. Вы можете использовать этот класс для построения структуры элементов с помощью пользовательского XML-парсера или парсера для какого-либо другого XML-подобного формата. *element\_factory* вызывается для создания новых экземпляров Element, если он задан.468469#### `close()`470471Сбрасывает буферы парсера и возвращает элемент документа верхнего уровня. Возвращает экземпляр Element.472473#### `data(data)`474475Добавляет текст в текущий элемент.476477*data*478479– строка. Она должна быть либо объектом480481[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)482483, содержащим только ASCII, либо объектом484485[`str`](https://python-all.ru/3.1/library/functions.html#str)486487.488489#### `end(tag)`490491Закрывает текущий элемент.492493*tag*494495– имя элемента. Возвращает закрытый элемент.496497#### `start(tag, attrs)`498499Открывает новый элемент.500501*tag*502503– имя элемента.504505*attrs*506507– словарь, содержащий атрибуты элемента. Возвращает открытый элемент.508509## 19.11.6. Объекты XMLTreeBuilder510511#### `class xml.etree.ElementTree.XMLTreeBuilder(html=0, target=None)`512513Построитель структуры элементов для исходных данных XML, основанный на парсере expat. *html* – предопределённые HTML-сущности. Этот флаг не поддерживается текущей реализацией. *target* – целевой объект. Если не указан, построитель использует экземпляр стандартного класса TreeBuilder.514515#### `close()`516517Завершает подачу данных парсеру. Возвращает структуру элемента.518519#### `doctype(name, pubid, system)`520521Обрабатывает объявление doctype.522523*name*524525– имя doctype.526527*pubid*528529– публичный идентификатор.530531*system*532533– системный идентификатор.534535#### `feed(data)`536537Подаёт данные парсеру.538539*data*540541– закодированные данные.542543[`XMLTreeBuilder.feed()`](https://python-all.ru/3.1/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLTreeBuilder.feed) вызывает метод `start()` объекта *target* для каждого открывающего тега, его метод `end()` для каждого закрывающего тега, а данные обрабатываются методом `data()`. [`XMLTreeBuilder.close()`](https://python-all.ru/3.1/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLTreeBuilder.close) вызывает метод `close()` объекта *target*. [`XMLTreeBuilder`](https://python-all.ru/3.1/library/xml.etree.elementtree.html#xml.etree.ElementTree.XMLTreeBuilder) может использоваться не только для построения древовидной структуры. Это пример подсчёта максимальной глубины XML-файла:544545```python546>>> from xml.etree.ElementTree import XMLTreeBuilder547>>> class MaxDepth:                     # Целевой объект парсера548...     maxDepth = 0549...     depth = 0550...     def start(self, tag, attrib):   # Вызывается для каждого открывающего тега.551...         self.depth += 1552...         if self.depth > self.maxDepth:553...             self.maxDepth = self.depth554...     def end(self, tag):             # Вызывается для каждого закрывающего тега.555...         self.depth -= 1556...     def data(self, data):557...         pass            # С данными ничего делать не нужно.558...     def close(self):    # Вызывается, когда все данные проанализированы.559...         return self.maxDepth560...561>>> target = MaxDepth()562>>> parser = XMLTreeBuilder(target=target)563>>> exampleXml = """564... <a>565...   <b>566...   </b>567...   <b>568...     <c>569...       <d>570...       </d>571...     </c>572...   </b>573... </a>"""574>>> parser.feed(exampleXml)575>>> parser.close()5764577```578579Сноски580581| \[1\] | Строка кодировки, входящая в состав вывода XML, должна соответствовать соответствующим стандартам. Например, «UTF-8» допустимо, а «UTF8» – нет. См. [http://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl](https://python-all.ru/3.1/library/xml.etree.elementtree.html) и [http://www.iana.org/assignments/character-sets](https://python-all.ru/3.1/library/xml.etree.elementtree.html). |582| --- | --- |583