summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorEli Bendersky <eliben@gmail.com>2012-03-16 12:37:14 (GMT)
committerEli Bendersky <eliben@gmail.com>2012-03-16 12:37:14 (GMT)
commit3fb05a90cefe29bad82c87336fa32de36e6add3d (patch)
tree6d39b838602d5c692bd47d3e2cd87f2fae33ae01 /Doc/library
parentbe3f851411f54b71251743997c1e8b2485f99de2 (diff)
downloadcpython-3fb05a90cefe29bad82c87336fa32de36e6add3d.zip
cpython-3fb05a90cefe29bad82c87336fa32de36e6add3d.tar.gz
cpython-3fb05a90cefe29bad82c87336fa32de36e6add3d.tar.bz2
Issue #14202: Greatly enhance the documentation of xml.dom.pulldom.
Patch by Florian Mladitsch
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/xml.dom.pulldom.rst84
1 files changed, 68 insertions, 16 deletions
diff --git a/Doc/library/xml.dom.pulldom.rst b/Doc/library/xml.dom.pulldom.rst
index 4a5ef4c..7dd38c0 100644
--- a/Doc/library/xml.dom.pulldom.rst
+++ b/Doc/library/xml.dom.pulldom.rst
@@ -9,33 +9,72 @@
--------------
-:mod:`xml.dom.pulldom` allows building only selected portions of a Document
-Object Model representation of a document from SAX events.
+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::
-.. class:: PullDOM(documentFactory=None)
+ from xml.dom import pulldom
- :class:`xml.sax.handler.ContentHandler` implementation that ...
+ 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 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:: DOMEventStream(stream, parser, bufsize)
- ...
+.. class:: PullDom(documentFactory=None)
+
+ Subclass of :class:`xml.sax.handler.ContentHandler`.
.. class:: SAX2DOM(documentFactory=None)
- :class:`xml.sax.handler.ContentHandler` implementation that ...
+ Subclass of :class:`xml.sax.handler.ContentHandler`.
.. function:: parse(stream_or_string, parser=None, bufsize=None)
- ...
+ 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:
.. function:: parseString(string, parser=None)
- ...
+ Return a :class:`DOMEventStream` that represents the (unicode) *string*.
.. data:: default_bufsize
@@ -51,18 +90,31 @@ Object Model representation of a document from SAX events.
DOMEventStream Objects
----------------------
+.. class:: DOMEventStream(stream, parser, bufsize)
-.. method:: DOMEventStream.getEvent()
-
- ...
+ .. method:: DOMEventStream.getEvent()
-.. method:: DOMEventStream.expandNode(node)
+ 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()
+ 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.exandNode(node)
+ # Following statement prints node with all its children '<p>Some text <div>and more</div></p>'
+ print(node.toxml())
- ...
+ .. method:: DOMEventStream.reset()