xml.etree.ElementTree – API ElementTree для XML¶xml.etree.ElementTree – The ElementTree XML API

Функции¶Functions

xml.etree.ElementTree.Comment([text])¶

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

xml.etree.ElementTree.dump(elem)¶

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

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

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

xml.etree.ElementTree.Element(tag[, attrib][, **extra])¶

Фабрика элементов. Эта функция возвращает объект, реализующий стандартный интерфейс Element. Точный класс или тип этого объекта зависит от реализации, но он всегда будет совместим с классом _ElementInterface в этом модуле.

Имя элемента, имена атрибутов и значения атрибутов могут быть объектом bytes только с ASCII или объектом str. tag – это имя элемента. attrib – необязательный словарь, содержащий атрибуты элемента. extra содержит дополнительные атрибуты, заданные как именованные аргументы. Возвращает экземпляр элемента.

xml.etree.ElementTree.fromstring(text)¶

Разбирает XML-фрагмент из строковой константы. То же, что и XML. text – это строка, содержащая XML-данные. Возвращает экземпляр Element.

xml.etree.ElementTree.iselement(element)¶

Проверяет, является ли объект корректным элементом. element – это экземпляр элемента. Возвращает истинное значение, если это объект элемента.

xml.etree.ElementTree.iterparse(source[, events])¶

Разбирает XML-фрагмент в дерево элементов поэтапно и сообщает пользователю о происходящем. source – это имя файла или файловый объект, содержащий XML-данные. events – это список событий, о которых нужно сообщать. Если не указан, сообщается только о событиях “end”. Возвращает итератор, предоставляющий пары (event, elem).

Примечание

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

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

xml.etree.ElementTree.parse(source[, parser])¶

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

xml.etree.ElementTree.ProcessingInstruction(target[, text])¶

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

xml.etree.ElementTree.SubElement(parent, tag[, attrib[, **extra]])¶

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

Имя элемента, имена атрибутов и значения атрибутов могут быть объектом bytes только с ASCII или объектом str. parent – это родительский элемент. tag – имя подэлемента. attrib – необязательный словарь, содержащий атрибуты элемента. extra содержит дополнительные атрибуты, заданные как именованные аргументы. Возвращает экземпляр элемента.

xml.etree.ElementTree.tostring(element[, encoding])¶

Генерирует строковое представление XML-элемента, включая все подэлементы. element – это экземпляр Element. encoding – кодировка вывода (по умолчанию US-ASCII). Возвращает закодированную строку, содержащую XML-данные.

xml.etree.ElementTree.XML(text)¶

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

xml.etree.ElementTree.XMLID(text)¶

Разбирает XML-фрагмент из строковой константы, а также возвращает словарь, который сопоставляет идентификаторы элементов с элементами. text – это строка, содержащая XML- данные. Возвращает кортеж, содержащий экземпляр Element и словарь.

Интерфейс Element¶The Element Interface

Объекты Element, возвращаемые функциями Element или SubElement, имеют следующие методы и атрибуты.

Element.tag¶

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

Element.text¶

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

Element.tail¶

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

Element.attrib¶

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

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

Element.clear()¶

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

Element.get(key[, default=None])¶

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

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

Element.items()¶

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

Element.keys()¶

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

Element.set(key, value)¶

Устанавливает атрибут key элемента в value.

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

Element.append(subelement)¶

Добавляет элемент subelement в конец внутреннего списка подэлементов данного элемента.

Element.find(match)¶

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

Element.findall(match)¶

Находит все подэлементы, соответствующие match. match может быть именем тега или путём. Возвращает итерируемый объект, выдающий все подходящие элементы в порядке документа.

Element.findtext(condition[, default=None])¶

Находит текст первого подэлемента, соответствующего condition. condition может быть именем тега или путём. Возвращает текстовое содержимое первого подходящего элемента или default, если элемент не найден. Обратите внимание: если у подходящего элемента нет текстового содержимого, возвращается пустая строка.

Element.getchildren()¶

Возвращает все подэлементы. Элементы возвращаются в порядке документа.

Element.getiterator([tag=None])¶

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

Element.insert(index, element)¶

Вставляет подэлемент в заданную позицию в данном элементе.

Element.makeelement(tag, attrib)¶

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

Element.remove(subelement)¶

Удаляет подэлемент из элемента. В отличие от методов findXYZ, этот метод сравнивает элементы на основе идентичности экземпляра, а не по значению тега или содержимому.

