root/trunk/diva/templating.py

# -*- coding: utf-8 -*-
#
# Copyright (C) 2007-2008 Christopher Lenz
# All rights reserved.
#
# This software is licensed as described in the file COPYING, which
# you should have received as part of this distribution.

"""Helpers for templating and output serialization using the Genshi template
engine.
"""

from datetime import date, datetime, time, timedelta
from itertools import groupby
import logging
from operator import attrgetter, itemgetter

from diva import app
from diva.core import register_filter
from diva.http import abort
from diva.i18n import gettext, ngettext
from diva.routing import abs_url, path_to
from diva.util import decorator, relpath, truncate
from genshi import Stream
from genshi.input import HTML, XML
from genshi.output import encode, get_serializer
from genshi.template import Context, TemplateNotFound

__all__ = ['output', 'render']
__docformat__ = 'restructuredtext en'

log = logging.getLogger('diva.templating')


def output(templatename=None, method=None, mimetype=None, encoding=None,
           **options):
    """Decorator to specify template and output serialization.
    
    :param templatename: the name of the template file
    :param method: the serialization method (one of "xml", "xhtml", "html", or
                   "text")
    :param mimetype: the content-type of the generated output
    :param encoding: the encoding (character set) of the generated output
    """
    def decorate(func):

        @decorator(func)
        def wrapper(*args, **kwargs):
            __traceback_hide__ = True
            method_, mimetype_, encoding_ = method, mimetype, encoding
            options_ = options.copy()

            if templatename:
                app.ctxt.template = app.templates.load(templatename)
            else:
                app.ctxt.template = None

            response = app.ctxt.response
            response.content_type = 'text/x-diva-temp'

            stream = func(*args, **kwargs)
            is_stream = isinstance(stream, Stream)

            if is_stream and mimetype_ is None:
                mimetype_, encoding_ = app.mime_types.guess_type(
                    app.ctxt.template.filename
                )
                if encoding is not None:
                    encoding_ = encoding
            if mimetype_ is None:
                mimetype_ = 'text/plain'
            if encoding_ is None:
                encoding_ = 'utf-8'
            if is_stream and method_ is None:
                method_ = {
                    'text/html': 'html',
                    'application/xhtml+xml': 'xhtml',
                    'text/plain': 'plain'
                }.get(mimetype_, 'xml')

            if response.content_type == 'text/x-diva-temp':
                response.content_type = mimetype_
            response.charset = encoding_
            if not is_stream:
                return stream

            if 'doctype' not in options_ and not app.ctxt.request.is_xhr \
                    and mimetype_ in ('text/html', 'application/xhtml+xml'):
                options_['doctype'] = app.config.get('doctype', 'html')
            app.ctxt.serializer = get_serializer(method_, **options_)

            return stream

        return wrapper
    return decorate


# Helper functions for use in templates


def classes(*args, **kwargs):
    """Helper function for dynamically assembling a list of CSS class names
    in templates.
    
    Any positional arguments are added to the list of class names. All
    positional arguments must be strings:
    
    >>> classes('foo', 'bar')
    u'foo bar'
    
    In addition, the names of any supplied keyword arguments are added if they
    have a truth value:
    
    >>> classes('foo', bar=True)
    u'foo bar'
    >>> classes('foo', bar=False)
    u'foo'
    
    If none of the arguments are added to the list, this function returns
    `None`:
    
    >>> classes(bar=False)
    """
    classes = list(filter(None, args)) + [k for k, v in kwargs.items() if v]
    if not classes:
        return None
    return u' '.join(classes)


