cmlenz@1: # -*- coding: utf-8 -*-
cmlenz@1: #
cmlenz@854: # Copyright (C) 2006-2009 Edgewall Software
cmlenz@1: # All rights reserved.
cmlenz@1: #
cmlenz@1: # This software is licensed as described in the file COPYING, which
cmlenz@1: # you should have received as part of this distribution. The terms
cmlenz@230: # are also available at http://genshi.edgewall.org/wiki/License.
cmlenz@1: #
cmlenz@1: # This software consists of voluntary contributions made by many
cmlenz@1: # individuals. For the exact contribution history, see the revision
cmlenz@230: # history and logs, available at http://genshi.edgewall.org/log/.
cmlenz@1: 
cmlenz@430: """Support for programmatically generating markup streams from Python code using
cmlenz@430: a very simple syntax. The main entry point to this module is the `tag` object
cmlenz@430: (which is actually an instance of the ``ElementFactory`` class). You should
cmlenz@430: rarely (if ever) need to directly import and use any of the other classes in
cmlenz@430: this module.
cmlenz@430: 
cmlenz@430: Elements can be created using the `tag` object using attribute access. For
cmlenz@430: example:
cmlenz@430: 
cmlenz@430: >>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.')
cmlenz@430: >>> doc
cmlenz@430: <Element "p">
cmlenz@430: 
cmlenz@430: This produces an `Element` instance which can be further modified to add child
cmlenz@430: nodes and attributes. This is done by "calling" the element: positional
cmlenz@430: arguments are added as child nodes (alternatively, the `Element.append` method
cmlenz@430: can be used for that purpose), whereas keywords arguments are added as
cmlenz@430: attributes:
cmlenz@430: 
cmlenz@430: >>> doc(tag.br)
cmlenz@430: <Element "p">
cmlenz@853: >>> print(doc)
cmlenz@430: <p>Some text and <a href="http://example.org/">a link</a>.<br/></p>
cmlenz@430: 
cmlenz@430: If an attribute name collides with a Python keyword, simply append an underscore
cmlenz@430: to the name:
cmlenz@430: 
cmlenz@430: >>> doc(class_='intro')
cmlenz@430: <Element "p">
cmlenz@853: >>> print(doc)
cmlenz@430: <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
cmlenz@430: 
cmlenz@430: As shown above, an `Element` can easily be directly rendered to XML text by
cmlenz@430: printing it or using the Python ``str()`` function. This is basically a
cmlenz@430: shortcut for converting the `Element` to a stream and serializing that
cmlenz@430: stream:
cmlenz@430: 
cmlenz@430: >>> stream = doc.generate()
cmlenz@431: >>> stream #doctest: +ELLIPSIS
cmlenz@430: <genshi.core.Stream object at ...>
cmlenz@853: >>> print(stream)
cmlenz@430: <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
cmlenz@430: 
cmlenz@430: 
cmlenz@430: The `tag` object also allows creating "fragments", which are basically lists
cmlenz@430: of nodes (elements or text) that don't have a parent element. This can be useful
cmlenz@430: for creating snippets of markup that are attached to a parent element later (for
cmlenz@430: example in a template). Fragments are created by calling the `tag` object, which
cmlenz@430: returns an object of type `Fragment`:
cmlenz@430: 
cmlenz@430: >>> fragment = tag('Hello, ', tag.em('world'), '!')
cmlenz@430: >>> fragment
cmlenz@430: <Fragment>
cmlenz@853: >>> print(fragment)
cmlenz@430: Hello, <em>world</em>!
cmlenz@430: """
cmlenz@425: 
cmlenz@737: from genshi.core import Attrs, Markup, Namespace, QName, Stream, \
cmlenz@737:                         START, END, TEXT
cmlenz@1: 
cmlenz@433: __all__ = ['Fragment', 'Element', 'ElementFactory', 'tag']
cmlenz@425: __docformat__ = 'restructuredtext en'
cmlenz@1: 
cmlenz@1: 
cmlenz@1: class Fragment(object):
cmlenz@28:     """Represents a markup fragment, which is basically just a list of element
cmlenz@28:     or text nodes.
cmlenz@28:     """
cmlenz@1:     __slots__ = ['children']
cmlenz@1: 
cmlenz@1:     def __init__(self):
cmlenz@433:         """Create a new fragment."""
cmlenz@1:         self.children = []
cmlenz@1: 
cmlenz@65:     def __add__(self, other):
cmlenz@65:         return Fragment()(self, other)
cmlenz@65: 
cmlenz@65:     def __call__(self, *args):
cmlenz@433:         """Append any positional arguments as child nodes.
cmlenz@433:         
cmlenz@433:         :see: `append`
cmlenz@433:         """
cmlenz@854:         for arg in args:
cmlenz@854:             self.append(arg)
cmlenz@65:         return self
cmlenz@65: 
cmlenz@65:     def __iter__(self):
cmlenz@98:         return self._generate()
cmlenz@65: 
cmlenz@65:     def __repr__(self):
cmlenz@860:         return '<%s>' % type(self).__name__
cmlenz@65: 
cmlenz@65:     def __str__(self):
cmlenz@65:         return str(self.generate())
cmlenz@65: 
cmlenz@65:     def __unicode__(self):
cmlenz@65:         return unicode(self.generate())
cmlenz@65: 
cmlenz@737:     def __html__(self):
cmlenz@737:         return Markup(self.generate())
cmlenz@737: 
cmlenz@1:     def append(self, node):
cmlenz@433:         """Append an element or string as child node.
cmlenz@433:         
cmlenz@433:         :param node: the node to append; can be an `Element`, `Fragment`, or a
cmlenz@433:                      `Stream`, or a Python string or number
cmlenz@433:         """
cmlenz@379:         if isinstance(node, (Stream, Element, basestring, int, float, long)):
cmlenz@1:             # For objects of a known/primitive type, we avoid the check for
cmlenz@1:             # whether it is iterable for better performance
cmlenz@1:             self.children.append(node)
cmlenz@1:         elif isinstance(node, Fragment):
cmlenz@133:             self.children.extend(node.children)
cmlenz@1:         elif node is not None:
cmlenz@1:             try:
cmlenz@854:                 for child in node:
cmlenz@854:                     self.append(child)
cmlenz@1:             except TypeError:
cmlenz@1:                 self.children.append(node)
cmlenz@94: 
cmlenz@94:     def _generate(self):
cmlenz@94:         for child in self.children:
cmlenz@94:             if isinstance(child, Fragment):
cmlenz@94:                 for event in child._generate():
cmlenz@94:                     yield event
cmlenz@379:             elif isinstance(child, Stream):
cmlenz@379:                 for event in child:
cmlenz@379:                     yield event
cmlenz@94:             else:
cmlenz@94:                 if not isinstance(child, basestring):
cmlenz@94:                     child = unicode(child)
cmlenz@133:                 yield TEXT, child, (None, -1, -1)
cmlenz@1: 
cmlenz@1:     def generate(self):
cmlenz@498:         """Return a markup event stream for the fragment.
cmlenz@498:         
cmlenz@498:         :rtype: `Stream`
cmlenz@498:         """
cmlenz@94:         return Stream(self._generate())
cmlenz@1: 
cmlenz@1: 
cmlenz@345: def _kwargs_to_attrs(kwargs):
cmlenz@735:     attrs = []
cmlenz@735:     names = set()
cmlenz@730:     for name, value in kwargs.items():
cmlenz@730:         name = name.rstrip('_').replace('_', '-')
cmlenz@735:         if value is not None and name not in names:
cmlenz@735:             attrs.append((QName(name), unicode(value)))
cmlenz@735:             names.add(name)
cmlenz@735:     return Attrs(attrs)
cmlenz@345: 
cmlenz@345: 
cmlenz@1: class Element(Fragment):
cmlenz@1:     """Simple XML output generator based on the builder pattern.
cmlenz@1: 
cmlenz@1:     Construct XML elements by passing the tag name to the constructor:
cmlenz@1: 
cmlenz@853:     >>> print(Element('strong'))
cmlenz@1:     <strong/>
cmlenz@1: 
cmlenz@1:     Attributes can be specified using keyword arguments. The values of the
cmlenz@1:     arguments will be converted to strings and any special XML characters
cmlenz@1:     escaped:
cmlenz@1: 
cmlenz@853:     >>> print(Element('textarea', rows=10, cols=60))
cmlenz@1:     <textarea rows="10" cols="60"/>
cmlenz@853:     >>> print(Element('span', title='1 < 2'))
cmlenz@1:     <span title="1 &lt; 2"/>
cmlenz@853:     >>> print(Element('span', title='"baz"'))
cmlenz@1:     <span title="&#34;baz&#34;"/>
cmlenz@1: 
cmlenz@1:     The " character is escaped using a numerical entity.
cmlenz@1:     The order in which attributes are rendered is undefined.
cmlenz@1: 
cmlenz@1:     If an attribute value evaluates to `None`, that attribute is not included
cmlenz@1:     in the output:
cmlenz@1: 
cmlenz@853:     >>> print(Element('a', name=None))
cmlenz@1:     <a/>
cmlenz@1: 
cmlenz@1:     Attribute names that conflict with Python keywords can be specified by
cmlenz@1:     appending an underscore:
cmlenz@1: 
cmlenz@853:     >>> print(Element('div', class_='warning'))
cmlenz@1:     <div class="warning"/>
cmlenz@1: 
cmlenz@1:     Nested elements can be added to an element using item access notation.
cmlenz@1:     The call notation can also be used for this and for adding attributes
cmlenz@1:     using keyword arguments, as one would do in the constructor.
cmlenz@1: 
cmlenz@853:     >>> print(Element('ul')(Element('li'), Element('li')))
cmlenz@1:     <ul><li/><li/></ul>
cmlenz@853:     >>> print(Element('a')('Label'))
cmlenz@1:     <a>Label</a>
cmlenz@853:     >>> print(Element('a')('Label', href="target"))
cmlenz@1:     <a href="target">Label</a>
cmlenz@1: 
cmlenz@1:     Text nodes can be nested in an element by adding strings instead of
cmlenz@1:     elements. Any special characters in the strings are escaped automatically:
cmlenz@1: 
cmlenz@853:     >>> print(Element('em')('Hello world'))
cmlenz@1:     <em>Hello world</em>
cmlenz@853:     >>> print(Element('em')(42))
cmlenz@1:     <em>42</em>
cmlenz@853:     >>> print(Element('em')('1 < 2'))
cmlenz@1:     <em>1 &lt; 2</em>
cmlenz@1: 
cmlenz@1:     This technique also allows mixed content:
cmlenz@1: 
cmlenz@853:     >>> print(Element('p')('Hello ', Element('b')('world')))
cmlenz@1:     <p>Hello <b>world</b></p>
cmlenz@1: 
mgood@34:     Quotes are not escaped inside text nodes:
cmlenz@853:     >>> print(Element('p')('"Hello"'))
mgood@34:     <p>"Hello"</p>
mgood@34: 
cmlenz@1:     Elements can also be combined with other elements or strings using the
cmlenz@1:     addition operator, which results in a `Fragment` object that contains the
cmlenz@1:     operands:
cmlenz@1:     
cmlenz@853:     >>> print(Element('br') + 'some text' + Element('br'))
cmlenz@1:     <br/>some text<br/>
cmlenz@1:     
cmlenz@1:     Elements with a namespace can be generated using the `Namespace` and/or
cmlenz@1:     `QName` classes:
cmlenz@1:     
cmlenz@230:     >>> from genshi.core import Namespace
cmlenz@1:     >>> xhtml = Namespace('http://www.w3.org/1999/xhtml')
cmlenz@853:     >>> print(Element(xhtml.html, lang='en'))
cmlenz@410:     <html xmlns="http://www.w3.org/1999/xhtml" lang="en"/>
cmlenz@1:     """
cmlenz@1:     __slots__ = ['tag', 'attrib']
cmlenz@1: 
cmlenz@1:     def __init__(self, tag_, **attrib):
cmlenz@1:         Fragment.__init__(self)
cmlenz@1:         self.tag = QName(tag_)
cmlenz@730:         self.attrib = _kwargs_to_attrs(attrib)
cmlenz@1: 
cmlenz@1:     def __call__(self, *args, **kwargs):
cmlenz@433:         """Append any positional arguments as child nodes, and keyword arguments
cmlenz@433:         as attributes.
cmlenz@433:         
cmlenz@498:         :return: the element itself so that calls can be chained
cmlenz@498:         :rtype: `Element`
cmlenz@433:         :see: `Fragment.append`
cmlenz@433:         """
cmlenz@730:         self.attrib |= _kwargs_to_attrs(kwargs)
cmlenz@98:         Fragment.__call__(self, *args)
cmlenz@98:         return self
cmlenz@1: 
cmlenz@65:     def __repr__(self):
cmlenz@860:         return '<%s "%s">' % (type(self).__name__, self.tag)
cmlenz@65: 
cmlenz@94:     def _generate(self):
cmlenz@133:         yield START, (self.tag, self.attrib), (None, -1, -1)
cmlenz@94:         for kind, data, pos in Fragment._generate(self):
cmlenz@94:             yield kind, data, pos
cmlenz@133:         yield END, self.tag, (None, -1, -1)
cmlenz@94: 
cmlenz@1:     def generate(self):
cmlenz@498:         """Return a markup event stream for the fragment.
cmlenz@498:         
cmlenz@498:         :rtype: `Stream`
cmlenz@498:         """
cmlenz@94:         return Stream(self._generate())
cmlenz@1: 
cmlenz@1: 
cmlenz@1: class ElementFactory(object):
cmlenz@28:     """Factory for `Element` objects.
cmlenz@28:     
cmlenz@28:     A new element is created simply by accessing a correspondingly named
cmlenz@28:     attribute of the factory object:
cmlenz@28:     
cmlenz@28:     >>> factory = ElementFactory()
cmlenz@853:     >>> print(factory.foo)
cmlenz@28:     <foo/>
cmlenz@853:     >>> print(factory.foo(id=2))
cmlenz@28:     <foo id="2"/>
cmlenz@28:     
cmlenz@119:     Markup fragments (lists of nodes without a parent element) can be created
cmlenz@119:     by calling the factory:
cmlenz@119:     
cmlenz@853:     >>> print(factory('Hello, ', factory.em('world'), '!'))
cmlenz@119:     Hello, <em>world</em>!
cmlenz@119:     
cmlenz@28:     A factory can also be bound to a specific namespace:
cmlenz@28:     
cmlenz@28:     >>> factory = ElementFactory('http://www.w3.org/1999/xhtml')
cmlenz@853:     >>> print(factory.html(lang="en"))
cmlenz@410:     <html xmlns="http://www.w3.org/1999/xhtml" lang="en"/>
cmlenz@28:     
cmlenz@28:     The namespace for a specific element can be altered on an existing factory
cmlenz@28:     by specifying the new namespace using item access:
cmlenz@28:     
cmlenz@28:     >>> factory = ElementFactory()
cmlenz@853:     >>> print(factory.html(factory['http://www.w3.org/2000/svg'].g(id=3)))
cmlenz@410:     <html><g xmlns="http://www.w3.org/2000/svg" id="3"/></html>
cmlenz@28:     
cmlenz@28:     Usually, the `ElementFactory` class is not be used directly. Rather, the
cmlenz@28:     `tag` instance should be used to create elements.
cmlenz@28:     """
cmlenz@1: 
cmlenz@19:     def __init__(self, namespace=None):
cmlenz@28:         """Create the factory, optionally bound to the given namespace.
cmlenz@28:         
cmlenz@425:         :param namespace: the namespace URI for any created elements, or `None`
cmlenz@425:                           for no namespace
cmlenz@28:         """
cmlenz@20:         if namespace and not isinstance(namespace, Namespace):
cmlenz@19:             namespace = Namespace(namespace)
cmlenz@19:         self.namespace = namespace
cmlenz@19: 
cmlenz@119:     def __call__(self, *args):
cmlenz@433:         """Create a fragment that has the given positional arguments as child
cmlenz@433:         nodes.
cmlenz@433: 
cmlenz@433:         :return: the created `Fragment`
cmlenz@498:         :rtype: `Fragment`
cmlenz@433:         """
cmlenz@119:         return Fragment()(*args)
cmlenz@119: 
cmlenz@19:     def __getitem__(self, namespace):
cmlenz@433:         """Return a new factory that is bound to the specified namespace.
cmlenz@433:         
cmlenz@433:         :param namespace: the namespace URI or `Namespace` object
cmlenz@433:         :return: an `ElementFactory` that produces elements bound to the given
cmlenz@433:                  namespace
cmlenz@498:         :rtype: `ElementFactory`
cmlenz@433:         """
cmlenz@19:         return ElementFactory(namespace)
cmlenz@19: 
cmlenz@19:     def __getattr__(self, name):
cmlenz@433:         """Create an `Element` with the given name.
cmlenz@433:         
cmlenz@433:         :param name: the tag name of the element to create
cmlenz@433:         :return: an `Element` with the specified name
cmlenz@498:         :rtype: `Element`
cmlenz@433:         """
cmlenz@19:         return Element(self.namespace and self.namespace[name] or name)
cmlenz@1: 
cmlenz@1: 
cmlenz@1: tag = ElementFactory()
cmlenz@498: """Global `ElementFactory` bound to the default namespace.
cmlenz@498: 
cmlenz@498: :type: `ElementFactory`
cmlenz@498: """