xml.etree.ElementTree — API XML ElementTree

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

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

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

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

20.5.1.1. Дерево XML и элементы

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

20.5.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'

20.5.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-документ и не хотите хранить его полностью в памяти.

20.5.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.

20.5.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>

20.5.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>

20.5.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

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

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

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

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

20.5.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]")

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

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

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

20.5.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 — экземпляр элемента. Возвращает истинное значение, если это объект элемента.

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

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

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")

20.5.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")

20.5.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 являются непрозрачными.

20.5.3.5. Объекты TreeBuilder

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

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

close()

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

data(data)

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

end(tag)

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

start(tag, attrs)

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

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

doctype(name, pubid, system)

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

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

20.5.3.6. Объекты XMLParser

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

Этот класс является базовым строительным блоком модуля. Он использует xml.parsers.expat для эффективного событийно-ориентированного разбора XML. Данные XML можно подавать по частям с помощью метода feed(), а события разбора переводятся в API с push-поддержкой — вызывая обратные вызовы на объекте 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

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

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

class xml.etree.ElementTree.ParseError

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

code

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

position

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

Сноски

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.