| 1 |
:mod:`!xml.sax.saxutils` --- SAX Utilities |
| 2 |
========================================== |
| 3 |
|
| 4 |
.. module:: xml.sax.saxutils |
| 5 |
:synopsis: Convenience functions and classes for use with SAX. |
| 6 |
|
| 7 |
.. moduleauthor:: Lars Marius Garshol <[email protected]> |
| 8 |
.. sectionauthor:: Martin v. Löwis <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/xml/sax/saxutils.py` |
| 11 |
|
| 12 |
-------------- |
| 13 |
|
| 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 |
|
| 19 |
.. function:: escape(data, entities={}) |
| 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 |
| 25 |
replaced with its corresponding value. The characters ``'&'``, ``'<'`` and |
| 26 |
``'>'`` are always escaped, even if *entities* is provided. |
| 27 |
|
| 28 |
.. note:: |
| 29 |
|
| 30 |
This function should only be used to escape characters that |
| 31 |
can't be used directly in XML. Do not use this function as a general |
| 32 |
string translation function. |
| 33 |
|
| 34 |
.. function:: unescape(data, entities={}) |
| 35 |
|
| 36 |
Unescape ``'&'``, ``'<'``, and ``'>'`` in a string of data. |
| 37 |
|
| 38 |
You can unescape other strings of data by passing a dictionary as the optional |
| 39 |
*entities* parameter. The keys and values must all be strings; each key will be |
| 40 |
replaced with its corresponding value. ``'&'``, ``'<'``, and ``'>'`` |
| 41 |
are always unescaped, even if *entities* is provided. |
| 42 |
|
| 43 |
|
| 44 |
.. function:: quoteattr(data, entities={}) |
| 45 |
|
| 46 |
Similar to :func:`escape`, but also prepares *data* to be used as an |
| 47 |
attribute value. The return value is a quoted version of *data* with any |
| 48 |
additional required replacements. :func:`quoteattr` will select a quote |
| 49 |
character based on the content of *data*, attempting to avoid encoding any |
| 50 |
quote characters in the string. If both single- and double-quote characters |
| 51 |
are already in *data*, the double-quote characters will be encoded and *data* |
| 52 |
will be wrapped in double-quotes. The resulting string can be used directly |
| 53 |
as an attribute value:: |
| 54 |
|
| 55 |
>>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef")) |
| 56 |
<element attr="ab ' cd " ef"> |
| 57 |
|
| 58 |
This function is useful when generating attribute values for HTML or any SGML |
| 59 |
using the reference concrete syntax. |
| 60 |
|
| 61 |
|
| 62 |
.. class:: XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False) |
| 63 |
|
| 64 |
This class implements the :class:`~xml.sax.handler.ContentHandler` interface |
| 65 |
by writing SAX |
| 66 |
events back into an XML document. In other words, using an :class:`XMLGenerator` |
| 67 |
as the content handler will reproduce the original document being parsed. *out* |
| 68 |
should be a file-like object which will default to *sys.stdout*. *encoding* is |
| 69 |
the encoding of the output stream which defaults to ``'iso-8859-1'``. |
| 70 |
*short_empty_elements* controls the formatting of elements that contain no |
| 71 |
content: if ``False`` (the default) they are emitted as a pair of start/end |
| 72 |
tags, if set to ``True`` they are emitted as a single self-closed tag. |
| 73 |
|
| 74 |
.. versionchanged:: 3.2 |
| 75 |
Added the *short_empty_elements* parameter. |
| 76 |
|
| 77 |
|
| 78 |
.. class:: XMLFilterBase(base) |
| 79 |
|
| 80 |
This class is designed to sit between an |
| 81 |
:class:`~xml.sax.xmlreader.XMLReader` and the client |
| 82 |
application's event handlers. By default, it does nothing but pass requests up |
| 83 |
to the reader and events on to the handlers unmodified, but subclasses can |
| 84 |
override specific methods to modify the event stream or the configuration |
| 85 |
requests as they pass through. |
| 86 |
|
| 87 |
|
| 88 |
.. function:: prepare_input_source(source, base='') |
| 89 |
|
| 90 |
This function takes an input source and an optional base URL and returns a |
| 91 |
fully resolved :class:`~xml.sax.xmlreader.InputSource` object ready for |
| 92 |
reading. The input source can be given as a string, a file-like object, or |
| 93 |
an :class:`~xml.sax.xmlreader.InputSource` object; parsers will use this |
| 94 |
function to implement the polymorphic *source* argument to their |
| 95 |
:meth:`~xml.sax.xmlreader.XMLReader.parse` method. |
| 96 |
|