The :mod:`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.

Example::

``event`` is a constant and can be one of:

* :data:`START_ELEMENT`

* :data:`END_ELEMENT`

* :data:`COMMENT`

* :data:`START_DOCUMENT`

* :data:`END_DOCUMENT`

* :data:`CHARACTERS`

* :data:`PROCESSING_INSTRUCTION`

* :data:`IGNORABLE_WHITESPACE`

``node`` is a object of type :class:`xml.dom.minidom.Document`,

:class:`xml.dom.minidom.Element` or :class:`xml.dom.minidom.Text`.

Since the document is treated as a "flat" stream of events, the document "tree"

is implicitly traversed and the desired elements are found regardless of their

depth in the tree. In other words, one does not need to consider hierarchical issues

such as recursive searching of the document nodes, although if the context of

elements were important, one would either need to maintain some context-related

state (ie. remembering where one is in the document at any given point) or to

make use of the :func:`DOMEventStream.expandNode` method and switch to DOM-related processing.

.. class:: PullDom(documentFactory=None)

Subclass of :class:`xml.sax.handler.ContentHandler`.

Subclass of :class:`xml.sax.handler.ContentHandler`.

Return a :class:`DOMEventStream` from the given input. *stream_or_string* may be

either a file name, or a file-like object. *parser*, if given, must be a

:class:`XmlReader` object. This function will change the document handler of the

parser and activate namespace support; other parser configuration (like

setting an entity resolver) must have been done in advance.

If you have XML in a string, you can use the :func:`parseString` function instead:

Return a :class:`DOMEventStream` that represents the (unicode) *string*.

.. class:: DOMEventStream(stream, parser, bufsize)

.. method:: DOMEventStream.getEvent()

Return a tuple containing *event* and the current *node* as

:class:`xml.dom.minidom.Document` if event equals START_DOCUMENT,

:class:`xml.dom.minidom.Element` if event equals START_ELEMENT or

END_ELEMENT or :class:`xml.dom.minidom.Text` if event equals CHARACTERS.

The current node does not contain informations about its children, unless

:func:`expandNode` is called.

.. method:: DOMEventStream.expandNode(node)

Expands all children of *node* into *node*. Example::

.. method:: DOMEventStream.reset()