xml.etree.ElementTree — API XML ElementTree

Исходный код: Lib/xml/etree/ElementTree.py

Модуль xml.etree.ElementTree реализует простой и эффективный API для разбора и создания XML-данных.

Руководство

Это краткое руководство по использованию xml.etree.ElementTree (ET вкратце). Цель – продемонстрировать некоторые составляющие и основные понятия модуля.

XML-дерево и элементы

XML – это иерархический формат данных, и наиболее естественный способ его представления – это дерево. Модуль ET содержит два класса для этой цели – ElementTree представляет весь XML-документ как дерево, а Element представляет собой узел в этом дереве. Взаимодействие с целым документом (чтение и запись в/из файлов) обычно происходит на уровне ElementTree. Взаимодействие с отдельным XML-элементом и его подэлементами осуществляется на уровне Element.

Разбор XML

Мы будем использовать следующий XML-документ в качестве примера данных для этого раздела:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank>1</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank>4</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank>68</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Мы можем импортировать эти данные, прочитав их из файла:

import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()

Или напрямую из строки:

root = ET.fromstring(country_data_as_string)

fromstring() парсит XML из строки непосредственно в Element, который является корневым элементом разборённого дерева. Другие функции разбора могут создать ElementTree. Проверьте документацию, чтобы убедиться.

В качестве Element, root имеет тег и словарь атрибутов:

>>> root.tag
'data'
>>> root.attrib
{}

У него также есть дочерние узлы, по которым мы можем итерироваться:

>>> for child in root:
...     print(child.tag, child.attrib)
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}

Дочерние элементы вложены, и мы можем получить доступ к конкретным дочерним узлам по индексу:

>>> root[0][1].text
'2008'

API потокового разбора для неблокирующего разбора

Большинство функций разбора, предоставляемых этим модулем, требуют, чтобы весь документ был прочитан целиком перед возвратом любого результата. Можно использовать XMLParser и поставлять данные по частям, но это API «push», который вызывает методы целевого обработчика, что слишком низкоуровнево и неудобно для большинства нужд. Иногда пользователь хочет иметь возможность по частям разбирать XML без блокирующих операций, наслаждаясь удобством полностью сформированных объектов Element.

Самый мощный инструмент для этого – XMLPullParser. Он не требует блокирующего чтения для получения XML-данных, вместо этого данные подаются по частям с помощью вызовов XMLPullParser.feed(). Чтобы получить разборённые XML-элементы, вызовите XMLPullParser.read_events(). Вот пример:

>>> parser = ET.XMLPullParser(['start', 'end'])
>>> parser.feed('<mytag>sometext')
>>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> parser.feed(' more text</mytag>')
>>> for event, elem in parser.read_events():
...     print(event)
...     print(elem.tag, 'text=', elem.text)
...
end

Очевидный случай использования – приложения, работающие в режиме без ожидания, где XML-данные поступают из сокета или считываются по частям с некоторого хранилища. В таких случаях блокирующие чтение недопустимы.

Из-за такой гибкости XMLPullParser может быть неудобно использовать для более простых случаев. Если вам не мешает блокирование вашего приложения при чтении XML-данных, но вам все же нужны возможности по частям разбора, взгляните на iterparse(). Он может быть полезен, когда вы читаете большой XML-документ и не хотите держать его целиком в памяти.

Поиск интересных элементов

Element имеет несколько полезных методов, которые помогают рекурсивно перебирать все поддеревья под ним (его дочерние элементы, их дочерние элементы и т. д.). Например, Element.iter():

>>> for neighbor in root.iter('neighbor'):
...     print(neighbor.attrib)
...
{'name': 'Austria', 'direction': 'E'}
{'name': 'Switzerland', 'direction': 'W'}
{'name': 'Malaysia', 'direction': 'N'}
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}

Element.findall() находит только элементы с тегом, которые являются прямыми дочерними элементами текущего элемента. Element.find() находит первый дочерний элемент с заданным тегом, а Element.text получает текстовое содержимое элемента. Element.get() получает доступ к атрибутам элемента:

