changed to pystache_custom to avoid conflict

README.rst

@@ -2,7 +2,7 @@
 Pystache
 ========
 
-.. image:: https://s3.amazonaws.com/webdev_bucket/pystache.png
+.. image:: https://s3.amazonaws.com/webdev_bucket/pystache_custom.png
 
 Pystache_ is a Python implementation of Mustache_.
 Mustache is a framework-agnostic, logic-free templating system inspired
@@ -48,8 +48,8 @@ Install It
 
 ::
 
-    pip install pystache
-    pystache-test
+    pip install pystache_custom
+    pystache_custom-test
 
 To install and test from source (e.g. from GitHub), see the Develop section.
 
@@ -59,8 +59,8 @@ Use It
 
 ::
 
-    >>> import pystache
-    >>> print pystache.render('Hi {{person}}!', {'person': 'Mom'})
+    >>> import pystache_custom
+    >>> print pystache_custom.render('Hi {{person}}!', {'person': 'Mom'})
     Hi Mom!
 
 You can also create dedicated view classes to hold your view logic.
@@ -74,7 +74,7 @@ Here's your view class (in examples/readme.py)::
 
 Like so::
 
-    >>> from pystache.tests.examples.readme import SayHello
+    >>> from pystache_custom.tests.examples.readme import SayHello
     >>> hello = SayHello()
 
 Then your template, say_hello.mustache (in the same directory by default
@@ -84,7 +84,7 @@ as your class definition)::
 
 Pull it together::
 
-    >>> renderer = pystache.Renderer()
+    >>> renderer = pystache_custom.Renderer()
     >>> print renderer.render(hello)
     Hello, Pizza!
 
@@ -150,7 +150,7 @@ Develop
 
 To test from a source distribution (without installing)-- ::
 
-    python test_pystache.py
+    python test_pystache_custom.py
 
 To test Pystache with multiple versions of Python (with a single command!),
 you can use tox_: ::
@@ -176,13 +176,13 @@ is present.  Otherwise, it parses the json files.  To install PyYAML-- ::
 To run a subset of the tests, you can use nose_: ::
 
     pip install nose
-    nosetests --tests pystache/tests/test_context.py:GetValueTests.test_dictionary__key_present
+    nosetests --tests pystache_custom/tests/test_context.py:GetValueTests.test_dictionary__key_present
 
 **Running Pystache from source with Python 3.**  Pystache is written in
 Python 2 and must be converted with 2to3_ prior to running under Python 3.
 The installation process (and tox) do this conversion automatically.
 
-To ``import pystache`` from a source distribution while using Python 3,
+To ``import pystache_custom`` from a source distribution while using Python 3,
 be sure that you are importing from a directory containing a converted
 version (e.g. from your site-packages directory after manually installing)
 and not from the original source directory.  Otherwise, you will get a
@@ -203,7 +203,7 @@ Authors
 ::
 
     >>> context = { 'author': 'Chris Wanstrath', 'maintainer': 'Chris Jerdonek' }
-    >>> print pystache.render("Author: {{author}}\nMaintainer: {{maintainer}}", context)
+    >>> print pystache_custom.render("Author: {{author}}\nMaintainer: {{maintainer}}", context)
     Author: Chris Wanstrath
     Maintainer: Chris Jerdonek
 
@@ -215,19 +215,19 @@ Authors
 .. _Distribute: http://pypi.python.org/pypi/distribute
 .. _et: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
 .. _json: http://docs.python.org/library/json.html
-.. _mailing list: http://librelist.com/browser/pystache/
+.. _mailing list: http://librelist.com/browser/pystache_custom/
 .. _Mustache: http://mustache.github.com/
 .. _Mustache spec: https://github.com/mustache/spec
 .. _mustache(5): http://mustache.github.com/mustache.5.html
 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/testing.html
 .. _only unicode strings: http://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs
-.. _PyPI: http://pypi.python.org/pypi/pystache
-.. _Pystache: https://github.com/defunkt/pystache
+.. _PyPI: http://pypi.python.org/pypi/pystache_custom
+.. _Pystache: https://github.com/defunkt/pystache_custom
 .. _PyYAML: http://pypi.python.org/pypi/PyYAML
-.. _Renderer: https://github.com/defunkt/pystache/blob/master/pystache/renderer.py
+.. _Renderer: https://github.com/defunkt/pystache_custom/blob/master/pystache_custom/renderer.py
 .. _semantically versioned: http://semver.org
 .. _simplejson: http://pypi.python.org/pypi/simplejson/
-.. _TemplateSpec: https://github.com/defunkt/pystache/blob/master/pystache/template_spec.py
+.. _TemplateSpec: https://github.com/defunkt/pystache_custom/blob/master/pystache_custom/template_spec.py
 .. _test: http://packages.python.org/distribute/setuptools.html#test
 .. _tox: http://pypi.python.org/pypi/tox
 .. _version 1.1.2: https://github.com/mustache/spec/tree/v1.1.2

pystache_custom/__init__.py

+
+"""
+TODO: add a docstring.
+
+"""
+
+# We keep all initialization code in a separate module.
+
+from pystache_custom.init import render, Renderer, TemplateSpec
+
+__all__ = ['render', 'Renderer', 'TemplateSpec']
+
+__version__ = '0.5.2'  # Also change in setup.py.

pystache_custom/commands/render.py

