|
1 |
|
2 :mod:`xml.sax.saxutils` --- SAX Utilities |
|
3 ========================================= |
|
4 |
|
5 .. module:: xml.sax.saxutils |
|
6 :synopsis: Convenience functions and classes for use with SAX. |
|
7 .. moduleauthor:: Lars Marius Garshol <larsga@garshol.priv.no> |
|
8 .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de> |
|
9 |
|
10 |
|
11 .. versionadded:: 2.0 |
|
12 |
|
13 The module :mod:`xml.sax.saxutils` contains a number of classes and functions |
|
14 that are commonly useful when creating SAX applications, either in direct use, |
|
15 or as base classes. |
|
16 |
|
17 |
|
18 .. function:: escape(data[, entities]) |
|
19 |
|
20 Escape ``'&'``, ``'<'``, and ``'>'`` in a string of data. |
|
21 |
|
22 You can escape other strings of data by passing a dictionary as the optional |
|
23 *entities* parameter. The keys and values must all be strings; each key will be |
|
24 replaced with its corresponding value. The characters ``'&'``, ``'<'`` and |
|
25 ``'>'`` are always escaped, even if *entities* is provided. |
|
26 |
|
27 |
|
28 .. function:: unescape(data[, entities]) |
|
29 |
|
30 Unescape ``'&'``, ``'<'``, and ``'>'`` in a string of data. |
|
31 |
|
32 You can unescape other strings of data by passing a dictionary as the optional |
|
33 *entities* parameter. The keys and values must all be strings; each key will be |
|
34 replaced with its corresponding value. ``'&'``, ``'<'``, and ``'>'`` |
|
35 are always unescaped, even if *entities* is provided. |
|
36 |
|
37 .. versionadded:: 2.3 |
|
38 |
|
39 |
|
40 .. function:: quoteattr(data[, entities]) |
|
41 |
|
42 Similar to :func:`escape`, but also prepares *data* to be used as an |
|
43 attribute value. The return value is a quoted version of *data* with any |
|
44 additional required replacements. :func:`quoteattr` will select a quote |
|
45 character based on the content of *data*, attempting to avoid encoding any |
|
46 quote characters in the string. If both single- and double-quote characters |
|
47 are already in *data*, the double-quote characters will be encoded and *data* |
|
48 will be wrapped in double-quotes. The resulting string can be used directly |
|
49 as an attribute value:: |
|
50 |
|
51 >>> print "<element attr=%s>" % quoteattr("ab ' cd \" ef") |
|
52 <element attr="ab ' cd " ef"> |
|
53 |
|
54 This function is useful when generating attribute values for HTML or any SGML |
|
55 using the reference concrete syntax. |
|
56 |
|
57 .. versionadded:: 2.2 |
|
58 |
|
59 |
|
60 .. class:: XMLGenerator([out[, encoding]]) |
|
61 |
|
62 This class implements the :class:`ContentHandler` interface by writing SAX |
|
63 events back into an XML document. In other words, using an :class:`XMLGenerator` |
|
64 as the content handler will reproduce the original document being parsed. *out* |
|
65 should be a file-like object which will default to *sys.stdout*. *encoding* is |
|
66 the encoding of the output stream which defaults to ``'iso-8859-1'``. |
|
67 |
|
68 |
|
69 .. class:: XMLFilterBase(base) |
|
70 |
|
71 This class is designed to sit between an :class:`XMLReader` and the client |
|
72 application's event handlers. By default, it does nothing but pass requests up |
|
73 to the reader and events on to the handlers unmodified, but subclasses can |
|
74 override specific methods to modify the event stream or the configuration |
|
75 requests as they pass through. |
|
76 |
|
77 |
|
78 .. function:: prepare_input_source(source[, base]) |
|
79 |
|
80 This function takes an input source and an optional base URL and returns a fully |
|
81 resolved :class:`InputSource` object ready for reading. The input source can be |
|
82 given as a string, a file-like object, or an :class:`InputSource` object; |
|
83 parsers will use this function to implement the polymorphic *source* argument to |
|
84 their :meth:`parse` method. |
|
85 |