>>> for country in root.findall('country'):
...     rank = country.find('rank').text
...     name = country.get('name')
...     print(name, rank)
...
Liechtenstein 1
Singapore 4
Panama 68

Более сложная спецификация элементов, которые нужно искать, возможна с помощью XPath.

Изменение XML-файла

ElementTree предоставляет простой способ построения XML-документов и записи их в файлы. Для этой цели предназначен метод ElementTree.write().

После создания объект Element может быть изменён путём непосредственного изменения его полей (таких как Element.text), добавления и изменения атрибутов (метод Element.set()), а также добавления новых дочерних элементов (например, с помощью Element.append()).

Предположим, мы хотим добавить единицу к рейтингу каждой страны и добавить атрибут updated к элементу рейтинга:

>>> for rank in root.iter('rank'):
...     new_rank = int(rank.text) + 1
...     rank.text = str(new_rank)
...     rank.set('updated', 'yes')
...
>>> tree.write('output.xml')

Наш XML теперь выглядит так:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank updated="yes">69</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

Мы можем удалить элементы с помощью Element.remove(). Предположим, мы хотим удалить все страны с рейтингом выше 50:

>>> for country in root.findall('country'):
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

Наш XML теперь выглядит так:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
</data>

Создание XML-документов

Функция SubElement() также предоставляет удобный способ создания новых подэлементов для данного элемента:

>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>

Разбор XML с именованными пространствами

Если входной XML содержит именованные пространства, теги и атрибуты с префиксами в форме prefix:sometag преобразуются в {uri}sometag , где префикс заменяется полным URI. Кроме того, если существует пространство имён по умолчанию, этот полный URI добавляется ко всем тегам без префикса.

Вот пример XML, который включает два именованных пространства, одно с префиксом «fictional», а другое используется как пространство имён по умолчанию:

<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
        xmlns="http://people.example.com">
    <actor>
        <name>John Cleese</name>
        <fictional:character>Lancelot</fictional:character>
        <fictional:character>Archie Leach</fictional:character>
    </actor>
    <actor>
        <name>Eric Idle</name>
        <fictional:character>Sir Robin</fictional:character>
        <fictional:character>Gunther</fictional:character>
        <fictional:character>Commander Clement</fictional:character>
    </actor>
</actors>

Один из способов поиска и изучения этого примера XML — вручную добавить URI к каждому тегу или атрибуту в выражении XPath для find() или findall():

root = fromstring(xml_text)
for actor in root.findall('{http://people.example.com}actor'):
    name = actor.find('{http://people.example.com}name')
    print(name.text)
    for char in actor.findall('{http://characters.example.com}character'):
        print(' |-->', char.text)

Более удобный способ поиска в примере XML с именованными пространствами — создать словарь со своими префиксами и использовать их в функциях поиска:

ns = {'real_person': 'http://people.example.com',
      'role': 'http://characters.example.com'}

for actor in root.findall('real_person:actor', ns):
    name = actor.find('real_person:name', ns)
    print(name.text)
    for char in actor.findall('role:character', ns):
        print(' |-->', char.text)

Оба этих подхода возвращают:

John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement

Дополнительные ресурсы

См. http://effbot.org/zone/element-index.htm для учебных материалов и ссылок на другие документы.

Поддержка XPath

Этот модуль предоставляет ограниченную поддержку выражений XPath для поиска элементов в дереве. Цель — поддерживать небольшой подмножество сокращенной синтаксической конструкции; полный движок XPath выходит за рамки модуля.

Пример

Вот пример, демонстрирующий некоторые возможности XPath модуля. Мы будем использовать countrydata документ XML из раздела Парсинг XML:

import xml.etree.ElementTree as ET

root = ET.fromstring(countrydata)

# Top-level elements
root.findall(".")

# All 'neighbor' grand-children of 'country' children of the top-level
# elements
root.findall("./country/neighbor")

# Nodes with name='Singapore' that have a 'year' child
root.findall(".//year/..[@name='Singapore']")

# 'year' nodes that are children of nodes with name='Singapore'
root.findall(".//*[@name='Singapore']/year")

# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")

Поддерживаемый синтаксис XPath

