Debian Codegraph @

Doc/library/xml.dom.pulldom.rst

raw
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
7 .. moduleauthor:: Paul Prescod <[email protected]>
8
9 **Source code:** :source:`Lib/xml/dom/pulldom.py`
10
11 --------------
12
13 The :mod:`!xml.dom.pulldom` module provides a "pull parser" which can also be
14 asked to produce DOM-accessible fragments of the document where necessary. The
15 basic concept involves pulling "events" from a stream of incoming XML and
16 processing them. In contrast to SAX which also employs an event-driven
17 processing model together with callbacks, the user of a pull parser is
18 responsible for explicitly pulling events from the stream, looping over those
19 events until either processing is finished or an error condition occurs.
20
21
22 .. note::
23
24 If you need to parse untrusted or unauthenticated data, see
25 :ref:`xml-security`.
26
27 .. versionchanged:: 3.7.1
28
29 The SAX parser no longer processes general external entities by default to
30 increase security by default. To enable processing of external entities,
31 pass a custom parser instance in::
32
33 from xml.dom.pulldom import parse
34 from xml.sax import make_parser
35 from xml.sax.handler import feature_external_ges
36
37 parser = make_parser()
38 parser.setFeature(feature_external_ges, True)
39 parse(filename, parser=parser)
40
41
42 Example::
43
44 from xml.dom import pulldom
45
46 doc = pulldom.parse('sales_items.xml')
47 for event, node in doc:
48 if event == pulldom.START_ELEMENT and node.tagName == 'item':
49 if int(node.getAttribute('price')) > 50:
50 doc.expandNode(node)
51 print(node.toxml())
52
53 ``event`` is a constant and can be one of:
54
55 * :data:`START_ELEMENT`
56 * :data:`END_ELEMENT`
57 * :data:`COMMENT`
58 * :data:`START_DOCUMENT`
59 * :data:`END_DOCUMENT`
60 * :data:`CHARACTERS`
61 * :data:`PROCESSING_INSTRUCTION`
62 * :data:`IGNORABLE_WHITESPACE`
63
64 ``node`` is an object of type :class:`xml.dom.minidom.Document`,
65 :class:`xml.dom.minidom.Element` or :class:`xml.dom.minidom.Text`.
66
67 Since the document is treated as a "flat" stream of events, the document "tree"
68 is implicitly traversed and the desired elements are found regardless of their
69 depth in the tree. In other words, one does not need to consider hierarchical
70 issues such as recursive searching of the document nodes, although if the
71 context of elements were important, one would either need to maintain some
72 context-related state (i.e. remembering where one is in the document at any
73 given point) or to make use of the :func:`DOMEventStream.expandNode` method
74 and switch to DOM-related processing.
75
76
77 .. class:: PullDOM(documentFactory=None)
78
79 Subclass of :class:`xml.sax.handler.ContentHandler`.
80
81
82 .. class:: SAX2DOM(documentFactory=None)
83
84 Subclass of :class:`xml.sax.handler.ContentHandler`.
85
86
87 .. function:: parse(stream_or_string, parser=None, bufsize=None)
88
89 Return a :class:`DOMEventStream` from the given input. *stream_or_string* may be
90 either a file name, or a file-like object. *parser*, if given, must be an
91 :class:`~xml.sax.xmlreader.XMLReader` object. This function will change the
92 document handler of the
93 parser and activate namespace support; other parser configuration (like
94 setting an entity resolver) must have been done in advance.
95
96 If you have XML in a string, you can use the :func:`parseString` function instead:
97
98 .. function:: parseString(string, parser=None)
99
100 Return a :class:`DOMEventStream` that represents the (Unicode) *string*.
101
102 .. data:: default_bufsize
103
104 Default value for the *bufsize* parameter to :func:`parse`.
105
106 The value of this variable can be changed before calling :func:`parse` and
107 the new value will take effect.
108
109 .. _domeventstream-objects:
110
111 DOMEventStream Objects
112 ----------------------
113
114 .. class:: DOMEventStream(stream, parser, bufsize)
115
116 .. versionchanged:: 3.11
117 Support for :meth:`~object.__getitem__` method has been removed.
118
119 .. method:: getEvent()
120
121 Return a tuple containing *event* and the current *node* as
122 :class:`xml.dom.minidom.Document` if event equals :data:`START_DOCUMENT`,
123 :class:`xml.dom.minidom.Element` if event equals :data:`START_ELEMENT` or
124 :data:`END_ELEMENT` or :class:`xml.dom.minidom.Text` if event equals
125 :data:`CHARACTERS`.
126 The current node does not contain information about its children, unless
127 :func:`expandNode` is called.
128
129 .. method:: expandNode(node)
130
131 Expands all children of *node* into *node*. Example::
132
133 from xml.dom import pulldom
134
135 xml = '<html><title>Foo</title> <p>Some text <div>and more</div></p> </html>'
136 doc = pulldom.parseString(xml)
137 for event, node in doc:
138 if event == pulldom.START_ELEMENT and node.tagName == 'p':
139 # Following statement only prints '<p/>'
140 print(node.toxml())
141 doc.expandNode(node)
142 # Following statement prints node with all its children '<p>Some text <div>and more</div></p>'
143 print(node.toxml())
144
145 .. method:: DOMEventStream.reset()