xml.etree.ElementTree — XML-API ElementTree¶

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

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

Синтаксический анализ XML¶

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

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

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

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

Или непосредственно из строки:

root = ET.fromstring(country_data_as_string)

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

Как Element, root содержит тег и словарь атрибутов:

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

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

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

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

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

Извлекаемый API для неблокирующего синтаксического анализа¶

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

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

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

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

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

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

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

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

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

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

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

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

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

Допустим, мы хотим добавить по одному к рейтингу каждой страны и добавить атрибут updated к элементу 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'):
...     # using root.findall() to avoid removal during traversal
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

Обратите внимание, что одновременное изменение во время итерации может привести к проблемам, точно так же, как при итерации и изменении списков Python или dicts. Поэтому в примере сначала собираются все совпадающие элементы с root.findall(), и только затем выполняется итерация по списку совпадений.

Теперь наш XML-файл выглядит следующим образом:

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

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

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

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

Синтаксический анализ XML с использованием пространств имен¶

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

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

<?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

Пример¶

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

Для XML с пространствами имен используйте обычную квалифицированную нотацию {namespace}tag:

# All dublin-core "title" tags in the document
root.findall(".//{http://purl.org/dc/elements/1.1/}title")

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

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

Функции¶

xml.etree.ElementTree.canonicalize(xml_data=None, *, out=None, from_file=None, **options)¶

C14N 2.0 функция преобразования.

Канонизация - это способ нормализовать вывод XML таким образом, чтобы было возможно побайтовое сравнение и использование цифровых подписей. Это уменьшило свободу, которой обладают XMLserializers, и вместо этого создало более ограниченное представление XML. Основные ограничения касаются размещения объявлений пространств имен, упорядочения атрибутов и игнорируемых пробелов.

Эта функция принимает строку данных XML (xml_data) или путь к файлу или файлоподобный объект (from_file) в качестве входных данных, преобразует их в каноническую форму и записывает с помощью объекта out file(-подобный), если он предусмотрен, или возвращает в виде текстовая строка, если нет. Выходной файл содержит текст, а не байты. Поэтому его следует открывать в текстовом режиме с кодировкой utf-8.

Типичные области применения:

xml_data = "<root>...</root>"
print(canonicalize(xml_data))

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(xml_data, out=out_file)

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(from_file="inputfile.xml", out=out_file)

Параметры конфигурации следующие:

• with_comments: установлено значение true для включения комментариев (по умолчанию: false)

• strip_text: установите значение true, чтобы убрать пробелы до и после текстового содержимого.

  (по умолчанию: false)

• rewrite_prefixes: установите значение true, чтобы заменить префиксы пространства имен на «n{число}».

  (по умолчанию: false)

• qname_aware_tags: набор имен тегов, поддерживающих qname, в которых префиксы

  должно быть заменено в текстовом содержимом (по умолчанию: пустое)

• qname_aware_attrs: набор имен атрибутов qnameaware, в которых префиксы

  должно быть заменено в текстовом содержимом (по умолчанию: пустое)

• exclude_attrs: набор имен атрибутов, которые не должны быть сериализованы

• exclude_tags: набор имен тегов, которые не должны быть сериализованы

В приведенном выше списке опций «набор» относится к любой коллекции или повторяемым строкам, упорядочение которых не ожидается.

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

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

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

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

xml.etree.ElementTree.dump(elem)¶

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

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

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

Изменено в версии 3.8: Функция dump() теперь сохраняет порядок атрибутов, указанный пользователем.

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

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

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

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

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

xml.etree.ElementTree.indent(tree, space='  ', level=0)¶

Добавляет пробелы к поддереву для визуального выделения отступов в дереве. Это может быть использовано для создания вывода в формате XML с красивым шрифтом. tree может быть элементом или ElementTree. пробел - это строка с пробелами, которая будет вставляться для каждого уровня отступа, по умолчанию два символа пробела. Для отступления частичных поддеревьев внутри уже имеющегося дерева с отступом укажите начальный уровень отступа как level.

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

xml.etree.ElementTree.iselement(element)¶

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

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

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

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

Примечание

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

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

Не рекомендуется, начиная с версии 3.4: Аргумент parser.

Изменено в версии 3.8: Были добавлены события comment и pi.

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

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

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

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

Обратите внимание, что XMLParser пропускает команды обработки во входных данных вместо создания для них PI-объектов. 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', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)¶

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

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

Изменено в версии 3.8: Добавлены параметры xml_declaration и default_namespace.

