xml.etree.ElementTree — A API XML ElementTree

Código-fonte: Lib/xml/etree/ElementTree.py


O módulo xml.etree.ElementTree implementa uma API simples e eficiente para análise e criação de dados XML.

Alterado na versão 3.3: Este módulo usará uma implementação rápida sempre que disponível.

Descontinuado desde a versão 3.3: O módulo xml.etree.cElementTree foi descontinuado.

Nota

Se você precisar analisar dados não confiáveis ou não autenticados, consulte Segurança no XML.

Tutorial

Esse é um tutorial curto para usar xml.etree.ElementTree (ET na versão resumida). O objetivo é demonstrar alguns conceitos básicos e trechos de códigos do módulo.

Árvore e elementos XML

XML é um formato de dados estritamente hierárquico, e a maneira mais natural de representá-lo é como uma árvore. ET possui duas classes para esse propósito - ElementTree representa todo o documento XML como uma árvore e Element representa um único nó desta árvore. Interações com o documento inteiro (ler e escrever de/para arquivos) são frequentemente feitos em nível de ElementTree. Interações com um único elemento XML e seus subelementos são feitos a nível de Element .

Analisando XML

Usaremos o documento XML fictício country_data.xml como dados de amostra para esta seção:

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

Nós podemos importar esses dados lendo de um arquivo:

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

Ou diretamente de uma string:

root = ET.fromstring(country_data_as_string)

fromstring() obtém o XML de uma string e armazena em um Element, que será o elemento raiz dessa árvore. Outras funções de análise sintática podem criar um ElementTree. Cheque a documentação para se certificar sobre qual dado será retornado.

Assim como um Element, root tem uma tag e um dicionário de atributos:

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

Ele também tem nós filhos sobre os quais nós podemos iterar:

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

Nós filhos são os mais próximos, e nós podemos acessar nós específicos por índices:

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

Nota

Nem todos os elementos da entrada XML acabarão como elementos da árvore analisada. Atualmente, este módulo ignora quaisquer comentários XML, instruções de processamento e declarações de tipo de documento na entrada. No entanto, árvores construídas usando a API deste módulo, em vez de serem analisadas a partir de texto XML, podem conter comentários e instruções de processamento; eles serão incluídos ao gerar a saída XML. Uma declaração de tipo de documento pode ser acessada passando uma instância personalizada TreeBuilder para o construtor XMLParser.

A API de pull para análise sem bloqueio

A maioria das funções de análise fornecidas por este módulo exigem que todo o documento seja lido de uma só vez antes de retornar qualquer resultado. É possível usar um XMLParser e alimentar dados nele de forma incremental, mas é uma API de push que chama métodos em um destino da função de retorno, o que é de muito baixo nível e inconveniente para a maioria das necessidades. Às vezes, o que o usuário realmente deseja é ser capaz de analisar XML de forma incremental, sem operações bloqueantes, enquanto desfruta da conveniência de objetos Element totalmente construídos.

A ferramenta mais poderosa para fazer isso é XMLPullParser. Ela não requer uma leitura bloqueante para obter os dados XML e, em vez disso, é alimentada com dados de forma incremental com chamadas de XMLPullParser.feed(). Para obter os elementos XML analisados, chame XMLPullParser.read_events(). Aqui está um exemplo:

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

O caso de uso óbvio são aplicações que operam sem bloqueio, onde os dados XML são recebidos de um soquete ou lidos de forma incremental de algum dispositivo de armazenamento. Nesses casos, leituras bloqueantes são inaceitáveis.

Por ser tão flexível, XMLPullParser pode ser inconveniente de usar em casos de uso mais simples. Se você não se importa que sua aplicação bloqueie a leitura de dados XML, mas ainda assim gostaria de ter recursos de análise incremental, dê uma olhada em iterparse(). Pode ser útil quando você está lendo um documento XML grande e não deseja mantê-lo totalmente na memória.

Onde o feedback imediato através de eventos é desejado, chamar o método XMLPullParser.flush() pode ajudar a reduzir o atraso; certifique-se de estudar as notas de segurança relacionadas.

Encontrando elementos interessantes

