Mercurial > genshi > genshi-test

annotate doc/streams.txt @ 729:1447d40df660

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* Add XHTML 1.1 doctype (closes #228). * Add option to include the XML decl in the output when serializing to XHTML.
author cmlenz
date Sat, 31 May 2008 20:48:43 +0000
parents ca7d707d51b0
children f9544a7cc57a
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
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
25 literal XML or HTML text to a markup stream:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
26
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
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
382
d7da3fba7faf * Added documentation for the various stream event kinds.
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
382
d7da3fba7faf * Added documentation for the various stream event kinds.
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
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
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 ...
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
51 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
52 TEXT u'Some text and ' (None, 1, 17)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
53 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
54 TEXT u'a link' (None, 1, 61)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
55 END QName(u'a') (None, 1, 67)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
56 TEXT u'.' (None, 1, 71)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
57 START (QName(u'br'), Attrs()) (None, 1, 72)
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
58 END QName(u'br') (None, 1, 77)
d7da3fba7faf * Added documentation for the various stream event kinds.
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
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
69 the filtered stream:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
70
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
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
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
79 filter directly:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
80
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
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
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
86 arbitrary number of filter callables and applies them all:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
87
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
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 (``|``),
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
93 which allows a syntax similar to pipes on Unix shells:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
94
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
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
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
103 ``__call__``, which means instances of the class are callable:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
104
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
105 .. code-block:: python
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
106
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
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
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
110 filters:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
111
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
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
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
117 That is equivalent to:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
118
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
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
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
123 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
124
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
125 .. _`Stream Filters`: filters.html
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
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
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
131 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
132 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
133 generating or otherwise processing markup.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
134
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
135 The ``Stream`` class provides two methods for serialization: ``serialize()`` and
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
136 ``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
137 (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
138 web). The latter returns a single string, by default UTF-8 encoded.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
139
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
140 Here's the output from ``serialize()``:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
141
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
142 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
143
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
144 >>> for output in stream.serialize():
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
145 ... print `output`
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
146 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147 <Markup u'<p class="intro">'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
148 <Markup u'Some text and '>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149 <Markup u'<a href="http://example.org/">'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150 <Markup u'a link'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
151 <Markup u'</a>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
152 <Markup u'.'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
153 <Markup u'<br/>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
154 <Markup u'</p>'>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
155
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
156 And here's the output from ``render()``:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
157
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
158 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
159
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
160 >>> print stream.render()
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
161 <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
162
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
163 Both methods can be passed a ``method`` parameter that determines how exactly
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
164 the events are serialzed to text. This parameter can be either “xml” (the
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
165 default), “xhtml”, “html”, “text”, or a custom serializer class:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
166
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
167 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
168
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
169 >>> print stream.render('html')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
170 <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
171
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
172 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
173 HTML.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
174
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
175 In addition, the ``render()`` method takes an ``encoding`` parameter, which
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
176 defaults to “UTF-8”. If set to ``None``, the result will be a unicode string.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
177
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
178 The different serializer classes in ``genshi.output`` can also be used
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
179 directly:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
180
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
181 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
182
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
183 >>> from genshi.filters import HTMLSanitizer
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
184 >>> from genshi.output import TextSerializer
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
185 >>> print ''.join(TextSerializer()(HTMLSanitizer()(stream)))
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
186 Some text and a link.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
187
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
188 The pipe operator allows a nicer syntax:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
189
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
190 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
191
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
192 >>> print stream | HTMLSanitizer() | TextSerializer()
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193 Some text and a link.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
194
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
195
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
196 Serialization Options
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
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
199 Both ``serialize()`` and ``render()`` support additional keyword arguments that
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
200 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
201 options are supported by the built-in serializers:
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
202
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
203 ``strip_whitespace``
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
204 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
205 to ``True``.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
206
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
207 (This option is not available for serialization to plain text.)
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
208
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
209 ``doctype``
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
210 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
211 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
212 output. If provided, this declaration will override any ``DOCTYPE``
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
213 declaration in the stream.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
214
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
215 (This option is not available for serialization to plain text.)
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
216
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
217 ``namespace_prefixes``
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
218 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
219 in the stream itself.
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
220
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
221 (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
222
729
1447d40df660 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
223 ``drop_xml_decl``
1447d40df660 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
224 Whether to remove the XML declaration (the ``<?xml ?>`` part at the
1447d40df660 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
225 beginning of a document) when serializing. This defaults to ``True`` as an
1447d40df660 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
226 XML declaration throws some older browsers into "Quirks" rendering mode.
1447d40df660 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
227
1447d40df660 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
228 (This option is only available for serialization to XHTML.)
1447d40df660 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
229
438
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
230
6fd7e4dc0318 Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
231
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
232 Using XPath
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
233 ===========
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
234
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235 XPath can be used to extract a specific subset of the stream via the
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
236 ``select()`` method:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
237
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
238 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
239
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
240 >>> substream = stream.select('a')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
241 >>> substream
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
242 <genshi.core.Stream object at ...>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
243 >>> print substream
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 <a href="http://example.org/">a link</a>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
246 Often, streams cannot be reused: in the above example, the sub-stream is based
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247 on a generator. Once it has been serialized, it will have been fully consumed,
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
248 and cannot be rendered again. To work around this, you can wrap such a stream
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
249 in a ``list``:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
250
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
251 .. code-block:: pycon
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
252
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
253 >>> from genshi import Stream
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
254 >>> substream = Stream(list(stream.select('a')))
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
255 >>> substream
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
256 <genshi.core.Stream object at ...>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257 >>> print substream
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258 <a href="http://example.org/">a link</a>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 >>> print substream.select('@href')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260 http://example.org/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261 >>> print substream.select('text()')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
262 a link
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
263
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
264 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
265 Genshi.
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 .. _`Using XPath in Genshi`: xpath.html
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
268
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
269
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
270 .. _`event kinds`:
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
271
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
272 Event Kinds
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
273 ===========
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 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
276 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
277 events are documented below.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
278
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 382
diff changeset
279 .. 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
280 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
281 Effectively, this means the entire event tuple is immutable.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
282
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
283 START
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
284 -----
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
285 The opening tag of an element.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
286
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
287 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
288 ``(tagname, attrs)``, where ``tagname`` is a ``QName`` instance describing the
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
289 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
290 the attribute names and values associated with the tag (excluding namespace
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
291 declarations):
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
292
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
293 .. code-block:: python
382
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 START, (QName(u'p'), Attrs([(u'class', u'intro')])), pos
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 END
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 The closing tag of an element.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
300
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
301 The ``data`` item of end events consists of just a ``QName`` instance
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
302 describing the qualified name of the tag:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
303
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
304 .. code-block:: python
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
305
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
306 END, QName(u'p'), pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
307
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
308 TEXT
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
309 ----
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 382
diff changeset
310 Character data outside of elements and comments.
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
311
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
312 For text events, the ``data`` item should be a unicode object:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
313
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
314 .. code-block:: python
382
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 TEXT, u'Hello, world!', pos
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 START_NS
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 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
321
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
322 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
323 ``(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
324 full URI to which the prefix is bound. Both should be unicode objects. If the
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
325 namespace is not bound to any prefix, the ``prefix`` item is an empty string:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
326
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
327 .. code-block:: python
382
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 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
330
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
331 END_NS
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 The end of a namespace mapping.
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 The ``data`` item of such events consists of only the namespace prefix (a
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
336 unicode object):
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
337
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
338 .. code-block:: python
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
339
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
340 END_NS, u'svg', pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
341
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
342 DOCTYPE
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
343 -------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
344 A document type declaration.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
345
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
346 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
347 ``(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
348 ``pubid`` is the public identifier of the DTD (or ``None``), and ``sysid`` is
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
349 the system identifier of the DTD (or ``None``):
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
350
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
351 .. code-block:: python
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
352
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
353 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
354 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
355
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
356 COMMENT
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
357 -------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
358 A comment.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
359
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
360 For such events, the ``data`` item is a unicode object containing all character
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
361 data between the comment delimiters:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
362
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
363 .. code-block:: python
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
364
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
365 COMMENT, u'Commented out', pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
366
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
367 PI
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
368 --
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
369 A processing instruction.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
370
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
371 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
372 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
373 application by which the instruction should be processed), and ``data`` is text
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
374 following the target (excluding the terminating question mark):
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
375
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
376 .. code-block:: python
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
377
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
378 PI, (u'php', u'echo "Yo" '), pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
379
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
380 START_CDATA
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
381 -----------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
382 Marks the beginning of a ``CDATA`` section.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
383
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
384 The ``data`` item for such events is always ``None``:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
385
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
386 .. code-block:: python
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
387
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
388 START_CDATA, None, pos
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
389
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
390 END_CDATA
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
391 ---------
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
392 Marks the end of a ``CDATA`` section.
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
393
508
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
394 The ``data`` item for such events is always ``None``:
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
395
cabd80e75dad Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
396 .. code-block:: python
382
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
397
d7da3fba7faf * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
398 END_CDATA, None, pos
Copyright (C) 2012-2017 Edgewall Software