Изменено в версии 3.8: Функция tostring() теперь сохраняет порядок атрибутов, указанный пользователем.

xml.etree.ElementTree.tostringlist(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)¶

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

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

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

Изменено в версии 3.8: Добавлены параметры xml_declaration и default_namespace.

Изменено в версии 3.8: Функция tostringlist() теперь сохраняет порядок атрибутов, указанный пользователем.

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

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

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

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

Пример¶

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

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

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

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

from xml.etree import ElementTree, ElementInclude

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

ElementInclude.include(root)

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

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

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

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

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

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

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

Функции¶

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

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

xml.etree.ElementInclude.include(elem, loader=None, base_url=None, max_depth=6)¶

Эта функция расширяет директивы Include. elem - это корневой элемент. loader - необязательный загрузчик ресурсов. Если он опущен, по умолчанию используется значение default_loader(). Если указано, то это должен быть вызываемый объект, который реализует тот же интерфейс, что и default_loader(). base_url - базовый URL исходного файла, для разрешения относительных ссылок на включаемые файлы. max_depth - максимальное количество рекурсивных включений. Ограничено для снижения риска распространения вредоносного контента. Укажите отрицательное значение, чтобы отключить ограничение.

Возвращает расширенный ресурс. Если режим синтаксического анализа "xml", то это экземпляр ElementTree. Если режим синтаксического анализа «текст», то это строка в Юникоде. Если загрузчик завершается ошибкой, он может вернуть значение None или вызвать исключение.

Изменено в версии 3.9: Добавлены параметры base_url и max_depth.

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

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

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

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

tag¶

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

text¶

tail¶

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

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

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

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

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

attrib¶

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

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

clear()¶

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

get(key, default=None)¶

Возвращает атрибут элемента с именем key.

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

items()¶

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

keys()¶

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

set(key, value)¶

Установите для атрибута key элемента значение value.

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

append(subelement)¶

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

extend(subelements)¶

Добавляет подэлементы из объекта последовательности, содержащего ноль или более элементов. Создает TypeError, если подэлемент не является Element.

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

find(match, namespaces=None)¶

Находит первый подэлемент, соответствующий match. match может быть именем тега или path. Возвращает экземпляр элемента или None. пространства имен - это необязательное преобразование префикса пространства имен в полное имя. Передайте '' в качестве префикса, чтобы переместить все имена тегов без префикса в выражении в данное пространство имен.

findall(match, namespaces=None)¶

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

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

Находит текст для первого подэлемента, соответствующего match. match может быть именем тега или path. Возвращает текстовое содержимое первого соответствующего элемента или default, если элемент не был найден. Обратите внимание, что если соответствующий элемент не содержит текстового содержимого, возвращается пустая строка. пространства имен - это необязательное преобразование префикса пространства имен в полное имя. Передайте '' в качестве префикса, чтобы переместить все имена тегов в выражении без префикса в заданное пространство имен.

insert(index, subelement)¶

Вставляет подэлемент в заданную позицию в этом элементе. Возвращает значение TypeError, если подэлемент не является Element.

iter(tag=None)¶

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

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

iterfind(match, namespaces=None)¶

Находит все совпадающие вложенные элементы по имени тега или path. Возвращает итерацию, в результате которой получаются все совпадающие элементы в порядке следования документа. пространства имен - это необязательное преобразование префикса пространства имен в полное имя.

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

itertext()¶

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

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

makeelement(tag, attrib)¶

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

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

До появления Python 3.8 порядок сериализации XML-атрибутов элементов был искусственно сделан предсказуемым путем сортировки атрибутов по их названию. Основываясь на теперь гарантированном упорядочении dicts, это произвольное изменение порядка было удалено в Python 3.8, чтобы сохранить порядок, в котором атрибуты изначально анализировались или создавались пользовательским кодом.

В общем, пользовательский код должен стараться не зависеть от конкретного порядка следования атрибутов, учитывая, что XML Information Set явно исключает порядок следования атрибутов из передачи информации. Код должен быть готов к работе с любым порядком ввода. В случаях, когда требуется детерминированный вывод XML, например, для криптографической подписи или тестовых наборов данных, доступна каноническая сериализация с помощью функции canonicalize().

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

def reorder_attributes(root):
    for el in root.iter():
        attrib = el.attrib
        if len(attrib) > 1:
            # adjust attribute order, e.g. by sorting
            attribs = sorted(attrib.items())
            attrib.clear()
            attrib.update(attribs)