Element possui alguns métodos úteis que ajudam a iterar recursivamente sobre toda a subárvore abaixo dele (seus filhos, seus filhos e assim por diante). Por exemplo, 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() encontra apenas elementos com uma tag que são filhos diretos do elemento atual. Element.find() encontra o primeiro filho com uma tag específica, e Element.text acessa o conteúdo de texto do elemento. Element.get() acessa os atributos do elemento:

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

Uma especificação mais sofisticada de quais elementos procurar é possível usando XPath.

Modificando um arquivo XML

ElementTree fornece uma maneira simples de construir documentos XML e escrevê-los em arquivos. O método ElementTree.write() serve para esse propósito.

Uma vez criado, um objeto Element pode ser manipulado alterando diretamente seus campos (como Element.text), adicionando e modificando atributos (método Element.set()), bem como como adicionar novos filhos (por exemplo, com Element.append()).

Digamos que queremos adicionar um à classificação de cada país e adicionar um atributo updated ao elemento de classificação:

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

Nosso XML agora se parece com isto:

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

Podemos remover elementos usando Element.remove(). Digamos que queremos remover todos os países com classificação superior a 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')

Observe que a modificação simultânea durante a iteração pode levar a problemas, assim como ao iterar e modificar listas ou dicionários do Python. Portanto, o exemplo primeiro coleta todos os elementos correspondentes com root.findall(), e só então itera sobre a lista de correspondências.

Nosso XML agora se parece com isto:

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

Construindo documentos XML

A função SubElement() também fornece uma maneira conveniente de criar novos subelementos para um determinado elemento:

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

Analisando XML com espaços de nomes

Se a entrada XML tiver espaços de nomes, tags e atributos com prefixos no formato prefixo:algumatag serão expandidos para {uri}algumatag onde prefixo é substituído pelo URI completo. Além disso, se houver um espaço de nomes padrão, esse URI completo será anexado a todas as tags não prefixadas.

Aqui está um exemplo XML que incorpora dois espaços de nomes, um com o prefixo “fictional” e outro servindo como espaço de nomes padrão:

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

Uma maneira de pesquisar e explorar este exemplo XML é adicionar manualmente o URI a cada tag ou atributo no xpath de um find() ou 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)

A melhor maneira de pesquisar o exemplo XML com espaço de nomes é criar um dicionário com seus próprios prefixos e usá-los nas funções de pesquisa:

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)

Essas duas abordagens resultam no seguinte:

John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement

Suporte a XPath

Este módulo fornece suporte limitado para expressões XPath para localizar elementos em uma árvore. O objetivo é oferecer suporte a um pequeno subconjunto da sintaxe abreviada; um mecanismo XPath completo está fora do escopo do módulo.

Exemplo

Aqui está um exemplo que demonstra alguns dos recursos XPath do módulo. Estaremos usando o documento XML countrydata da seção Analisando 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]")

Para XML com espaços de nomes, use a notação qualificada usual {espaço-de-nomes}tag:

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

Підтримуваний синтаксис XPath

Sintaxe

Significado

tag

Вибирає всі дочірні елементи з заданим тегом. Наприклад, spam вибирає всі дочірні елементи з іменем spam, а spam/egg вибирає всіх онуків з іменем egg у всіх дочірніх елементах з іменем spam. {namespace}* вибирає всі теги в заданому просторі імен, {*}spam вибирає теги з назвою spam у будь-якому просторі імен (або без нього), а {}* лише вибирає теги, які не знаходяться в просторі імен.

Alterado na versão 3.8: Додано підтримку символів підстановки зірок.

*

Вибирає всі дочірні елементи, включаючи коментарі та інструкції з обробки. Наприклад, */egg вибирає всіх онуків з іменем egg.

.

Вибирає поточний вузол. Це здебільшого корисно на початку шляху, щоб вказати, що це відносний шлях.

//

Вибирає всі піделементи на всіх рівнях під поточним елементом. Наприклад, .//egg вибирає всі елементи egg у всьому дереві.

..

Вибирає батьківський елемент. Повертає None, якщо шлях намагається досягти предків початкового елемента (був викликаний елемент find).

[@attrib]

Вибирає всі елементи, які мають заданий атрибут.

[@attrib='value']

Вибирає всі елементи, для яких даний атрибут має задане значення. Значення не може містити лапки.

[@attrib!='value']

Selects all elements for which the given attribute does not have the given value. The value cannot contain quotes.