Предикаты (выражения в квадратных скобках) должны предшествовать имени тега, звездочке или другому предикату. position предикаты должны предшествовать имени тега.

Справочник

Функции

xml.etree.ElementTree.Comment(text=None)

Фабрика элементов комментариев. Эта функция-фабрика создает специальный элемент, который будет сериализован как XML-комментарий стандартным сериализатором. Строка комментария может быть строкой байтов или строкой Юникода. text — строка, содержащая строку комментария. Возвращает экземпляр элемента, представляющего комментарий.

Обратите внимание, что XMLParser пропускает комментарии ввода вместо создания для них объектов комментариев. ElementTree будет содержать узлы комментариев только в том случае, если они были вставлены в дерево с помощью одного из методов Element.

xml.etree.ElementTree.dump(elem)

Выводит дерево элементов или структуру элементов в sys.stdout. Эта функция должна использоваться только для отладки.

Точный формат вывода зависит от реализации. В этой версии он выводится как обычный XML-файл.

elem — это дерево элементов или отдельный элемент.

xml.etree.ElementTree.fromstring(text, parser=None)

Парсит XML-раздел из строковой константы. То же самое, что и XML(). text — строка, содержащая XML-данные. parser — необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор XMLParser. Возвращает экземпляр Element.

xml.etree.ElementTree.fromstringlist(sequence, parser=None)

Парсит XML-документ из последовательности фрагментов строк. sequence — список или другая последовательность, содержащая фрагменты XML-данных. parser — необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор XMLParser. Возвращает экземпляр Element.

Добавлена в версии 3.2.

xml.etree.ElementTree.iselement(element)

Проверяет, является ли объект допустимым объектом элемента. element — экземпляр элемента. Возвращает True , если это объект элемента.

xml.etree.ElementTree.iterparse(source, events=None, parser=None)

Постепенно парсит XML-раздел в дерево элементов и сообщает пользователю, что происходит. source — имя файла или объект файла, содержащий XML-данные. events — последовательность событий, которые нужно сообщить обратно. Поддерживаемые события — строки "start", "end", "start-ns" и "end-ns" (события «ns» используются для получения подробной информации о пространствах имен). Если events опущено, сообщаются только события "end". parser — необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор XMLParser. parser должен быть подклассом XMLParser и может использовать только целевой TreeBuilder. Возвращает итератор, предоставляющий пары (event, elem).

Обратите внимание, что, хотя iterparse() строит дерево по частям, он выполняет блокирующие чтения на source (или файле, который он называет). Таким образом, он не подходит для приложений, где блокирующие чтения выполнить нельзя. Для полностью асинхронного парсинга см. XMLPullParser.

Примечание

iterparse() гарантирует, что он увидел символ «>» начального тега при выводе события «start», поэтому атрибуты определены, но содержимое атрибутов text и tail не определено в этот момент. То же самое относится к дочерним элементам; они могут или не могут быть присутствовать.

Если вам нужен полностью заполненный элемент, ищите события «end» вместо этого.

Устарело начиная с версии 3.4: Аргумент parser.

xml.etree.ElementTree.parse(source, parser=None)

Парсит XML-раздел в дерево элементов. source — имя файла или объект файла, содержащий XML-данные. parser — необязательный экземпляр анализатора. Если не указан, используется стандартный анализатор XMLParser. Возвращает экземпляр ElementTree.

xml.etree.ElementTree.ProcessingInstruction(target, text=None)

Фабрика элементов PI. Эта функция-фабрика создаёт специальный элемент, который будет сериализован как инструкция обработки XML. target — строка, содержащая цель PI. text — строка, содержащая содержимое PI, если задано. Возвращает экземпляр элемента, представляющий инструкцию обработки.

Обратите внимание, что XMLParser пропускает инструкции обработки ввода вместо создания для них объектов комментариев. ElementTree будет содержать узлы инструкций обработки только в том случае, если они были вставлены в дерево с помощью одного из методов Element.

xml.etree.ElementTree.register_namespace(prefix, uri)

Регистрирует префикс пространства имён. Регистр глобальный, и любая существующая сопоставление для заданного префикса или URI пространства имён будет удалено. prefix — префикс пространства имён. uri — URI пространства имён. Теги и атрибуты в этом пространстве имён будут сериализованы с заданным префиксом, если это возможно.

Новое в версии 3.2.

xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)

Фабрика дочерних элементов. Эта функция создаёт экземпляр элемента и добавляет его в существующий элемент.

Имя элемента, имена атрибутов и значения атрибутов могут быть либо строками байтов, либо строками Юникода. parent — родительский элемент. tag — имя дочернего элемента. attrib — необязательный словарь, содержащий атрибуты элемента. extra содержит дополнительные атрибуты, заданные в качестве ключевых аргументов. Возвращает экземпляр элемента.

xml.etree.ElementTree.tostring(element, encoding="us-ascii", method="xml", *, short_empty_elements=True)

Генерирует строковое представление XML-элемента, включая все дочерние элементы. element — экземпляр Element. encoding 1 — кодировка вывода (по умолчанию — US-ASCII). Используйте encoding="unicode" для генерации строки Юникода (в противном случае генерируется строка байтов). method — либо "xml", "html" или "text" (по умолчанию "xml"). short_empty_elements имеет то же значение, что и в ElementTree.write(). Возвращает (необязательно) закодированную строку, содержащую XML-данные.

Новое в версии 3.4: Параметр short_empty_elements.

xml.etree.ElementTree.tostringlist(element, encoding="us-ascii", method="xml", *, short_empty_elements=True)

Генерирует строковое представление XML-элемента, включая все дочерние элементы. element — экземпляр Element. encoding 1 — кодировка вывода (по умолчанию — US-ASCII). Используйте encoding="unicode" для генерации строки Юникода (в противном случае генерируется строка байтов). method — либо "xml", "html" или "text" (по умолчанию "xml"). short_empty_elements имеет то же значение, что и в ElementTree.write(). Возвращает список (необязательно) закодированных строк, содержащих XML-данные. Он не гарантирует какой-либо конкретной последовательности, за исключением того, что b"".join(tostringlist(element)) == tostring(element).

Новое в версии 3.2.

Новое в версии 3.4: Параметр short_empty_elements.

xml.etree.ElementTree.XML(text, parser=None)

Парсит раздел XML из константы строки. Эту функцию можно использовать для вставки «литералов XML» в код Python. text — строка, содержащая XML-данные. parser — необязательный экземпляр парсера. Если не задан, используется стандартный парсер XMLParser. Возвращает экземпляр Element.

xml.etree.ElementTree.XMLID(text, parser=None)

Парсит раздел XML из константы строки и также возвращает словарь, который отображает id элементов к элементам. text — строка, содержащая XML-данные. parser — необязательный экземпляр парсера. Если не задан, используется стандартный парсер XMLParser. Возвращает кортеж, содержащий экземпляр Element и словарь.

Поддержка XInclude

Этот модуль предоставляет ограниченную поддержку директив XInclude через модуль-помощник xml.etree.ElementInclude. Этот модуль можно использовать для вставки поддеревьев и строковых данных в деревья элементов на основе информации в дереве.

Пример

Вот пример, демонстрирующий использование модуля XInclude. Для включения XML-документа в текущий документ используйте элемент {http://www.w3.org/2001/XInclude}include и установите атрибут parse в "xml", а атрибут href — для указания документа для включения.

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>

По умолчанию атрибут href обрабатывается как имя файла. Вы можете использовать пользовательские загрузчики для переопределения этого поведения. Также обратите внимание, что стандартный помощник не поддерживает синтаксис XPointer.

Для обработки этого файла загрузите его обычным образом и передайте корневой элемент модулю xml.etree.ElementTree:

from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)

