xml.etree.ElementTree — API ElementTree для XML

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

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

1. Руководство

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

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

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

1.2. Парсинг 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'

1.3. API Pull для неблокирующего парсинга

Большинство функций парсинга, предоставляемых этим модулем, требуют, чтобы весь документ был прочитан за один раз, прежде чем вернуть любой результат. Возможна передача данных в 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-документ и не хотите загружать его полностью в память.

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

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.

1.5. Изменение 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>

1.6. Создание 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>

1.7. Парсинг 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

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

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

2. Поддержка XPath

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

2.1. Пример

Вот пример, который демонстрирует некоторые возможности XPath-модуля. Мы будем использовать документ XML countrydata из раздела Разбор 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]")

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

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

3. Справочник

3.1. Функции

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)

Разбирает фрагмент XML из строковой константы. То же самое, что XML(). text — строка, содержащая XML-данные. Возвращает экземпляр 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)

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

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

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

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

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

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

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

Имя элемента, имена атрибутов и значения атрибутов могут быть строками байтов или строками Unicode. 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" для генерации строки 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" для генерации строки 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 из строковой константы и также возвращает словарь, который сопоставляет идентификаторы элементов с самими элементами. text — строка, содержащая XML-данные. parser — необязательный экземпляр парсера. Если не указан, используется стандартный парсер XMLParser. Возвращает кортеж, содержащий экземпляр Element и словарь.

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

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

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

Имя элемента, имена атрибутов и значения атрибутов могут быть либо строками байтов, либо строками Юникода. 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")

3.3. Объекты 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")

3.4. Объекты 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 непрозрачны.

3.5. Объекты 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.

3.6. Объекты 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

3.7. Объекты XMLPullParser

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

Парсер с вытягиванием данных, подходящий для неблокирующих приложений. Его входной 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.

3.8. Исключения

class xml.etree.ElementTree.ParseError

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

code

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

position

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

Сноски