Объекты Element также поддерживают следующие методы последовательностей для работы с подэлементами: __delitem__(), __getitem__(), __setitem__(), __len__().

Внимание: поскольку объекты Element не определяют метод __bool__(), элементы без подэлементов будут проверяться как False.

element = root.find('foo')

if not element: # осторожно!
    print("element not found, or element has no subelements")

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

Объекты ElementTree¶ElementTree Objects

class xml.etree.ElementTree.ElementTree([element][, file])¶

Класс-обёртка ElementTree. Этот класс представляет целую иерархию элементов и добавляет дополнительную поддержку для сериализации в стандартный XML и из него.

element – корневой элемент. Дерево инициализируется содержимым XML-файла, если он указан.

_setroot(element)¶

Заменяет корневой элемент этого дерева. При этом отбрасывается текущее содержимое дерева и заменяется указанным элементом. Используйте с осторожностью. element – экземпляр элемента.

find(path)¶

Находит первый элемент верхнего уровня с указанным тегом. То же, что getroot().find(path). path – элемент для поиска. Возвращает первый подходящий элемент или None, если элемент не найден.

findall(path)¶

Находит все элементы верхнего уровня с указанным тегом. То же, что getroot().findall(path). path – элемент для поиска. Возвращает список или итератор, содержащий все подходящие элементы, в порядке документа.

findtext(path[, default])¶

Находит текст элемента для первого элемента верхнего уровня с указанным тегом. То же, что getroot().findtext(path). path – элемент верхнего уровня для поиска. default – значение, возвращаемое, если элемент не найден. Возвращает текстовое содержимое первого подходящего элемента или значение по умолчанию, если элемент не найден. Обратите внимание, что если элемент найден, но не имеет текстового содержимого, этот метод возвращает пустую строку.

getiterator([tag])¶

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

getroot()¶

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

parse(source[, parser])¶

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

write(file[, encoding])¶

Записывает дерево элементов в файл в формате XML. file – это имя файла или файловый объект, открытый для записи. encoding [1] – кодировка вывода (по умолчанию US-ASCII).

Это 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 b7d3f1ec>
>>> p = tree.find("body/p")     # Находит первое вхождение тега p в body
>>> p
<Element p at 8416e0c>
>>> links = p.getiterator("a")  # Возвращает список всех ссылок
>>> links
[<Element a at b7d4f9ec>, <Element a at b7d4fb0c>]
>>> for i in links:             # Перебирает все найденные ссылки
...     i.attrib["target"] = "blank"
>>> tree.write("output.xhtml")

Объекты QName¶QName Objects

class xml.etree.ElementTree.QName(text_or_uri[, tag])¶

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

Объекты TreeBuilder¶TreeBuilder Objects

class xml.etree.ElementTree.TreeBuilder([element_factory])¶

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

close()¶

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

data(data)¶

Добавляет текст в текущий элемент. data – строка. Она должна быть либо объектом bytes, содержащим только ASCII, либо объектом str.

end(tag)¶

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

start(tag, attrs)¶

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

Объекты XMLTreeBuilder¶XMLTreeBuilder Objects

class xml.etree.ElementTree.XMLTreeBuilder([html][, target])¶

Построитель структуры элементов для исходных данных XML, основанный на парсере expat. html – предопределённые HTML-сущности. Этот флаг не поддерживается текущей реализацией. target – целевой объект. Если не указан, построитель использует экземпляр стандартного класса TreeBuilder.

close()¶

Завершает подачу данных парсеру. Возвращает структуру элемента.

doctype(name, pubid, system)¶

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

feed(data)¶

Подаёт данные парсеру. data – закодированные данные.

XMLTreeBuilder.feed() вызывает метод start() объекта target для каждого открывающего тега, его метод end() для каждого закрывающего тега, а данные обрабатываются методом data(). XMLTreeBuilder.close() вызывает метод close() объекта target. XMLTreeBuilder может использоваться не только для построения древовидной структуры. Это пример подсчёта максимальной глубины XML-файла:

>>> from xml.etree.ElementTree import XMLTreeBuilder
>>> 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 = XMLTreeBuilder(target=target)
>>> exampleXml = """
... <a>
...   <b>
...   </b>
...   <b>
...     <c>
...       <d>
...       </d>
...     </c>
...   </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4

Сноски