Объекты 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(), начиная с корня дерева.

getroot()¶

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

iter(tag=None)¶

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

iterfind(match, namespaces=None)¶

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

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

parse(source, parser=None)¶

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

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

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

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

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

Изменено в версии 3.8: Метод write() теперь сохраняет порядок атрибутов, указанный пользователем.

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

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

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

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

Объекты QName¶

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

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

Объекты древовидного конструктора¶

class xml.etree.ElementTree.TreeBuilder(element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)¶

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

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

Функции comment_factory и pi_factory, если они заданы, должны вести себя как функции Comment() и ProcessingInstruction() для создания комментариев и инструкций по обработке. Если они не заданы, будут использоваться фабрики по умолчанию. Когда значение insert_comments и/или insert_pis равно true, комментарии/картинки будут вставлены в дерево, если они отображаются внутри корневого элемента (но не за его пределами).

close()¶

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

data(data)¶

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

end(tag)¶

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

start(tag, attrs)¶

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

comment(text)¶

Создает комментарий с заданным текстом. Если insert_comments имеет значение true, это также добавит его в дерево.

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

pi(target, text)¶

Создает инструкцию процесса с заданным именем target и текстом*. Если insert_pis равно true, это также добавит ее в дерево.

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

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

doctype(name, pubid, system)¶

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

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

start_ns(prefix, uri)¶

Вызывается всякий раз, когда синтаксический анализатор обнаруживает новое объявление пространства имен, перед обратным вызовом start() для открывающего элемента, который его определяет. префикс равен '' для пространства имен по умолчанию и в противном случае для объявленного префикса пространства имен. uri - это URI пространства имен.

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

end_ns(prefix)¶

Вызывается после end() обратного вызова элемента, который объявил отображение префикса пространства имен с именем prefix, которое вышло за пределы области видимости.

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

class xml.etree.ElementTree.C14NWriterTarget(write, *, with_comments=False, strip_text=False, rewrite_prefixes=False, qname_aware_tags=None, qname_aware_attrs=None, exclude_attrs=None, exclude_tags=None)¶

Функция записи C14N 2.0. Аргументы те же, что и для функции canonicalize(). Этот класс не строит дерево, а преобразует события обратного вызова непосредственно в сериализованную форму с помощью функции write.

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

Объекты XML-анализатора¶

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

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

Изменено в версии 3.8: Параметры теперь keyword-only. Аргумент html больше не поддерживается.

close()¶

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

feed(data)¶

Передает данные в анализатор. data - это закодированные данные.

flush()¶

Запускает синтаксический анализ любых ранее переданных непроверенных данных, что может быть использовано для обеспечения более оперативной обратной связи, в частности, с Expat >=2.6.0. Реализация flush() временно отключает перенос повторной обработки с помощью Expat (если он включен в данный момент) и запускает повторную обработку. Отключение переноса повторной обработки имеет последствия для безопасности; пожалуйста, смотрите xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() для получения подробной информации.

Обратите внимание, что flush() был перенесен в некоторые предыдущие версии Python в качестве исправления безопасности. Проверьте наличие flush(), используя hasattr(), если он используется в коде, работающем на разных версиях Python.

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

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

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

Объекты XmlPullParser¶

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

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

feed(data)¶

Передайте данные в байтах в синтаксический анализатор.

flush()¶

Запускает синтаксический анализ любых ранее переданных непроверенных данных, что может быть использовано для обеспечения более оперативной обратной связи, в частности, с Expat >=2.6.0. Реализация flush() временно отключает перенос повторной обработки с помощью Expat (если он включен в данный момент) и запускает повторную обработку. Отключение переноса повторной обработки имеет последствия для безопасности; пожалуйста, смотрите xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() для получения подробной информации.

Обратите внимание, что flush() был перенесен в некоторые предыдущие версии Python в качестве исправления безопасности. Проверьте наличие flush(), используя hasattr(), если он используется в коде, работающем на разных версиях Python.

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

close()¶

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

read_events()¶

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

• start, end: текущий элемент.

• comment, pi: текущая инструкция по обработке комментариев

• start-ns: кортеж (prefix, uri), обозначающий объявленное отображение пространства имен.

• end-ns: None ( это может измениться в будущей версии)

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

Примечание

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

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

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

Изменено в версии 3.8: Были добавлены события comment и pi.

Исключения¶

class xml.etree.ElementTree.ParseError¶

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

code¶

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

position¶

Набор из номеров строк, столбцов, указывающих, где произошла ошибка.

Сноски