Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/xmlsaxutils.tex @ 27998:e27f58a50737 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SF bug #690377: Dud footnote reference in distutils docs
author Raymond Hettinger <python@rcn.com>
date Fri, 21 Feb 2003 02:47:09 +0000
parents 7049268f252d
children 462a4c3118bb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
15183
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{xml.sax.saxutils} ---
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 SAX Utilities}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{xml.sax.saxutils}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \modulesynopsis{Convenience functions and classes for use with SAX.}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 \moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 \versionadded{2.0}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 The module \module{xml.sax.saxutils} contains a number of classes and
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 functions that are commonly useful when creating SAX applications,
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 either in direct use, or as base classes.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 \begin{funcdesc}{escape}{data\optional{, entities}}
18740
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
17 Escape \character{\&}, \character{<}, and \character{>} in a string
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
18 of data.
15183
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 You can escape other strings of data by passing a dictionary as the
18740
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
21 optional \var{entities} parameter. The keys and values must all be
15183
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 strings; each key will be replaced with its corresponding value.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 \end{funcdesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24
25927
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
25 \begin{funcdesc}{unescape}{data\optional{, entities}}
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
26 Unescape \character{\&amp;}, \character{\&lt;}, and \character{\&gt;}
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
27 in a string of data.
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
28
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
29 You can unescape other strings of data by passing a dictionary as the
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
30 optional \var{entities} parameter. The keys and values must all be
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
31 strings; each key will be replaced with its corresponding value.
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
32
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
33 \versionadded{2.3}
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
34 \end{funcdesc}
7049268f252d Patch #613256: Add nescape method to xml.sax.saxutils.
Martin v. Löwis <martin@v.loewis.de>
parents: 19159
diff changeset
35
18740
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
36 \begin{funcdesc}{quoteattr}{data\optional{, entities}}
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
37 Similar to \function{escape()}, but also prepares \var{data} to be
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
38 used as an attribute value. The return value is a quoted version of
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
39 \var{data} with any additional required replacements.
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
40 \function{quoteattr()} will select a quote character based on the
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
41 content of \var{data}, attempting to avoid encoding any quote
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
42 characters in the string. If both single- and double-quote
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
43 characters are already in \var{data}, the double-quote characters
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
44 will be encoded and \var{data} will be wrapped in doule-quotes. The
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
45 resulting string can be used directly as an attribute value:
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
46
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
47 \begin{verbatim}
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
48 >>> print "<element attr=%s>" % quoteattr("ab ' cd \" ef")
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
49 <element attr="ab ' cd &quot; ef">
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
50 \end{verbatim}
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
51
19159
3537062b3dc1 Add a note that the quoteattr() function is useful for HTML and SGML
Fred Drake <fdrake@acm.org>
parents: 18740
diff changeset
52 This function is useful when generating attribute values for HTML or
3537062b3dc1 Add a note that the quoteattr() function is useful for HTML and SGML
Fred Drake <fdrake@acm.org>
parents: 18740
diff changeset
53 any SGML using the reference concrete syntax.
18740
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
54 \versionadded{2.2}
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
55 \end{funcdesc}
1aa7e219f52d Added function xml.sax.saxutils.quoteattr().
Fred Drake <fdrake@acm.org>
parents: 15183
diff changeset
56
15183
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 \begin{classdesc}{XMLGenerator}{\optional{out\optional{, encoding}}}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 This class implements the \class{ContentHandler} interface by
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 writing SAX events back into an XML document. In other words, using
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 an \class{XMLGenerator} as the content handler will reproduce the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 original document being parsed. \var{out} should be a file-like
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62 object which will default to \var{sys.stdout}. \var{encoding} is the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 encoding of the output stream which defaults to \code{'iso-8859-1'}.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 \end{classdesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 \begin{classdesc}{XMLFilterBase}{base}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 This class is designed to sit between an \class{XMLReader} and the
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 client application's event handlers. By default, it does nothing
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 but pass requests up to the reader and events on to the handlers
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 unmodified, but subclasses can override specific methods to modify
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 the event stream or the configuration requests as they pass through.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 \end{classdesc}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 \begin{funcdesc}{prepare_input_source}{source\optional{, base}}
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 This function takes an input source and an optional base URL and
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 returns a fully resolved \class{InputSource} object ready for
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77 reading. The input source can be given as a string, a file-like
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 object, or an \class{InputSource} object; parsers will use this
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 function to implement the polymorphic \var{source} argument to their
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \method{parse()} method.
4d2187264cfa Massive addition of SAX documentation from Martin von Loewis
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 \end{funcdesc}