+# coding: utf-8
+
+"""
+This module provides command-line access to pystache_custom.
+
+Run this script using the -h option for command-line help.
+
+"""
+
+
+try:
+    import json
+except:
+    # The json module is new in Python 2.6, whereas simplejson is
+    # compatible with earlier versions.
+    try:
+        import simplejson as json
+    except ImportError:
+        # Raise an error with a type different from ImportError as a hack around
+        # this issue:
+        #   http://bugs.python.org/issue7559
+        from sys import exc_info
+        ex_type, ex_value, tb = exc_info()
+        new_ex = Exception("%s: %s" % (ex_type.__name__, ex_value))
+        raise new_ex.__class__, new_ex, tb
+
+# The optparse module is deprecated in Python 2.7 in favor of argparse.
+# However, argparse is not available in Python 2.6 and earlier.
+from optparse import OptionParser
+import sys
+
+# We use absolute imports here to allow use of this script from its
+# location in source control (e.g. for development purposes).
+# Otherwise, the following error occurs:
+#
+#   ValueError: Attempted relative import in non-package
+#
+from pystache_custom.common import TemplateNotFoundError
+from pystache_custom.renderer import Renderer
+
+
+USAGE = """\
+%prog [-h] template context
+
+Render a mustache template with the given context.
+
+positional arguments:
+  template    A filename or template string.
+  context     A filename or JSON string."""
+
+
+def parse_args(sys_argv, usage):
+    """
+    Return an OptionParser for the script.
+
+    """
+    args = sys_argv[1:]
+
+    parser = OptionParser(usage=usage)
+    options, args = parser.parse_args(args)
+
+    template, context = args
+
+    return template, context
+
+
+# TODO: verify whether the setup() method's entry_points argument
+# supports passing arguments to main:
+#
+#     http://packages.python.org/distribute/setuptools.html#automatic-script-creation
+#
+def main(sys_argv=sys.argv):
+    template, context = parse_args(sys_argv, USAGE)
+
+    if template.endswith('.mustache'):
+        template = template[:-9]
+
+    renderer = Renderer()
+
+    try:
+        template = renderer.load_template(template)
+    except TemplateNotFoundError:
+        pass
+
+    try:
+        context = json.load(open(context))
+    except IOError:
+        context = json.loads(context)
+
+    rendered = renderer.render(template, context)
+    print rendered
+
+
+if __name__=='__main__':
+    main()

pystache_custom/commands/test.py

+# coding: utf-8
+
+"""
+This module provides a command to test pystache_custom (unit tests, doctests, etc).
+
+"""
+
+import sys
+
+from pystache_custom.tests.main import main as run_tests
+
+
+def main(sys_argv=sys.argv):
+    run_tests(sys_argv=sys_argv)
+
+
+if __name__=='__main__':
+    main()

pystache_custom/common.py-e

+# coding: utf-8
+
+"""
+Exposes functionality needed throughout the project.
+
+"""
+
+# This function was designed to be portable across Python versions -- both
+# with older versions and with Python 3 after applying 2to3.
+def read(path):
+    """
+    Return the contents of a text file as a byte string.
+
+    """
+    # Opening in binary mode is necessary for compatibility across Python
+    # 2 and 3.  In both Python 2 and 3, open() defaults to opening files in
+    # text mode.  However, in Python 2, open() returns file objects whose
+    # read() method returns byte strings (strings of type `str` in Python 2),
+    # whereas in Python 3, the file object returns unicode strings (strings
+    # of type `str` in Python 3).
+    f = open(path, 'rb')
+    # We avoid use of the with keyword for Python 2.4 support.
+    try:
+        return f.read()
+    finally:
+        f.close()
+
+
+class PystacheError(Exception):
+    """Base class for Pystache exceptions."""
+    pass
+
+
+class TemplateNotFoundError(PystacheError):
+    """An exception raised when a template is not found."""
+    pass

pystache_custom/defaults.py-e

+# coding: utf-8
+
+"""
+This module provides a central location for defining default behavior.
+
+Throughout the package, these defaults take effect only when the user
+does not otherwise specify a value.
+
+"""
+
+try:
+    # Python 3.2 adds html.escape() and deprecates cgi.escape().
+    from html import escape
+except ImportError:
+    from cgi import escape
+
+import os
+import sys
+
+
+# How to handle encoding errors when decoding strings from str to unicode.
+#
+# This value is passed as the "errors" argument to Python's built-in
+# unicode() function:
+#
+#   http://docs.python.org/library/functions.html#unicode
+#
+DECODE_ERRORS = 'strict'
+
+# The name of the encoding to use when converting to unicode any strings of
+# type str encountered during the rendering process.
+STRING_ENCODING = sys.getdefaultencoding()
+
+# The name of the encoding to use when converting file contents to unicode.
+# This default takes precedence over the STRING_ENCODING default for
+# strings that arise from files.
+FILE_ENCODING = sys.getdefaultencoding()
+
+# The starting list of directories in which to search for templates when
+# loading a template by file name.
+SEARCH_DIRS = [os.curdir]  # i.e. ['.']
+
+# The escape function to apply to strings that require escaping when
+# rendering templates (e.g. for tags enclosed in double braces).
+# Only unicode strings will be passed to this function.
+#
+# The quote=True argument causes double but not single quotes to be escaped
+# in Python 3.1 and earlier, and both double and single quotes to be
+# escaped in Python 3.2 and later:
+#
+#   http://docs.python.org/library/cgi.html#cgi.escape
+#   http://docs.python.org/dev/library/html.html#html.escape
+#
+TAG_ESCAPE = lambda u: escape(u, quote=True)
+
+# The default template extension.
+TEMPLATE_EXTENSION = 'mustache'

pystache_custom/init.py

+# encoding: utf-8
+
+"""
+This module contains the initialization logic called by __init__.py.
+
+"""
+
+from pystache_custom.renderer import Renderer
+from pystache_custom.template_spec import TemplateSpec
+
+
+def render(template, context=None, **kwargs):
+    """
+    Return the given template string rendered using the given context.
+
+    """
+    renderer = Renderer()
+    return renderer.render(template, context, **kwargs)

pystache_custom/loader.py