Adicionado na versão 3.10.

[tag]

Вибирає всі елементи, які мають дочірні елементи з іменем tag. Утримуються лише найближчі діти.

[.='text']

Вибирає всі елементи, повний текстовий вміст яких, включаючи нащадків, дорівнює заданому тексту.

Adicionado na versão 3.7.

[.!='text']

Selects all elements whose complete text content, including descendants, does not equal the given text.

Adicionado na versão 3.10.

[tag='text']

Вибирає всі елементи, які мають дочірні елементи з назвою tag, повний текстовий вміст яких, включаючи нащадків, дорівнює заданому text.

[tag!='text']

Selects all elements that have a child named tag whose complete text content, including descendants, does not equal the given text.

Adicionado na versão 3.10.

[position]

Вибирає всі елементи, які розташовані на заданій позиції. Позиція може бути цілим числом (1 — перша позиція), виразом last() (для останньої позиції) або позицією відносно останньої позиції (наприклад, last()-1 ).

Предикати (вирази в квадратних дужках) мають передувати назві тегу, зірочці або іншому предикату. Предикатам position має передувати ім’я тегу.

Referência

Funções

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

C14N 2.0 функція перетворення.

Canonicalization is a way to normalise XML output in a way that allows byte-by-byte comparisons and digital signatures. It reduces the freedom that XML serializers have and instead generates a more constrained XML representation. The main restrictions regard the placement of namespace declarations, the ordering of attributes, and ignorable whitespace.

Ця функція приймає рядок XML-даних (xml_data) або шлях до файлу або файлоподібний об’єкт (from_file) як вхідні дані, перетворює їх у канонічну форму та записує за допомогою out file(-like) об’єкт, якщо він наданий, або повертає його як текстовий рядок, якщо ні. Вихідний файл отримує текст, а не байти. Тому його слід відкривати в текстовому режимі з кодуванням 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{number}”

    (за замовчуванням: false)

  • qname_aware_tags: набір імен тегів qname, у яких префікси

    слід замінити в текстовому вмісті (за замовчуванням: пусто)

  • qname_aware_attrs: набір імен атрибутів, що підтримують qname, у яких префікси

    слід замінити в текстовому вмісті (за замовчуванням: пусто)

  • exclude_attrs: набір імен атрибутів, які не повинні бути серіалізовані

  • exclude_tags: набір імен тегів, які не повинні бути серіалізовані

У наведеному вище списку параметрів “набір” відноситься до будь-якої колекції або ітерації рядків, упорядкування не очікується.

Adicionado na versão 3.8.

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

Фабрика елементів коментарів. Ця фабрична функція створює спеціальний елемент, який буде серіалізовано як коментар XML стандартним серіалізатором. Рядок коментаря може бути байтовим рядком або рядком Unicode. text – це рядок, що містить рядок коментаря. Повертає екземпляр елемента, що представляє коментар.

Зауважте, що XMLParser пропускає коментарі у вхідних даних замість того, щоб створювати для них об’єкти коментарів. ElementTree міститиме лише вузли коментарів, якщо вони були вставлені в дерево за допомогою одного з методів Element.

xml.etree.ElementTree.dump(elem)

Записує дерево елементів або структуру елементів у sys.stdout. Цю функцію слід використовувати лише для налагодження.

Точний вихідний формат залежить від реалізації. У цій версії він написаний як звичайний файл XML.

elem — дерево елементів або окремий елемент.

Alterado na versão 3.8: Функція dump() тепер зберігає порядок атрибутів, указаний користувачем.

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

Розбирає розділ XML із константи рядка. Те саме, що XML(). текст — це рядок, що містить дані XML. parser є необов’язковим екземпляром парсера. Якщо не вказано, використовується стандартний аналізатор XMLParser. Повертає екземпляр Element.

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

Розбирає XML-документ із послідовності фрагментів рядків. послідовність — це список або інша послідовність, що містить фрагменти даних XML. parser є необов’язковим екземпляром парсера. Якщо не вказано, використовується стандартний аналізатор XMLParser. Повертає екземпляр Element.

Adicionado na versão 3.2.

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

