Mercurial > genshi > genshi-test

comparison doc/streams.txt @ 500:0742f421caba experimental-inline

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged revisions 487-603 via svnmerge from http://svn.edgewall.org/repos/genshi/trunk
author cmlenz
date Fri, 01 Jun 2007 17:21:47 +0000
parents 55cf81951686
children 1837f39efd6f
comparison
equal deleted inserted replaced
499:869b7885a516 500:0742f421caba
16 ====== 16 ======
17 17
18 A stream can be attained in a number of ways. It can be: 18 A stream can be attained in a number of ways. It can be:
19 19
20 * the result of parsing XML or HTML text, or 20 * the result of parsing XML or HTML text, or
21 * programmatically generated, or 21 * the result of selecting a subset of another stream using XPath, or
22 * the result of selecting a subset of another stream filtered by an XPath 22 * programmatically generated.
23 expression.
24 23
25 For example, the functions ``XML()`` and ``HTML()`` can be used to convert 24 For example, the functions ``XML()`` and ``HTML()`` can be used to convert
26 literal XML or HTML text to a markup stream:: 25 literal XML or HTML text to a markup stream::
27 26
28 >>> from genshi import XML 27 >>> from genshi import XML
89 88
90 One example of a filter included with Genshi is the ``HTMLSanitizer`` in 89 One example of a filter included with Genshi is the ``HTMLSanitizer`` in
91 ``genshi.filters``. It processes a stream of HTML markup, and strips out any 90 ``genshi.filters``. It processes a stream of HTML markup, and strips out any
92 potentially dangerous constructs, such as Javascript event handlers. 91 potentially dangerous constructs, such as Javascript event handlers.
93 ``HTMLSanitizer`` is not a function, but rather a class that implements 92 ``HTMLSanitizer`` is not a function, but rather a class that implements
94 ``__call__``, which means instances of the class are callable. 93 ``__call__``, which means instances of the class are callable::
94
95 stream = stream | HTMLSanitizer()
95 96
96 Both the ``filter()`` method and the pipe operator allow easy chaining of 97 Both the ``filter()`` method and the pipe operator allow easy chaining of
97 filters:: 98 filters::
98 99
99 from genshi.filters import HTMLSanitizer 100 from genshi.filters import HTMLSanitizer
101 102
102 That is equivalent to:: 103 That is equivalent to::
103 104
104 stream = stream | noop | HTMLSanitizer() 105 stream = stream | noop | HTMLSanitizer()
105 106
107 For more information about the built-in filters, see `Stream Filters`_.
108
109 .. _`Stream Filters`: filters.html
110
106 111
107 Serialization 112 Serialization
108 ============= 113 =============
109 114
110 The ``Stream`` class provides two methods for serializing this list of events: 115 Serialization means producing some kind of textual output from a stream of
111 ``serialize()`` and ``render()``. The former is a generator that yields chunks 116 events, which you'll need when you want to transmit or store the results of
112 of ``Markup`` objects (which are basically unicode strings that are considered 117 generating or otherwise processing markup.
113 safe for output on the web). The latter returns a single string, by default 118
114 UTF-8 encoded. 119 The ``Stream`` class provides two methods for serialization: ``serialize()`` and
120 ``render()``. The former is a generator that yields chunks of ``Markup`` objects
121 (which are basically unicode strings that are considered safe for output on the
122 web). The latter returns a single string, by default UTF-8 encoded.
115 123
116 Here's the output from ``serialize()``:: 124 Here's the output from ``serialize()``::
117 125
118 >>> for output in stream.serialize(): 126 >>> for output in stream.serialize():
119 ... print `output` 127 ... print `output`
157 165
158 >>> print stream | HTMLSanitizer() | TextSerializer() 166 >>> print stream | HTMLSanitizer() | TextSerializer()
159 Some text and a link. 167 Some text and a link.
160 168
161 169
170 Serialization Options
171 ---------------------
172
173 Both ``serialize()`` and ``render()`` support additional keyword arguments that
174 are passed through to the initializer of the serializer class. The following
175 options are supported by the built-in serializers:
176
177 ``strip_whitespace``
178 Whether the serializer should remove trailing spaces and empty lines. Defaults
179 to ``True``.
180
181 (This option is not available for serialization to plain text.)
182
183 ``doctype``
184 A ``(name, pubid, sysid)`` tuple defining the name, publid identifier, and
185 system identifier of a ``DOCTYPE`` declaration to prepend to the generated
186 output. If provided, this declaration will override any ``DOCTYPE``
187 declaration in the stream.
188
189 (This option is not available for serialization to plain text.)
190
191 ``namespace_prefixes``
192 The namespace prefixes to use for namespace that are not bound to a prefix
193 in the stream itself.
194
195 (This option is not available for serialization to HTML or plain text.)
196
197
198
162 Using XPath 199 Using XPath
163 =========== 200 ===========
164 201
165 XPath can be used to extract a specific subset of the stream via the 202 XPath can be used to extract a specific subset of the stream via the
166 ``select()`` method:: 203 ``select()`` method::
Copyright (C) 2012-2017 Edgewall Software