python-nevow 0.10.0-4build1 / usr / share / pyshared / nevow / flat / ten.py

# Copyright (c) 2004 Divmod.
# See LICENSE for details.

from __future__ import generators

import types
import warnings
from zope.interface import declarations, interface

import twisted.python.components as tpc

from nevow import inevow
from nevow import tags
from nevow import util
from nevow.inevow import ISerializable

"""
# NOTE:
# If you're about to import something from this module then you probably want
# to get it from nevow.flat instead. The idea is that flat's __init__.py may
# get smarter about the version of serialize/flatten/etc that is used,
# depending on what else is available. For instance, non-Twisted versions of
# these function may be imported into nevow.flat if Twisted is not installed.
"""

def registerFlattener(flattener, forType):
    """Register a function, 'flattener', which will be invoked when an object of type 'forType'
    is encountered in the stan dom. This function should return or yield strings, or objects
    for which there is also a flattener registered.
    
    flattener should take (original, ctx) where original is the object to flatten.
    """
    if type(flattener) is str or type(forType) is str:
        assert type(flattener) is str and type(forType) is str, "Must pass both strings or no strings to registerFlattener"
        flattener = util._namedAnyWithBuiltinTranslation(flattener)
        forType = util._namedAnyWithBuiltinTranslation(forType)

    if not isinstance(forType, interface.InterfaceClass):
        forType = declarations.implementedBy(forType)
        
    tpc.globalRegistry.register([forType], ISerializable, 'nevow.flat', flattener)

def getFlattener(original):
    """Get a flattener function with signature (ctx, original) for the object original.
    """
    return tpc.globalRegistry.lookup1(declarations.providedBy(original), ISerializable, 'nevow.flat')

def getSerializer(obj):
    warnings.warn('getSerializer is deprecated; It has been renamed getFlattener.', stacklevel=2)
    return getFlattener(obj)


def partialflatten(context, obj):
    """Run a flattener on the object 'obj' in the context 'context'.
    
    The return results from this function will not necessarily be a string, but will probably
    need further processing.
    """
    flattener = getFlattener(obj)
    if flattener is not None:
        return flattener(obj, context)

    raise NotImplementedError(
        'There is no flattener function registered for object %r of type %s.' %
        (obj, type(obj)))


def serialize(obj, context):
    #warnings.warn('serialize is deprecated; it has been renamed partialflatten.', stacklevel=2)
    return partialflatten(context, obj)


def iterflatten(stan, ctx, writer, shouldYieldItem=None):
    """This is the main meat of the nevow renderer. End-user programmers should
    instead use either flatten or precompile.
    """
    # 'rest' is a list of generators.
    # initialize as one-element list of a one-element generator of 
    rest = [ iter([partialflatten(ctx, stan)]) ]
    straccum = []
    while rest:
        gen = rest.pop()
        for item in gen:
            if isinstance(item, str):
                straccum.append(item)
            elif isinstance(item, unicode):
                straccum.append(item.encode('utf8'))
            elif isinstance(item, (list, types.GeneratorType)):
                # stop iterating this generator and put it back on the stack
                # and start iterating the new item instead.
                rest.append(gen)
                rest.append(iter(item))
                break
            else:
                if straccum:
                    writer(tags.raw(''.join(straccum)))
                    del straccum[:]
                if shouldYieldItem is not None and shouldYieldItem(item):
                    replacement = []
                    yield item, replacement.append
                    rest.append(gen)
                    rest.append(iter([replacement]))
                    break
                else:
                    if ctx.precompile:
                        ## We're precompiling and this is an item which can't be calculated until render time
                        ## add it to the list in 'precompile'
                        writer(item)
                    else:
                        rest.append(gen)
                        rest.append(iter([partialflatten(ctx, item)]))
                        break

    if straccum:
        writer(tags.raw(''.join(straccum)))


def flatten(stan, ctx=None):
    """Given the stan and the optional context, return a string containing the
    representation of the tree in the given context.
    """
    if ctx is None:
        from nevow.context import RequestContext, PageContext
        from nevow.testutil import FakeRequest
        ctx = PageContext(tag=None, parent=RequestContext(tag=FakeRequest()))
        ctx.remember(None, inevow.IData)
    result = []
    list(iterflatten(stan, ctx, result.append))
    return tags.raw(''.join(result))


def precompile(stan, ctx=None):
    """Given the stan and the optional context, return a list of strings and
    Context instances, optimizing as much static content as possible into contiguous
    string runs.

    The Context instances will have Tag instances whose .children have also been
    precompiled.
    """
    from nevow.context import WovenContext
    newctx = WovenContext(precompile=True)
    if ctx is not None:
        macroFactory = inevow.IMacroFactory(ctx, None)
        if macroFactory is not None:
            newctx.remember(macroFactory, inevow.IMacroFactory)
    doc = []
    list(iterflatten(stan, newctx, doc.append))
    return doc