До піддерева додає пробіли для візуального відступу дерева. Це можна використати для генерації красивого друкованого виводу XML. дерево може бути елементом або деревом елементів. пробіл — це пробільний рядок, який буде вставлено для кожного рівня відступу, два символи пробілу за замовчуванням. Для відступу часткових піддерев усередині дерева з відступами передайте початковий рівень відступу як level.

Adicionado na versão 3.9.

xml.etree.ElementTree.iselement(element)

Перевірте, чи об’єкт є дійсним об’єктом елемента. element — екземпляр елемента. Повертає True, якщо це об’єкт елемента.

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

Parses an XML section into an element tree incrementally, and reports what’s going on to the user. source is a filename or file object containing XML data. events is a sequence of events to report back. The supported events are the strings "start", "end", "comment", "pi", "start-ns" and "end-ns" (the “ns” events are used to get detailed namespace information). If events is omitted, only "end" events are reported. parser is an optional parser instance. If not given, the standard XMLParser parser is used. parser must be a subclass of XMLParser and can only use the default TreeBuilder as a target. Returns an iterator providing (event, elem) pairs; it has a root attribute that references the root element of the resulting XML tree once source is fully read. The iterator has the close() method that closes the internal file object if source is a filename.

Зауважте, що хоча iterparse() будує дерево поступово, він блокує читання source (або файлу, який він називає). Таким чином, він не підходить для додатків, де блокування зчитування неможливе. Повністю неблокуючий аналіз див. XMLPullParser.

Nota

iterparse() лише гарантує, що він побачив символ “>” початкового тегу, коли він випромінює подію “start”, тому атрибути визначені, але вміст атрибутів text і tail на цьому етапі не визначено . Те саме стосується елемента діти; вони можуть бути або не бути присутніми.

Якщо вам потрібен повністю заповнений елемент, шукайте події “кінець”.

Descontinuado desde a versão 3.4: Аргумент parser.

Alterado na versão 3.8: Додано події comment і pi.

Alterado na versão 3.13: Added the close() method.

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

Розбирає розділ XML у дерево елементів. джерело — це ім’я файлу або об’єкт файлу, що містить дані XML. parser є необов’язковим екземпляром парсера. Якщо не вказано, використовується стандартний аналізатор XMLParser. Повертає екземпляр ElementTree.

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

Завод ПІ-елементів. Ця фабрична функція створює спеціальний елемент, який буде серіалізовано як інструкцію обробки XML. target — це рядок, що містить ціль PI. текст — це рядок, що містить вміст PI, якщо його вказано. Повертає екземпляр елемента, що представляє інструкцію обробки.

Note that XMLParser skips over processing instructions in the input instead of creating PI objects for them. An ElementTree will only contain processing instruction nodes if they have been inserted into to the tree using one of the Element methods.

xml.etree.ElementTree.register_namespace(prefix, uri)

Реєструє префікс простору імен. Реєстр є глобальним, і будь-яке існуюче відображення для заданого префікса або URI простору імен буде видалено. префікс — це префікс простору імен. uri — це uri простору імен. Теги й атрибути в цьому просторі імен будуть серіалізовані з заданим префіксом, якщо це взагалі можливо.

Adicionado na versão 3.2.

xml.etree.ElementTree.SubElement(parent, tag, attrib={}, **extra)

Піделементний завод. Ця функція створює екземпляр елемента та додає його до існуючого елемента.

Ім’я елемента, назви атрибутів і значення атрибутів можуть бути байтовими рядками або рядками Unicode. parent є батьківським елементом. тег — це назва піделемента. 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. кодування [1] — вихідне кодування (за замовчуванням — US-ASCII). Використовуйте encoding="unicode", щоб створити рядок Юнікод (інакше буде згенеровано байтовий рядок). method — це "xml", "html" або "text" (за замовчуванням "xml"). xml_declaration, default_namespace і short_empty_elements мають те саме значення, що й у ElementTree.write(). Повертає (необов’язково) закодований рядок, що містить дані XML.

Alterado na versão 3.4: Foi adicionado o parâmetro short_empty_elements.

Alterado na versão 3.8: Added the xml_declaration and default_namespace parameters.

