genshi/genshi-test: doc/streams.txt comparison

comparison doc/streams.txt @ 511:1a29617a5d87 stable-0.4.x

Ported [611:614] to 0.4.x branch.

author	cmlenz
date	Wed, 06 Jun 2007 11:18:46 +0000
parents	6fd7e4dc0318
children

comparison

equal deleted inserted replaced

-:90eecd360b18
+:1a29617a5d87
 * the result of parsing XML or HTML text, or
 * the result of selecting a subset of another stream using XPath, or
 * programmatically generated.
 For example, the functions ``XML()`` and ``HTML()`` can be used to convert
-literal XML or HTML text to a markup stream::
+literal XML or HTML text to a markup stream:
+.. code-block:: pycon
 >>> from genshi import XML
 >>> stream = XML('<p class="intro">Some text and '
 ...              '<a href="http://example.org/">a link</a>.'
 ...              '<br/></p>')
 * ``data`` is the actual data associated with the event. How this looks depends
 on the event kind (see  `event kinds`_)
 * ``pos`` is a ``(filename, lineno, column)`` tuple that describes where the
 event “comes from”.
-::
+.. code-block:: pycon
 >>> for kind, data, pos in stream:
 ...     print kind, `data`, pos
 ...
 START (QName(u'p'), Attrs([(QName(u'class'), u'intro')])) (None, 1, 0)
 One important feature of markup streams is that you can apply *filters* to the
 stream, either filters that come with Genshi, or your own custom filters.
 A filter is simply a callable that accepts the stream as parameter, and returns
-the filtered stream::
+the filtered stream:
+.. code-block:: python
 def noop(stream):
 """A filter that doesn't actually do anything with the stream."""
 for kind, data, pos in stream:
 yield kind, data, pos
 Filters can be applied in a number of ways. The simplest is to just call the
-filter directly::
+filter directly:
+.. code-block:: python
 stream = noop(stream)
 The ``Stream`` class also provides a ``filter()`` method, which takes an
-arbitrary number of filter callables and applies them all::
+arbitrary number of filter callables and applies them all:
+.. code-block:: python
 stream = stream.filter(noop)
 Finally, filters can also be applied using the *bitwise or* operator (``|``),
-which allows a syntax similar to pipes on Unix shells::
+which allows a syntax similar to pipes on Unix shells:
+.. code-block:: python
 stream = stream | noop
 One example of a filter included with Genshi is the ``HTMLSanitizer`` in
 ``genshi.filters``. It processes a stream of HTML markup, and strips out any
 potentially dangerous constructs, such as Javascript event handlers.
 ``HTMLSanitizer`` is not a function, but rather a class that implements
-``__call__``, which means instances of the class are callable::
+``__call__``, which means instances of the class are callable:
+.. code-block:: python
 stream = stream | HTMLSanitizer()
 Both the ``filter()`` method and the pipe operator allow easy chaining of
-filters::
+filters:
+.. code-block:: python
 from genshi.filters import HTMLSanitizer
 stream = stream.filter(noop, HTMLSanitizer())
-That is equivalent to::
+That is equivalent to:
+.. code-block:: python
 stream = stream | noop | HTMLSanitizer()
 For more information about the built-in filters, see `Stream Filters`_.
 The ``Stream`` class provides two methods for serialization: ``serialize()`` and
 ``render()``. The former is a generator that yields chunks of ``Markup`` objects
 (which are basically unicode strings that are considered safe for output on the
 web). The latter returns a single string, by default UTF-8 encoded.
-Here's the output from ``serialize()``::
+Here's the output from ``serialize()``:
+.. code-block:: pycon
 >>> for output in stream.serialize():
 ...     print `output`
 ...
 <Markup u'<p class="intro">'>
 <Markup u'</a>'>
 <Markup u'.'>
 <Markup u'<br/>'>
 <Markup u'</p>'>
-And here's the output from ``render()``::
+And here's the output from ``render()``:
+.. code-block:: pycon
 >>> print stream.render()
 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
 Both methods can be passed a ``method`` parameter that determines how exactly
 the events are serialzed to text. This parameter can be either “xml” (the
-default), “xhtml”, “html”, “text”, or a custom serializer class::
+default), “xhtml”, “html”, “text”, or a custom serializer class:
+.. code-block:: pycon
 >>> print stream.render('html')
 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br></p>
 Note how the `<br>` element isn't closed, which is the right thing to do for
 In addition, the ``render()`` method takes an ``encoding`` parameter, which
 defaults to “UTF-8”. If set to ``None``, the result will be a unicode string.
 The different serializer classes in ``genshi.output`` can also be used
