20.5. xml.etree.ElementTree – API ElementTree XML¶xml.etree.ElementTree – The ElementTree XML API

20.5.1.1. XML-дерево и элементы¶XML tree and elements

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

20.5.1.2. Разбор XML¶Parsing 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. Pull API для неблокирующего разбора¶Pull API for non-blocking parsing

Большинство функций разбора, предоставляемых этим модулем, требуют чтения всего документа целиком перед возвратом какого-либо результата. Можно использовать XMLParser и передавать в него данные по частям, но это push-API, которое вызывает методы на цель-колбэк, что слишком низкоуровнево и неудобно для большинства задач. Иногда пользователь действительно хочет иметь возможность разбирать 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. Поиск интересующих элементов¶Finding interesting elements

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-файла¶Modifying an XML File

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

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

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

>>> 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-документов¶Building XML documents

Функция 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 с пространствами имён¶Parsing XML with Namespaces

Если 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. Дополнительные ресурсы¶Additional resources

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

20.5.2.1. Пример¶Example

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

import xml.etree.ElementTree as ET

root = ET.fromstring(countrydata)

# Элементы верхнего уровня
root.findall(".")

# Все элементы 'neighbor', являющиеся внуками дочерних элементов 'country' верхнего уровня
# элементы
root.findall("./country/neighbor")

# Узлы с name='Singapore', имеющие дочерний элемент 'year'
root.findall(".//year/..[@name='Singapore']")

# Элементы 'year', являющиеся дочерними для узлов с name='Singapore'
root.findall(".//*[@name='Singapore']/year")

# Все элементы 'neighbor', являющиеся вторым дочерним элементом своего родителя
root.findall(".//neighbor[2]")

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

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

20.5.3.1. Функции¶Functions

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

Фабрика элементов Comment. Эта фабричная функция создаёт специальный элемент, который будет сериализован как XML-комментарий стандартным сериализатором. Строка комментария может быть как байтовой строкой, так и строкой Unicode. 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)¶

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

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

20.5.3.2. Объекты Element¶Element Objects

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

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

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

Находит все подходящие подэлементы по имени тега или path. Возвращает итерируемый объект, выдающий все подходящие элементы в порядке документа. 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:  # осторожно!
    print("element not found, or element has no subelements")

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

20.5.3.3. Объекты ElementTree¶ElementTree Objects

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")     # Находит первое вхождение тега p в body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a"))   # Возвращает список всех ссылок
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links:             # Перебирает все найденные ссылки
...     i.attrib["target"] = "blank"
>>> tree.write("output.xhtml")

20.5.3.4. Объекты QName¶QName Objects

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¶TreeBuilder Objects

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.

20.5.3.6. Объекты XMLParser¶XMLParser Objects

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

Этот класс является низкоуровневым строительным блоком модуля. Он использует xml.parsers.expat для эффективного, событийно-ориентированного разбора XML. Данные XML можно передавать ему по частям с помощью метода feed(), и события разбора преобразуются в push-интерфейс (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() вызывает метод start(tag, attrs_dict) объекта target для каждого открывающего тега, его метод end(tag) – для каждого закрывающего тега, а данные обрабатываются методом data(data). XMLParser.close() вызывает метод close() объекта target. XMLParser можно использовать не только для построения древовидной структуры. Ниже приведен пример подсчета максимальной глубины XML-файла:

>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth:                     # Целевой объект парсера
...     maxDepth = 0
...     depth = 0
...     def start(self, tag, attrib):   # Вызывается для каждого открывающего тега.
...         self.depth += 1
...         if self.depth > self.maxDepth:
...             self.maxDepth = self.depth
...     def end(self, tag):             # Вызывается для каждого закрывающего тега.
...         self.depth -= 1
...     def data(self, data):
...         pass            # С данными ничего делать не нужно.
...     def close(self):    # Вызывается, когда все данные проанализированы.
...         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¶XMLPullParser Objects

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. Исключения¶Exceptions

class xml.etree.ElementTree.ParseError¶

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

code¶

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

position¶

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

Сноски