Class Stream

Parameters:

• events - a sequence or iterable providing the events
• serializer - the default serialization method to use for this stream

Overrides: object.__init__

Override the "bitwise or" operator to apply filters or serializers to the stream, providing a syntax similar to pipes on Unix shells.

Assume the following stream produced by the HTML function:

>>> from genshi.input import HTML
>>> html = HTML('''<p onclick="alert('Whoa')">Hello, world!</p>''')
>>> print(html)
<p onclick="alert('Whoa')">Hello, world!</p>

A filter such as the HTML sanitizer can be applied to that stream using the pipe notation as follows:

>>> from genshi.filters import HTMLSanitizer
>>> sanitizer = HTMLSanitizer()
>>> print(html | sanitizer)
<p>Hello, world!</p>

Filters can be any function that accepts and produces a stream (where a stream is anything that iterates over events):

>>> def uppercase(stream):
...     for kind, data, pos in stream:
...         if kind is TEXT:
...             data = data.upper()
...         yield kind, data, pos
>>> print(html | sanitizer | uppercase)
<p>HELLO, WORLD!</p>

Serializers can also be used with this notation:

>>> from genshi.output import TextSerializer
>>> output = TextSerializer()
>>> print(html | sanitizer | uppercase | output)
HELLO, WORLD!

Commonly, serializers should be used at the end of the "pipeline"; using them somewhere in the middle may produce unexpected results.

Parameters:

• function - the callable object that should be applied as a filter

Returns: Stream

the filtered stream

Apply filters to the stream.

This method returns a new stream with the given filters applied. The filters must be callables that accept the stream object as parameter, and return the filtered stream.

The call:

stream.filter(filter1, filter2)

is equivalent to:

stream | filter1 | filter2

Parameters:

• filters - one or more callable objects that should be applied as filters

Returns: Stream

the filtered stream

Return a string representation of the stream.

Any additional keyword arguments are passed to the serializer, and thus depend on the method parameter value.

Parameters:

• method - determines how the stream is serialized; can be either "xml", "xhtml", "html", "text", or a custom serializer class; if None, the default serialization method of the stream is used
• encoding - how the output string should be encoded; if set to None, this method returns a unicode object
• out - a file-like object that the output should be written to instead of being returned as one big string; note that if this is a file or socket (or similar), the encoding must not be None (that is, the output must be encoded)

Returns: basestring

a str or unicode object (depending on the encoding parameter), or None if the out parameter is provided

Return a new stream that contains the events matching the given XPath expression.

>>> from genshi import HTML
>>> stream = HTML('<doc><elem>foo</elem><elem>bar</elem></doc>')
>>> print(stream.select('elem'))
<elem>foo</elem><elem>bar</elem>
>>> print(stream.select('elem/text()'))
foobar

Note that the outermost element of the stream becomes the context node for the XPath test. That means that the expression "doc" would not match anything in the example above, because it only tests against child elements of the outermost element:

>>> print(stream.select('doc'))
<BLANKLINE>

You can use the "." expression to match the context node itself (although that usually makes little sense):

>>> print(stream.select('.'))
<doc><elem>foo</elem><elem>bar</elem></doc>

Parameters:

• path - a string containing the XPath expression
• namespaces - mapping of namespace prefixes used in the path
• variables - mapping of variable names to values

Returns: Stream

the selected substream

Raises:

• PathSyntaxError - if the given path expression is invalid or not supported

Generate strings corresponding to a specific serialization of the stream.

Unlike the render() method, this method is a generator that returns the serialized output incrementally, as opposed to returning a single string.

Any additional keyword arguments are passed to the serializer, and thus depend on the method parameter value.

Parameters:

• method - determines how the stream is serialized; can be either "xml", "xhtml", "html", "text", or a custom serializer class; if None, the default serialization method of the stream is used

Returns: iterator

an iterator over the serialization results (Markup or unicode objects, depending on the serialization method)

Overrides: object.__str__

(inherited documentation)