-directly::
+directly:
+.. code-block:: pycon
 >>> from genshi.filters import HTMLSanitizer
 >>> from genshi.output import TextSerializer
 >>> print ''.join(TextSerializer()(HTMLSanitizer()(stream)))
 Some text and a link.
-The pipe operator allows a nicer syntax::
+The pipe operator allows a nicer syntax:
+.. code-block:: pycon
 >>> print stream | HTMLSanitizer() | TextSerializer()
 Some text and a link.
 Using XPath
 ===========
 XPath can be used to extract a specific subset of the stream via the
-``select()`` method::
+``select()`` method:
+.. code-block:: pycon
 >>> substream = stream.select('a')
 >>> substream
 <genshi.core.Stream object at ...>
 >>> print substream
 <a href="http://example.org/">a link</a>
 Often, streams cannot be reused: in the above example, the sub-stream is based
 on a generator. Once it has been serialized, it will have been fully consumed,
 and cannot be rendered again. To work around this, you can wrap such a stream
-in a ``list``::
+in a ``list``:
+.. code-block:: pycon
 >>> from genshi import Stream
 >>> substream = Stream(list(stream.select('a')))
 >>> substream
 <genshi.core.Stream object at ...>
 For this kind of event, the ``data`` item is a tuple of the form
 ``(tagname, attrs)``, where ``tagname`` is a ``QName`` instance describing the
 qualified name of the tag, and ``attrs`` is an ``Attrs`` instance containing
 the attribute names and values associated with the tag (excluding namespace
-declarations)::
+declarations):
+.. code-block:: python
 START, (QName(u'p'), Attrs([(u'class', u'intro')])), pos
 END
 ---
 The closing tag of an element.
 The ``data`` item of end events consists of just a ``QName`` instance
-describing the qualified name of the tag::
+describing the qualified name of the tag:
+.. code-block:: python
 END, QName(u'p'), pos
 TEXT
 ----
 Character data outside of elements and comments.
-For text events, the ``data`` item should be a unicode object::
+For text events, the ``data`` item should be a unicode object:
+.. code-block:: python
 TEXT, u'Hello, world!', pos
 START_NS
 --------
 The start of a namespace mapping, binding a namespace prefix to a URI.
 The ``data`` item of this kind of event is a tuple of the form
 ``(prefix, uri)``, where ``prefix`` is the namespace prefix and ``uri`` is the
 full URI to which the prefix is bound. Both should be unicode objects. If the
-namespace is not bound to any prefix, the ``prefix`` item is an empty string::
+namespace is not bound to any prefix, the ``prefix`` item is an empty string:
+.. code-block:: python
 START_NS, (u'svg', u'http://www.w3.org/2000/svg'), pos
 END_NS
 ------
 The end of a namespace mapping.
 The ``data`` item of such events consists of only the namespace prefix (a
-unicode object)::
+unicode object):
+.. code-block:: python
 END_NS, u'svg', pos
 DOCTYPE
 -------
 A document type declaration.
 For this type of event, the ``data`` item is a tuple of the form
 ``(name, pubid, sysid)``, where ``name`` is the name of the root element,
 ``pubid`` is the public identifier of the DTD (or ``None``), and ``sysid`` is
-the system identifier of the DTD (or ``None``)::
+the system identifier of the DTD (or ``None``):
+.. code-block:: python
 DOCTYPE, (u'html', u'-//W3C//DTD XHTML 1.0 Transitional//EN', \
 u'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'), pos
 COMMENT
 -------
 A comment.
 For such events, the ``data`` item is a unicode object containing all character
-data between the comment delimiters::
+data between the comment delimiters:
+.. code-block:: python
 COMMENT, u'Commented out', pos
 PI
 --
 A processing instruction.
 The ``data`` item is a tuple of the form ``(target, data)`` for processing
 instructions, where ``target`` is the target of the PI (used to identify the
 application by which the instruction should be processed), and ``data`` is text
-following the target (excluding the terminating question mark)::
+following the target (excluding the terminating question mark):
+.. code-block:: python
 PI, (u'php', u'echo "Yo" '), pos
 START_CDATA
 -----------
 Marks the beginning of a ``CDATA`` section.
-The ``data`` item for such events is always ``None``::
+The ``data`` item for such events is always ``None``:
+.. code-block:: python
 START_CDATA, None, pos
 END_CDATA
 ---------
 Marks the end of a ``CDATA`` section.
-The ``data`` item for such events is always ``None``::
+The ``data`` item for such events is always ``None``:
+.. code-block:: python
 END_CDATA, None, pos

Mercurial > genshi > genshi-test

comparison doc/streams.txt @ 511:1a29617a5d87 stable-0.4.x