+# coding: utf-8
+
+"""
+This module provides a Loader class for locating and reading templates.
+
+"""
+
+import os
+import sys
+
+from pystache_custom import common
+from pystache_custom import defaults
+from pystache_custom.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.
+
+    """
+
+    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.  Pass False for no
+            extension (i.e. 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)
+
+    # TODO: unit-test this method.
+    def load_name(self, name):
+        """
+        Find and return the template with the given name.
+
+        Arguments:
+
+          name: the name of the template.
+
+          search_dirs: the list of directories in which to search.
+
+        """
+        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)

pystache_custom/locator.py

+# coding: utf-8
+
+"""
+This module provides a Locator class for finding template files.
+
+"""
+
+import os
+import re
+import sys
+
+from pystache_custom.common import TemplateNotFoundError
+from pystache_custom import defaults
+
+
+class Locator(object):
+
+    def __init__(self, extension=None):
+        """
+        Construct a template locator.
+
+        Arguments:
+
+          extension: the template file extension.  Pass False for no
+            extension (i.e. to use extensionless template files).
+            Defaults to the package default.
+
+        """
+        if extension is None:
+            extension = defaults.TEMPLATE_EXTENSION
+
+        self.template_extension = extension
+
+    def get_object_directory(self, obj):
+        """
+        Return the directory containing an object's defining class.
+
+        Returns None if there is no such directory, for example if the
+        class was defined in an interactive Python session, or in a
+        doctest that appears in a text file (rather than a Python file).
+
+        """
+        if not hasattr(obj, '__module__'):
+            return None
+
+        module = sys.modules[obj.__module__]
+
+        if not hasattr(module, '__file__'):
+            # TODO: add a unit test for this case.
+            return None
+
+        path = module.__file__
+
+        return os.path.dirname(path)
+
+    def make_template_name(self, obj):
+        """
+        Return the canonical template name for an object instance.
+
+        This method converts Python-style class names (PEP 8's recommended
+        CamelCase, aka CapWords) to lower_case_with_underscords.  Here
+        is an example with code:
+
+        >>> class HelloWorld(object):
+        ...     pass
+        >>> hi = HelloWorld()
+        >>>
+        >>> locator = Locator()
+        >>> locator.make_template_name(hi)
+        'hello_world'
+
+        """
+        template_name = obj.__class__.__name__
+
+        def repl(match):
+            return '_' + match.group(0).lower()
+
+        return re.sub('[A-Z]', repl, template_name)[1:]
+
+    def make_file_name(self, template_name, template_extension=None):
+        """
+        Generate and return the file name for the given template name.
+
+        Arguments:
+
+          template_extension: defaults to the instance's extension.
+
+        """
+        file_name = template_name
+
+        if template_extension is None:
+            template_extension = self.template_extension
+
+        if template_extension is not False:
+            file_name += os.path.extsep + template_extension
+
+        return file_name
+
+    def _find_path(self, search_dirs, file_name):
+        """
+        Search for the given file, and return the path.
+
+        Returns None if the file is not found.
+
+        """
+        for dir_path in search_dirs:
+            file_path = os.path.join(dir_path, file_name)
+            if os.path.exists(file_path):
+                return file_path
+
+        return None
+
+    def _find_path_required(self, search_dirs, file_name):
+        """
+        Return the path to a template with the given file name.
+
+        """
+        path = self._find_path(search_dirs, file_name)
+
+        if path is None:
+            raise TemplateNotFoundError('File %s not found in dirs: %s' %
+                                        (repr(file_name), repr(search_dirs)))
+
+        return path
+
+    def find_name(self, template_name, search_dirs):
+        """
+        Return the path to a template with the given name.
+
+        """
+        file_name = self.make_file_name(template_name)
+
+        return self._find_path_required(search_dirs, file_name)
+
+    def find_object(self, obj, search_dirs, file_name=None):
+        """
+        Return the path to a template associated with the given object.
+
+        """
+        if file_name is None:
+            # TODO: should we define a make_file_name() method?
+            template_name = self.make_template_name(obj)
+            file_name = self.make_file_name(template_name)
+
+        dir_path = self.get_object_directory(obj)
+
+        if dir_path is not None:
+            search_dirs = [dir_path] + search_dirs
+
+        path = self._find_path_required(search_dirs, file_name)
+
+        return path

pystache_custom/parsed.py-e

+# coding: utf-8
+
+"""
+Exposes a class that represents a parsed (or compiled) template.
+
+This module is meant only for internal use.
+
+"""
+
+
+class ParsedTemplate(object):
+
+    def __init__(self, parse_tree):
+        """
+        Arguments:
+
+          parse_tree: a list, each element of which is either--
+
+            (1) a unicode string, or
+            (2) a "rendering" callable that accepts a ContextStack instance
+                and returns a unicode string.
+
+        The possible rendering callables are the return values of the
+        following functions:
+
+        * RenderEngine._make_get_escaped()
+        * RenderEngine._make_get_inverse()
+        * RenderEngine._make_get_literal()
+        * RenderEngine._make_get_partial()
+        * RenderEngine._make_get_section()
+
+        """
+        self._parse_tree = parse_tree
+
+    def __repr__(self):
+        return "[%s]" % (", ".join([repr(part) for part in self._parse_tree]))
+
+    def render(self, context):
+        """
+        Returns: a string of type unicode.
+
+        """
+        # We avoid use of the ternary operator for Python 2.4 support.
+        def get_unicode(val):
+            if callable(val):
+                return val(context)
+            return val
+        parts = map(get_unicode, self._parse_tree)
+        s = ''.join(parts)
+
+        return unicode(s)
+

pystache_custom/parser.py

+# coding: utf-8
+
+"""
+Provides a class for parsing template strings.
+
+This module is only meant for internal use by the renderengine module.
+
+"""
+
+import re
+
+from pystache_custom.common import TemplateNotFoundError
+from pystache_custom.parsed import ParsedTemplate
+
+
+DEFAULT_DELIMITERS = (u'{{', u'}}')
+END_OF_LINE_CHARACTERS = [u'\r', u'\n']
+NON_BLANK_RE = re.compile(ur'^(.)', re.M)
+
+
+def _compile_template_re(delimiters=None):
+    """
+    Return a regular expresssion object (re.RegexObject) instance.
+
+    """
+    if delimiters is None:
+        delimiters = DEFAULT_DELIMITERS
+
+    # The possible tag type characters following the opening tag,
+    # excluding "=" and "{".
+    tag_types = "!>&/#^"
+
+    # TODO: are we following this in the spec?
+    #
+    #   The tag's content MUST be a non-whitespace character sequence
+    #   NOT containing the current closing delimiter.
+    #
+    tag = r"""
+        (?P<whitespace>[\ \t]*)
+        %(otag)s \s*
+        (?:
+          (?P<change>=) \s* (?P<delims>.+?)   \s* = |
+          (?P<raw>{)    \s* (?P<raw_name>.+?) \s* } |
+          (?P<tag>[%(tag_types)s]?)  \s* (?P<tag_key>[\s\S]+?)
+        )
+        \s* %(ctag)s
+    """ % {'tag_types': tag_types, 'otag': re.escape(delimiters[0]), 'ctag': re.escape(delimiters[1])}
+
+    return re.compile(tag, re.VERBOSE)
+
+
+class ParsingError(Exception):
+
+    pass
+
+
+class Parser(object):
+
+    _delimiters = None
+    _template_re = None
+
+    def __init__(self, engine, delimiters=None):
+        """
+        Construct an instance.
+
+        Arguments:
+
+          engine: a RenderEngine instance.
+
+        """
+        if delimiters is None:
+            delimiters = DEFAULT_DELIMITERS
+
+        self._delimiters = delimiters
+        self.engine = engine
+
+    def compile_template_re(self):
+        self._template_re = _compile_template_re(self._delimiters)
+
+    def _change_delimiters(self, delimiters):
+        self._delimiters = delimiters
+        self.compile_template_re()
+
+    def parse(self, template, start_index=0, section_key=None):
+        """
+        Parse a template string starting at some index.
+
+        This method uses the current tag delimiter.
+
+        Arguments:
+
+          template: a unicode string that is the template to parse.
+
+          index: the index at which to start parsing.
+
+        Returns:
+
+          a ParsedTemplate instance.
+
+        """
+        parse_tree = []
+        index = start_index
+
+        while True:
+            match = self._template_re.search(template, index)
+
+            if match is None:
+                break
+
+            match_index = match.start()
+            end_index = match.end()
+
+            before_tag = template[index : match_index]
+
+            parse_tree.append(before_tag)
+
+            matches = match.groupdict()
+
+            # Normalize the matches dictionary.
+            if matches['change'] is not None:
+                matches.update(tag='=', tag_key=matches['delims'])
+            elif matches['raw'] is not None:
+                matches.update(tag='&', tag_key=matches['raw_name'])
+
+            tag_type = matches['tag']
+            tag_key = matches['tag_key']
+            leading_whitespace = matches['whitespace']
+
+            # Standalone (non-interpolation) tags consume the entire line,
+            # both leading whitespace and trailing newline.
+            did_tag_begin_line = match_index == 0 or template[match_index - 1] in END_OF_LINE_CHARACTERS
+            did_tag_end_line = end_index == len(template) or template[end_index] in END_OF_LINE_CHARACTERS
+            is_tag_interpolating = tag_type in ['', '&']
+
+            if did_tag_begin_line and did_tag_end_line and not is_tag_interpolating:
+                if end_index < len(template):
+                    end_index += template[end_index] == '\r' and 1 or 0
+                if end_index < len(template):
+                    end_index += template[end_index] == '\n' and 1 or 0
+            elif leading_whitespace:
+                parse_tree.append(leading_whitespace)
+                match_index += len(leading_whitespace)
+                leading_whitespace = ''
+
+            if tag_type == '/':
+                if tag_key != section_key:
+                    raise ParsingError("Section end tag mismatch: %s != %s" % (tag_key, section_key))
+
+                return ParsedTemplate(parse_tree), match_index, end_index
+
+            index = self._handle_tag_type(template, parse_tree, tag_type, tag_key, leading_whitespace, end_index)
+
+        # Save the rest of the template.
+        parse_tree.append(template[index:])
+
+        return ParsedTemplate(parse_tree)
+
+    def _parse_section(self, template, start_index, section_key):
+        """
+        Parse the contents of a template section.
+
+        Arguments:
+
+          template: a unicode template string.
+
+          start_index: the string index at which the section contents begin.
+
+          section_key: the tag key of the section.
+
+        Returns: a 3-tuple:
+
+          parsed_section: the section contents parsed as a ParsedTemplate
+            instance.
+
+          content_end_index: the string index after the section contents.
+
+          end_index: the string index after the closing section tag (and
+            including any trailing newlines).
+
+        """
+        parsed_section, content_end_index, end_index = \
+            self.parse(template=template, start_index=start_index, section_key=section_key)
+
+        return parsed_section, template[start_index:content_end_index], end_index
+
+    def _handle_tag_type(self, template, parse_tree, tag_type, tag_key, leading_whitespace, end_index):
+
+        # TODO: switch to using a dictionary instead of a bunch of ifs and elifs.
+        if tag_type == '!':
+            return end_index
+
+        if tag_type == '=':
+            delimiters = tag_key.split()
+            self._change_delimiters(delimiters)
+            return end_index
+
+        engine = self.engine
+
+        if tag_type == '':
+
+            func = engine._make_get_escaped(tag_key)
+
+        elif tag_type == '&':
+
+            func = engine._make_get_literal(tag_key)
+
+        elif tag_type == '#':
+
+            parsed_section, section_contents, end_index = self._parse_section(template, end_index, tag_key)
+            func = engine._make_get_section(tag_key, parsed_section, section_contents, self._delimiters)
+
+        elif tag_type == '^':
+
+            parsed_section, section_contents, end_index = self._parse_section(template, end_index, tag_key)
+            func = engine._make_get_inverse(tag_key, parsed_section)
+
+        elif tag_type == '>':
+
+            try:
+                # TODO: make engine.load() and test it separately.
+                template = engine.load_partial(tag_key)
+            except TemplateNotFoundError:
+                template = u''
+
+            # Indent before rendering.
+            template = re.sub(NON_BLANK_RE, leading_whitespace + ur'\1', template)
+
+            func = engine._make_get_partial(template)
+
+        else:
+
+            raise Exception("Unrecognized tag type: %s" % repr(tag_type))
+
+        parse_tree.append(func)
+
+        return end_index
+

pystache_custom/specloader.py

+# coding: utf-8
+
+"""
+This module supports customized (aka special or specified) template loading.
+
+"""
+
+import os.path
+
+from pystache_custom.loader import Loader
+
+
+# TODO: add test cases for this class.
+class SpecLoader(object):
+
+    """
+    Supports loading custom-specified templates (from TemplateSpec instances).
+
+    """
+
+    def __init__(self, loader=None):
+        if loader is None:
+            loader = Loader()
+
+        self.loader = loader
+
+    def _find_relative(self, spec):
+        """
+        Return the path to the template as a relative (dir, file_name) pair.
+
+        The directory returned is relative to the directory containing the
+        class definition of the given object.  The method returns None for
+        this directory if the directory is unknown without first searching
+        the search directories.
+
+        """
+        if spec.template_rel_path is not None:
+            return os.path.split(spec.template_rel_path)
+        # Otherwise, determine the file name separately.
+
+        locator = self.loader._make_locator()
+
+        # We do not use the ternary operator for Python 2.4 support.
+        if spec.template_name is not None:
+            template_name = spec.template_name
+        else:
+            template_name = locator.make_template_name(spec)
+
+        file_name = locator.make_file_name(template_name, spec.template_extension)
+
+        return (spec.template_rel_directory, file_name)
+
+    def _find(self, spec):
+        """
+        Find and return the path to the template associated to the instance.
+
+        """
+        dir_path, file_name = self._find_relative(spec)
+
+        locator = self.loader._make_locator()
+
+        if dir_path is None:
+            # Then we need to search for the path.
+            path = locator.find_object(spec, self.loader.search_dirs, file_name=file_name)
+        else:
+            obj_dir = locator.get_object_directory(spec)
+            path = os.path.join(obj_dir, dir_path, file_name)
+
+        return path
+
+    def load(self, spec):
+        """
+        Find and return the template associated to a TemplateSpec instance.
+
+        Returns the template as a unicode string.
+
+        Arguments:
+
+          spec: a TemplateSpec instance.
+
+        """
+        if spec.template is not None:
+            return self.loader.unicode(spec.template, spec.template_encoding)
+
+        path = self._find(spec)
+
+        return self.loader.read(path, spec.template_encoding)

pystache_custom/template_spec.py-e

+# coding: utf-8
+
+"""
+Provides a class to customize template information on a per-view basis.
+
+To customize template properties for a particular view, create that view
+from a class that subclasses TemplateSpec.  The "Spec" in TemplateSpec
+stands for template information that is "special" or "specified".
+
+"""
+
+# TODO: finish the class docstring.
+class TemplateSpec(object):
+
+    """
+    A mixin or interface for specifying custom template information.
+
+    The "spec" in TemplateSpec can be taken to mean that the template
+    information is either "specified" or "special."
+
+    A view should subclass this class only if customized template loading
+    is needed.  The following attributes allow one to customize/override
+    template information on a per view basis.  A None value means to use
+    default behavior for that value and perform no customization.  All
+    attributes are initialized to None.
+
+    Attributes:
+
+      template: the template as a string.
+
+      template_rel_path: the path to the template file, relative to the
+        directory containing the module defining the class.
+
+      template_rel_directory: the directory containing the template file, relative
+        to the directory containing the module defining the class.
+
+      template_extension: the template file extension.  Defaults to "mustache".
+        Pass False for no extension (i.e. extensionless template files).
+
+    """
+
+    template = None
+    template_rel_path = None
+    template_rel_directory = None
+    template_name = None
+    template_extension = None
+    template_encoding = None

pystache_custom/tests/benchmark.py

+#!/usr/bin/env python
+# coding: utf-8
+
+"""
+A rudimentary backward- and forward-compatible script to benchmark pystache_custom.
+
+Usage:
+
+tests/benchmark.py 10000
+
+"""
+
+import sys
+from timeit import Timer
+
+import pystache_custom
+
+# TODO: make the example realistic.
+
+examples = [
+    # Test case: 1
+    ("""{{#person}}Hi {{name}}{{/person}}""",
+    {"person": {"name": "Jon"}},
+    "Hi Jon"),
+
+    # Test case: 2
+    ("""\
+<div class="comments">
+<h3>{{header}}</h3>
+<ul>
+{{#comments}}<li class="comment">
+<h5>{{name}}</h5><p>{{body}}</p>
+</li>{{/comments}}
+</ul>
+</div>""",
+    {'header': "My Post Comments",
+     'comments': [
+         {'name': "Joe", 'body': "Thanks for this post!"},
+         {'name': "Sam", 'body': "Thanks for this post!"},
+         {'name': "Heather", 'body': "Thanks for this post!"},
+         {'name': "Kathy", 'body': "Thanks for this post!"},
+         {'name': "George", 'body': "Thanks for this post!"}]},
+    """\
+<div class="comments">
+<h3>My Post Comments</h3>
+<ul>
+<li class="comment">
+<h5>Joe</h5><p>Thanks for this post!</p>
+</li><li class="comment">
+<h5>Sam</h5><p>Thanks for this post!</p>
+</li><li class="comment">
+<h5>Heather</h5><p>Thanks for this post!</p>
+</li><li class="comment">
+<h5>Kathy</h5><p>Thanks for this post!</p>
+</li><li class="comment">
+<h5>George</h5><p>Thanks for this post!</p>
+</li>
+</ul>
+</div>"""),
+]
+
+
+def make_test_function(example):
+
+    template, context, expected = example
+
+    def test():
+        actual = pystache_custom.render(template, context)
+        if actual != expected:
+            raise Exception("Benchmark mismatch: \n%s\n*** != ***\n%s" % (expected, actual))
+
+    return test
+
+
+def main(sys_argv):
+    args = sys_argv[1:]
+    count = int(args[0])
+
+    print "Benchmarking: %sx" % count
+    print
+
+    for example in examples:
+
+        test = make_test_function(example)
+
+        t = Timer(test,)
+        print min(t.repeat(repeat=3, number=count))
+
+    print "Done"
+
+
+if __name__ == '__main__':
+    main(sys.argv)
+

