20.5. xml.etree.ElementTree – XML-интерфейс ElementTree¶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 к элементу ранга:

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

Добавляет подэлементы из последовательности с нулём или более элементов. Возбуждает 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)¶

Обрабатывает объявление doctype. name – имя doctype. 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() цели, переданной при создании; по умолчанию это корневой элемент документа.

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, указывающий, где произошла ошибка.

Сноски