Mercurial > genshi > mirror

annotate doc/streams.txt @ 696:66eead58c120 trunk

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