Local Extensions

New in Cookiecutter 2.1

A template may extend the Cookiecutter environment with local extensions. These can be part of the template itself, providing it with more sophisticated custom tags and filters.

To do so, a template author must specify the required extensions in cookiecutter.json as follows:

{
    "project_slug": "Foobar",
    "year": "{% now 'utc', '%Y' %}",
    "_extensions": ["local_extensions.FoobarExtension"]
}

This example uses a simple module local_extensions.py which exists in the template root, containing the following (for instance):

from jinja2.ext import Extension


class FoobarExtension(Extension):
    def __init__(self, environment):
        super(FoobarExtension, self).__init__(environment)
        environment.filters['foobar'] = lambda v: v * 2

This will register the foobar filter for the template.

For many cases, this will be unnecessarily complicated. It’s likely that we’d only want to register a single function as a filter. For this, we can use the simple_filter decorator:

{
    "project_slug": "Foobar",
    "year": "{% now 'utc', '%Y' %}",
    "_extensions": ["local_extensions.simplefilterextension"]
}

from cookiecutter.utils import simple_filter


@simple_filter
def simplefilterextension(v):
    return v * 2

This snippet will achieve the exact same result as the previous one.

For complex use cases, a python module local_extensions (a folder with an __init__.py) can also be created in the template root. Here, for example, a module main.py would have to export all extensions with from .main import FoobarExtension, simplefilterextension or from .main import * in the __init__.py.