Mercurial > genshi > mirror

annotate doc/streams.txt @ 729:be0b4a7b2fd4 trunk

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 1bdccd3bda00
children 74b5c5476ddb
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
729
be0b4a7b2fd4 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
223 ``drop_xml_decl``
be0b4a7b2fd4 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
224 Whether to remove the XML declaration (the ``<?xml ?>`` part at the
be0b4a7b2fd4 * 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
be0b4a7b2fd4 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
226 XML declaration throws some older browsers into "Quirks" rendering mode.
be0b4a7b2fd4 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
227
be0b4a7b2fd4 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
228 (This option is only available for serialization to XHTML.)
be0b4a7b2fd4 * Add XHTML 1.1 doctype (closes #228).
cmlenz
parents: 510
diff changeset
229
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
230
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 394
diff changeset
231
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
232 Using XPath
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
233 ===========
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
234
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235 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
236 ``select()`` method:
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
237
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
238 .. code-block:: pycon
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
239
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
240 >>> substream = stream.select('a')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
241 >>> substream
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
242 <genshi.core.Stream object at ...>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
243 >>> print substream
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 <a href="http://example.org/">a link</a>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
246 Often, streams cannot be reused: in the above example, the sub-stream is based
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247 on a generator. Once it has been serialized, it will have been fully consumed,
4d8a9e03b23d 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
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
249 in a ``list``:
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
250
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 508
diff changeset
251 .. code-block:: pycon
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
252
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
253 >>> from genshi import Stream
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
254 >>> substream = Stream(list(stream.select('a')))
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
255 >>> substream
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
256 <genshi.core.Stream object at ...>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257 >>> print substream
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258 <a href="http://example.org/">a link</a>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 >>> print substream.select('@href')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260 http://example.org/
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261 >>> print substream.select('text()')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
262 a link
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
263
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
265 Genshi.
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 .. _`Using XPath in Genshi`: xpath.html
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
268
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
269
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
270 .. _`event kinds`:
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
271
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
272 Event Kinds
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
273 ===========
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
274
2682dabbcd04 * 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
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
277 events are documented below.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
278
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 382
diff changeset
279 .. 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
280 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
281 Effectively, this means the entire event tuple is immutable.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
282
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
283 START
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
284 -----
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
285 The opening tag of an element.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
286
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
288 ``(tagname, attrs)``, where ``tagname`` is a ``QName`` instance describing the
2682dabbcd04 * 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
2682dabbcd04 * 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
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
291 declarations):
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
292
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
293 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
294
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
295 START, (QName(u'p'), Attrs([(u'class', u'intro')])), pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
296
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
297 END
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 The closing tag of an element.
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 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
302 describing the qualified name of the tag:
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
303
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
304 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
305
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
306 END, QName(u'p'), pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
307
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
308 TEXT
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
309 ----
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 382
diff changeset
310 Character data outside of elements and comments.
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
311
508
5fbc1cde74d6 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:
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
313
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
314 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
315
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
316 TEXT, u'Hello, world!', pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
317
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
318 START_NS
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
319 --------
2682dabbcd04 * 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.
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 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
323 ``(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
324 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
325 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
326
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
327 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
328
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
330
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
331 END_NS
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 The end of a namespace mapping.
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 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
336 unicode object):
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
337
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
338 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
339
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
340 END_NS, u'svg', pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
341
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
342 DOCTYPE
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
343 -------
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
344 A document type declaration.
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 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
347 ``(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
348 ``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
349 the system identifier of the DTD (or ``None``):
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
350
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
351 .. code-block:: python
382
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 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
354 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
355
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
356 COMMENT
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 A comment.
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 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
361 data between the comment delimiters:
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
362
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
363 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
364
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
365 COMMENT, u'Commented out', pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
366
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
367 PI
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
368 --
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
369 A processing instruction.
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 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
372 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
373 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
374 following the target (excluding the terminating question mark):
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
375
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
376 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
377
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
378 PI, (u'php', u'echo "Yo" '), pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
379
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
380 START_CDATA
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
381 -----------
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
382 Marks the beginning of a ``CDATA`` section.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
383
508
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
384 The ``data`` item for such events is always ``None``:
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
385
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
386 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
387
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
388 START_CDATA, None, pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
389
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
390 END_CDATA
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
391 ---------
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
392 Marks the end of a ``CDATA`` section.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
393
508
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
394 The ``data`` item for such events is always ``None``:
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
395
5fbc1cde74d6 Enable syntax highlighting (with Pygments) on doc page.
cmlenz
parents: 438
diff changeset
396 .. code-block:: python
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
397
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
398 END_CDATA, None, pos
Copyright (C) 2012-2017 Edgewall Software