xml.dom.pulldom — Suporte para construir árvores parciais de DOM

Código-fonte: Lib/xml/dom/pulldom.py

O módulo xml.dom.pulldom fornece um “analisador sintático de pull” que também pode ser solicitado a produzir fragmentos do documento acessíveis via DOM, quando necessário. O conceito básico envolve extrair “eventos” de um fluxo de XML recebido e processá-los. Ao contrário do SAX, que também emprega um modelo de processamento orientado a eventos juntamente com retornos de chamada, o usuário de um analisador sintático pull é responsável por extrair explicitamente os eventos do fluxo, repetindo esses eventos até que o processamento seja concluído ou ocorra uma condição de erro.

Aviso

The xml.dom.pulldom module is not secure against maliciously constructed data. If you need to parse untrusted or unauthenticated data see Vulnerabilidades em XML.

Alterado na versão 3.7.1: O analisador sintático de SAX não processa mais entidades externas gerais por padrão para aumentar a segurança. Para habilitar o processamento de entidades externas, passe uma instância personalizada do analisador sintático em:

from xml.dom.pulldom import parse
from xml.sax import make_parser
from xml.sax.handler import feature_external_ges

parser = make_parser()
parser.setFeature(feature_external_ges, True)
parse(filename, parser=parser)

Exemplo:

from xml.dom import pulldom

doc = pulldom.parse('sales_items.xml')
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'item':
        if int(node.getAttribute('price')) > 50:
            doc.expandNode(node)
            print(node.toxml())

event é uma constante e pode ser um de:

  • START_ELEMENT

  • END_ELEMENT

  • COMMENT

  • START_DOCUMENT

  • END_DOCUMENT

  • CHARACTERS

  • PROCESSING_INSTRUCTION

  • IGNORABLE_WHITESPACE

node é um objeto do tipo xml.dom.minidom.Document, xml.dom.minidom.Element ou xml.dom.minidom.Text.

Como o documento é tratado como um fluxo “plano” de eventos, a “árvore” do documento é implicitamente percorrida e os elementos desejados são encontrados independentemente de sua profundidade na árvore. Em outras palavras, não é necessário considerar questões hierárquicas, como a busca recursiva dos nós do documento, embora, se o contexto dos elementos fosse importante, seria necessário manter algum estado relacionado ao contexto (ou seja, lembrar onde se está no documento em um determinado ponto) ou utilizar o método DOMEventStream.expandNode() e alternar para o processamento relacionado ao DOM.

class xml.dom.pulldom.PullDom(documentFactory=None)

Subclasse de xml.sax.handler.ContentHandler.

class xml.dom.pulldom.SAX2DOM(documentFactory=None)

Subclasse de xml.sax.handler.ContentHandler.

xml.dom.pulldom.parse(stream_or_string, parser=None, bufsize=None)

Retorna um DOMEventStream da entrada fornecida. stream_or_string pode ser um nome de arquivo ou um objeto arquivo ou similar. parser, se fornecido, deve ser um objeto XMLReader. Esta função alterará o manipulador de documentos do analisador e ativará o suporte a espaços de nomes; outras configurações do analisador sintático (como a definição de um resolvedor de entidades) devem ter sido feitas previamente.

Se você tiver XML em uma string, poderá usar a função parseString():

xml.dom.pulldom.parseString(string, parser=None)

Retorna um DOMEventStream que representa a string (Unicode).

xml.dom.pulldom.default_bufsize

Valor padrão para o parâmetro bufsize para parse().

O valor desta variável pode ser alterado antes de chamar parse() e o novo valor entrará em vigor.

Objetos DOMEventStream

class xml.dom.pulldom.DOMEventStream(stream, parser, bufsize)

Alterado na versão 3.11: O suporte para o método __getitem__() foi removido

getEvent()

Retorna uma tupla contendo evento event e o nó node atual como xml.dom.minidom.Document se o evento for igual a START_DOCUMENT, xml.dom.minidom.Element se o evento for igual a START_ELEMENT ou END_ELEMENT ou xml.dom.minidom.Text se o evento for igual a CHARACTERS. O nó atual não contém informações sobre seus filhos, a menos que expandNode() seja chamado.

expandNode(node)

Expande todos os filhos de node para node. Exemplo:

from xml.dom import pulldom

xml = '<html><title>Foo</title> <p>Algum texto <div>e mais</div></p> </html>'
doc = pulldom.parseString(xml)
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'p':
        # A seguinte instrução só exibe '<p/>'
        print(node.toxml())
        doc.expandNode(node)
        # A seguinte instrução exibe o nó com todos os seus filhos '<p>Algum texto <div>e mais</div></p>'
        print(node.toxml())
reset()