Модуль ElementInclude заменяет элемент {http://www.w3.org/2001/XInclude}include корневым элементом из документа source.xml. Результат может выглядеть примерно так:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>This is a paragraph.</para>
</document>

Если атрибут parse опущен, он по умолчанию равен «xml». Атрибут href обязателен.

Для включения текстового документа используйте элемент {http://www.w3.org/2001/XInclude}include и установите атрибут parse в «text»:

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>

Результат может выглядеть примерно так:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) 2003.
</document>

Справочник

Функции

xml.etree.ElementInclude.default_loader(href, parse, encoding=None)

Загрузчик по умолчанию. Этот загрузчик по умолчанию считывает включённый ресурс с диска. href — URL. parse — для режима парсинга либо «xml», либо «text». encoding — необязательная кодировка текста. Если не задана, кодировка — utf-8. Возвращает расширенный ресурс. Если режим парсинга "xml", это экземпляр ElementTree. Если режим парсинга «text», это строка Юникода. Если загрузчик терпит неудачу, он может вернуть None или вызвать исключение.

xml.etree.ElementInclude.include(elem, loader=None)

Эта функция расширяет директивы XInclude. elem — корневой элемент. loader — необязательный загрузчик ресурсов. Если опущен, по умолчанию используется default_loader(). Если задан, он должен быть вызываемым объектом, реализующим тот же интерфейс, что и default_loader(). Возвращает расширенный ресурс. Если режим парсинга "xml", это экземпляр ElementTree. Если режим парсинга «text», это строка Юникода. Если загрузчик терпит неудачу, он может вернуть None или вызвать исключение.

Объекты элементов

class xml.etree.ElementTree.Element(tag, attrib={}, **extra)

Класс элементов. Этот класс определяет интерфейс элемента и предоставляет реализацию этого интерфейса по умолчанию.

Имя элемента, имена атрибутов и значения атрибутов могут быть строками байтов или строками Unicode. tag — это имя элемента. attrib — это необязательный словарь, содержащий атрибуты элемента. extra содержит дополнительные атрибуты, заданные в качестве ключевых аргументов.

tag

Строка, идентифицирующая, какой тип данных представляет этот элемент (другими словами, тип элемента).

text

tail

Эти атрибуты могут использоваться для хранения дополнительных данных, связанных с элементом. Их значения обычно являются строками, но могут быть любыми объектами, специфичными для приложения. Если элемент создан из XML-файла, атрибут text содержит либо текст между открывающим тегом элемента и его первым дочерним элементом или закрывающим тегом, либо None, а атрибут tail содержит либо текст между закрывающим тегом элемента и следующим тегом, либо None. Для XML-данных

<a><b>1<c>2<d/>3</c></b>4</a>

элемент a имеет None для атрибутов text и tail, элемент b имеет text "1" и tail "4", элемент c имеет text "2" и tail None, а элемент d имеет text None и tail "3".

Чтобы собрать внутренний текст элемента, см. itertext(), например "".join(element.itertext()).

Приложения могут хранить произвольные объекты в этих атрибутах.

attrib

Словарь, содержащий атрибуты элемента. Обратите внимание, что хотя значение attrib всегда является реальным изменяемым словарем Python, реализация ElementTree может выбрать другую внутреннюю структуру представления и создать словарь только в случае запроса. Чтобы воспользоваться такими реализациями, используйте методы словаря, когда это возможно.

Следующие методы, подобные методам словаря, работают с атрибутами элемента.

clear()

Сбрасывает элемент. Эта функция удаляет все дочерние элементы, очищает все атрибуты и устанавливает атрибуты text и tail в None.

get(key, default=None)

Получает атрибут элемента с именем key.

Возвращает значение атрибута или default, если атрибут не найден.

items()

Возвращает атрибуты элемента как последовательность пар (имя, значение). Атрибуты возвращаются в произвольном порядке.

keys()

Возвращает имена атрибутов элементов в виде списка. Имена возвращаются в произвольном порядке.

set(key, value)

Устанавливает атрибут key элемента в value.

Следующие методы работают с дочерними элементами (подэлементами).

append(subelement)

Добавляет элемент subelement в конец внутреннего списка дочерних элементов этого элемента. Возбуждает TypeError, если subelement не является Element.

extend(subelements)

Добавляет subelements из последовательности объектов с нулем или более элементами. Возбуждает TypeError, если подэлемент не является Element.

Добавлен в версии 3.2.

find(match, namespaces=None)

Ищет первый подэлемент, соответствующий match. match может быть именем тега или путем. Возвращает экземпляр элемента или None. namespaces — это необязательное отображение от префикса пространства имен к полному имени.

findall(match, namespaces=None)

Ищет все соответствующие подэлементы по имени тега или пути. Возвращает список, содержащий все соответствующие элементы в порядке документа. namespaces — это необязательное отображение от префикса пространства имен к полному имени.

findtext(match, default=None, namespaces=None)

Ищет текст для первого подэлемента, соответствующего match. match может быть именем тега или путем. Возвращает текстовое содержимое первого соответствующего элемента или default, если элемент не найден. Обратите внимание, что если у соответствующего элемента нет текстового содержимого, возвращается пустая строка. namespaces — это необязательное отображение от префикса пространства имен к полному имени.

getchildren()

Устаревшее начиная с версии 3.2: Используйте list(elem) или итерацию.

getiterator(tag=None)

Устаревшее начиная с версии 3.2: Используйте метод Element.iter() вместо этого.

insert(index, subelement)

Вставляет subelement в заданную позицию в этом элементе. Возбуждает TypeError, если subelement не является Element.

iter(tag=None)

Создает итератор дерева итератор с текущим элементом в качестве корня. Итератор перебирает этот элемент и все элементы ниже него в порядке документа (поиск в глубину). Если tag не является None или '*', из итератора возвращаются только элементы, чья метка равна tag. Если структура дерева изменяется во время итерации, результат неопределён.

Добавлен в версии 3.2.

iterfind(match, namespaces=None)

Ищет все соответствующие подэлементы по имени тега или пути. Возвращает итерируемый объект, возвращающий все соответствующие элементы в порядке документа. namespaces — это необязательное отображение от префикса пространства имен к полному имени.

Добавлен в версии 3.2.

itertext()

Создаёт итератор текста. Итератор перебирает этот элемент и все подэлементы в порядке документа и возвращает весь внутренний текст.

Добавлен в версии 3.2.

makeelement(tag, attrib)

Создаёт новый объект элемента того же типа, что и этот элемент. Не вызывайте этот метод, используйте функцию-фабрику SubElement() вместо этого.

remove(subelement)

Удаляет subelement из элемента. В отличие от методов find*, этот метод сравнивает элементы по идентичности экземпляра, а не по значению тега или содержимому.

Element объекты также поддерживают следующие методы типа последовательности для работы с подэлементами: __delitem__(), __getitem__(), __setitem__(), __len__().

Предупреждение: Элементы без подэлементов будут проверены как False. Это поведение изменится в будущих версиях. Используйте специальные len(elem) или elem is None тесты вместо этого.

element = root.find('foo')

if not element:  # careful!
    print("element not found, or element has no subelements")

if element is None:
    print("element not found")

Объекты ElementTree

class xml.etree.ElementTree.ElementTree(element=None, file=None)

Класс-обёртка ElementTree. Этот класс представляет собой всю иерархию элементов и добавляет дополнительную поддержку сериализации в стандартный XML и из него.

element — корневой элемент. Дерево инициализируется содержимым XML-файла, если он задан.

_setroot(element)

Заменяет корневой элемент для этого дерева. Это отбрасывает текущее содержимое дерева и заменяет его заданным элементом. Используйте с осторожностью. element — экземпляр элемента.

find(match, namespaces=None)

То же, что и Element.find(), начиная с корня дерева.

findall(match, namespaces=None)

То же, что и Element.findall(), начиная с корня дерева.

findtext(match, default=None, namespaces=None)

То же, что и Element.findtext(), начиная с корня дерева.

getiterator(tag=None)

Устарело начиная с версии 3.2: Используйте метод ElementTree.iter() вместо него.

getroot()

Возвращает корневой элемент для этого дерева.

iter(tag=None)

Создаёт и возвращает итератор дерева для корневого элемента. Итератор проходит по всем элементам в этом дереве в порядке секции. tag — тег для поиска (по умолчанию возвращает все элементы).

iterfind(match, namespaces=None)

То же, что и Element.iterfind(), начиная с корня дерева.

Добавлена в версии 3.2.

parse(source, parser=None)

Загружает внешний XML фрагмент в это дерево элементов. source — имя файла или объект файла. parser — необязательный экземпляр парсера. Если не указан, используется стандартный парсер XMLParser. Возвращает корневой элемент фрагмента.

write(file, encoding="us-ascii", xml_declaration=None, default_namespace=None, method="xml", *, short_empty_elements=True)

Записывает дерево элементов в файл в формате XML. file — имя файла или объект файла, открытый для записи. encoding 1 — кодировка вывода (по умолчанию US-ASCII). xml_declaration управляет добавлением объявления XML в файл. Используйте False для никогда, True для всегда, None только если не US-ASCII или UTF-8 или Unicode (по умолчанию None). default_namespace задаёт стандартное XML пространство имён (для “xmlns”). method — либо "xml", "html" или "text" (по умолчанию "xml"). Параметр short_empty_elements (только ключевое слово) управляет форматированием элементов, не содержащих содержимого. Если True (по умолчанию), они выводятся как один самозакрывающийся тег, в противном случае они выводятся как пара открывающего/закрывающего тегов.

Вывод — либо строка (str) или двоичные данные (bytes). Это контролируется аргументом encoding. Если encoding — "unicode", вывод — строка; в противном случае — двоичные данные. Обратите внимание, что это может конфликтовать с типом file, если это открытый объект файла; убедитесь, что вы не пытаетесь записать строку в двоичный поток и наоборот.

Добавлена в версии 3.4: Параметр short_empty_elements.

Это XML-файл, который будет обрабатываться:

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>Moved to <a href="http://example.org/">example.org</a>
        or <a href="http://example.com/">example.com</a>.</p>
    </body>
</html>

Пример изменения атрибута “target” каждого ссылки в первом абзаце:

>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a"))   # Returns list of all links
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links:             # Iterates through all found links
...     i.attrib["target"] = "blank"
>>> tree.write("output.xhtml")

Объекты QName

class xml.etree.ElementTree.QName(text_or_uri, tag=None)

Обёртка QName. Это можно использовать для обёртки значения атрибута QName, чтобы получить правильную обработку пространства имён при выводе. text_or_uri — строка, содержащая значение QName в форме {uri}local или, если задан аргумент tag, часть URI QName. Если задан tag, первый аргумент интерпретируется как URI, а этот аргумент интерпретируется как локальное имя. Экземпляры QName являются непрозрачными.

Объекты TreeBuilder

class xml.etree.ElementTree.TreeBuilder(element_factory=None)

Универсальный конструктор структуры элементов. Этот конструктор преобразует последовательность вызовов start, data и end в правильно сформированную структуру элементов. Вы можете использовать этот класс для построения структуры элементов с помощью пользовательского XML-парсера или парсера для другого формата, похожего на XML. element_factory, если задан, должен быть вызываемым объектом, принимающим два позиционных аргумента: тег и словарь атрибутов. Ожидается, что он вернёт новый экземпляр элемента.

close()

Очищает буферы конструктора и возвращает корневой элемент документа. Возвращает экземпляр Element.

data(data)

Добавляет текст к текущему элементу. data — строка. Это должна быть либо строка байтов, либо строка Unicode.

end(tag)

Закрывает текущий элемент. tag — имя элемента. Возвращает закрытый элемент.

start(tag, attrs)

Открывает новый элемент. tag — имя элемента. attrs — словарь, содержащий атрибуты элемента. Возвращает открытый элемент.

Кроме того, пользовательский объект TreeBuilder может предоставить следующий метод:

doctype(name, pubid, system)

Обрабатывает объявление типа документа. name — имя типа документа. pubid — общественный идентификатор. system — системный идентификатор. Этот метод не существует в стандартном классе TreeBuilder.

Добавлена в версии 3.2.

Объекты XMLParser

class xml.etree.ElementTree.XMLParser(html=0, target=None, encoding=None)

Этот класс является базовым строительным блоком модуля. Он использует xml.parsers.expat для эффективного событийно-ориентированного разбора XML. К нему можно передавать данные XML по частям с помощью метода feed(), а события разбора преобразуются в API обратного вызова, вызывая обратные вызовы на объекте target. Если target опущен, используется стандартный TreeBuilder. Аргумент html исторически использовался для обратной совместимости и теперь устарел. Если указано encoding 1, значение переопределяет кодировку, указанную в файле XML.

Устарело начиная с версии 3.4: Аргумент html. Остальные аргументы должны передаваться через ключевые слова, чтобы подготовиться к удалению аргумента html.

close()

Завершает подачу данных в парсер. Возвращает результат вызова метода close() объекта target, переданного во время создания; по умолчанию, это корневой элемент документа.

doctype(name, pubid, system)

Устарело начиная с версии 3.2: Определите метод TreeBuilder.doctype() в целевом объекте TreeBuilder.

feed(data)

Передает данные в парсер. data — закодированные данные.

XMLParser.feed() вызывает метод target start(tag, attrs_dict) для каждого открывающего тега, метод end(tag) для каждого закрывающего тега, и данные обрабатываются методом data(data). XMLParser.close() вызывает метод target close(). XMLParser может использоваться не только для построения структуры дерева. Это пример подсчета максимальной глубины XML-файла:

>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth:                     # The target object of the parser
...     maxDepth = 0
...     depth = 0
...     def start(self, tag, attrib):   # Called for each opening tag.
...         self.depth += 1
...         if self.depth > self.maxDepth:
...             self.maxDepth = self.depth
...     def end(self, tag):             # Called for each closing tag.
...         self.depth -= 1
...     def data(self, data):
...         pass            # We do not need to do anything with data.
...     def close(self):    # Called when all data has been parsed.
...         return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
...   <b>
...   </b>
...   <b>
...     <c>
...       <d>
...       </d>
...     </c>
...   </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4

Объекты XMLPullParser

class xml.etree.ElementTree.XMLPullParser(events=None)

Парсер pull, подходящий для задач, не требующих блокировки. Его API со стороны ввода похож на API XMLParser, но вместо того, чтобы передавать вызовы в целевой объект обратного вызова, XMLPullParser собирает внутренний список событий разбора и позволяет пользователю читать из него. events — последовательность событий, которые должны быть возвращены. Поддерживаемые события — это строки "start", "end", "start-ns" и "end-ns" (события «ns» используются для получения подробной информации о пространствах имен). Если events опущено, сообщаются только события "end".

feed(data)

Передать данные в парсер.

close()

Сигнализировать парсеру о том, что поток данных завершен. В отличие от XMLParser.close(), этот метод всегда возвращает None. Любые события, которые ещё не были получены, когда парсер закрывается, всё ещё могут быть прочитаны с помощью read_events().

read_events()

Возвращает итератор по событиям, которые были встречены в данных, переданных в парсер. Итератор возвращает пары (event, elem), где event — строка, представляющая тип события (например, "end"), а elem — встреченный объект Element.

События, предоставленные в предыдущем вызове read_events(), больше не будут возвращены. События потребляются из внутренней очереди только при получении из итератора, поэтому несколько читателей, проходящих по итераторам, полученным из read_events() параллельно, приведут к непредсказуемым результатам.

Примечание

XMLPullParser гарантирует, что он видел символ «>» стартового тега, когда отправляет событие «start», поэтому атрибуты определены, но содержимое атрибутов text и tail в этот момент неопределено. То же самое относится к дочерним элементам; они могут или могут не присутствовать.

Если вам нужен полностью заполненный элемент, ищите события «end» вместо этого.

Добавлен в версии 3.4.

Исключения

class xml.etree.ElementTree.ParseError

Ошибка разбора XML, генерируемая различными методами разбора в этом модуле при неудачном разборе. Строковое представление экземпляра этого исключения будет содержать понятное сообщение об ошибке. Кроме того, будут доступны следующие атрибуты:

code

Числовой код ошибки от парсера expat. См. документацию xml.parsers.expat для списка кодов ошибок и их значений.

position

Кортеж строка, столбец, указывающий, где произошла ошибка.

Сноски

1(1,2,3,4)

Строка кодировки, включенная в выходные данные XML, должна соответствовать соответствующим стандартам. Например, «UTF-8» допустимо, но «UTF8» нет. См. https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl и https://www.iana.org/assignments/character-sets/character-sets.xhtml.