Adding pystache to third_party

third_party/pystache/src/renderer.py

+# coding: utf-8
+
+"""
+This module provides a Renderer class to render templates.
+
+"""
+
+import sys
+
+from pystache import defaults
+from pystache.common import TemplateNotFoundError, MissingTags, is_string
+from pystache.context import ContextStack, KeyNotFoundError
+from pystache.loader import Loader
+from pystache.parsed import ParsedTemplate
+from pystache.renderengine import context_get, RenderEngine
+from pystache.specloader import SpecLoader
+from pystache.template_spec import TemplateSpec
+
+
+class Renderer(object):
+
+    """
+    A class for rendering mustache templates.
+
+    This class supports several rendering options which are described in
+    the constructor's docstring.  Other behavior can be customized by
+    subclassing this class.
+
+    For example, one can pass a string-string dictionary to the constructor
+    to bypass loading partials from the file system:
+
+    >>> partials = {'partial': 'Hello, {{thing}}!'}
+    >>> renderer = Renderer(partials=partials)
+    >>> # We apply print to make the test work in Python 3 after 2to3.
+    >>> print renderer.render('{{>partial}}', {'thing': 'world'})
+    Hello, world!
+
+    To customize string coercion (e.g. to render False values as ''), one can
+    subclass this class.  For example:
+
+        class MyRenderer(Renderer):
+            def str_coerce(self, val):
+                if not val:
+                    return ''
+                else:
+                    return str(val)
+
+    """
+
+    def __init__(self, file_encoding=None, string_encoding=None,
+                 decode_errors=None, search_dirs=None, file_extension=None,
+                 escape=None, partials=None, missing_tags=None):
+        """
+        Construct an instance.
+
+        Arguments:
+
+          file_encoding: the name of the encoding to use by default when
+            reading template files.  All templates are converted to unicode
+            prior to parsing.  Defaults to the package default.
+
+          string_encoding: the name of the encoding to use when converting
+            to unicode any byte strings (type str in Python 2) encountered
+            during the rendering process.  This name will be passed as the
+            encoding argument to the built-in function unicode().
+            Defaults to the package default.
+
+          decode_errors: the string to pass as the errors argument to the
+            built-in function unicode() when converting byte strings to
+            unicode.  Defaults to the package default.
+
+          search_dirs: the list of directories in which to search when
+            loading a template by name or file name.  If given a string,
+            the method interprets the string as a single directory.
+            Defaults to the package default.
+
+          file_extension: the template file extension.  Pass False for no
+            extension (i.e. to use extensionless template files).
+            Defaults to the package default.
+
+          partials: an object (e.g. a dictionary) for custom partial loading
+            during the rendering process.
+                The object should have a get() method that accepts a string
+            and returns the corresponding template as a string, preferably
+            as a unicode string.  If there is no template with that name,
+            the get() method should either return None (as dict.get() does)
+            or raise an exception.
+                If this argument is None, the rendering process will use
+            the normal procedure of locating and reading templates from
+            the file system -- using relevant instance attributes like
+            search_dirs, file_encoding, etc.
+
+          escape: the function used to escape variable tag values when
+            rendering a template.  The function should accept a unicode
+            string (or subclass of unicode) and return an escaped string
+            that is again unicode (or a subclass of unicode).
+                This function need not handle strings of type `str` because
+            this class will only pass it unicode strings.  The constructor
+            assigns this function to the constructed instance's escape()
+            method.
+                To disable escaping entirely, one can pass `lambda u: u`
+            as the escape function, for example.  One may also wish to
+            consider using markupsafe's escape function: markupsafe.escape().
+            This argument defaults to the package default.
+
+          missing_tags: a string specifying how to handle missing tags.
+            If 'strict', an error is raised on a missing tag.  If 'ignore',
+            the value of the tag is the empty string.  Defaults to the
+            package default.
+
+        """
+        if decode_errors is None:
+            decode_errors = defaults.DECODE_ERRORS
+
+        if escape is None:
+            escape = defaults.TAG_ESCAPE
+
+        if file_encoding is None:
+            file_encoding = defaults.FILE_ENCODING
+
+        if file_extension is None:
+            file_extension = defaults.TEMPLATE_EXTENSION
+
+        if missing_tags is None:
+            missing_tags = defaults.MISSING_TAGS
+
+        if search_dirs is None:
+            search_dirs = defaults.SEARCH_DIRS
+
+        if string_encoding is None:
+            string_encoding = defaults.STRING_ENCODING
+
+        if isinstance(search_dirs, basestring):
+            search_dirs = [search_dirs]
+
+        self._context = None
+        self.decode_errors = decode_errors
+        self.escape = escape
+        self.file_encoding = file_encoding
+        self.file_extension = file_extension
+        self.missing_tags = missing_tags
+        self.partials = partials
+        self.search_dirs = search_dirs
+        self.string_encoding = string_encoding
+
+    # This is an experimental way of giving views access to the current context.
+    # TODO: consider another approach of not giving access via a property,
+    #   but instead letting the caller pass the initial context to the
+    #   main render() method by reference.  This approach would probably
+    #   be less likely to be misused.
+    @property
+    def context(self):
+        """
+        Return the current rendering context [experimental].
+
+        """
+        return self._context
+
+    # We could not choose str() as the name because 2to3 renames the unicode()
+    # method of this class to str().
+    def str_coerce(self, val):
+        """
+        Coerce a non-string value to a string.
+
+        This method is called whenever a non-string is encountered during the
+        rendering process when a string is needed (e.g. if a context value
+        for string interpolation is not a string).  To customize string
+        coercion, you can override this method.
+
+        """
+        return str(val)
+
+    def _to_unicode_soft(self, s):
+        """
+        Convert a basestring to unicode, preserving any unicode subclass.
+
+        """
+        # We type-check to avoid "TypeError: decoding Unicode is not supported".
+        # We avoid the Python ternary operator for Python 2.4 support.
+        if isinstance(s, unicode):
+            return s
+        return self.unicode(s)
+
+    def _to_unicode_hard(self, s):
+        """
+        Convert a basestring to a string with type unicode (not subclass).
+
+        """
+        return unicode(self._to_unicode_soft(s))
+
+    def _escape_to_unicode(self, s):
+        """
+        Convert a basestring to unicode (preserving any unicode subclass), and escape it.
+
+        Returns a unicode string (not subclass).
+
+        """
+        return unicode(self.escape(self._to_unicode_soft(s)))
+
+    def unicode(self, b, encoding=None):
+        """
+        Convert a byte string to unicode, using string_encoding and decode_errors.
+
+        Arguments:
+
+          b: a byte string.
+
+          encoding: the name of an encoding.  Defaults to the string_encoding
+            attribute for this instance.
+
+        Raises:
+
+          TypeError: Because this method calls Python's built-in unicode()
+            function, this method raises the following exception if the
+            given string is already unicode:
+
+              TypeError: decoding Unicode is not supported
+
+        """
+        if encoding is None:
+            encoding = self.string_encoding
+
+        # TODO: Wrap UnicodeDecodeErrors with a message about setting
+        # the string_encoding and decode_errors attributes.
+        return unicode(b, encoding, self.decode_errors)
+
+    def _make_loader(self):
+        """
+        Create a Loader instance using current attributes.
+
+        """
+        return Loader(file_encoding=self.file_encoding, extension=self.file_extension,
+                      to_unicode=self.unicode, search_dirs=self.search_dirs)
+
+    def _make_load_template(self):
+        """
+        Return a function that loads a template by name.
+
+        """
+        loader = self._make_loader()
+
+        def load_template(template_name):
+            return loader.load_name(template_name)
+
+        return load_template
+
+    def _make_load_partial(self):
+        """
+        Return a function that loads a partial by name.
+
+        """
+        if self.partials is None:
+            return self._make_load_template()
+
+        # Otherwise, create a function from the custom partial loader.
+        partials = self.partials
+
+        def load_partial(name):
+            # TODO: consider using EAFP here instead.
+            #     http://docs.python.org/glossary.html#term-eafp
+            #   This would mean requiring that the custom partial loader
+            #   raise a KeyError on name not found.
+            template = partials.get(name)
+            if template is None:
+                raise TemplateNotFoundError("Name %s not found in partials: %s" %
+                                            (repr(name), type(partials)))
+
+            # RenderEngine requires that the return value be unicode.
+            return self._to_unicode_hard(template)
+
+        return load_partial
+
+    def _is_missing_tags_strict(self):
+        """
+        Return whether missing_tags is set to strict.
+
+        """
+        val = self.missing_tags
+
+        if val == MissingTags.strict:
+            return True
+        elif val == MissingTags.ignore:
+            return False
+
+        raise Exception("Unsupported 'missing_tags' value: %s" % repr(val))
+
+    def _make_resolve_partial(self):
+        """
+        Return the resolve_partial function to pass to RenderEngine.__init__().
+
+        """
+        load_partial = self._make_load_partial()
+
+        if self._is_missing_tags_strict():
+            return load_partial
+        # Otherwise, ignore missing tags.
+
+        def resolve_partial(name):
+            try:
+                return load_partial(name)
+            except TemplateNotFoundError:
+                return u''
+
+        return resolve_partial
+
+    def _make_resolve_context(self):
+        """
+        Return the resolve_context function to pass to RenderEngine.__init__().
+
+        """
+        if self._is_missing_tags_strict():
+            return context_get
+        # Otherwise, ignore missing tags.
+
+        def resolve_context(stack, name):
+            try:
+                return context_get(stack, name)
+            except KeyNotFoundError:
+                return u''
+
+        return resolve_context
+
+    def _make_render_engine(self):
+        """
+        Return a RenderEngine instance for rendering.
+
+        """
+        resolve_context = self._make_resolve_context()
+        resolve_partial = self._make_resolve_partial()
+
+        engine = RenderEngine(literal=self._to_unicode_hard,
+                              escape=self._escape_to_unicode,
+                              resolve_context=resolve_context,
+                              resolve_partial=resolve_partial,
+                              to_str=self.str_coerce)
+        return engine
+
+    # TODO: add unit tests for this method.
+    def load_template(self, template_name):
+        """
+        Load a template by name from the file system.
+
+        """
+        load_template = self._make_load_template()
+        return load_template(template_name)
+
+    def _render_object(self, obj, *context, **kwargs):
+        """
+        Render the template associated with the given object.
+
+        """
+        loader = self._make_loader()
+
+        # TODO: consider an approach that does not require using an if
+        #   block here.  For example, perhaps this class's loader can be
+        #   a SpecLoader in all cases, and the SpecLoader instance can
+        #   check the object's type.  Or perhaps Loader and SpecLoader
+        #   can be refactored to implement the same interface.
+        if isinstance(obj, TemplateSpec):
+            loader = SpecLoader(loader)
+            template = loader.load(obj)
+        else:
+            template = loader.load_object(obj)
+
+        context = [obj] + list(context)
+
+        return self._render_string(template, *context, **kwargs)
+
+    def render_name(self, template_name, *context, **kwargs):
+        """
+        Render the template with the given name using the given context.
+
+        See the render() docstring for more information.
+
+        """
+        loader = self._make_loader()
+        template = loader.load_name(template_name)
+        return self._render_string(template, *context, **kwargs)
+
+    def render_path(self, template_path, *context, **kwargs):
+        """
+        Render the template at the given path using the given context.
+
+        Read the render() docstring for more information.
+
+        """
+        loader = self._make_loader()
+        template = loader.read(template_path)
+
+        return self._render_string(template, *context, **kwargs)
+
+    def _render_string(self, template, *context, **kwargs):
+        """
+        Render the given template string using the given context.
+
+        """
+        # RenderEngine.render() requires that the template string be unicode.
+        template = self._to_unicode_hard(template)
+
+        render_func = lambda engine, stack: engine.render(template, stack)
+
+        return self._render_final(render_func, *context, **kwargs)
+
+    # All calls to render() should end here because it prepares the
+    # context stack correctly.
+    def _render_final(self, render_func, *context, **kwargs):
+        """
+        Arguments:
+
+          render_func: a function that accepts a RenderEngine and ContextStack
+            instance and returns a template rendering as a unicode string.
+
+        """
+        stack = ContextStack.create(*context, **kwargs)
+        self._context = stack
+
+        engine = self._make_render_engine()
+
+        return render_func(engine, stack)
+
+    def render(self, template, *context, **kwargs):
+        """
+        Render the given template string, view template, or parsed template.
+
+        Returns a unicode string.
+
+        Prior to rendering, this method will convert a template that is a
+        byte string (type str in Python 2) to unicode using the string_encoding
+        and decode_errors attributes.  See the constructor docstring for
+        more information.
+
+        Arguments:
+
+          template: a template string that is unicode or a byte string,
+            a ParsedTemplate instance, or another object instance.  In the
+            final case, the function first looks for the template associated
+            to the object by calling this class's get_associated_template()
+            method.  The rendering process also uses the passed object as
+            the first element of the context stack when rendering.
+
+          *context: zero or more dictionaries, ContextStack instances, or objects
+            with which to populate the initial context stack.  None
+            arguments are skipped.  Items in the *context list are added to
+            the context stack in order so that later items in the argument
+            list take precedence over earlier items.
+
+          **kwargs: additional key-value data to add to the context stack.
+            As these arguments appear after all items in the *context list,
+            in the case of key conflicts these values take precedence over
+            all items in the *context list.
+
+        """
+        if is_string(template):
+            return self._render_string(template, *context, **kwargs)
+        if isinstance(template, ParsedTemplate):
+            render_func = lambda engine, stack: template.render(engine, stack)
+            return self._render_final(render_func, *context, **kwargs)
+        # Otherwise, we assume the template is an object.
+
+        return self._render_object(template, *context, **kwargs)