Mercurial > genshi > genshi-test

annotate doc/streams.txt @ 828:eb8aa8690480 experimental-inline

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
inline branch: template object can be compiled, and remembers the generated module.
author cmlenz
date Fri, 13 Mar 2009 16:06:42 +0000
parents 1837f39efd6f
children 09cc3627654c
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
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
11 :depth: 2
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
500
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
21 * the result of selecting a subset of another stream using XPath, or
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
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
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
25 literal XML or HTML text to a markup stream:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
26
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
27 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
29 >>> from genshi import XML
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 >>> stream = XML('<p class="intro">Some text and '
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31 ... '<a href="http://example.org/">a link</a>.'
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32 ... '<br/></p>')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
33 >>> stream
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
34 <genshi.core.Stream object at ...>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 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
37 of the form ``(kind, data, pos)``, where:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 * ``kind`` defines what kind of event it is (such as the start of an element,
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
40 text, a comment, etc).
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
41 * ``data`` is the actual data associated with the event. How this looks depends
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
42 on the event kind (see `event kinds`_)
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43 * ``pos`` is a ``(filename, lineno, column)`` tuple that describes where the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
44 event “comes from”.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
45
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
46 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
47
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48 >>> for kind, data, pos in stream:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 ... print kind, `data`, pos
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
50 ...
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
51 START (QName(u'p'), Attrs([(QName(u'class'), u'intro')])) (None, 1, 0)
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
52 TEXT u'Some text and ' (None, 1, 17)
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
53 START (QName(u'a'), Attrs([(QName(u'href'), u'http://example.org/')])) (None, 1, 31)
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
54 TEXT u'a link' (None, 1, 61)
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
55 END QName(u'a') (None, 1, 67)
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
56 TEXT u'.' (None, 1, 71)
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
57 START (QName(u'br'), Attrs()) (None, 1, 72)
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
58 END QName(u'br') (None, 1, 77)
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
59 END QName(u'p') (None, 1, 77)
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
60
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
61
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
62 Filtering
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63 =========
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
65 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
66 stream, either filters that come with Genshi, or your own custom filters.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68 A filter is simply a callable that accepts the stream as parameter, and returns
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
69 the filtered stream:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
70
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
71 .. code-block:: python
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73 def noop(stream):
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
74 """A filter that doesn't actually do anything with the stream."""
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
75 for kind, data, pos in stream:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
76 yield kind, data, pos
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78 Filters can be applied in a number of ways. The simplest is to just call the
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
79 filter directly:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
80
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
81 .. code-block:: python
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
82
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
83 stream = noop(stream)
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85 The ``Stream`` class also provides a ``filter()`` method, which takes an
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
86 arbitrary number of filter callables and applies them all:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
87
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
88 .. code-block:: python
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
89
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
90 stream = stream.filter(noop)
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
91
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
92 Finally, filters can also be applied using the *bitwise or* operator (``|``),
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
93 which allows a syntax similar to pipes on Unix shells:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
94
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
95 .. code-block:: python
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
96
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 stream = stream | noop
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
99 One example of a filter included with Genshi is the ``HTMLSanitizer`` in
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
100 ``genshi.filters``. It processes a stream of HTML markup, and strips out any
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
101 potentially dangerous constructs, such as Javascript event handlers.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
102 ``HTMLSanitizer`` is not a function, but rather a class that implements
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
103 ``__call__``, which means instances of the class are callable:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
104
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
105 .. code-block:: python
500
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
106
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
107 stream = stream | HTMLSanitizer()
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
108
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
109 Both the ``filter()`` method and the pipe operator allow easy chaining of
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
110 filters:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
111
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
112 .. code-block:: python
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
113
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
114 from genshi.filters import HTMLSanitizer
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
115 stream = stream.filter(noop, HTMLSanitizer())
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
116
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
117 That is equivalent to:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
118
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
119 .. code-block:: python
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
120
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
121 stream = stream | noop | HTMLSanitizer()
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
122
500
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
123 For more information about the built-in filters, see `Stream Filters`_.
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
124
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
125 .. _`Stream Filters`: filters.html
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
126
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
127
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
128 Serialization
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
129 =============
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
130
500
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
131 Serialization means producing some kind of textual output from a stream of
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
132 events, which you'll need when you want to transmit or store the results of
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
133 generating or otherwise processing markup.
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
134
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
135 The ``Stream`` class provides two methods for serialization: ``serialize()``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
136 and ``render()``. The former is a generator that yields chunks of ``Markup``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
137 objects (which are basically unicode strings that are considered safe for
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
138 output on the web). The latter returns a single string, by default UTF-8
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
139 encoded.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
140
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
141 Here's the output from ``serialize()``:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
142
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
143 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
144
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
145 >>> for output in stream.serialize():
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
146 ... print `output`
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
148 <Markup u'<p class="intro">'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149 <Markup u'Some text and '>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150 <Markup u'<a href="http://example.org/">'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
151 <Markup u'a link'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
152 <Markup u'</a>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
153 <Markup u'.'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
154 <Markup u'<br/>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
155 <Markup u'</p>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
156
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
157 And here's the output from ``render()``:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
158
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
159 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
160
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
161 >>> print stream.render()
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
162 <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
163
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
164 Both methods can be passed a ``method`` parameter that determines how exactly
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
165 the events are serialized to text. This parameter can be either a string or a
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
166 custom serializer class:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
167
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
168 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
169
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
170 >>> print stream.render('html')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
171 <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
172
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
173 Note how the `<br>` element isn't closed, which is the right thing to do for
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
174 HTML. See `serialization methods`_ for more details.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
175
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
176 In addition, the ``render()`` method takes an ``encoding`` parameter, which
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
177 defaults to “UTF-8”. If set to ``None``, the result will be a unicode string.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
178
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
179 The different serializer classes in ``genshi.output`` can also be used
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
180 directly:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
181
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
182 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
183
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
184 >>> from genshi.filters import HTMLSanitizer
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
185 >>> from genshi.output import TextSerializer
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
186 >>> print ''.join(TextSerializer()(HTMLSanitizer()(stream)))
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
187 Some text and a link.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
188
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
189 The pipe operator allows a nicer syntax:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
190
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
191 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
192
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193 >>> print stream | HTMLSanitizer() | TextSerializer()
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
194 Some text and a link.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
195
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
196
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
197 .. _`serialization methods`:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
198
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
199 Serialization Methods
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
200 ---------------------
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
201
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
202 Genshi supports the use of different serialization methods to use for creating
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
203 a text representation of a markup stream.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
204
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
205 ``xml``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
206 The ``XMLSerializer`` is the default serialization method and results in
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
207 proper XML output including namespace support, the XML declaration, CDATA
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
208 sections, and so on. It is not generally not suitable for serving HTML or
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
209 XHTML web pages (unless you want to use true XHTML 1.1), for which the
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
210 ``xhtml`` and ``html`` serializers described below should be preferred.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
211
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
212 ``xhtml``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
213 The ``XHTMLSerializer`` is a specialization of the generic ``XMLSerializer``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
214 that understands the pecularities of producing XML-compliant output that can
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
215 also be parsed without problems by the HTML parsers found in modern web
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
216 browsers. Thus, the output by this serializer should be usable whether sent
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
217 as "text/html" or "application/xhtml+html" (although there are a lot of
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
218 subtle issues to pay attention to when switching between the two, in
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
219 particular with respect to differences in the DOM and CSS).
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
220
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
221 For example, instead of rendering a script tag as ``<script/>`` (which
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
222 confuses the HTML parser in many browsers), it will produce
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
223 ``<script></script>``. Also, it will normalize any boolean attributes values
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
224 that are minimized in HTML, so that for example ``<hr noshade="1"/>``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
225 becomes ``<hr noshade="noshade" />``.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
226
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
227 This serializer supports the use of namespaces for compound documents, for
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
228 example to use inline SVG inside an XHTML document.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
229
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
230 ``html``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
231 The ``HTMLSerializer`` produces proper HTML markup. The main differences
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
232 compared to ``xhtml`` serialization are that boolean attributes are
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
233 minimized, empty tags are not self-closing (so it's ``<br>`` instead of
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
234 ``<br />``), and that the contents of ``<script>`` and ``<style>`` elements
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
235 are not escaped.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
236
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
237 ``text``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
238 The ``TextSerializer`` produces plain text from markup streams. This is
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
239 useful primarily for `text templates`_, but can also be used to produce
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
240 plain text output from markup templates or other sources.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
241
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
242 .. _`text templates`: text-templates.html
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
243
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
244
500
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
245 Serialization Options
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
246 ---------------------
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
247
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
248 Both ``serialize()`` and ``render()`` support additional keyword arguments that
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
249 are passed through to the initializer of the serializer class. The following
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
250 options are supported by the built-in serializers:
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
251
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
252 ``strip_whitespace``
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
253 Whether the serializer should remove trailing spaces and empty lines.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
254 Defaults to ``True``.
500
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
255
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
256 (This option is not available for serialization to plain text.)
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
257
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
258 ``doctype``
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
259 A ``(name, pubid, sysid)`` tuple defining the name, publid identifier, and
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
260 system identifier of a ``DOCTYPE`` declaration to prepend to the generated
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
261 output. If provided, this declaration will override any ``DOCTYPE``
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
262 declaration in the stream.
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
263
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
264 The parameter can also be specified as a string to refer to commonly used
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
265 doctypes:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
266
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
267 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
268 | Shorthand | DOCTYPE |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
269 +=============================+===========================================+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
270 | ``html`` or | HTML 4.01 Strict |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
271 | ``html-strict`` | |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
272 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
273 | ``html-transitional`` | HTML 4.01 Transitional |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
274 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
275 | ``html-frameset`` | HTML 4.01 Frameset |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
276 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
277 | ``html5`` | DOCTYPE proposed for the work-in-progress |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
278 | | HTML5 standard |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
279 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
280 | ``xhtml`` or | XHTML 1.0 Strict |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
281 | ``xhtml-strict`` | |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
282 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
283 | ``xhtml-transitional`` | XHTML 1.0 Transitional |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
284 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
285 | ``xhtml-frameset`` | XHTML 1.0 Frameset |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
286 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
287 | ``xhtml11`` | XHTML 1.1 |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
288 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
289 | ``svg`` or ``svg-full`` | SVG 1.1 |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
290 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
291 | ``svg-basic`` | SVG 1.1 Basic |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
292 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
293 | ``svg-tiny`` | SVG 1.1 Tiny |
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
294 +-----------------------------+-------------------------------------------+
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
295
500
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
296 (This option is not available for serialization to plain text.)
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
297
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
298 ``namespace_prefixes``
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
299 The namespace prefixes to use for namespace that are not bound to a prefix
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
300 in the stream itself.
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
301
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
302 (This option is not available for serialization to HTML or plain text.)
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
303
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
304 ``drop_xml_decl``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
305 Whether to remove the XML declaration (the ``<?xml ?>`` part at the
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
306 beginning of a document) when serializing. This defaults to ``True`` as an
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
307 XML declaration throws some older browsers into "Quirks" rendering mode.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
308
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
309 (This option is only available for serialization to XHTML.)
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
310
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
311 ``strip_markup``
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
312 Whether the text serializer should detect and remove any tags or entity
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
313 encoded characters in the text.
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
314
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
315 (This option is only available for serialization to plain text.)
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
316
500
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
317
0742f421caba Merged revisions 487-603 via svnmerge from
cmlenz
parents: 395
diff changeset
318
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
319 Using XPath
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
320 ===========
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
321
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
322 XPath can be used to extract a specific subset of the stream via the
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
323 ``select()`` method:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
324
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
325 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
326
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
327 >>> substream = stream.select('a')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
328 >>> substream
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
329 <genshi.core.Stream object at ...>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
330 >>> print substream
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
331 <a href="http://example.org/">a link</a>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
332
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
333 Often, streams cannot be reused: in the above example, the sub-stream is based
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
334 on a generator. Once it has been serialized, it will have been fully consumed,
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
335 and cannot be rendered again. To work around this, you can wrap such a stream
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
336 in a ``list``:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
337
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
338 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
339
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
340 >>> from genshi import Stream
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
341 >>> substream = Stream(list(stream.select('a')))
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
342 >>> substream
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
343 <genshi.core.Stream object at ...>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
344 >>> print substream
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
345 <a href="http://example.org/">a link</a>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
346 >>> print substream.select('@href')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
347 http://example.org/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
348 >>> print substream.select('text()')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
349 a link
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
350
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
351 See `Using XPath in Genshi`_ for more information about the XPath support in
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
352 Genshi.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
353
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
354 .. _`Using XPath in Genshi`: xpath.html
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
355
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
356
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
357 .. _`event kinds`:
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
358
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
359 Event Kinds
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
360 ===========
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
361
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
362 Every event in a stream is of one of several *kinds*, which also determines
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
363 what the ``data`` item of the event tuple looks like. The different kinds of
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
364 events are documented below.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
365
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
366 .. note:: The ``data`` item is generally immutable. If the data is to be
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
367 modified when processing a stream, it must be replaced by a new tuple.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
368 Effectively, this means the entire event tuple is immutable.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
369
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
370 START
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
371 -----
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
372 The opening tag of an element.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
373
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
374 For this kind of event, the ``data`` item is a tuple of the form
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
375 ``(tagname, attrs)``, where ``tagname`` is a ``QName`` instance describing the
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
376 qualified name of the tag, and ``attrs`` is an ``Attrs`` instance containing
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
377 the attribute names and values associated with the tag (excluding namespace
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
378 declarations):
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
379
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
380 .. code-block:: python
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
381
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
382 START, (QName(u'p'), Attrs([(QName(u'class'), u'intro')])), pos
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
383
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
384 END
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
385 ---
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
386 The closing tag of an element.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
387
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
388 The ``data`` item of end events consists of just a ``QName`` instance
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
389 describing the qualified name of the tag:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
390
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
391 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
392
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
393 END, QName(u'p'), pos
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
394
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
395 TEXT
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
396 ----
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
397 Character data outside of elements and comments.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
398
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
399 For text events, the ``data`` item should be a unicode object:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
400
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
401 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
402
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
403 TEXT, u'Hello, world!', pos
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
404
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
405 START_NS
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
406 --------
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
407 The start of a namespace mapping, binding a namespace prefix to a URI.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
408
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
409 The ``data`` item of this kind of event is a tuple of the form
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
410 ``(prefix, uri)``, where ``prefix`` is the namespace prefix and ``uri`` is the
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
411 full URI to which the prefix is bound. Both should be unicode objects. If the
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
412 namespace is not bound to any prefix, the ``prefix`` item is an empty string:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
413
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
414 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
415
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
416 START_NS, (u'svg', u'http://www.w3.org/2000/svg'), pos
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
417
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
418 END_NS
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
419 ------
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
420 The end of a namespace mapping.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
421
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
422 The ``data`` item of such events consists of only the namespace prefix (a
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
423 unicode object):
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
424
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
425 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
426
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
427 END_NS, u'svg', pos
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
428
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
429 DOCTYPE
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
430 -------
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
431 A document type declaration.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
432
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
433 For this type of event, the ``data`` item is a tuple of the form
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
434 ``(name, pubid, sysid)``, where ``name`` is the name of the root element,
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
435 ``pubid`` is the public identifier of the DTD (or ``None``), and ``sysid`` is
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
436 the system identifier of the DTD (or ``None``):
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
437
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
438 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
439
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
440 DOCTYPE, (u'html', u'-//W3C//DTD XHTML 1.0 Transitional//EN', \
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
441 u'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'), pos
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
442
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
443 COMMENT
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
444 -------
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
445 A comment.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
446
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
447 For such events, the ``data`` item is a unicode object containing all character
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
448 data between the comment delimiters:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
449
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
450 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
451
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
452 COMMENT, u'Commented out', pos
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
453
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
454 PI
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
455 --
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
456 A processing instruction.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
457
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
458 The ``data`` item is a tuple of the form ``(target, data)`` for processing
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
459 instructions, where ``target`` is the target of the PI (used to identify the
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
460 application by which the instruction should be processed), and ``data`` is text
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
461 following the target (excluding the terminating question mark):
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
462
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
463 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
464
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
465 PI, (u'php', u'echo "Yo" '), pos
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
466
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
467 START_CDATA
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
468 -----------
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
469 Marks the beginning of a ``CDATA`` section.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
470
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
471 The ``data`` item for such events is always ``None``:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
472
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
473 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
474
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
475 START_CDATA, None, pos
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
476
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
477 END_CDATA
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
478 ---------
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
479 Marks the end of a ``CDATA`` section.
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
480
820
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
481 The ``data`` item for such events is always ``None``:
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
482
1837f39efd6f Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents: 500
diff changeset
483 .. code-block:: python
395
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
484
55cf81951686 inline branch: Merged [439:479/trunk].
cmlenz
parents: 230
diff changeset
485 END_CDATA, None, pos
Copyright (C) 2012-2017 Edgewall Software