Alterado na versão 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. кодування [1] — вихідне кодування (за замовчуванням — US-ASCII). Використовуйте encoding="unicode", щоб створити рядок Юнікод (інакше буде згенеровано байтовий рядок). method — це "xml", "html" або "text" (за замовчуванням "xml"). xml_declaration, default_namespace і short_empty_elements мають те саме значення, що й у ElementTree.write(). Повертає список (необов’язково) закодованих рядків, що містять дані XML. Це не гарантує жодної конкретної послідовності, за винятком того, що b"".join(tostringlist(element)) == tostring(element).

Adicionado na versão 3.2.

Alterado na versão 3.4: Foi adicionado o parâmetro short_empty_elements.

Alterado na versão 3.8: Added the xml_declaration and default_namespace parameters.

Alterado na versão 3.8: Функція tostringlist() тепер зберігає порядок атрибутів, указаний користувачем.

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

Розбирає розділ XML із константи рядка. Цю функцію можна використовувати для вбудовування “XML-літералів” у код Python. текст — це рядок, що містить дані XML. parser є необов’язковим екземпляром парсера. Якщо не вказано, використовується стандартний аналізатор XMLParser. Повертає екземпляр Element.

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

Розбирає розділ XML із константи рядка, а також повертає словник, який відображає ідентифікатори елемента: елементи. текст — це рядок, що містить дані XML. parser є необов’язковим екземпляром парсера. Якщо не вказано, використовується стандартний аналізатор XMLParser. Повертає кортеж, що містить екземпляр Element і словник.

XInclude підтримка

Цей модуль надає обмежену підтримку для XInclude директив через допоміжний модуль xml.etree.ElementInclude. Цей модуль можна використовувати для вставки піддерев і текстових рядків у дерева елементів на основі інформації в дереві.

Exemplo

Ось приклад, який демонструє використання модуля XInclude. Щоб включити 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)

Модуль ElementInclude замінює елемент {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>

Referência

Funções

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

Default loader. This default loader reads an included resource from disk. href is a URL. parse is for parse mode either “xml” or “text”. encoding is an optional text encoding. If not given, encoding is utf-8. Returns the expanded resource. If the parse mode is "xml", this is an Element instance. If the parse mode is "text", this is a string. If the loader fails, it can return None or raise an exception.

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

This function expands XInclude directives in-place in tree pointed by elem. elem is either the root Element or an ElementTree instance to find such element. loader is an optional resource loader. If omitted, it defaults to default_loader(). If given, it should be a callable that implements the same interface as default_loader(). base_url is base URL of the original file, to resolve relative include file references. max_depth is the maximum number of recursive inclusions. Limited to reduce the risk of malicious content explosion. Pass None to disable the limitation.

Alterado na versão 3.9: Added the base_url and max_depth parameters.

Об’єкти елементів

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

Клас елемента. Цей клас визначає інтерфейс Element і забезпечує еталонну реалізацію цього інтерфейсу.

Ім’я елемента, назви атрибутів і значення атрибутів можуть бути байтовими рядками або рядками Unicode. тег — це назва елемента. 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)

Appends subelements from an iterable of elements. Raises TypeError if a subelement is not an Element.

Adicionado na versão 3.2.

find(match, namespaces=None)

Знаходить перший піделемент, що відповідає match. match може бути назвою тегу або шляхом. Повертає екземпляр елемента або None. простори імен — це необов’язкове відображення префікса простору імен на повне ім’я. Передайте '' як префікс, щоб перемістити всі імена тегів без префіксів у виразі до вказаного простору імен.

findall(match, namespaces=None)

Знаходить усі відповідні піделементи за назвою тегу або шляхом. Повертає список, що містить усі відповідні елементи в порядку документа. простори імен — це необов’язкове відображення префікса простору імен на повне ім’я. Передайте '' як префікс, щоб перемістити всі імена тегів без префіксів у виразі до вказаного простору імен.

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

Знаходить текст для першого піделемента, який відповідає match. match може бути назвою тегу або шляхом. Повертає текстовий вміст першого відповідного елемента або за замовчуванням, якщо елемент не знайдено. Зауважте, що якщо відповідний елемент не має текстового вмісту, повертається порожній рядок. простори імен — це необов’язкове відображення префікса простору імен на повне ім’я. Передайте '' як префікс, щоб перемістити всі імена тегів без префіксів у виразі до вказаного простору імен.

insert(index, subelement)

