Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / cpython3 / 349c802fd885e744b2a803bd41e8d234cc1688e9 / . / Doc / library / xml.dom.pulldom.rst
blob: eb16a0933da761e73ea687249304721a732e78f3 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]1:mod:`xml.dom.pulldom` --- Support for building partial DOM trees
2=================================================================
3
4.. module:: xml.dom.pulldom
5 :synopsis: Support for building partial DOM trees from SAX events.
6.. moduleauthor:: Paul Prescod <paul@prescod.net>
7
Raymond Hettinger3029aff2011-02-10 08:09:36 +0000[diff] [blame]8**Source code:** :source:`Lib/xml/dom/pulldom.py`
9
10--------------
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]11
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]12The :mod:`xml.dom.pulldom` module provides a "pull parser" which can also be
13asked to produce DOM-accessible fragments of the document where necessary. The
14basic concept involves pulling "events" from a stream of incoming XML and
15processing them. In contrast to SAX which also employs an event-driven
16processing model together with callbacks, the user of a pull parser is
17responsible for explicitly pulling events from the stream, looping over those
18events until either processing is finished or an error condition occurs.
19
20Example::
21
22 from xml.dom import pulldom
23
24 doc = pulldom.parse('sales_items.xml')
25 for event, node in doc:
26 if event == pulldom.START_ELEMENT and node.tagName == 'item':
27 if int(node.getAttribute('price')) > 50:
28 doc.expandNode(node)
29 print(node.toxml())
30
31``event`` is a constant and can be one of:
32
33* :data:`START_ELEMENT`
34* :data:`END_ELEMENT`
35* :data:`COMMENT`
36* :data:`START_DOCUMENT`
37* :data:`END_DOCUMENT`
38* :data:`CHARACTERS`
39* :data:`PROCESSING_INSTRUCTION`
40* :data:`IGNORABLE_WHITESPACE`
41
42``node`` is a object of type :class:`xml.dom.minidom.Document`,
43:class:`xml.dom.minidom.Element` or :class:`xml.dom.minidom.Text`.
44
45Since the document is treated as a "flat" stream of events, the document "tree"
46is implicitly traversed and the desired elements are found regardless of their
Eli Bendersky969b8da2012-03-16 16:49:58 +0200[diff] [blame]47depth in the tree. In other words, one does not need to consider hierarchical
48issues such as recursive searching of the document nodes, although if the
49context of elements were important, one would either need to maintain some
50context-related state (i.e. remembering where one is in the document at any
51given point) or to make use of the :func:`DOMEventStream.expandNode` method
52and switch to DOM-related processing.
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]53
54
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]55.. class:: PullDom(documentFactory=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]56
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]57 Subclass of :class:`xml.sax.handler.ContentHandler`.
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]58
59
Georg Brandl7f01a132009-09-16 15:58:14 +0000[diff] [blame]60.. class:: SAX2DOM(documentFactory=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]61
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]62 Subclass of :class:`xml.sax.handler.ContentHandler`.
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]63
64
Georg Brandl7f01a132009-09-16 15:58:14 +0000[diff] [blame]65.. function:: parse(stream_or_string, parser=None, bufsize=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]66
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]67 Return a :class:`DOMEventStream` from the given input. *stream_or_string* may be
68 either a file name, or a file-like object. *parser*, if given, must be a
69 :class:`XmlReader` object. This function will change the document handler of the
70 parser and activate namespace support; other parser configuration (like
71 setting an entity resolver) must have been done in advance.
72
73If you have XML in a string, you can use the :func:`parseString` function instead:
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]74
Georg Brandl7f01a132009-09-16 15:58:14 +0000[diff] [blame]75.. function:: parseString(string, parser=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]76
Eli Bendersky969b8da2012-03-16 16:49:58 +0200[diff] [blame]77 Return a :class:`DOMEventStream` that represents the (Unicode) *string*.
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]78
79.. data:: default_bufsize
80
81 Default value for the *bufsize* parameter to :func:`parse`.
82
Georg Brandl55ac8f02007-09-01 13:51:09 +0000[diff] [blame]83 The value of this variable can be changed before calling :func:`parse` and
84 the new value will take effect.
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]85
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]86.. _domeventstream-objects:
87
88DOMEventStream Objects
89----------------------
90
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]91.. class:: DOMEventStream(stream, parser, bufsize)
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]92
93
Eli Bendersky969b8da2012-03-16 16:49:58 +0200[diff] [blame]94 .. method:: getEvent()
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]95
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]96 Return a tuple containing *event* and the current *node* as
Eli Bendersky969b8da2012-03-16 16:49:58 +0200[diff] [blame]97 :class:`xml.dom.minidom.Document` if event equals :data:`START_DOCUMENT`,
98 :class:`xml.dom.minidom.Element` if event equals :data:`START_ELEMENT` or
99 :data:`END_ELEMENT` or :class:`xml.dom.minidom.Text` if event equals
100 :data:`CHARACTERS`.
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]101 The current node does not contain informations about its children, unless
102 :func:`expandNode` is called.
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]103
Eli Bendersky969b8da2012-03-16 16:49:58 +0200[diff] [blame]104 .. method:: expandNode(node)
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]105
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]106 Expands all children of *node* into *node*. Example::
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]107
Eli Bendersky3fb05a92012-03-16 14:37:14 +0200[diff] [blame]108 xml = '<html><title>Foo</title> <p>Some text <div>and more</div></p> </html>'
109 doc = pulldom.parseString(xml)
110 for event, node in doc:
111 if event == pulldom.START_ELEMENT and node.tagName == 'p':
112 # Following statement only prints '<p/>'
113 print(node.toxml())
114 doc.exandNode(node)
115 # Following statement prints node with all its children '<p>Some text <div>and more</div></p>'
116 print(node.toxml())
117
118 .. method:: DOMEventStream.reset()
Georg Brandl116aa622007-08-15 14:28:22 +0000[diff] [blame]119