Mercurial > genshi > genshi-test

annotate doc/streams.txt @ 438:6fd7e4dc0318

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added documentation page on the builtin stream filters.
author cmlenz
date Mon, 02 Apr 2007 18:21:03 +0000
parents ebc7c1a3bc4d
children cabd80e75dad 1a29617a5d87
rev   line source
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
2
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
3 ==============
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
4 Markup Streams
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
5 ==============
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
6
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
7 A stream is the common representation of markup as a *stream of events*.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
8
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
9
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
10 .. contents:: Contents
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
11 :depth: 1
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
12 .. sectnum::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
13
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
14
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
15 Basics
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
16 ======
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
17
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
18 A stream can be attained in a number of ways. It can be:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
19
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
20 * the result of parsing XML or HTML text, or
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
21 * the result of selecting a subset of another stream using XPath, or
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
22 * programmatically generated.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
24 For example, the functions ``XML()`` and ``HTML()`` can be used to convert
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
25 literal XML or HTML text to a markup stream::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
26
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
27 >>> from genshi import XML
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28 >>> stream = XML('<p class="intro">Some text and '
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29 ... '<a href="http://example.org/">a link</a>.'
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 ... '<br/></p>')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31 >>> stream
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
32 <genshi.core.Stream object at ...>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
33
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34 The stream is the result of parsing the text into events. Each event is a tuple
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35 of the form ``(kind, data, pos)``, where:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37 * ``kind`` defines what kind of event it is (such as the start of an element,
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38 text, a comment, etc).
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 * ``data`` is the actual data associated with the event. How this looks depends
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
40 on the event kind (see `event kinds`_)
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
41 * ``pos`` is a ``(filename, lineno, column)`` tuple that describes where the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42 event “comes from”.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
44 ::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
45
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
46 >>> for kind, data, pos in stream:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
47 ... print kind, `data`, pos
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48 ...
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
49 START (QName(u'p'), Attrs([(QName(u'class'), u'intro')])) (None, 1, 0)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
50 TEXT u'Some text and ' (None, 1, 17)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
51 START (QName(u'a'), Attrs([(QName(u'href'), u'http://example.org/')])) (None, 1, 31)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
52 TEXT u'a link' (None, 1, 61)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
53 END QName(u'a') (None, 1, 67)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
54 TEXT u'.' (None, 1, 71)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
55 START (QName(u'br'), Attrs()) (None, 1, 72)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
56 END QName(u'br') (None, 1, 77)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
57 END QName(u'p') (None, 1, 77)
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
58
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
60 Filtering
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
61 =========
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
62
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63 One important feature of markup streams is that you can apply *filters* to the
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
64 stream, either filters that come with Genshi, or your own custom filters.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
65
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
66 A filter is simply a callable that accepts the stream as parameter, and returns
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67 the filtered stream::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 def noop(stream):
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 """A filter that doesn't actually do anything with the stream."""
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71 for kind, data, pos in stream:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 yield kind, data, pos
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
74 Filters can be applied in a number of ways. The simplest is to just call the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
75 filter directly::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
76
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77 stream = noop(stream)
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
79 The ``Stream`` class also provides a ``filter()`` method, which takes an
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
80 arbitrary number of filter callables and applies them all::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
81
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
82 stream = stream.filter(noop)
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
83
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84 Finally, filters can also be applied using the *bitwise or* operator (``|``),
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85 which allows a syntax similar to pipes on Unix shells::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
86
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
87 stream = stream | noop
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
88
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
89 One example of a filter included with Genshi is the ``HTMLSanitizer`` in
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
90 ``genshi.filters``. It processes a stream of HTML markup, and strips out any
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
91 potentially dangerous constructs, such as Javascript event handlers.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
92 ``HTMLSanitizer`` is not a function, but rather a class that implements
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
93 ``__call__``, which means instances of the class are callable::
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
94
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
95 stream = stream | HTMLSanitizer()
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
96
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 Both the ``filter()`` method and the pipe operator allow easy chaining of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98 filters::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
99
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
100 from genshi.filters import HTMLSanitizer
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
101 stream = stream.filter(noop, HTMLSanitizer())
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
102
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
103 That is equivalent to::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
104
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
105 stream = stream | noop | HTMLSanitizer()
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
106
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
107 For more information about the built-in filters, see `Stream Filters`_.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
108
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
109 .. _`Stream Filters`: filters.html
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
110
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
111
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
112 Serialization
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
113 =============
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
114
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
115 Serialization means producing some kind of textual output from a stream of
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
116 events, which you'll need when you want to transmit or store the results of
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
117 generating or otherwise processing markup.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
118
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
119 The ``Stream`` class provides two methods for serialization: ``serialize()`` and
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
120 ``render()``. The former is a generator that yields chunks of ``Markup`` objects
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
121 (which are basically unicode strings that are considered safe for output on the
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
122 web). The latter returns a single string, by default UTF-8 encoded.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
123
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
124 Here's the output from ``serialize()``::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
125
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
126 >>> for output in stream.serialize():
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
127 ... print `output`
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
128 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
129 <Markup u'<p class="intro">'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
130 <Markup u'Some text and '>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
131 <Markup u'<a href="http://example.org/">'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
132 <Markup u'a link'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
133 <Markup u'</a>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
134 <Markup u'.'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
135 <Markup u'<br/>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
136 <Markup u'</p>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
137
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
138 And here's the output from ``render()``::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
139
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
140 >>> print stream.render()
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
141 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
142
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
143 Both methods can be passed a ``method`` parameter that determines how exactly
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
144 the events are serialzed to text. This parameter can be either “xml” (the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
145 default), “xhtml”, “html”, “text”, or a custom serializer class::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
146
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147 >>> print stream.render('html')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
148 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br></p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150 Note how the `<br>` element isn't closed, which is the right thing to do for
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
151 HTML.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
152
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
153 In addition, the ``render()`` method takes an ``encoding`` parameter, which
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
154 defaults to “UTF-8”. If set to ``None``, the result will be a unicode string.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
155
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
156 The different serializer classes in ``genshi.output`` can also be used
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
157 directly::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
158
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
159 >>> from genshi.filters import HTMLSanitizer
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
160 >>> from genshi.output import TextSerializer
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
161 >>> print ''.join(TextSerializer()(HTMLSanitizer()(stream)))
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
162 Some text and a link.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
163
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
164 The pipe operator allows a nicer syntax::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
165
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
166 >>> print stream | HTMLSanitizer() | TextSerializer()
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
167 Some text and a link.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
168
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
169
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
170 Serialization Options
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
171 ---------------------
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
172
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
173 Both ``serialize()`` and ``render()`` support additional keyword arguments that
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
174 are passed through to the initializer of the serializer class. The following
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
175 options are supported by the built-in serializers:
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
176
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
177 ``strip_whitespace``
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
178 Whether the serializer should remove trailing spaces and empty lines. Defaults
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
179 to ``True``.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
180
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
181 (This option is not available for serialization to plain text.)
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
182
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
183 ``doctype``
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
184 A ``(name, pubid, sysid)`` tuple defining the name, publid identifier, and
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
185 system identifier of a ``DOCTYPE`` declaration to prepend to the generated
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
186 output. If provided, this declaration will override any ``DOCTYPE``
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
187 declaration in the stream.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
188
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
189 (This option is not available for serialization to plain text.)
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
190
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
191 ``namespace_prefixes``
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
192 The namespace prefixes to use for namespace that are not bound to a prefix
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
193 in the stream itself.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
194
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
195 (This option is not available for serialization to HTML or plain text.)
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
196
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
197
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
198
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
199 Using XPath
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
200 ===========
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
201
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
202 XPath can be used to extract a specific subset of the stream via the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
203 ``select()`` method::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
204
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
205 >>> substream = stream.select('a')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
206 >>> substream
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
207 <genshi.core.Stream object at ...>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
208 >>> print substream
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
209 <a href="http://example.org/">a link</a>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
210
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
211 Often, streams cannot be reused: in the above example, the sub-stream is based
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
212 on a generator. Once it has been serialized, it will have been fully consumed,
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
213 and cannot be rendered again. To work around this, you can wrap such a stream
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
214 in a ``list``::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
215
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
216 >>> from genshi import Stream
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
217 >>> substream = Stream(list(stream.select('a')))
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
218 >>> substream
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
219 <genshi.core.Stream object at ...>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
220 >>> print substream
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
221 <a href="http://example.org/">a link</a>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
222 >>> print substream.select('@href')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
223 http://example.org/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
224 >>> print substream.select('text()')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
225 a link
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
226
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
227 See `Using XPath in Genshi`_ for more information about the XPath support in
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
228 Genshi.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
229
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
230 .. _`Using XPath in Genshi`: xpath.html
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
231
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
232
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
233 .. _`event kinds`:
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
234
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
235 Event Kinds
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
236 ===========
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
237
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
238 Every event in a stream is of one of several *kinds*, which also determines
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
239 what the ``data`` item of the event tuple looks like. The different kinds of
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
240 events are documented below.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
241
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 382
diff changeset
242 .. note:: The ``data`` item is generally immutable. If the data is to be
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
243 modified when processing a stream, it must be replaced by a new tuple.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
244 Effectively, this means the entire event tuple is immutable.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
245
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
246 START
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
247 -----
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
248 The opening tag of an element.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
249
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
250 For this kind of event, the ``data`` item is a tuple of the form
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
251 ``(tagname, attrs)``, where ``tagname`` is a ``QName`` instance describing the
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
252 qualified name of the tag, and ``attrs`` is an ``Attrs`` instance containing
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
253 the attribute names and values associated with the tag (excluding namespace
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
254 declarations)::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
255
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
256 START, (QName(u'p'), Attrs([(u'class', u'intro')])), pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
257
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
258 END
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
259 ---
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
260 The closing tag of an element.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
261
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
262 The ``data`` item of end events consists of just a ``QName`` instance
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
263 describing the qualified name of the tag::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
264
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
265 END, QName(u'p'), pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
266
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
267 TEXT
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
268 ----
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 382
diff changeset
269 Character data outside of elements and comments.
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
270
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
271 For text events, the ``data`` item should be a unicode object::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
272
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
273 TEXT, u'Hello, world!', pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
274
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
275 START_NS
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
276 --------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
277 The start of a namespace mapping, binding a namespace prefix to a URI.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
278
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
279 The ``data`` item of this kind of event is a tuple of the form
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
280 ``(prefix, uri)``, where ``prefix`` is the namespace prefix and ``uri`` is the
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
281 full URI to which the prefix is bound. Both should be unicode objects. If the
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
282 namespace is not bound to any prefix, the ``prefix`` item is an empty string::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
283
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
284 START_NS, (u'svg', u'http://www.w3.org/2000/svg'), pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
285
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
286 END_NS
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
287 ------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
288 The end of a namespace mapping.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
289
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
290 The ``data`` item of such events consists of only the namespace prefix (a
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
291 unicode object)::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
292
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
293 END_NS, u'svg', pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
294
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
295 DOCTYPE
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
296 -------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
297 A document type declaration.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
298
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
299 For this type of event, the ``data`` item is a tuple of the form
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
300 ``(name, pubid, sysid)``, where ``name`` is the name of the root element,
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
301 ``pubid`` is the public identifier of the DTD (or ``None``), and ``sysid`` is
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
302 the system identifier of the DTD (or ``None``)::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
303
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
304 DOCTYPE, (u'html', u'-//W3C//DTD XHTML 1.0 Transitional//EN', \
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
305 u'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'), pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
306
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
307 COMMENT
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
308 -------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
309 A comment.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
310
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
311 For such events, the ``data`` item is a unicode object containing all character
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
312 data between the comment delimiters::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
313
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
314 COMMENT, u'Commented out', pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
315
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
316 PI
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
317 --
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
318 A processing instruction.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
319
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
320 The ``data`` item is a tuple of the form ``(target, data)`` for processing
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
321 instructions, where ``target`` is the target of the PI (used to identify the
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
322 application by which the instruction should be processed), and ``data`` is text
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
323 following the target (excluding the terminating question mark)::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
324
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
325 PI, (u'php', u'echo "Yo" '), pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
326
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
327 START_CDATA
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
328 -----------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
329 Marks the beginning of a ``CDATA`` section.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
330
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
331 The ``data`` item for such events is always ``None``::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
332
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
333 START_CDATA, None, pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
334
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
335 END_CDATA
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
336 ---------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
337 Marks the end of a ``CDATA`` section.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
338
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
339 The ``data`` item for such events is always ``None``::
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
340
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
341 END_CDATA, None, pos
Copyright (C) 2012-2017 Edgewall Software