template_extensions.rst

Template Extensions

New in Cookiecutter 1.4

A template may extend the Cookiecutter environment with custom Jinja2 extensions, that can add extra filters, tests, globals or even extend the parser.

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

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

On invocation Cookiecutter tries to import the extensions and add them to its environment respectively.

In the above example, Cookiecutter provides the additional tag now, after installing the jinja2_time.TimeExtension and enabling it in cookiecutter.json.

Please note that Cookiecutter will not install any dependencies on its own! As a user you need to make sure you have all the extensions installed, before running Cookiecutter on a template that requires custom Jinja2 extensions.

By default Cookiecutter includes the following extensions:

• cookiecutter.extensions.JsonifyExtension
• cookiecutter.extensions.RandomStringExtension
• jinja2_time.TimeExtension

Jsonify extension

The cookiecutter.extensions.JsonifyExtension extension provides a jsonify filter in templates that converts a Python object to JSON:

{% {'a': True} | jsonify %}

Would output:

{"a": true}

Random string extension

New in Cookiecutter 1.7

The cookiecutter.extensions.RandomStringExtension extension provides a random_ascii_string method in templates that generates a random fixed-length string, optionally with punctuation.

Generate a random n-size character string. Example for n=12:

{{ random_ascii_string(12) }}

Outputs:

bIIUczoNvswh

The second argument controls if punctuation and special characters !"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~ should be present in the result:

{{ random_ascii_string(12, punctuation=True) }}

Outputs:

fQupUkY}W!)!

Slugify extension

The cookiecutter.extensions.SlugifyExtension extension provides a slugify filter in templates that converts string into its underscored ("slugified") version:

{% "It's a random version" | slugify %}

Would output:

it-s-a-random-version

It is diferent from a mere replace of spaces since it also trates some special characters such as ' in the example above. The function accepts all arguments that can be passed to the slugify function of python-slugify. For example to change the output from it-s-a-random-version to it_s_a_random_version, the parameter separator='_' would be passed to slugify().