pystache_custom/tests/common.py

+# coding: utf-8
+
+"""
+Provides test-related code that can be used by all tests.
+
+"""
+
+import os
+
+import pystache_custom
+from pystache_custom import defaults
+from pystache_custom.tests import examples
+
+# Save a reference to the original function to avoid recursion.
+_DEFAULT_TAG_ESCAPE = defaults.TAG_ESCAPE
+_TESTS_DIR = os.path.dirname(pystache_custom.tests.__file__)
+
+DATA_DIR = os.path.join(_TESTS_DIR, 'data')  # i.e. 'pystache_custom/tests/data'.
+EXAMPLES_DIR = os.path.dirname(examples.__file__)
+PACKAGE_DIR = os.path.dirname(pystache_custom.__file__)
+PROJECT_DIR = os.path.join(PACKAGE_DIR, '..')
+SPEC_TEST_DIR = os.path.join(PROJECT_DIR, 'ext', 'spec', 'specs')
+# TEXT_DOCTEST_PATHS: the paths to text files (i.e. non-module files)
+# containing doctests.  The paths should be relative to the project directory.
+TEXT_DOCTEST_PATHS = ['README.rst']
+
+UNITTEST_FILE_PREFIX = "test_"
+
+
+def html_escape(u):
+    """
+    An html escape function that behaves the same in both Python 2 and 3.
+
+    This function is needed because single quotes are escaped in Python 3
+    (to '''), but not in Python 2.
+
+    The global defaults.TAG_ESCAPE can be set to this function in the
+    setUp() and tearDown() of unittest test cases, for example, for
+    consistent test results.
+
+    """
+    u = _DEFAULT_TAG_ESCAPE(u)
+    return u.replace("'", ''')
+
+
+def get_data_path(file_name):
+    return os.path.join(DATA_DIR, file_name)
+
+
+# Functions related to get_module_names().
+
+def _find_files(root_dir, should_include):
+    """
+    Return a list of paths to all modules below the given directory.
+
+    Arguments:
+
+      should_include: a function that accepts a file path and returns True or False.
+
+    """
+    paths = []  # Return value.
+
+    is_module = lambda path: path.endswith(".py")
+
+    # os.walk() is new in Python 2.3
+    #   http://docs.python.org/library/os.html#os.walk
+    for dir_path, dir_names, file_names in os.walk(root_dir):
+        new_paths = [os.path.join(dir_path, file_name) for file_name in file_names]
+        new_paths = filter(is_module, new_paths)
+        new_paths = filter(should_include, new_paths)
+        paths.extend(new_paths)
+
+    return paths
+
+
+def _make_module_names(package_dir, paths):
+    """
+    Return a list of fully-qualified module names given a list of module paths.
+
+    """
+    package_dir = os.path.abspath(package_dir)
+    package_name = os.path.split(package_dir)[1]
+
+    prefix_length = len(package_dir)
+
+    module_names = []
+    for path in paths:
+        path = os.path.abspath(path)  # for example <path_to_package>/subpackage/module.py
+        rel_path = path[prefix_length:]  # for example /subpackage/module.py
+        rel_path = os.path.splitext(rel_path)[0]  # for example /subpackage/module
+
+        parts = []
+        while True:
+            (rel_path, tail) = os.path.split(rel_path)
+            if not tail:
+                break
+            parts.insert(0, tail)
+        # We now have, for example, ['subpackage', 'module'].
+        parts.insert(0, package_name)
+        module = ".".join(parts)
+        module_names.append(module)
+
+    return module_names
+
+
+def get_module_names(package_dir=None, should_include=None):
+    """
+    Return a list of fully-qualified module names in the given package.
+
+    """
+    if package_dir is None:
+        package_dir = PACKAGE_DIR
+
+    if should_include is None:
+        should_include = lambda path: True
+
+    paths = _find_files(package_dir, should_include)
+    names = _make_module_names(package_dir, paths)
+    names.sort()
+
+    return names
+
+
+class AssertStringMixin:
+
+    """A unittest.TestCase mixin to check string equality."""
+
+    def assertString(self, actual, expected, format=None):
+        """
+        Assert that the given strings are equal and have the same type.
+
+        Arguments:
+
+          format: a format string containing a single conversion specifier %s.
+            Defaults to "%s".
+
+        """
+        if format is None:
+            format = "%s"
+
+        # Show both friendly and literal versions.
+        details = """String mismatch: %%s\
+
+
+        Expected: \"""%s\"""
+        Actual:   \"""%s\"""
+
+        Expected: %s
+        Actual:   %s""" % (expected, actual, repr(expected), repr(actual))
+
+        def make_message(reason):
+            description = details % reason
+            return format % description
+
+        self.assertEqual(actual, expected, make_message("different characters"))
+
+        reason = "types different: %s != %s (actual)" % (repr(type(expected)), repr(type(actual)))
+        self.assertEqual(type(expected), type(actual), make_message(reason))
+
+
+class AssertIsMixin:
+
+    """A unittest.TestCase mixin adding assertIs()."""
+
+    # unittest.assertIs() is not available until Python 2.7:
+    #   http://docs.python.org/library/unittest.html#unittest.TestCase.assertIsNone
+    def assertIs(self, first, second):
+        self.assertTrue(first is second, msg="%s is not %s" % (repr(first), repr(second)))
+
+
+class AssertExceptionMixin:
+
+    """A unittest.TestCase mixin adding assertException()."""
+
+    # unittest.assertRaisesRegexp() is not available until Python 2.7:
+    #   http://docs.python.org/library/unittest.html#unittest.TestCase.assertRaisesRegexp
+    def assertException(self, exception_type, msg, callable, *args, **kwds):
+        try:
+            callable(*args, **kwds)
+            raise Exception("Expected exception: %s: %s" % (exception_type, repr(msg)))
+        except exception_type, err:
+            self.assertEqual(str(err), msg)
+
+
+class SetupDefaults(object):
+
+    """
+    Mix this class in to a unittest.TestCase for standard defaults.
+
+    This class allows for consistent test results across Python 2/3.
+
+    """
+
+    def setup_defaults(self):
+        self.original_decode_errors = defaults.DECODE_ERRORS
+        self.original_file_encoding = defaults.FILE_ENCODING
+        self.original_string_encoding = defaults.STRING_ENCODING
+
+        defaults.DECODE_ERRORS = 'strict'
+        defaults.FILE_ENCODING = 'ascii'
+        defaults.STRING_ENCODING = 'ascii'
+
+    def teardown_defaults(self):
+        defaults.DECODE_ERRORS = self.original_decode_errors
+        defaults.FILE_ENCODING = self.original_file_encoding
+        defaults.STRING_ENCODING = self.original_string_encoding
+
+
+class Attachable(object):
+    """
+    A class that attaches all constructor named parameters as attributes.
+
+    For example--
+
+    >>> obj = Attachable(foo=42, size="of the universe")
+    >>> repr(obj)
+    "Attachable(foo=42, size='of the universe')"
+    >>> obj.foo
+    42
+    >>> obj.size
+    'of the universe'
+
+    """
+    def __init__(self, **kwargs):
+        self.__args__ = kwargs
+        for arg, value in kwargs.iteritems():
+            setattr(self, arg, value)
+
+    def __repr__(self):
+        return "%s(%s)" % (self.__class__.__name__,
+                           ", ".join("%s=%s" % (k, repr(v))
+                                     for k, v in self.__args__.iteritems()))

pystache_custom/tests/data/__init__.py-e

+"""
+TODO: add a docstring.
+
+"""

pystache_custom/tests/data/locator/__init__.py

+"""
+TODO: add a docstring.
+
+"""

pystache_custom/tests/data/locator/__init__.py-e

+"""
+TODO: add a docstring.
+
+"""

pystache_custom/tests/data/views.py

+# coding: utf-8
+
+"""
+TODO: add a docstring.
+
+"""
+
+from pystache_custom import TemplateSpec
+
+class SayHello(object):
+
+    def to(self):
+        return "World"
+
+
+class SampleView(TemplateSpec):
+    pass
+
+
+class NonAscii(TemplateSpec):
+    pass

pystache_custom/tests/doctesting.py

+# coding: utf-8
+
+"""
+Exposes a get_doctests() function for the project's test harness.
+
+"""
+
+import doctest
+import os
+import pkgutil
+import sys
+import traceback
+
+if sys.version_info >= (3,):
+    # Then pull in modules needed for 2to3 conversion.  The modules
+    # below are not necessarily available in older versions of Python.
+    from lib2to3.main import main as lib2to3main  # new in Python 2.6?
+    from shutil import copyfile
+
+from pystache_custom.tests.common import TEXT_DOCTEST_PATHS
+from pystache_custom.tests.common import get_module_names
+
+
+# This module follows the guidance documented here:
+#
+#   http://docs.python.org/library/doctest.html#unittest-api
+#
+
+def get_doctests(text_file_dir):
+    """
+    Return a list of TestSuite instances for all doctests in the project.
+
+    Arguments:
+
+      text_file_dir: the directory in which to search for all text files
+        (i.e. non-module files) containing doctests.
+
+    """
+    # Since module_relative is False in our calls to DocFileSuite below,
+    # paths should be OS-specific.  See the following for more info--
+    #
+    #   http://docs.python.org/library/doctest.html#doctest.DocFileSuite
+    #
+    paths = [os.path.normpath(os.path.join(text_file_dir, path)) for path in TEXT_DOCTEST_PATHS]
+
+    if sys.version_info >= (3,):
+        paths = _convert_paths(paths)
+
+    suites = []
+
+    for path in paths:
+        suite = doctest.DocFileSuite(path, module_relative=False)
+        suites.append(suite)
+
+    modules = get_module_names()
+    for module in modules:
+        suite = doctest.DocTestSuite(module)
+        suites.append(suite)
+
+    return suites
+
+
+def _convert_2to3(path):
+    """
+    Convert the given file, and return the path to the converted files.
+
+    """
+    base, ext = os.path.splitext(path)
+    # For example, "README.temp2to3.rst".
+    new_path = "%s.temp2to3%s" % (base, ext)
+
+    copyfile(path, new_path)
+
+    args = ['--doctests_only', '--no-diffs', '--write', '--nobackups', new_path]
+    lib2to3main("lib2to3.fixes", args=args)
+
+    return new_path
+
+
+def _convert_paths(paths):
+    """
+    Convert the given files, and return the paths to the converted files.
+
+    """
+    new_paths = []
+    for path in paths:
+        new_path = _convert_2to3(path)
+        new_paths.append(new_path)
+
+    return new_paths

pystache_custom/tests/examples/__init__.py

+"""
+TODO: add a docstring.
+
+"""

pystache_custom/tests/examples/__init__.py-e

+"""
+TODO: add a docstring.
+
+"""

pystache_custom/tests/examples/comments.py-e

+
+"""
+TODO: add a docstring.
+
+"""
+
+class Comments(object):
+
+    def title(self):
+        return "A Comedy of Errors"

pystache_custom/tests/examples/complex.py-e

+
+"""
+TODO: add a docstring.
+
+"""
+
+class Complex(object):
+
+    def header(self):
+        return "Colors"
+
+    def item(self):
+        items = []
+        items.append({ 'name': 'red', 'current': True, 'url': '#Red' })
+        items.append({ 'name': 'green', 'link': True, 'url': '#Green' })
+        items.append({ 'name': 'blue', 'link': True, 'url': '#Blue' })
+        return items
+
+    def list(self):
+        return not self.empty()
+
+    def empty(self):
+        return len(self.item()) == 0
+
+    def empty_list(self):
+        return [];

pystache_custom/tests/examples/delimiters.py-e

+
+"""
+TODO: add a docstring.
+
+"""
+
+class Delimiters(object):
+
+    def first(self):
+        return "It worked the first time."
+
+    def second(self):
+        return "And it worked the second time."
+
+    def third(self):
+        return "Then, surprisingly, it worked the third time."

pystache_custom/tests/examples/double_section.py-e

+
+"""
+TODO: add a docstring.
+
+"""
+
+class DoubleSection(object):
+
+    def t(self):
+        return True
+
+    def two(self):
+        return "second"

pystache_custom/tests/examples/escaped.py-e

+
+"""
+TODO: add a docstring.
+
+"""
+
+class Escaped(object):
+
+    def title(self):
+        return "Bear > Shark"

pystache_custom/tests/examples/inverted.py

+
+"""
+TODO: add a docstring.
+
+"""
+
+from pystache_custom import TemplateSpec
+
+class Inverted(object):
+
+    def t(self):
+        return True
+
+    def f(self):
+        return False
+
+    def two(self):
+        return 'two'
+
+    def empty_list(self):
+        return []
+
+    def populated_list(self):
+        return ['some_value']
+
+class InvertedLists(Inverted, TemplateSpec):
+    template_name = 'inverted'
+
+    def t(self):
+        return [0, 1, 2]
+
+    def f(self):
+        return []

pystache_custom/tests/examples/lambdas.py

+
+"""
+TODO: add a docstring.
+
+"""
+
+from pystache_custom import TemplateSpec
+
+def rot(s, n=13):
+    r = ""
+    for c in s:
+        cc = c
+        if cc.isalpha():
+            cc = cc.lower()
+            o = ord(cc)
+            ro = (o+n) % 122
+            if ro == 0: ro = 122
+            if ro < 97: ro += 96
+            cc = chr(ro)
+        r = ''.join((r,cc))
+    return r
+
+def replace(subject, this='foo', with_this='bar'):
+    return subject.replace(this, with_this)
+
+
+# This class subclasses TemplateSpec because at least one unit test
+# sets the template attribute.
+class Lambdas(TemplateSpec):
+
+    def replace_foo_with_bar(self, text=None):
+        return replace
+
+    def rot13(self, text=None):
+        return rot
+
+    def sort(self, text=None):
+        return lambda text: ''.join(sorted(text))

pystache_custom/tests/examples/nested_context.py

+
+"""
+TODO: add a docstring.
+
+"""
+
+from pystache_custom import TemplateSpec
+
+class NestedContext(TemplateSpec):
+
+    def __init__(self, renderer):
+        self.renderer = renderer
+
+    def _context_get(self, key):
+        return self.renderer.context.get(key)
+
+    def outer_thing(self):
+        return "two"
+
+    def foo(self):
+        return {'thing1': 'one', 'thing2': 'foo'}
+
+    def derp(self):
+        return [{'inner': 'car'}]
+
+    def herp(self):
+        return [{'outer': 'car'}]
+
+    def nested_context_in_view(self):
+        if self._context_get('outer') == self._context_get('inner'):
+            return 'it works!'
+        return ''

pystache_custom/tests/examples/partials_with_lambdas.py

+
+"""
+TODO: add a docstring.
+
+"""
+
+from pystache_custom.tests.examples.lambdas import rot
+
+class PartialsWithLambdas(object):
+
+    def rot(self):
+        return rot

pystache_custom/tests/examples/readme.py-e

+
+"""
+TODO: add a docstring.
+
+"""
+
+class SayHello(object):
+    def to(self):
+        return "Pizza"

pystache_custom/tests/examples/simple.py

+
+"""
+TODO: add a docstring.
+
+"""
+
+from pystache_custom import TemplateSpec
+
+class Simple(TemplateSpec):
+
+    def thing(self):
+        return "pizza"
+
+    def blank(self):
+        return ''

pystache_custom/tests/examples/template_partial.py

+
+"""
+TODO: add a docstring.
+
+"""
+
+from pystache_custom import TemplateSpec
+
+class TemplatePartial(TemplateSpec):
+
+    def __init__(self, renderer):
+        self.renderer = renderer
+
+    def _context_get(self, key):
+        return self.renderer.context.get(key)
+
+    def title(self):
+        return "Welcome"
+
+    def title_bars(self):
+        return '-' * len(self.title())
+
+    def looping(self):
+        return [{'item': 'one'}, {'item': 'two'}, {'item': 'three'}]
+
+    def thing(self):
+        return self._context_get('prop')