cmlenz@860: # -*- coding: utf-8 -*-
cmlenz@860: #
cmlenz@860: # Copyright (C) 2006-2009 Edgewall Software
cmlenz@860: # All rights reserved.
cmlenz@860: #
cmlenz@860: # This software is licensed as described in the file COPYING, which
cmlenz@860: # you should have received as part of this distribution. The terms
cmlenz@860: # are also available at http://genshi.edgewall.org/wiki/License.
cmlenz@860: #
cmlenz@860: # This software consists of voluntary contributions made by many
cmlenz@860: # individuals. For the exact contribution history, see the revision
cmlenz@860: # history and logs, available at http://genshi.edgewall.org/log/.
cmlenz@860: 
cmlenz@860: """Core classes for markup processing."""
cmlenz@860: 
cmlenz@860: try:
cmlenz@860:     reduce # builtin in Python < 3
cmlenz@860: except NameError:
cmlenz@860:     from functools import reduce
hodgestar@915: import sys
cmlenz@860: from itertools import chain
cmlenz@860: import operator
cmlenz@860: 
cmlenz@860: from genshi.util import plaintext, stripentities, striptags, stringrepr
cmlenz@860: 
cmlenz@860: __all__ = ['Stream', 'Markup', 'escape', 'unescape', 'Attrs', 'Namespace',
cmlenz@860:            'QName']
cmlenz@860: __docformat__ = 'restructuredtext en'
cmlenz@860: 
cmlenz@860: 
cmlenz@860: class StreamEventKind(str):
cmlenz@860:     """A kind of event on a markup stream."""
cmlenz@860:     __slots__ = []
cmlenz@860:     _instances = {}
cmlenz@860: 
cmlenz@860:     def __new__(cls, val):
cmlenz@860:         return cls._instances.setdefault(val, str.__new__(cls, val))
cmlenz@860: 
cmlenz@860: 
cmlenz@860: class Stream(object):
cmlenz@860:     """Represents a stream of markup events.
cmlenz@860:     
cmlenz@860:     This class is basically an iterator over the events.
cmlenz@860:     
cmlenz@860:     Stream events are tuples of the form::
cmlenz@860:     
cmlenz@860:       (kind, data, position)
cmlenz@860:     
cmlenz@860:     where ``kind`` is the event kind (such as `START`, `END`, `TEXT`, etc),
cmlenz@860:     ``data`` depends on the kind of event, and ``position`` is a
cmlenz@860:     ``(filename, line, offset)`` tuple that contains the location of the
cmlenz@860:     original element or text in the input. If the original location is unknown,
cmlenz@860:     ``position`` is ``(None, -1, -1)``.
cmlenz@860:     
cmlenz@860:     Also provided are ways to serialize the stream to text. The `serialize()`
cmlenz@860:     method will return an iterator over generated strings, while `render()`
cmlenz@860:     returns the complete generated text at once. Both accept various parameters
cmlenz@860:     that impact the way the stream is serialized.
cmlenz@860:     """
cmlenz@860:     __slots__ = ['events', 'serializer']
cmlenz@860: 
cmlenz@860:     START = StreamEventKind('START') #: a start tag
cmlenz@860:     END = StreamEventKind('END') #: an end tag
cmlenz@860:     TEXT = StreamEventKind('TEXT') #: literal text
cmlenz@860:     XML_DECL = StreamEventKind('XML_DECL') #: XML declaration
cmlenz@860:     DOCTYPE = StreamEventKind('DOCTYPE') #: doctype declaration
cmlenz@860:     START_NS = StreamEventKind('START_NS') #: start namespace mapping
cmlenz@860:     END_NS = StreamEventKind('END_NS') #: end namespace mapping
cmlenz@860:     START_CDATA = StreamEventKind('START_CDATA') #: start CDATA section
cmlenz@860:     END_CDATA = StreamEventKind('END_CDATA') #: end CDATA section
cmlenz@860:     PI = StreamEventKind('PI') #: processing instruction
cmlenz@860:     COMMENT = StreamEventKind('COMMENT') #: comment
cmlenz@860: 
cmlenz@860:     def __init__(self, events, serializer=None):
cmlenz@860:         """Initialize the stream with a sequence of markup events.
cmlenz@860:         
cmlenz@860:         :param events: a sequence or iterable providing the events
cmlenz@860:         :param serializer: the default serialization method to use for this
cmlenz@860:                            stream
cmlenz@860: 
cmlenz@860:         :note: Changed in 0.5: added the `serializer` argument
cmlenz@860:         """
cmlenz@860:         self.events = events #: The underlying iterable producing the events
cmlenz@860:         self.serializer = serializer #: The default serializion method
cmlenz@860: 
cmlenz@860:     def __iter__(self):
cmlenz@860:         return iter(self.events)
cmlenz@860: 
cmlenz@860:     def __or__(self, function):
cmlenz@860:         """Override the "bitwise or" operator to apply filters or serializers
cmlenz@860:         to the stream, providing a syntax similar to pipes on Unix shells.
cmlenz@860:         
cmlenz@860:         Assume the following stream produced by the `HTML` function:
cmlenz@860:         
cmlenz@860:         >>> from genshi.input import HTML
hodgestar@915:         >>> html = HTML('''<p onclick="alert('Whoa')">Hello, world!</p>''', encoding='utf-8')
cmlenz@860:         >>> print(html)
cmlenz@860:         <p onclick="alert('Whoa')">Hello, world!</p>
cmlenz@860:         
cmlenz@860:         A filter such as the HTML sanitizer can be applied to that stream using
cmlenz@860:         the pipe notation as follows:
cmlenz@860:         
cmlenz@860:         >>> from genshi.filters import HTMLSanitizer
cmlenz@860:         >>> sanitizer = HTMLSanitizer()
cmlenz@860:         >>> print(html | sanitizer)
cmlenz@860:         <p>Hello, world!</p>
cmlenz@860:         
cmlenz@860:         Filters can be any function that accepts and produces a stream (where
cmlenz@860:         a stream is anything that iterates over events):
cmlenz@860:         
cmlenz@860:         >>> def uppercase(stream):
cmlenz@860:         ...     for kind, data, pos in stream:
cmlenz@860:         ...         if kind is TEXT:
cmlenz@860:         ...             data = data.upper()
cmlenz@860:         ...         yield kind, data, pos
cmlenz@860:         >>> print(html | sanitizer | uppercase)
cmlenz@860:         <p>HELLO, WORLD!</p>
cmlenz@860:         
cmlenz@860:         Serializers can also be used with this notation:
cmlenz@860:         
cmlenz@860:         >>> from genshi.output import TextSerializer
cmlenz@860:         >>> output = TextSerializer()
cmlenz@860:         >>> print(html | sanitizer | uppercase | output)
cmlenz@860:         HELLO, WORLD!
cmlenz@860:         
cmlenz@860:         Commonly, serializers should be used at the end of the "pipeline";
cmlenz@860:         using them somewhere in the middle may produce unexpected results.
cmlenz@860:         
cmlenz@860:         :param function: the callable object that should be applied as a filter
cmlenz@860:         :return: the filtered stream
cmlenz@860:         :rtype: `Stream`
cmlenz@860:         """
cmlenz@860:         return Stream(_ensure(function(self)), serializer=self.serializer)
cmlenz@860: 
cmlenz@860:     def filter(self, *filters):
cmlenz@860:         """Apply filters to the stream.
cmlenz@860:         
cmlenz@860:         This method returns a new stream with the given filters applied. The
cmlenz@860:         filters must be callables that accept the stream object as parameter,
cmlenz@860:         and return the filtered stream.
cmlenz@860:         
cmlenz@860:         The call::
cmlenz@860:         
cmlenz@860:             stream.filter(filter1, filter2)
cmlenz@860:         
cmlenz@860:         is equivalent to::
cmlenz@860:         
cmlenz@860:             stream | filter1 | filter2
cmlenz@860:         
cmlenz@860:         :param filters: one or more callable objects that should be applied as
cmlenz@860:                         filters
cmlenz@860:         :return: the filtered stream
cmlenz@860:         :rtype: `Stream`
cmlenz@860:         """
cmlenz@860:         return reduce(operator.or_, (self,) + filters)
cmlenz@860: 
hodgestar@915:     def render(self, method=None, encoding=None, out=None, **kwargs):
cmlenz@860:         """Return a string representation of the stream.
cmlenz@860:         
cmlenz@860:         Any additional keyword arguments are passed to the serializer, and thus
cmlenz@860:         depend on the `method` parameter value.
cmlenz@860:         
cmlenz@860:         :param method: determines how the stream is serialized; can be either
cmlenz@860:                        "xml", "xhtml", "html", "text", or a custom serializer
cmlenz@860:                        class; if `None`, the default serialization method of
cmlenz@860:                        the stream is used
cmlenz@860:         :param encoding: how the output string should be encoded; if set to
cmlenz@860:                          `None`, this method returns a `unicode` object
cmlenz@860:         :param out: a file-like object that the output should be written to
cmlenz@860:                     instead of being returned as one big string; note that if
cmlenz@860:                     this is a file or socket (or similar), the `encoding` must
cmlenz@860:                     not be `None` (that is, the output must be encoded)
cmlenz@860:         :return: a `str` or `unicode` object (depending on the `encoding`
cmlenz@860:                  parameter), or `None` if the `out` parameter is provided
cmlenz@860:         :rtype: `basestring`
cmlenz@860:         
cmlenz@860:         :see: XMLSerializer, XHTMLSerializer, HTMLSerializer, TextSerializer
cmlenz@860:         :note: Changed in 0.5: added the `out` parameter
cmlenz@860:         """
cmlenz@860:         from genshi.output import encode
cmlenz@860:         if method is None:
cmlenz@860:             method = self.serializer or 'xml'
cmlenz@860:         generator = self.serialize(method=method, **kwargs)
cmlenz@860:         return encode(generator, method=method, encoding=encoding, out=out)
cmlenz@860: 
cmlenz@860:     def select(self, path, namespaces=None, variables=None):
cmlenz@860:         """Return a new stream that contains the events matching the given
cmlenz@860:         XPath expression.
cmlenz@860:         
cmlenz@860:         >>> from genshi import HTML
hodgestar@915:         >>> stream = HTML('<doc><elem>foo</elem><elem>bar</elem></doc>', encoding='utf-8')
cmlenz@860:         >>> print(stream.select('elem'))
cmlenz@860:         <elem>foo</elem><elem>bar</elem>
cmlenz@860:         >>> print(stream.select('elem/text()'))
cmlenz@860:         foobar
cmlenz@860:         
cmlenz@860:         Note that the outermost element of the stream becomes the *context
cmlenz@860:         node* for the XPath test. That means that the expression "doc" would
cmlenz@860:         not match anything in the example above, because it only tests against
cmlenz@860:         child elements of the outermost element:
cmlenz@860:         
cmlenz@860:         >>> print(stream.select('doc'))
cmlenz@860:         <BLANKLINE>
cmlenz@860:         
cmlenz@860:         You can use the "." expression to match the context node itself
cmlenz@860:         (although that usually makes little sense):
cmlenz@860:         
cmlenz@860:         >>> print(stream.select('.'))
cmlenz@860:         <doc><elem>foo</elem><elem>bar</elem></doc>
cmlenz@860:         
cmlenz@860:         :param path: a string containing the XPath expression
cmlenz@860:         :param namespaces: mapping of namespace prefixes used in the path
cmlenz@860:         :param variables: mapping of variable names to values
cmlenz@860:         :return: the selected substream
cmlenz@860:         :rtype: `Stream`
cmlenz@860:         :raises PathSyntaxError: if the given path expression is invalid or not
cmlenz@860:                                  supported
cmlenz@860:         """
cmlenz@860:         from genshi.path import Path
cmlenz@860:         return Path(path).select(self, namespaces, variables)
cmlenz@860: 
cmlenz@860:     def serialize(self, method='xml', **kwargs):
cmlenz@860:         """Generate strings corresponding to a specific serialization of the
cmlenz@860:         stream.
cmlenz@860:         
cmlenz@860:         Unlike the `render()` method, this method is a generator that returns
cmlenz@860:         the serialized output incrementally, as opposed to returning a single
cmlenz@860:         string.
cmlenz@860:         
cmlenz@860:         Any additional keyword arguments are passed to the serializer, and thus
cmlenz@860:         depend on the `method` parameter value.
cmlenz@860:         
cmlenz@860:         :param method: determines how the stream is serialized; can be either
cmlenz@860:                        "xml", "xhtml", "html", "text", or a custom serializer
cmlenz@860:                        class; if `None`, the default serialization method of
cmlenz@860:                        the stream is used
cmlenz@860:         :return: an iterator over the serialization results (`Markup` or
cmlenz@860:                  `unicode` objects, depending on the serialization method)
cmlenz@860:         :rtype: ``iterator``
cmlenz@860:         :see: XMLSerializer, XHTMLSerializer, HTMLSerializer, TextSerializer
cmlenz@860:         """
cmlenz@860:         from genshi.output import get_serializer
cmlenz@860:         if method is None:
cmlenz@860:             method = self.serializer or 'xml'
cmlenz@860:         return get_serializer(method, **kwargs)(_ensure(self))
cmlenz@860: 
cmlenz@860:     def __str__(self):
cmlenz@860:         return self.render()
cmlenz@860: 
cmlenz@860:     def __unicode__(self):
cmlenz@860:         return self.render(encoding=None)
cmlenz@860: 
cmlenz@860:     def __html__(self):
cmlenz@860:         return self
cmlenz@860: 
cmlenz@860: 
cmlenz@860: START = Stream.START
cmlenz@860: END = Stream.END
cmlenz@860: TEXT = Stream.TEXT
cmlenz@860: XML_DECL = Stream.XML_DECL
cmlenz@860: DOCTYPE = Stream.DOCTYPE
cmlenz@860: START_NS = Stream.START_NS
cmlenz@860: END_NS = Stream.END_NS
cmlenz@860: START_CDATA = Stream.START_CDATA
cmlenz@860: END_CDATA = Stream.END_CDATA
cmlenz@860: PI = Stream.PI
cmlenz@860: COMMENT = Stream.COMMENT
cmlenz@860: 
cmlenz@860: 
cmlenz@860: def _ensure(stream):
cmlenz@860:     """Ensure that every item on the stream is actually a markup event."""
cmlenz@860:     stream = iter(stream)
cmlenz@860:     event = stream.next()
cmlenz@860: 
cmlenz@860:     # Check whether the iterable is a real markup event stream by examining the
cmlenz@860:     # first item it yields; if it's not we'll need to do some conversion
cmlenz@860:     if type(event) is not tuple or len(event) != 3:
cmlenz@860:         for event in chain([event], stream):
cmlenz@860:             if hasattr(event, 'totuple'):
cmlenz@860:                 event = event.totuple()
cmlenz@860:             else:
cmlenz@860:                 event = TEXT, unicode(event), (None, -1, -1)
cmlenz@860:             yield event
cmlenz@860:         return
cmlenz@860: 
cmlenz@860:     # This looks like a markup event stream, so we'll just pass it through
cmlenz@860:     # unchanged
cmlenz@860:     yield event
cmlenz@860:     for event in stream:
cmlenz@860:         yield event
cmlenz@860: 
cmlenz@860: 
cmlenz@860: class Attrs(tuple):
cmlenz@860:     """Immutable sequence type that stores the attributes of an element.
cmlenz@860:     
cmlenz@860:     Ordering of the attributes is preserved, while access by name is also
cmlenz@860:     supported.
cmlenz@860:     
cmlenz@860:     >>> attrs = Attrs([('href', '#'), ('title', 'Foo')])
cmlenz@860:     >>> attrs
cmlenz@860:     Attrs([('href', '#'), ('title', 'Foo')])
cmlenz@860:     
cmlenz@860:     >>> 'href' in attrs
cmlenz@860:     True
cmlenz@860:     >>> 'tabindex' in attrs
cmlenz@860:     False
cmlenz@860:     >>> attrs.get('title')
cmlenz@860:     'Foo'
cmlenz@860:     
cmlenz@860:     Instances may not be manipulated directly. Instead, the operators ``|`` and
cmlenz@860:     ``-`` can be used to produce new instances that have specific attributes
cmlenz@860:     added, replaced or removed.
cmlenz@860:     
cmlenz@860:     To remove an attribute, use the ``-`` operator. The right hand side can be
cmlenz@860:     either a string or a set/sequence of strings, identifying the name(s) of
cmlenz@860:     the attribute(s) to remove:
cmlenz@860:     
cmlenz@860:     >>> attrs - 'title'
cmlenz@860:     Attrs([('href', '#')])
cmlenz@860:     >>> attrs - ('title', 'href')
cmlenz@860:     Attrs()
cmlenz@860:     
cmlenz@860:     The original instance is not modified, but the operator can of course be
cmlenz@860:     used with an assignment:
cmlenz@860: 
cmlenz@860:     >>> attrs
cmlenz@860:     Attrs([('href', '#'), ('title', 'Foo')])
cmlenz@860:     >>> attrs -= 'title'
cmlenz@860:     >>> attrs
cmlenz@860:     Attrs([('href', '#')])
cmlenz@860:     
cmlenz@860:     To add a new attribute, use the ``|`` operator, where the right hand value
cmlenz@860:     is a sequence of ``(name, value)`` tuples (which includes `Attrs`
cmlenz@860:     instances):
cmlenz@860:     
cmlenz@860:     >>> attrs | [('title', 'Bar')]
cmlenz@860:     Attrs([('href', '#'), ('title', 'Bar')])
cmlenz@860:     
cmlenz@860:     If the attributes already contain an attribute with a given name, the value
cmlenz@860:     of that attribute is replaced:
cmlenz@860:     
cmlenz@860:     >>> attrs | [('href', 'http://example.org/')]
cmlenz@860:     Attrs([('href', 'http://example.org/')])
cmlenz@860:     """
cmlenz@860:     __slots__ = []
cmlenz@860: 
cmlenz@860:     def __contains__(self, name):
cmlenz@860:         """Return whether the list includes an attribute with the specified
cmlenz@860:         name.
cmlenz@860:         
cmlenz@860:         :return: `True` if the list includes the attribute
cmlenz@860:         :rtype: `bool`
cmlenz@860:         """
cmlenz@860:         for attr, _ in self:
cmlenz@860:             if attr == name:
cmlenz@860:                 return True
cmlenz@860: 
cmlenz@860:     def __getitem__(self, i):
cmlenz@860:         """Return an item or slice of the attributes list.
cmlenz@860:         
cmlenz@860:         >>> attrs = Attrs([('href', '#'), ('title', 'Foo')])
cmlenz@860:         >>> attrs[1]
cmlenz@860:         ('title', 'Foo')
cmlenz@860:         >>> attrs[1:]
cmlenz@860:         Attrs([('title', 'Foo')])
cmlenz@860:         """
cmlenz@860:         items = tuple.__getitem__(self, i)
cmlenz@860:         if type(i) is slice:
cmlenz@860:             return Attrs(items)
cmlenz@860:         return items
cmlenz@860: 
cmlenz@860:     def __getslice__(self, i, j):
cmlenz@860:         """Return a slice of the attributes list.
cmlenz@860:         
cmlenz@860:         >>> attrs = Attrs([('href', '#'), ('title', 'Foo')])
cmlenz@860:         >>> attrs[1:]
cmlenz@860:         Attrs([('title', 'Foo')])
cmlenz@860:         """
cmlenz@860:         return Attrs(tuple.__getslice__(self, i, j))
cmlenz@860: 
cmlenz@860:     def __or__(self, attrs):
cmlenz@860:         """Return a new instance that contains the attributes in `attrs` in
cmlenz@904:         addition to any already existing attributes. Any attributes in the new
cmlenz@904:         set that have a value of `None` are removed.
cmlenz@860:         
cmlenz@860:         :return: a new instance with the merged attributes
cmlenz@860:         :rtype: `Attrs`
cmlenz@860:         """
cmlenz@904:         remove = set([an for an, av in attrs if av is None])
cmlenz@904:         replace = dict([(an, av) for an, av in attrs
cmlenz@904:                         if an in self and av is not None])
cmlenz@904:         return Attrs([(sn, replace.get(sn, sv)) for sn, sv in self
cmlenz@904:                       if sn not in remove] +
cmlenz@904:                      [(an, av) for an, av in attrs
cmlenz@904:                       if an not in self and an not in remove])
cmlenz@860: 
cmlenz@860:     def __repr__(self):
cmlenz@860:         if not self:
cmlenz@860:             return 'Attrs()'
cmlenz@860:         return 'Attrs([%s])' % ', '.join([repr(item) for item in self])
cmlenz@860: 
cmlenz@860:     def __sub__(self, names):
cmlenz@860:         """Return a new instance with all attributes with a name in `names` are
cmlenz@860:         removed.
cmlenz@860:         
cmlenz@860:         :param names: the names of the attributes to remove
cmlenz@860:         :return: a new instance with the attribute removed
cmlenz@860:         :rtype: `Attrs`
cmlenz@860:         """
cmlenz@860:         if isinstance(names, basestring):
cmlenz@860:             names = (names,)
cmlenz@860:         return Attrs([(name, val) for name, val in self if name not in names])
cmlenz@860: 
cmlenz@860:     def get(self, name, default=None):
cmlenz@860:         """Return the value of the attribute with the specified name, or the
cmlenz@860:         value of the `default` parameter if no such attribute is found.
cmlenz@860:         
cmlenz@860:         :param name: the name of the attribute
cmlenz@860:         :param default: the value to return when the attribute does not exist
cmlenz@860:         :return: the attribute value, or the `default` value if that attribute
cmlenz@860:                  does not exist
cmlenz@860:         :rtype: `object`
cmlenz@860:         """
cmlenz@860:         for attr, value in self:
cmlenz@860:             if attr == name:
cmlenz@860:                 return value
cmlenz@860:         return default
cmlenz@860: 
cmlenz@860:     def totuple(self):
cmlenz@860:         """Return the attributes as a markup event.
cmlenz@860:         
cmlenz@860:         The returned event is a `TEXT` event, the data is the value of all
cmlenz@860:         attributes joined together.
cmlenz@860:         
cmlenz@860:         >>> Attrs([('href', '#'), ('title', 'Foo')]).totuple()
cmlenz@860:         ('TEXT', '#Foo', (None, -1, -1))
cmlenz@860:         
cmlenz@860:         :return: a `TEXT` event
cmlenz@860:         :rtype: `tuple`
cmlenz@860:         """
cmlenz@860:         return TEXT, ''.join([x[1] for x in self]), (None, -1, -1)
cmlenz@860: 
cmlenz@860: 
cmlenz@860: class Markup(unicode):
cmlenz@860:     """Marks a string as being safe for inclusion in HTML/XML output without
cmlenz@860:     needing to be escaped.
cmlenz@860:     """
cmlenz@860:     __slots__ = []
cmlenz@860: 
cmlenz@860:     def __add__(self, other):
cmlenz@860:         return Markup(unicode.__add__(self, escape(other)))
cmlenz@860: 
cmlenz@860:     def __radd__(self, other):
cmlenz@860:         return Markup(unicode.__add__(escape(other), self))
cmlenz@860: 
cmlenz@860:     def __mod__(self, args):
cmlenz@860:         if isinstance(args, dict):
cmlenz@860:             args = dict(zip(args.keys(), map(escape, args.values())))
cmlenz@860:         elif isinstance(args, (list, tuple)):
cmlenz@860:             args = tuple(map(escape, args))
cmlenz@860:         else:
cmlenz@860:             args = escape(args)
cmlenz@860:         return Markup(unicode.__mod__(self, args))
cmlenz@860: 
cmlenz@860:     def __mul__(self, num):
cmlenz@860:         return Markup(unicode.__mul__(self, num))
cmlenz@860:     __rmul__ = __mul__
cmlenz@860: 
cmlenz@860:     def __repr__(self):
cmlenz@860:         return "<%s %s>" % (type(self).__name__, unicode.__repr__(self))
cmlenz@860: 
cmlenz@860:     def join(self, seq, escape_quotes=True):
cmlenz@860:         """Return a `Markup` object which is the concatenation of the strings
cmlenz@860:         in the given sequence, where this `Markup` object is the separator
cmlenz@860:         between the joined elements.
cmlenz@860:         
cmlenz@860:         Any element in the sequence that is not a `Markup` instance is
cmlenz@860:         automatically escaped.
cmlenz@860:         
cmlenz@860:         :param seq: the sequence of strings to join
cmlenz@860:         :param escape_quotes: whether double quote characters in the elements
cmlenz@860:                               should be escaped
cmlenz@860:         :return: the joined `Markup` object
cmlenz@860:         :rtype: `Markup`
cmlenz@860:         :see: `escape`
cmlenz@860:         """
cmlenz@860:         return Markup(unicode.join(self, [escape(item, quotes=escape_quotes)
cmlenz@860:                                           for item in seq]))
cmlenz@860: 
cmlenz@860:     @classmethod
cmlenz@860:     def escape(cls, text, quotes=True):
cmlenz@860:         """Create a Markup instance from a string and escape special characters
cmlenz@860:         it may contain (<, >, & and \").
cmlenz@860:         
cmlenz@860:         >>> escape('"1 < 2"')
cmlenz@860:         <Markup u'&#34;1 &lt; 2&#34;'>
cmlenz@860:         
cmlenz@860:         If the `quotes` parameter is set to `False`, the \" character is left
cmlenz@860:         as is. Escaping quotes is generally only required for strings that are
cmlenz@860:         to be used in attribute values.
cmlenz@860:         
cmlenz@860:         >>> escape('"1 < 2"', quotes=False)
cmlenz@860:         <Markup u'"1 &lt; 2"'>
cmlenz@860:         
cmlenz@860:         :param text: the text to escape
cmlenz@860:         :param quotes: if ``True``, double quote characters are escaped in
cmlenz@860:                        addition to the other special characters
cmlenz@860:         :return: the escaped `Markup` string
cmlenz@860:         :rtype: `Markup`
cmlenz@860:         """
cmlenz@860:         if not text:
cmlenz@860:             return cls()
cmlenz@860:         if type(text) is cls:
cmlenz@860:             return text
cmlenz@860:         if hasattr(text, '__html__'):
cmlenz@904:             return cls(text.__html__())
cmlenz@860: 
cmlenz@860:         text = text.replace('&', '&amp;') \
cmlenz@860:                    .replace('<', '&lt;') \
cmlenz@860:                    .replace('>', '&gt;')
cmlenz@860:         if quotes:
cmlenz@860:             text = text.replace('"', '&#34;')
cmlenz@860:         return cls(text)
cmlenz@860: 
cmlenz@860:     def unescape(self):
cmlenz@860:         """Reverse-escapes &, <, >, and \" and returns a `unicode` object.
cmlenz@860:         
cmlenz@860:         >>> Markup('1 &lt; 2').unescape()
cmlenz@860:         u'1 < 2'
cmlenz@860:         
cmlenz@860:         :return: the unescaped string
cmlenz@860:         :rtype: `unicode`
cmlenz@860:         :see: `genshi.core.unescape`
cmlenz@860:         """
cmlenz@860:         if not self:
cmlenz@860:             return ''
cmlenz@860:         return unicode(self).replace('&#34;', '"') \
cmlenz@860:                             .replace('&gt;', '>') \
cmlenz@860:                             .replace('&lt;', '<') \
cmlenz@860:                             .replace('&amp;', '&')
cmlenz@860: 
cmlenz@860:     def stripentities(self, keepxmlentities=False):
cmlenz@860:         """Return a copy of the text with any character or numeric entities
cmlenz@860:         replaced by the equivalent UTF-8 characters.
cmlenz@860:         
cmlenz@860:         If the `keepxmlentities` parameter is provided and evaluates to `True`,
cmlenz@860:         the core XML entities (``&amp;``, ``&apos;``, ``&gt;``, ``&lt;`` and
cmlenz@860:         ``&quot;``) are not stripped.
cmlenz@860:         
cmlenz@860:         :return: a `Markup` instance with entities removed
cmlenz@860:         :rtype: `Markup`
cmlenz@860:         :see: `genshi.util.stripentities`
cmlenz@860:         """
cmlenz@860:         return Markup(stripentities(self, keepxmlentities=keepxmlentities))
cmlenz@860: 
cmlenz@860:     def striptags(self):
cmlenz@860:         """Return a copy of the text with all XML/HTML tags removed.
cmlenz@860:         
cmlenz@860:         :return: a `Markup` instance with all tags removed
cmlenz@860:         :rtype: `Markup`
cmlenz@860:         :see: `genshi.util.striptags`
cmlenz@860:         """
cmlenz@860:         return Markup(striptags(self))
cmlenz@860: 
cmlenz@860: 
cmlenz@860: try:
cmlenz@860:     from genshi._speedups import Markup
cmlenz@860: except ImportError:
cmlenz@860:     pass # just use the Python implementation
cmlenz@860: 
cmlenz@860: 
cmlenz@860: escape = Markup.escape
cmlenz@860: 
cmlenz@860: 
cmlenz@860: def unescape(text):
cmlenz@860:     """Reverse-escapes &, <, >, and \" and returns a `unicode` object.
cmlenz@860:     
cmlenz@860:     >>> unescape(Markup('1 &lt; 2'))
cmlenz@860:     u'1 < 2'
cmlenz@860:     
cmlenz@860:     If the provided `text` object is not a `Markup` instance, it is returned
cmlenz@860:     unchanged.
cmlenz@860:     
cmlenz@860:     >>> unescape('1 &lt; 2')
cmlenz@860:     '1 &lt; 2'
cmlenz@860:     
cmlenz@860:     :param text: the text to unescape
cmlenz@860:     :return: the unescsaped string
cmlenz@860:     :rtype: `unicode`
cmlenz@860:     """
cmlenz@860:     if not isinstance(text, Markup):
cmlenz@860:         return text
cmlenz@860:     return text.unescape()
cmlenz@860: 
cmlenz@860: 
cmlenz@860: class Namespace(object):
cmlenz@860:     """Utility class creating and testing elements with a namespace.
cmlenz@860:     
cmlenz@860:     Internally, namespace URIs are encoded in the `QName` of any element or
cmlenz@860:     attribute, the namespace URI being enclosed in curly braces. This class
cmlenz@860:     helps create and test these strings.
cmlenz@860:     
cmlenz@860:     A `Namespace` object is instantiated with the namespace URI.
cmlenz@860:     
cmlenz@860:     >>> html = Namespace('http://www.w3.org/1999/xhtml')
cmlenz@860:     >>> html
cmlenz@860:     Namespace('http://www.w3.org/1999/xhtml')
cmlenz@860:     >>> html.uri
cmlenz@860:     u'http://www.w3.org/1999/xhtml'
cmlenz@860:     
cmlenz@860:     The `Namespace` object can than be used to generate `QName` objects with
cmlenz@860:     that namespace:
cmlenz@860:     
cmlenz@860:     >>> html.body
cmlenz@860:     QName('http://www.w3.org/1999/xhtml}body')
cmlenz@860:     >>> html.body.localname
cmlenz@860:     u'body'
cmlenz@860:     >>> html.body.namespace
cmlenz@860:     u'http://www.w3.org/1999/xhtml'
cmlenz@860:     
cmlenz@860:     The same works using item access notation, which is useful for element or
cmlenz@860:     attribute names that are not valid Python identifiers:
cmlenz@860:     
cmlenz@860:     >>> html['body']
cmlenz@860:     QName('http://www.w3.org/1999/xhtml}body')
cmlenz@860:     
cmlenz@860:     A `Namespace` object can also be used to test whether a specific `QName`
cmlenz@860:     belongs to that namespace using the ``in`` operator:
cmlenz@860:     
cmlenz@860:     >>> qname = html.body
cmlenz@860:     >>> qname in html
cmlenz@860:     True
cmlenz@860:     >>> qname in Namespace('http://www.w3.org/2002/06/xhtml2')
cmlenz@860:     False
cmlenz@860:     """
cmlenz@860:     def __new__(cls, uri):
cmlenz@860:         if type(uri) is cls:
cmlenz@860:             return uri
cmlenz@860:         return object.__new__(cls)
cmlenz@860: 
cmlenz@860:     def __getnewargs__(self):
cmlenz@860:         return (self.uri,)
cmlenz@860: 
cmlenz@860:     def __getstate__(self):
cmlenz@860:         return self.uri
cmlenz@860: 
cmlenz@860:     def __setstate__(self, uri):
cmlenz@860:         self.uri = uri
cmlenz@860: 
cmlenz@860:     def __init__(self, uri):
cmlenz@860:         self.uri = unicode(uri)
cmlenz@860: 
cmlenz@860:     def __contains__(self, qname):
cmlenz@860:         return qname.namespace == self.uri
cmlenz@860: 
cmlenz@860:     def __ne__(self, other):
cmlenz@860:         return not self == other
cmlenz@860: 
cmlenz@860:     def __eq__(self, other):
cmlenz@860:         if isinstance(other, Namespace):
cmlenz@860:             return self.uri == other.uri
cmlenz@860:         return self.uri == other
cmlenz@860: 
cmlenz@860:     def __getitem__(self, name):
cmlenz@860:         return QName(self.uri + '}' + name)
cmlenz@860:     __getattr__ = __getitem__
cmlenz@860: 
cmlenz@860:     def __hash__(self):
cmlenz@860:         return hash(self.uri)
cmlenz@860: 
hodgestar@915:     if sys.version_info[0] == 2:
hodgestar@915:         # Only use stringrepr in python 2
hodgestar@915:         def __repr__(self):
hodgestar@915:             return '%s(%s)' % (type(self).__name__, stringrepr(self.uri))
hodgestar@915:     else:
hodgestar@915:         def __repr__(self):
hodgestar@915:             return '%s(%r)' % (type(self).__name__, self.uri)
cmlenz@860: 
cmlenz@860:     def __str__(self):
cmlenz@860:         return self.uri.encode('utf-8')
cmlenz@860: 
cmlenz@860:     def __unicode__(self):
cmlenz@860:         return self.uri
cmlenz@860: 
cmlenz@860: 
cmlenz@860: # The namespace used by attributes such as xml:lang and xml:space
cmlenz@860: XML_NAMESPACE = Namespace('http://www.w3.org/XML/1998/namespace')
cmlenz@860: 
cmlenz@860: 
cmlenz@860: class QName(unicode):
cmlenz@860:     """A qualified element or attribute name.
cmlenz@860:     
cmlenz@860:     The unicode value of instances of this class contains the qualified name of
cmlenz@860:     the element or attribute, in the form ``{namespace-uri}local-name``. The
cmlenz@860:     namespace URI can be obtained through the additional `namespace` attribute,
cmlenz@860:     while the local name can be accessed through the `localname` attribute.
cmlenz@860:     
cmlenz@860:     >>> qname = QName('foo')
cmlenz@860:     >>> qname
cmlenz@860:     QName('foo')
cmlenz@860:     >>> qname.localname
cmlenz@860:     u'foo'
cmlenz@860:     >>> qname.namespace
cmlenz@860:     
cmlenz@860:     >>> qname = QName('http://www.w3.org/1999/xhtml}body')
cmlenz@860:     >>> qname
cmlenz@860:     QName('http://www.w3.org/1999/xhtml}body')
cmlenz@860:     >>> qname.localname
cmlenz@860:     u'body'
cmlenz@860:     >>> qname.namespace
cmlenz@860:     u'http://www.w3.org/1999/xhtml'
cmlenz@860:     """
cmlenz@860:     __slots__ = ['namespace', 'localname']
cmlenz@860: 
cmlenz@860:     def __new__(cls, qname):
cmlenz@860:         """Create the `QName` instance.
cmlenz@860:         
cmlenz@860:         :param qname: the qualified name as a string of the form
cmlenz@860:                       ``{namespace-uri}local-name``, where the leading curly
cmlenz@860:                       brace is optional
cmlenz@860:         """
cmlenz@860:         if type(qname) is cls:
cmlenz@860:             return qname
cmlenz@860: 
hodgestar@920:         qname = qname.lstrip('{')
hodgestar@920:         parts = qname.split('}', 1)
cmlenz@860:         if len(parts) > 1:
cmlenz@860:             self = unicode.__new__(cls, '{%s' % qname)
cmlenz@860:             self.namespace, self.localname = map(unicode, parts)
cmlenz@860:         else:
cmlenz@860:             self = unicode.__new__(cls, qname)
cmlenz@860:             self.namespace, self.localname = None, unicode(qname)
cmlenz@860:         return self
cmlenz@860: 
cmlenz@860:     def __getnewargs__(self):
cmlenz@860:         return (self.lstrip('{'),)
cmlenz@860: 
hodgestar@915:     if sys.version_info[0] == 2:
hodgestar@915:         # Only use stringrepr in python 2
hodgestar@915:         def __repr__(self):
hodgestar@915:             return '%s(%s)' % (type(self).__name__, stringrepr(self.lstrip('{')))
hodgestar@915:     else:
hodgestar@915:         def __repr__(self):
hodgestar@915:             return '%s(%r)' % (type(self).__name__, self.lstrip('{'))