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
  • cookiecutter.extensions.SlugifyExtension
  • 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().