"xml.dom.pulldom" --- 부분 DOM 트리 구축 지원
*********************************************

**소스 코드:** Lib/xml/dom/pulldom.py

======================================================================

The "xml.dom.pulldom" module provides a "pull parser" which can also
be asked to produce DOM-accessible fragments of the document where
necessary. The basic concept involves pulling "events" from a stream
of incoming XML and processing them. In contrast to SAX which also
employs an event-driven processing model together with callbacks, the
user of a pull parser is responsible for explicitly pulling events
from the stream, looping over those events until either processing is
finished or an error condition occurs.

참고:

  If you need to parse untrusted or unauthenticated data, see XML
  security.

버전 3.7.1에서 변경: SAX 구문 분석기는 보안을 강화하기 위해 더는 일반
외부 엔티티를 처리하지 않습니다. 외부 엔티티를 처리를 활성화하려면, 사
용자 정의 구문 분석기 인스턴스를 전달하십시오:

   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)

예:

   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" is one of the following constants, and "node" is the node
which the event is about. The nodes implement the "xml.dom"
interfaces; they are created by the DOM implementation given to
"PullDOM", which is "xml.dom.minidom" by default.

xml.dom.pulldom.START_DOCUMENT
xml.dom.pulldom.END_DOCUMENT

   The start and the end of the document. *node* is the "Document".

xml.dom.pulldom.START_ELEMENT
xml.dom.pulldom.END_ELEMENT

   The start tag and the end tag of an element. *node* is the
   "Element".

xml.dom.pulldom.CHARACTERS

   Character data. *node* is the "Text" node.

xml.dom.pulldom.IGNORABLE_WHITESPACE

   White space in element content, as declared in the DTD. *node* is
   the "Text" node.

xml.dom.pulldom.COMMENT

   A comment. *node* is the "Comment" node.

xml.dom.pulldom.PROCESSING_INSTRUCTION

   A processing instruction. *node* is the "ProcessingInstruction"
   node.

문서는 "평평한(flat)" 이벤트 스트림으로 취급되므로, 문서 "트리"는 묵시
적으로 탐색 되며 트리에서의 깊이와 관계없이 원하는 요소를 찾습니다. 다
시 말해, 문서 노드의 재귀적 검색과 같은 계층적 문제를 고려할 필요는 없
습니다. 하지만, 엘리먼트의 문맥이 중요하다면, 문맥과 관련된 상태를 유
지하거나 (즉, 주어진 지점에서 문서의 어느 위치에 있는지 기억함으로써),
"DOMEventStream.expandNode()" 메서드를 사용하고 DOM 관련 처리로 전환해
야 합니다.

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

   Subclass of "xml.sax.handler.ContentHandler" which turns SAX events
   into the events of the pull parser. The nodes are created, but they
   are not added to the tree, unless "expandNode()" is called.
   *documentFactory*, if given, is a DOM implementation used to create
   the document; by default the implementation of "xml.dom.minidom" is
   used.

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

   Subclass of "PullDOM" which also adds every created node to the
   tree, so that the complete document is built.

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

   주어진 입력으로부터 "DOMEventStream"을 반환합니다.
   *stream_or_string*은 파일 이름이거나 파일류 객체일 수 있습니다. 주
   어질 때, *parser*는 "XMLReader" 객체여야 합니다. 이 함수는 구문 분
   석기의 문서 처리기를 변경하고 이름 공간 지원을 활성화합니다; 다른
   구문 분석기 구성(엔티티 해석기 설정과 같은)은 미리 수행되어 있어야
   합니다.

문자열로 XML을 갖고 있다면, "parseString()" 함수를 대신 사용할 수 있습
니다:

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

   Return a "DOMEventStream" that represents the *string*. *string*
   must be a "str" instance; to parse bytes, pass a binary file object
   to "parse()".

xml.dom.pulldom.default_bufsize

   "parse()"의 *bufsize* 매개 변수의 기본값.

   이 변수의 값은 "parse()"를 호출하기 전에 변경될 수 있으며 새 값이
   적용됩니다.


DOMEventStream 객체
===================

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

   Produce the events for the data read from the file object *stream*
   by the "XMLReader" *parser*. The data is read by *bufsize* bytes,
   or characters for a text stream, at a time.

   버전 3.11에서 변경: "__getitem__()" 메서드 지원은 제거했습니다.

   getEvent()

      Return the next "(event, node)" tuple, or "None" at the end of
      the document. See above for the events and the corresponding
      nodes. The current node does not contain information about its
      children, unless "expandNode()" is called.

   expandNode(node)

      *node*의 모든 자식을 *node*로 확장합니다. 예:

         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':
                 # 다음 문장은 '<p/>' 만 인쇄합니다
                 print(node.toxml())
                 doc.expandNode(node)
                 # 다음 문장은 노드와 모든 자식을 인쇄합니다 '<p>Some text <div>and more</div></p>'
                 print(node.toxml())

   reset()

      Discard the events which are not read yet and prepare the object
      for parsing a new document.

   clear()

      Release the parser and the document. The stream is not closed,
      and the object can no longer be used.
