Mercurial > genshi > mirror

annotate doc/streams.txt @ 386:c66370dfc41b trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Unit test fixes for Python 2.3.
author cmlenz
date Mon, 11 Dec 2006 11:13:35 +0000
parents 2682dabbcd04
children cab6b0256019
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
21 * programmatically generated, or
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 * the result of selecting a subset of another stream filtered by an XPath
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23 expression.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
24
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
25 For example, the functions ``XML()`` and ``HTML()`` can be used to convert
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
26 literal XML or HTML text to a markup stream::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
28 >>> from genshi import XML
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29 >>> stream = XML('<p class="intro">Some text and '
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 ... '<a href="http://example.org/">a link</a>.'
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31 ... '<br/></p>')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32 >>> stream
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
33 <genshi.core.Stream object at ...>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34
4d8a9e03b23d 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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 of the form ``(kind, data, pos)``, where:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38 * ``kind`` defines what kind of event it is (such as the start of an element,
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 text, a comment, etc).
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
40 * ``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
41 on the event kind (see `event kinds`_)
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42 * ``pos`` is a ``(filename, lineno, column)`` tuple that describes where the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43 event “comes from”.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
44
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
45 ::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
46
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
47 >>> for kind, data, pos in stream:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48 ... print kind, `data`, pos
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 ...
382
2682dabbcd04 * 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)
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
51 TEXT u'Some text and ' (None, 1, 17)
2682dabbcd04 * 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)
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
53 TEXT u'a link' (None, 1, 61)
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
54 END QName(u'a') (None, 1, 67)
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
55 TEXT u'.' (None, 1, 71)
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
56 START (QName(u'br'), Attrs()) (None, 1, 72)
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
57 END QName(u'br') (None, 1, 77)
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
58 END QName(u'p') (None, 1, 77)
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
60
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
61 Filtering
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
62 =========
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64 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
65 stream, either filters that come with Genshi, or your own custom filters.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
66
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67 A filter is simply a callable that accepts the stream as parameter, and returns
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68 the filtered stream::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 def noop(stream):
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71 """A filter that doesn't actually do anything with the stream."""
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 for kind, data, pos in stream:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73 yield kind, data, pos
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
74
4d8a9e03b23d 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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
76 filter directly::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78 stream = noop(stream)
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
79
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
80 The ``Stream`` class also provides a ``filter()`` method, which takes an
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
81 arbitrary number of filter callables and applies them all::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
82
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
83 stream = stream.filter(noop)
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85 Finally, filters can also be applied using the *bitwise or* operator (``|``),
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
86 which allows a syntax similar to pipes on Unix shells::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
87
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
88 stream = stream | noop
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
89
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
90 One example of a filter included with Genshi is the ``HTMLSanitizer`` in
84168828b074 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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
92 potentially dangerous constructs, such as Javascript event handlers.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
93 ``HTMLSanitizer`` is not a function, but rather a class that implements
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
94 ``__call__``, which means instances of the class are callable.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
95
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
96 Both the ``filter()`` method and the pipe operator allow easy chaining of
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 filters::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
99 from genshi.filters import HTMLSanitizer
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
100 stream = stream.filter(noop, HTMLSanitizer())
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
101
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
102 That is equivalent to::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
103
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
104 stream = stream | noop | HTMLSanitizer()
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
105
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
106
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
107 Serialization
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
108 =============
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
109
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
110 The ``Stream`` class provides two methods for serializing this list of events:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
111 ``serialize()`` and ``render()``. The former is a generator that yields chunks
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
112 of ``Markup`` objects (which are basically unicode strings that are considered
84168828b074 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
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
114 UTF-8 encoded.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
115
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
116 Here's the output from ``serialize()``::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
117
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
118 >>> for output in stream.serialize():
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
119 ... print `output`
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
120 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
121 <Markup u'<p class="intro">'>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
122 <Markup u'Some text and '>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
123 <Markup u'<a href="http://example.org/">'>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
124 <Markup u'a link'>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
125 <Markup u'</a>'>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
126 <Markup u'.'>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
127 <Markup u'<br/>'>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
128 <Markup u'</p>'>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
129
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
130 And here's the output from ``render()``::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
131
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
132 >>> print stream.render()
4d8a9e03b23d 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>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
134
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
135 Both methods can be passed a ``method`` parameter that determines how exactly
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
136 the events are serialzed to text. This parameter can be either “xml” (the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
137 default), “xhtml”, “html”, “text”, or a custom serializer class::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
138
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
139 >>> print stream.render('html')
4d8a9e03b23d 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>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
141
4d8a9e03b23d 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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
143 HTML.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
144
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
145 In addition, the ``render()`` method takes an ``encoding`` parameter, which
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
146 defaults to “UTF-8”. If set to ``None``, the result will be a unicode string.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
148 The different serializer classes in ``genshi.output`` can also be used
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149 directly::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
151 >>> from genshi.filters import HTMLSanitizer
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
152 >>> from genshi.output import TextSerializer
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
153 >>> print ''.join(TextSerializer()(HTMLSanitizer()(stream)))
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
154 Some text and a link.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
155
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
156 The pipe operator allows a nicer syntax::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
157
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
158 >>> print stream | HTMLSanitizer() | TextSerializer()
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
159 Some text and a link.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
160
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
161
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
162 Using XPath
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
163 ===========
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
164
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
165 XPath can be used to extract a specific subset of the stream via the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
166 ``select()`` method::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
167
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
168 >>> substream = stream.select('a')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
169 >>> substream
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
170 <genshi.core.Stream object at ...>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
171 >>> print substream
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
172 <a href="http://example.org/">a link</a>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
173
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
174 Often, streams cannot be reused: in the above example, the sub-stream is based
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
175 on a generator. Once it has been serialized, it will have been fully consumed,
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
176 and cannot be rendered again. To work around this, you can wrap such a stream
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
177 in a ``list``::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
178
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
179 >>> from genshi import Stream
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
180 >>> substream = Stream(list(stream.select('a')))
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
181 >>> substream
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
182 <genshi.core.Stream object at ...>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
183 >>> print substream
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
184 <a href="http://example.org/">a link</a>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
185 >>> print substream.select('@href')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
186 http://example.org/
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
187 >>> print substream.select('text()')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
188 a link
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
189
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
191 Genshi.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
192
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
193 .. _`Using XPath in Genshi`: xpath.html
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
194
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
195
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
196 .. _`event kinds`:
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
197
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
198 Event Kinds
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
199 ===========
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
200
2682dabbcd04 * 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
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
203 events are documented below.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
204
2682dabbcd04 * 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
2682dabbcd04 * 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.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
207 Effectively, this means the entire event tuple is immutable.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
208
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
209 START
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
210 -----
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
211 The opening tag of an element.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
212
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
214 ``(tagname, attrs)``, where ``tagname`` is a ``QName`` instance describing the
2682dabbcd04 * 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
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
217 declarations)::
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
218
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
219 START, (QName(u'p'), Attrs([(u'class', u'intro')])), pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
220
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
221 END
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
222 ---
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
223 The closing tag of an element.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
224
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
226 describing the qualified name of the tag::
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
227
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
228 END, QName(u'p'), pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
229
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
230 TEXT
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
231 ----
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
232 Character data outside of elements and other nodes.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
233
2682dabbcd04 * 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::
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
235
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
236 TEXT, u'Hello, world!', pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
237
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
238 START_NS
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
239 --------
2682dabbcd04 * 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.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
241
2682dabbcd04 * 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
2682dabbcd04 * 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
2682dabbcd04 * 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
2682dabbcd04 * 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::
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
246
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
248
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
249 END_NS
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
250 ------
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
251 The end of a namespace mapping.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
252
2682dabbcd04 * 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
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
254 unicode object)::
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
255
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
256 END_NS, u'svg', pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
257
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
258 DOCTYPE
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 A document type declaration.
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 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
263 ``(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
264 ``pubid`` is the public identifier of the DTD (or ``None``), and ``sysid`` is
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
265 the system identifier of the DTD (or ``None``)::
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 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
268 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
269
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
270 COMMENT
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 A comment.
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 For such events, the ``data`` item is a unicode object containing all character
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
275 data between the comment delimiters::
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
276
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
277 COMMENT, u'Commented out', pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
278
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
279 PI
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
280 --
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
281 A processing instruction.
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 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
284 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
285 application by which the instruction should be processed), and ``data`` is text
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
286 following the target (excluding the terminating question mark)::
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 PI, (u'php', u'echo "Yo" '), 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 START_CDATA
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 Marks the beginning of a ``CDATA`` section.
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 for such events is always ``None``::
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
295
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
296 START_CDATA, None, pos
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
297
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
298 END_CDATA
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
299 ---------
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
300 Marks the end of a ``CDATA`` section.
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
301
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
302 The ``data`` item for such events is always ``None``::
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
303
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 230
diff changeset
304 END_CDATA, None, pos
Copyright (C) 2012-2017 Edgewall Software