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

19.6.1. Функции¶Functions

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

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

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 не поддерживается cElementTree. Возвращает итератор, предоставляющий пары (event, elem).

Примечание

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

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

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, если задано. Возвращает экземпляр элемента, представляющий инструкцию обработки.

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

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

xml.etree.ElementTree.tostringlist(element, encoding="us-ascii", method="xml")¶

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

Новое в версии 3.2.

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 и словарь.

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

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

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

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

tag¶

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

text¶

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

tail¶

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

attrib¶

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

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

clear()¶

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

get(key, default=None)¶

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

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

items()¶

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

keys()¶

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

set(key, value)¶

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

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

append(subelement)¶

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

extend(subelements)¶

Добавляет subelements из объекта-последовательности, содержащего ноль или более элементов. Возникает исключение AssertionError, если подэлемент не является допустимым объектом.

Новое в версии 3.2.

find(match)¶

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

findall(match)¶

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

findtext(match, default=None)¶

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

getchildren()¶

Устарело с версии 3.2: Используйте list(elem) или итерацию.

getiterator(tag=None)¶

Устарело с версии 3.2: Вместо этого используйте метод Element.iter().

insert(index, element)¶

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

iter(tag=None)¶

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

Новое в версии 3.2.

iterfind(match)¶

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

Новое в версии 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")

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

class xml.etree.ElementTree.ElementTree(element=None, file=None)¶

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

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

_setroot(element)¶

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

find(match)¶

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

findall(match)¶

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

findtext(match, default=None)¶

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

getiterator(tag=None)¶

Устарело с версии 3.2: Вместо этого используйте метод ElementTree.iter().

getroot()¶

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

iter(tag=None)¶

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

iterfind(match)¶

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

Новое в версии 3.2.

parse(source, parser=None)¶

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

write(file, encoding="us-ascii", xml_declaration=None, default_namespace=None, method="xml")¶

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

Это 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")

19.6.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 непрозрачны.

19.6.5. Объекты TreeBuilder¶TreeBuilder Objects

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

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

close()¶

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

data(data)¶

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

end(tag)¶

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

start(tag, attrs)¶

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

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

doctype(name, pubid, system)¶

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

Новое в версии 3.2.

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

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

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

close()¶

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

doctype(name, pubid, system)¶

Устарело с версии 3.2: определите метод TreeBuilder.doctype() для пользовательского TreeBuilder target.

feed(data)¶

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

XMLParser.feed() вызывает метод target start() для каждого открывающего тега, его метод end() для каждого закрывающего тега, а данные обрабатываются методом data(). XMLParser.close() вызывает метод target close(). 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

Сноски