Вставляє піделемент у задану позицію цього елемента. Викликає TypeError, якщо subelement не є Element.

iter(tag=None)

Створює дерево iterator з поточним елементом як коренем. Ітератор повторює цей елемент і всі елементи під ним у порядку документа (спочатку глибина). Якщо tag не є None або '*', ітератор повертає лише елементи, тег яких дорівнює tag. Якщо структуру дерева змінено під час ітерації, результат буде невизначеним.

Adicionado na versão 3.2.

iterfind(match, namespaces=None)

Знаходить усі відповідні піделементи за назвою тегу або шляхом. Повертає iterable, що дає всі відповідні елементи в порядку документа. простори імен — це необов’язкове відображення префікса простору імен на повне ім’я.

Adicionado na versão 3.2.

itertext()

Створює текстовий ітератор. Ітератор проходить по цьому елементу та всім піделементам у порядку документа та повертає весь внутрішній текст.

Adicionado na versão 3.2.

makeelement(tag, attrib)

Створює новий об’єкт елемента того самого типу, що й цей елемент. Не викликайте цей метод, замість цього використовуйте фабричну функцію SubElement().

remove(subelement)

Видаляє піделемент з елемента. На відміну від методів find*, цей метод порівнює елементи на основі ідентичності екземпляра, а не на основі значення тегу чи вмісту.

Об’єкти Element також підтримують такі методи типу послідовності для роботи з піделементами: __delitem__(), __getitem__(), __setitem__(), __len__().

Caution: Elements with no subelements will test as False. In a future release of Python, all elements will test as True regardless of whether subelements exist. Instead, prefer explicit len(elem) or elem is not None tests.:

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

Alterado na versão 3.12: Testing the truth value of an Element emits DeprecationWarning.

До Python 3.8 порядок серіалізації XML-атрибутів елементів штучно робили передбачуваним шляхом сортування атрибутів за їх назвою. Базуючись на тепер гарантованому порядку диктовок, цей довільний порядок було вилучено в Python 3.8, щоб зберегти порядок, у якому атрибути були спочатку проаналізовані або створені кодом користувача.

Загалом код користувача має намагатися не залежати від певного порядку атрибутів, враховуючи, що Набір інформації XML явно виключає порядок атрибутів із передачі інформації. Код має бути готовий до будь-якого впорядкування вхідних даних. У випадках, коли потрібен детермінований вивід 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)

Створює та повертає ітератор дерева для кореневого елемента. Ітератор перебирає всі елементи в цьому дереві в порядку секцій. тег — це тег, який потрібно шукати (за замовчуванням повертаються всі елементи).

iterfind(match, namespaces=None)

Те саме, що Element.iterfind(), починаючи з кореня дерева.

Adicionado na versão 3.2.

parse(source, parser=None)

