"xml.dom.pulldom" --- Support for building partial DOM trees
************************************************************

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

  O módulo "xml.dom.pulldom" não é seguro contra dados construídos de
  forma maliciosa. Se você precisa processar dados não-confiáveis ou
  sem autenticação, veja 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)

   Obsoleto desde a versão 3.8: Support for "sequence protocol" is
   deprecated.

   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>Some text <div>and more</div></p> </html>'
         doc = pulldom.parseString(xml)
         for event, node in doc:
             if event == pulldom.START_ELEMENT and node.tagName == 'p':
                 # Following statement only prints '<p/>'
                 print(node.toxml())
                 doc.expandNode(node)
                 # Following statement prints node with all its children '<p>Some text <div>and more</div></p>'
                 print(node.toxml())

   reset()