def group(iterable, num, predicate=None):
    """Combines the elements produced by the given iterable so that every `num`
    items are returned as a tuple.
    
    >>> items = [1, 2, 3, 4]
    >>> for item in group(items, 2):
    ...     print item
    (1, 2)
    (3, 4)
    
    The last tuple is padded with ``None`` values if its' length is smaller
    than `num`.
    
    >>> items = [1, 2, 3, 4, 5]
    >>> for item in group(items, 2):
    ...     print item
    (1, 2)
    (3, 4)
    (5, None)
    
    The optional `predicate` parameter can be used to flag elements that should
    not be packed together with other items. Only those elements where the
    predicate function returns True are grouped with other elements, otherwise
    they are returned as a tuple of length 1:
    
    >>> items = [1, 2, 3, 4]
    >>> for item in group(items, 2, lambda x: x != 3):
    ...     print item
    (1, 2)
    (3,)
    (4, None)
    
    :param iterable: the iterable to group
    :param num: the number of items to pack into each tuple
    :param predicate: an optional function called with the current item on
                      every iteration; if the function returns ``False`` that
                      item is emitted as a singleton tuple
    """
    buf = []
    for item in iterable:
        flush = predicate and not predicate(item)
        if buf and flush:
            buf += [None] * (num - len(buf))
            yield tuple(buf)
            del buf[:]
        buf.append(item)
        if flush or len(buf) == num:
            yield tuple(buf)
            del buf[:]
    if buf:
        buf += [None] * (num - len(buf))
        yield tuple(buf)


def separated(items, separator=', '):
    """Separates a sequence of items by the specified string.
    
    >>> list(separated(['Peter', 'Paul', 'Mary']))
    [('Peter', ', '), ('Paul', ', '), ('Mary', None)]

    >>> list(separated([]))
    []
    
    :param items: the iterable to separate
    :param separator: the string (or other object) to use to separate the items
    """
    items = iter(items)
    last = items.next()
    for item in items:
        yield last, separator
        last = item
    yield last, None


defaults = {
    'app': app,

    # helper functions
    'abs_url': abs_url,
    'classes': classes,
    'path_to': path_to,
    'separated': separated,
    'truncate': truncate,

    # translation
    '_': gettext,
    'gettext': gettext,
    'ngettext': ngettext,

    # functional tools
    'attrgetter': attrgetter,
    'group': group,
    'groupby': groupby,
    'itemgetter': itemgetter,

    # datetime
    'date': date,
    'datetime': datetime,
    'time': time,
    'timedelta': timedelta,

    'HTML': HTML,
    'XML': XML
}


def render(*args, **kwargs):
    """Render the data given as keyword arguments using the selected template.
    
    The template can be specified either by using the `output` decorator, or
    by passing the name of the template file as first argument to this function.
    
    Any keyword arguments are passed on into the template context. They will be
    available for use in templates, in addition to the various default
    variables (such as the ``request`` and ``response`` objects).
    """
    if args:
        assert len(args) == 1, 'Expected one arg, but got %r' % (args,)
        app.ctxt.template = app.templates.load(args[0])
    log.debug('Render with variables %r', kwargs.keys())

    ctxt = getattr(app.ctxt, 'context', None)
    if ctxt is None:
        ctxt = prepare_context(request=app.ctxt.request,
                               response=app.ctxt.response)
    ctxt.push(kwargs)

    template = app.ctxt.template
    assert template, 'No template specified'
    log.debug('Render using template %r', relpath(template.filepath))
    return template.generate(ctxt)


def prepare_context(**kwargs):
    data = defaults.copy() 
    data.update(kwargs) 
    ctxt = Context(**data)
    app.ctxt.context = ctxt
    return ctxt


def serialize(stream):
    if not isinstance(stream, Stream):
        return stream
    stream = Stream(list(stream))
    charset = app.ctxt.response.charset
    serializer = app.ctxt.serializer
    log.debug('Serialize using %r with encoding %s', serializer, charset)
    output = encode(serializer(stream), method=serializer, encoding=charset)
    return output


@register_filter('templating', requires='error-handling')
def template_filter(request, response, chain):
    """Request filter that serializes a Genshi template output stream."""
    prepare_context(request=request, response=response)
    return serialize(chain.next()(request, response, chain))


@output()
def view(request, response, template):
    """Generic request handler that renders a template with only the default
    data.
    
    :param request: the request object
    :param response: the response object
    :param template: the file name of the template
    """
    try:
        return render(template)
    except TemplateNotFound:
        abort(404)