genshi/mirror: doc/streams.txt annotate

annotate doc/streams.txt @ 697:3d3c322ca978 trunk

Fix for #205.

author	cmlenz
date	Thu, 27 Mar 2008 14:12:13 +0000
parents	1bdccd3bda00
children	be0b4a7b2fd4 ea46fb523485

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

Mercurial > genshi > mirror

annotate doc/streams.txt @ 697:3d3c322ca978 trunk