« back to all changes in this revision
Viewing changes to Doc/library/xmllib.rst
- browse files at revision 39019
- compare with another revision
- download diff
- download tarball
- view history from revision 39019
- Committer: benjamin.peterson
- Date: 2008-04-25 01:29:10 UTC
- Revision ID: svn-v3-trunk1:6015fed2-1504-0410-9fe1-9d1591cc4771:python%2Ftrunk:62490
reformat some documentation of classes so methods and attributes are under the class directive
- files modified:
- Doc/library/asynchat.rst
added
removed
Doc/library/xmllib.rst
28
28
29
29
The :class:`XMLParser` class must be instantiated without arguments. [#]_
30
30
31
This class provides the following interface methods and instance variables:
32
33
34
.. attribute:: XMLParser.attributes
35
36
A mapping of element names to mappings. The latter mapping maps attribute names
37
that are valid for the element to the default value of the attribute, or if
38
there is no default to ``None``. The default value is the empty dictionary.
39
This variable is meant to be overridden, not extended since the default is
40
shared by all instances of :class:`XMLParser`.
41
42
43
.. attribute:: XMLParser.elements
44
45
A mapping of element names to tuples. The tuples contain a function for
46
handling the start and end tag respectively of the element, or ``None`` if the
47
method :meth:`unknown_starttag` or :meth:`unknown_endtag` is to be called. The
48
default value is the empty dictionary. This variable is meant to be overridden,
49
not extended since the default is shared by all instances of :class:`XMLParser`.
50
51
52
.. attribute:: XMLParser.entitydefs
53
54
A mapping of entitynames to their values. The default value contains
55
definitions for ``'lt'``, ``'gt'``, ``'amp'``, ``'quot'``, and ``'apos'``.
56
57
58
.. method:: XMLParser.reset()
59
60
Reset the instance. Loses all unprocessed data. This is called implicitly at
61
the instantiation time.
62
63
64
.. method:: XMLParser.setnomoretags()
65
66
Stop processing tags. Treat all following input as literal input (CDATA).
67
68
69
.. method:: XMLParser.setliteral()
70
71
Enter literal mode (CDATA mode). This mode is automatically exited when the
72
close tag matching the last unclosed open tag is encountered.
73
74
75
.. method:: XMLParser.feed(data)
76
77
Feed some text to the parser. It is processed insofar as it consists of
78
complete tags; incomplete data is buffered until more data is fed or
79
:meth:`close` is called.
80
81
82
.. method:: XMLParser.close()
83
84
Force processing of all buffered data as if it were followed by an end-of-file
85
mark. This method may be redefined by a derived class to define additional
86
processing at the end of the input, but the redefined version should always call
87
:meth:`close`.
88
89
90
.. method:: XMLParser.translate_references(data)
91
92
Translate all entity and character references in *data* and return the
93
translated string.
94
95
96
.. method:: XMLParser.getnamespace()
97
98
Return a mapping of namespace abbreviations to namespace URIs that are currently
99
in effect.
100
101
102
.. method:: XMLParser.handle_xml(encoding, standalone)
103
104
This method is called when the ``<?xml ...?>`` tag is processed. The arguments
105
are the values of the encoding and standalone attributes in the tag. Both
106
encoding and standalone are optional. The values passed to :meth:`handle_xml`
107
default to ``None`` and the string ``'no'`` respectively.
108
109
110
.. method:: XMLParser.handle_doctype(tag, pubid, syslit, data)
111
112
.. index::
113
single: DOCTYPE declaration
114
single: Formal Public Identifier
115
116
This method is called when the ``<!DOCTYPE...>`` declaration is processed. The
117
arguments are the tag name of the root element, the Formal Public Identifier (or
118
``None`` if not specified), the system identifier, and the uninterpreted
119
contents of the internal DTD subset as a string (or ``None`` if not present).
120
121
122
.. method:: XMLParser.handle_starttag(tag, method, attributes)
123
124
This method is called to handle start tags for which a start tag handler is
125
defined in the instance variable :attr:`elements`. The *tag* argument is the
126
name of the tag, and the *method* argument is the function (method) which should
127
be used to support semantic interpretation of the start tag. The *attributes*
128
argument is a dictionary of attributes, the key being the *name* and the value
129
being the *value* of the attribute found inside the tag's ``<>`` brackets.
130
Character and entity references in the *value* have been interpreted. For
131
instance, for the start tag ``<A HREF="http://www.cwi.nl/">``, this method would
132
be called as ``handle_starttag('A', self.elements['A'][0], {'HREF':
133
'http://www.cwi.nl/'})``. The base implementation simply calls *method* with
134
*attributes* as the only argument.
135
136
137
.. method:: XMLParser.handle_endtag(tag, method)
138
139
This method is called to handle endtags for which an end tag handler is defined
140
in the instance variable :attr:`elements`. The *tag* argument is the name of
141
the tag, and the *method* argument is the function (method) which should be used
142
to support semantic interpretation of the end tag. For instance, for the endtag
143
``</A>``, this method would be called as ``handle_endtag('A',
144
self.elements['A'][1])``. The base implementation simply calls *method*.
145
146
147
.. method:: XMLParser.handle_data(data)
148
149
This method is called to process arbitrary data. It is intended to be
150
overridden by a derived class; the base class implementation does nothing.
151
152
153
.. method:: XMLParser.handle_charref(ref)
154
155
This method is called to process a character reference of the form ``&#ref;``.
156
*ref* can either be a decimal number, or a hexadecimal number when preceded by
157
an ``'x'``. In the base implementation, *ref* must be a number in the range
158
0-255. It translates the character to ASCII and calls the method
159
:meth:`handle_data` with the character as argument. If *ref* is invalid or out
160
of range, the method ``unknown_charref(ref)`` is called to handle the error. A
161
subclass must override this method to provide support for character references
162
outside of the ASCII range.
163
164
165
.. method:: XMLParser.handle_comment(comment)
166
167
This method is called when a comment is encountered. The *comment* argument is
168
a string containing the text between the ``<!--`` and ``-->`` delimiters, but
169
not the delimiters themselves. For example, the comment ``<!--text-->`` will
170
cause this method to be called with the argument ``'text'``. The default method
171
does nothing.
172
173
174
.. method:: XMLParser.handle_cdata(data)
175
176
This method is called when a CDATA element is encountered. The *data* argument
177
is a string containing the text between the ``<![CDATA[`` and ``]]>``
178
delimiters, but not the delimiters themselves. For example, the entity
179
``<![CDATA[text]]>`` will cause this method to be called with the argument
180
``'text'``. The default method does nothing, and is intended to be overridden.
181
182
183
.. method:: XMLParser.handle_proc(name, data)
184
185
This method is called when a processing instruction (PI) is encountered. The
186
*name* is the PI target, and the *data* argument is a string containing the text
187
between the PI target and the closing delimiter, but not the delimiter itself.
188
For example, the instruction ``<?XML text?>`` will cause this method to be
189
called with the arguments ``'XML'`` and ``'text'``. The default method does
190
nothing. Note that if a document starts with ``<?xml ..?>``, :meth:`handle_xml`
191
is called to handle it.
192
193
194
.. method:: XMLParser.handle_special(data)
195
196
.. index:: single: ENTITY declaration
197
198
This method is called when a declaration is encountered. The *data* argument is
199
a string containing the text between the ``<!`` and ``>`` delimiters, but not
200
the delimiters themselves. For example, the entity declaration ``<!ENTITY
201
text>`` will cause this method to be called with the argument ``'ENTITY text'``.
202
The default method does nothing. Note that ``<!DOCTYPE ...>`` is handled
203
separately if it is located at the start of the document.
204
205
206
.. method:: XMLParser.syntax_error(message)
207
208
This method is called when a syntax error is encountered. The *message* is a
209
description of what was wrong. The default method raises a :exc:`RuntimeError`
210
exception. If this method is overridden, it is permissible for it to return.
211
This method is only called when the error can be recovered from. Unrecoverable
212
errors raise a :exc:`RuntimeError` without first calling :meth:`syntax_error`.
213
214
215
.. method:: XMLParser.unknown_starttag(tag, attributes)
216
217
This method is called to process an unknown start tag. It is intended to be
218
overridden by a derived class; the base class implementation does nothing.
219
220
221
.. method:: XMLParser.unknown_endtag(tag)
222
223
This method is called to process an unknown end tag. It is intended to be
224
overridden by a derived class; the base class implementation does nothing.
225
226
227
.. method:: XMLParser.unknown_charref(ref)
228
229
This method is called to process unresolvable numeric character references. It
230
is intended to be overridden by a derived class; the base class implementation
231
does nothing.
232
233
234
.. method:: XMLParser.unknown_entityref(ref)
235
236
This method is called to process an unknown entity reference. It is intended to
237
be overridden by a derived class; the base class implementation calls
238
:meth:`syntax_error` to signal an error.
31
This class provides the following interface methods and instance variables:
32
33
34
.. attribute:: attributes
35
36
A mapping of element names to mappings. The latter mapping maps attribute
37
names that are valid for the element to the default value of the
38
attribute, or if there is no default to ``None``. The default value is
39
the empty dictionary. This variable is meant to be overridden, not
40
extended since the default is shared by all instances of
41
:class:`XMLParser`.
42
43
44
.. attribute:: elements
45
46
A mapping of element names to tuples. The tuples contain a function for
47
handling the start and end tag respectively of the element, or ``None`` if
48
the method :meth:`unknown_starttag` or :meth:`unknown_endtag` is to be
49
called. The default value is the empty dictionary. This variable is
50
meant to be overridden, not extended since the default is shared by all
51
instances of :class:`XMLParser`.
52
53
54
.. attribute:: entitydefs
55
56
A mapping of entitynames to their values. The default value contains
57
definitions for ``'lt'``, ``'gt'``, ``'amp'``, ``'quot'``, and ``'apos'``.
58
59
60
.. method:: reset()
61
62
Reset the instance. Loses all unprocessed data. This is called
63
implicitly at the instantiation time.
64
65
66
.. method:: setnomoretags()
67
68
Stop processing tags. Treat all following input as literal input (CDATA).
69
70
71
.. method:: setliteral()
72
73
Enter literal mode (CDATA mode). This mode is automatically exited when
74
the close tag matching the last unclosed open tag is encountered.
75
76
77
.. method:: feed(data)
78
79
Feed some text to the parser. It is processed insofar as it consists of
80
complete tags; incomplete data is buffered until more data is fed or
81
:meth:`close` is called.
82
83
84
.. method:: close()
85
86
Force processing of all buffered data as if it were followed by an
87
end-of-file mark. This method may be redefined by a derived class to
88
define additional processing at the end of the input, but the redefined
89
version should always call :meth:`close`.
90
91
92
.. method:: translate_references(data)
93
94
Translate all entity and character references in *data* and return the
95
translated string.
96
97
98
.. method:: getnamespace()
99
100
Return a mapping of namespace abbreviations to namespace URIs that are
101
currently in effect.
102
103
104
.. method:: handle_xml(encoding, standalone)
105
106
This method is called when the ``<?xml ...?>`` tag is processed. The
107
arguments are the values of the encoding and standalone attributes in the
108
tag. Both encoding and standalone are optional. The values passed to
109
:meth:`handle_xml` default to ``None`` and the string ``'no'``
110
respectively.
111
112
113
.. method:: handle_doctype(tag, pubid, syslit, data)
114
115
.. index::
116
single: DOCTYPE declaration
117
single: Formal Public Identifier
118
119
This method is called when the ``<!DOCTYPE...>`` declaration is processed.
120
The arguments are the tag name of the root element, the Formal Public
121
Identifier (or ``None`` if not specified), the system identifier, and the
122
uninterpreted contents of the internal DTD subset as a string (or ``None``
123
if not present).
124
125
126
.. method:: handle_starttag(tag, method, attributes)
127
128
This method is called to handle start tags for which a start tag handler
129
is defined in the instance variable :attr:`elements`. The *tag* argument
130
is the name of the tag, and the *method* argument is the function (method)
131
which should be used to support semantic interpretation of the start tag.
132
The *attributes* argument is a dictionary of attributes, the key being the
133
*name* and the value being the *value* of the attribute found inside the
134
tag's ``<>`` brackets. Character and entity references in the *value*
135
have been interpreted. For instance, for the start tag ``<A
136
HREF="http://www.cwi.nl/">``, this method would be called as
137
``handle_starttag('A', self.elements['A'][0], {'HREF':
138
'http://www.cwi.nl/'})``. The base implementation simply calls *method*
139
with *attributes* as the only argument.
140
141
142
.. method:: handle_endtag(tag, method)
143
144
This method is called to handle endtags for which an end tag handler is
145
defined in the instance variable :attr:`elements`. The *tag* argument is
146
the name of the tag, and the *method* argument is the function (method)
147
which should be used to support semantic interpretation of the end tag.
148
For instance, for the endtag ``</A>``, this method would be called as
149
``handle_endtag('A', self.elements['A'][1])``. The base implementation
150
simply calls *method*.
151
152
153
.. method:: handle_data(data)
154
155
This method is called to process arbitrary data. It is intended to be
156
overridden by a derived class; the base class implementation does nothing.
157
158
159
.. method:: handle_charref(ref)
160
161
This method is called to process a character reference of the form
162
``&#ref;``. *ref* can either be a decimal number, or a hexadecimal number
163
when preceded by an ``'x'``. In the base implementation, *ref* must be a
164
number in the range 0-255. It translates the character to ASCII and calls
165
the method :meth:`handle_data` with the character as argument. If *ref*
166
is invalid or out of range, the method ``unknown_charref(ref)`` is called
167
to handle the error. A subclass must override this method to provide
168
support for character references outside of the ASCII range.
169
170
171
.. method:: handle_comment(comment)
172
173
This method is called when a comment is encountered. The *comment*
174
argument is a string containing the text between the ``<!--`` and ``-->``
175
delimiters, but not the delimiters themselves. For example, the comment
176
``<!--text-->`` will cause this method to be called with the argument
177
``'text'``. The default method does nothing.
178
179
180
.. method:: handle_cdata(data)
181
182
This method is called when a CDATA element is encountered. The *data*
183
argument is a string containing the text between the ``<![CDATA[`` and
184
``]]>`` delimiters, but not the delimiters themselves. For example, the
185
entity ``<![CDATA[text]]>`` will cause this method to be called with the
186
argument ``'text'``. The default method does nothing, and is intended to
187
be overridden.
188
189
190
.. method:: handle_proc(name, data)
191
192
This method is called when a processing instruction (PI) is encountered.
193
The *name* is the PI target, and the *data* argument is a string
194
containing the text between the PI target and the closing delimiter, but
195
not the delimiter itself. For example, the instruction ``<?XML text?>``
196
will cause this method to be called with the arguments ``'XML'`` and
197
``'text'``. The default method does nothing. Note that if a document
198
starts with ``<?xml ..?>``, :meth:`handle_xml` is called to handle it.
199
200
201
.. method:: handle_special(data)
202
203
.. index:: single: ENTITY declaration
204
205
This method is called when a declaration is encountered. The *data*
206
argument is a string containing the text between the ``<!`` and ``>``
207
delimiters, but not the delimiters themselves. For example, the entity
208
declaration ``<!ENTITY text>`` will cause this method to be called with
209
the argument ``'ENTITY text'``. The default method does nothing. Note
210
that ``<!DOCTYPE ...>`` is handled separately if it is located at the
211
start of the document.
212
213
214
.. method:: syntax_error(message)
215
216
This method is called when a syntax error is encountered. The *message*
217
is a description of what was wrong. The default method raises a
218
:exc:`RuntimeError` exception. If this method is overridden, it is
219
permissible for it to return. This method is only called when the error
220
can be recovered from. Unrecoverable errors raise a :exc:`RuntimeError`
221
without first calling :meth:`syntax_error`.
222
223
224
.. method:: unknown_starttag(tag, attributes)
225
226
This method is called to process an unknown start tag. It is intended to
227
be overridden by a derived class; the base class implementation does nothing.
228
229
230
.. method:: unknown_endtag(tag)
231
232
This method is called to process an unknown end tag. It is intended to be
233
overridden by a derived class; the base class implementation does nothing.
234
235
236
.. method:: unknown_charref(ref)
237
238
This method is called to process unresolvable numeric character
239
references. It is intended to be overridden by a derived class; the base
240
class implementation does nothing.
241
242
243
.. method:: unknown_entityref(ref)
244
245
This method is called to process an unknown entity reference. It is
246
intended to be overridden by a derived class; the base class
247
implementation calls :meth:`syntax_error` to signal an error.
239
248
240
249
241
250
.. seealso::
Loggerhead is a web-based interface for Breezy
Version: 2.0.1