Adding pystache to third_party

third_party/pystache/src/loader.py

+# coding: utf-8
+
+"""
+This module provides a Loader class for locating and reading templates.
+
+"""
+
+import os
+import sys
+
+from pystache import common
+from pystache import defaults
+from pystache.locator import Locator
+
+
+# We make a function so that the current defaults take effect.
+# TODO: revisit whether this is necessary.
+
+def _make_to_unicode():
+    def to_unicode(s, encoding=None):
+        """
+        Raises a TypeError exception if the given string is already unicode.
+
+        """
+        if encoding is None:
+            encoding = defaults.STRING_ENCODING
+        return unicode(s, encoding, defaults.DECODE_ERRORS)
+    return to_unicode
+
+
+class Loader(object):
+
+    """
+    Loads the template associated to a name or user-defined object.
+
+    All load_*() methods return the template as a unicode string.
+
+    """
+
+    def __init__(self, file_encoding=None, extension=None, to_unicode=None,
+                 search_dirs=None):
+        """
+        Construct a template loader instance.
+
+        Arguments:
+
+          extension: the template file extension, without the leading dot.
+            Pass False for no extension (e.g. to use extensionless template
+            files).  Defaults to the package default.
+
+          file_encoding: the name of the encoding to use when converting file
+            contents 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.  Defaults to the package default.
+
+          to_unicode: the function to use when converting strings of type
+            str to unicode.  The function should have the signature:
+
+              to_unicode(s, encoding=None)
+
+            It should accept a string of type str and an optional encoding
+            name and return a string of type unicode.  Defaults to calling
+            Python's built-in function unicode() using the package string
+            encoding and decode errors defaults.
+
+        """
+        if extension is None:
+            extension = defaults.TEMPLATE_EXTENSION
+
+        if file_encoding is None:
+            file_encoding = defaults.FILE_ENCODING
+
+        if search_dirs is None:
+            search_dirs = defaults.SEARCH_DIRS
+
+        if to_unicode is None:
+            to_unicode = _make_to_unicode()
+
+        self.extension = extension
+        self.file_encoding = file_encoding
+        # TODO: unit test setting this attribute.
+        self.search_dirs = search_dirs
+        self.to_unicode = to_unicode
+
+    def _make_locator(self):
+        return Locator(extension=self.extension)
+
+    def unicode(self, s, encoding=None):
+        """
+        Convert a string to unicode using the given encoding, and return it.
+
+        This function uses the underlying to_unicode attribute.
+
+        Arguments:
+
+          s: a basestring instance to convert to unicode.  Unlike Python's
+            built-in unicode() function, it is okay to pass unicode strings
+            to this function.  (Passing a unicode string to Python's unicode()
+            with the encoding argument throws the error, "TypeError: decoding
+            Unicode is not supported.")
+
+          encoding: the encoding to pass to the to_unicode attribute.
+            Defaults to None.
+
+        """
+        if isinstance(s, unicode):
+            return unicode(s)
+
+        return self.to_unicode(s, encoding)
+
+    def read(self, path, encoding=None):
+        """
+        Read the template at the given path, and return it as a unicode string.
+
+        """
+        b = common.read(path)
+
+        if encoding is None:
+            encoding = self.file_encoding
+
+        return self.unicode(b, encoding)
+
+    def load_file(self, file_name):
+        """
+        Find and return the template with the given file name.
+
+        Arguments:
+
+          file_name: the file name of the template.
+
+        """
+        locator = self._make_locator()
+
+        path = locator.find_file(file_name, self.search_dirs)
+
+        return self.read(path)
+
+    def load_name(self, name):
+        """
+        Find and return the template with the given template name.
+
+        Arguments:
+
+          name: the name of the template.
+
+        """
+        locator = self._make_locator()
+
+        path = locator.find_name(name, self.search_dirs)
+
+        return self.read(path)
+
+    # TODO: unit-test this method.
+    def load_object(self, obj):
+        """
+        Find and return the template associated to the given object.
+
+        Arguments:
+
+          obj: an instance of a user-defined class.
+
+          search_dirs: the list of directories in which to search.
+
+        """
+        locator = self._make_locator()
+
+        path = locator.find_object(obj, self.search_dirs)
+
+        return self.read(path)