Mercurial > genshi > genshi-test

annotate doc/streams.txt @ 382:d7da3fba7faf

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