Завантажує зовнішній розділ XML у це дерево елементів. джерело — це ім’я файлу або 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, відкритий для запису. кодування [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. Якщо кодування є "юнікодом", результатом є рядок; інакше це двійковий файл. Зауважте, що це може конфліктувати з типом file, якщо це відкритий file object; переконайтеся, що ви не намагаєтесь записати рядок у двійковий потік і навпаки.

Alterado na versão 3.4: Foi adicionado o parâmetro short_empty_elements.

Alterado na versão 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 або, якщо вказано аргумент тегу, частину URI QName. Якщо вказано тег, перший аргумент інтерпретується як URI, а цей аргумент інтерпретується як локальне ім’я. Екземпляри QName є непрозорими.

Об’єкти TreeBuilder

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

Загальний конструктор структур елемента. Цей конструктор перетворює послідовність викликів методу початку, даних, кінця, коментаря та pi у добре сформовану структуру елементів. Ви можете використовувати цей клас, щоб побудувати структуру елемента за допомогою спеціального синтаксичного аналізатора XML або іншого XML-подібного формату.

element_factory, якщо задано, має бути викликом, що приймає два позиційні аргументи: тег і dict атрибутів. Очікується, що він поверне новий екземпляр елемента.

Функції comment_factory і pi_factory, якщо їх надано, повинні поводитися як функції Comment() і ProcessingInstruction() для створення коментарів і інструкцій з обробки. Якщо не вказано, будуть використані фабрики за замовчуванням. Якщо insert_comments і/або insert_pis має значення true, коментарі/pis буде вставлено в дерево, якщо вони з’являться в кореневому елементі (але не поза ним).

close()

Очищає буфери конструктора та повертає елемент документа верхнього рівня. Повертає екземпляр Element.

data(data)

Додає текст до поточного елемента. data — це рядок. Це має бути байтовий рядок або рядок Unicode.

end(tag)

Закриває поточний елемент. тег — це назва елемента. Повертає закритий елемент.

start(tag, attrs)

Відкриває новий елемент. тег — це назва елемента. attrs — це словник, що містить атрибути елементів. Повертає відкритий елемент.

comment(text)

Створює коментар із заданим текстом. Якщо insert_comments має значення true, це також додасть його до дерева.

Adicionado na versão 3.8.

pi(target, text)

Creates a process instruction with the given target name and text. If insert_pis is true, this will also add it to the tree.

Adicionado na versão 3.8.

Крім того, спеціальний об’єкт TreeBuilder може надавати такі методи:

doctype(name, pubid, system)

Обробляє оголошення doctype. name — це ім’я типу документа. pubid є публічним ідентифікатором. system — це ідентифікатор системи. Цей метод не існує в класі TreeBuilder за замовчуванням.

Adicionado na versão 3.2.

start_ns(prefix, uri)

Викликається кожного разу, коли синтаксичний аналізатор зустрічає нове оголошення простору імен перед зворотним викликом start() для початкового елемента, який його визначає. префікс — це '' для простору імен за замовчуванням, а в інших випадках – оголошене ім’я префікса простору імен. uri — URI простору імен.

Adicionado na versão 3.8.

end_ns(prefix)

Викликається після зворотного виклику end() елемента, який оголосив відображення префікса простору імен, з назвою префікса, який вийшов за межі області видимості.

Adicionado na versão 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.

Adicionado na versão 3.8.

Objetos XMLParser

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

Цей клас є будівельним блоком низького рівня модуля. Він використовує xml.parsers.expat для ефективного аналізу XML на основі подій. Він може передавати XML-дані поетапно за допомогою методу feed(), а події синтаксичного аналізу транслюються в push API шляхом виклику зворотних викликів для об’єкта target. Якщо target опущено, використовується стандартний TreeBuilder. Якщо вказано кодування [1], значення має перевагу над кодуванням, указаним у файлі XML.

Alterado na versão 3.8: Parameters are now keyword-only. The html argument is no longer supported.

close()

Завершує подачу даних до аналізатора. Повертає результат виклику методу close() target, переданого під час створення; за замовчуванням це елемент документа верхнього рівня.

feed(data)

Подає дані в аналізатор. data — це закодовані дані.

flush()

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

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

Adicionado na versão 3.13.

XMLParser.feed() викликає метод target start(tag, attrs_dict) для кожного початкового тегу, його метод end(tag) для кожного закриваючого тегу, і дані обробляються методом дані(дані). Інші підтримувані методи зворотного виклику див. у класі TreeBuilder. 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” використовуються для отримання детальної інформації про простір імен). Якщо events опущено, повідомляються лише події "end".

feed(data)

Передайте надані дані в байтах аналізатору.

flush()

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

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

Adicionado na versão 3.13.

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(), матимуть непередбачувані результати.

Nota

XMLPullParser лише гарантує, що він побачив символ “>” початкового тегу, коли він випромінює подію “start”, тому атрибути визначені, але вміст атрибутів text і tail на той момент не визначено . Те саме стосується елемента діти; вони можуть бути або не бути присутніми.

Якщо вам потрібен повністю заповнений елемент, шукайте події “кінець”.

Adicionado na versão 3.4.

Alterado na versão 3.8: Додано події comment і pi.

Exceções

class xml.etree.ElementTree.ParseError

Помилка аналізу XML, викликана різними методами аналізу в цьому модулі, коли аналіз не вдається. Рядкове представлення екземпляра цього винятку міститиме зручне повідомлення про помилку. Крім того, він матиме такі доступні атрибути:

code

Числовий код помилки від аналізатора expat. Перегляньте документацію xml.parsers.expat, щоб переглянути список кодів помилок та їх значення.

position

Кортеж чисел рядка, стовпця, що вказує, де сталася помилка.

Notas de rodapé