Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`xml.sax.saxutils` --- SAX Utilities |
| 2 | ========================================= |
| 3 | |
| 4 | .. module:: xml.sax.saxutils |
| 5 | :synopsis: Convenience functions and classes for use with SAX. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Lars Marius Garshol <larsga@garshol.priv.no> |
| 8 | .. sectionauthor:: Martin v. Lรถwis <martin@v.loewis.de> |
| 9 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 10 | **Source code:** :source:`Lib/xml/sax/saxutils.py` |
| 11 | |
| 12 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | The module :mod:`xml.sax.saxutils` contains a number of classes and functions |
| 15 | that are commonly useful when creating SAX applications, either in direct use, |
| 16 | or as base classes. |
| 17 | |
| 18 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 19 | .. function:: escape(data, entities={}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
| 21 | Escape ``'&'``, ``'<'``, and ``'>'`` in a string of data. |
| 22 | |
| 23 | You can escape other strings of data by passing a dictionary as the optional |
| 24 | *entities* parameter. The keys and values must all be strings; each key will be |
Christian Heimes | fdab48e | 2008-01-20 09:06:41 +0000 | [diff] [blame] | 25 | replaced with its corresponding value. The characters ``'&'``, ``'<'`` and |
| 26 | ``'>'`` are always escaped, even if *entities* is provided. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | |
| 28 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 29 | .. function:: unescape(data, entities={}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
| 31 | Unescape ``'&'``, ``'<'``, and ``'>'`` in a string of data. |
| 32 | |
| 33 | You can unescape other strings of data by passing a dictionary as the optional |
| 34 | *entities* parameter. The keys and values must all be strings; each key will be |
Christian Heimes | fdab48e | 2008-01-20 09:06:41 +0000 | [diff] [blame] | 35 | replaced with its corresponding value. ``'&'``, ``'<'``, and ``'>'`` |
| 36 | are always unescaped, even if *entities* is provided. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 39 | .. function:: quoteattr(data, entities={}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
| 41 | Similar to :func:`escape`, but also prepares *data* to be used as an |
| 42 | attribute value. The return value is a quoted version of *data* with any |
| 43 | additional required replacements. :func:`quoteattr` will select a quote |
| 44 | character based on the content of *data*, attempting to avoid encoding any |
| 45 | quote characters in the string. If both single- and double-quote characters |
| 46 | are already in *data*, the double-quote characters will be encoded and *data* |
| 47 | will be wrapped in double-quotes. The resulting string can be used directly |
| 48 | as an attribute value:: |
| 49 | |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 50 | >>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef")) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 51 | <element attr="ab ' cd " ef"> |
| 52 | |
| 53 | This function is useful when generating attribute values for HTML or any SGML |
| 54 | using the reference concrete syntax. |
| 55 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
R. David Murray | a90032a | 2010-10-17 22:46:45 +0000 | [diff] [blame] | 57 | .. class:: XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 58 | |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 59 | This class implements the :class:`~xml.sax.handler.ContentHandler` interface |
| 60 | by writing SAX |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | events back into an XML document. In other words, using an :class:`XMLGenerator` |
| 62 | as the content handler will reproduce the original document being parsed. *out* |
| 63 | should be a file-like object which will default to *sys.stdout*. *encoding* is |
| 64 | the encoding of the output stream which defaults to ``'iso-8859-1'``. |
R. David Murray | a90032a | 2010-10-17 22:46:45 +0000 | [diff] [blame] | 65 | *short_empty_elements* controls the formatting of elements that contain no |
Serhiy Storchaka | a97cd2e | 2016-10-19 16:43:42 +0300 | [diff] [blame] | 66 | content: if ``False`` (the default) they are emitted as a pair of start/end |
| 67 | tags, if set to ``True`` they are emitted as a single self-closed tag. |
R. David Murray | a90032a | 2010-10-17 22:46:45 +0000 | [diff] [blame] | 68 | |
| 69 | .. versionadded:: 3.2 |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 70 | The *short_empty_elements* parameter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
| 72 | |
| 73 | .. class:: XMLFilterBase(base) |
| 74 | |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 75 | This class is designed to sit between an |
| 76 | :class:`~xml.sax.xmlreader.XMLReader` and the client |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | application's event handlers. By default, it does nothing but pass requests up |
| 78 | to the reader and events on to the handlers unmodified, but subclasses can |
| 79 | override specific methods to modify the event stream or the configuration |
| 80 | requests as they pass through. |
| 81 | |
| 82 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 83 | .. function:: prepare_input_source(source, base='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
Serhiy Storchaka | 15e6590 | 2013-08-29 10:28:44 +0300 | [diff] [blame] | 85 | This function takes an input source and an optional base URL and returns a |
| 86 | fully resolved :class:`~xml.sax.xmlreader.InputSource` object ready for |
| 87 | reading. The input source can be given as a string, a file-like object, or |
| 88 | an :class:`~xml.sax.xmlreader.InputSource` object; parsers will use this |
| 89 | function to implement the polymorphic *source* argument to their |
| 90 | :meth:`parse` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |