Changes between Version 4 and Version 5 of MarkupStream

Timestamp:

Aug 28, 2006, 11:45:12 AM (18 years ago)

Author:

cmlenz

Comment:

Added section on stream filtering

MarkupStream

@@ -39 +39 @@
 }}}
 
+== Filtering ==
+
+One important feature of markup streams is that you can apply ''filters'' to the stream, either filters that come with Markup, or your own custom filters.
+
+A filter is simply a callable that accepts the stream as parameter, and returns the filtered stream:
+
+{{{
+#!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:
+
+{{{
+#!python
+stream = noop(stream)
+}}}
+
+The `Stream` class also provides a `filter()` method, which takes an arbitrary number of filter callables and applies them all:
+
+{{{
+#!python
+stream = stream.filter(noop)
+}}}
+
+Finally, filters can also be applied using the ''right shift'' operator (`>>`):
+
+{{{
+#!python
+stream = stream >> noop
+}}}
+
+ ''Note: this is only available in the current development version (0.3)''
+
+One example of a filter included with Markup is the `HTMLSanitizer` in `markup.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.
+
+Both the `filter()` method and the right-shift operator allow easy chaining of filters:
+
+{{{
+#!python
+from markup.filters import HTMLSanitizer
+stream = stream.filter(noop, HTMLSanitizer())
+}}}
+
+That is equivalent to:
+
+{{{
+#!python
+stream = stream >> noop >> HTMLSanitizer()
+}}}
+
 == Serialization ==
 
@@ -66 +120 @@
 }}}
 
-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”, or a subclass of the `markup.output.Serializer` class:
+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:
 
 {{{
@@ -76 +130 @@
 
 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 `markup.output` can also be used directly:
+
+{{{
+>>> from markup.filters import HTMLSanitizer
+>>> from markup.output import TextSerializer
+>>> print TextSerializer()(HTMLSanitizer()(stream))
+Some text and a link.
+}}}
+
+The right-shift operator (added in 0.3) allows a nicer syntax:
+
+{{{
+>>> print stream >> HTMLSanitizer() >> TextSerializer()
+Some text and a link.
+}}}
 
 == Using XPath ==