Advanced usage

Hooks

You can write pre- or post-generate hooks. The Jinja template variables will be integrated into the scripts, for example:

if "Not open source" == "{{ cookiecutter.license }}":
    remove_file("LICENSE")

Variables, for example, can be validated in a pre-generate hook:

import re
import sys


MODULE_REGEX = r"^[_a-zA-Z][_a-zA-Z0-9]+$"

module_name = "{{ cookiecutter.module_name }}"

if not re.match(MODULE_REGEX, module_name):
    print(f"ERROR: {module_name} is not a valid Python module name!")

    # exits with status 1 to indicate failure
    sys.exit(1)

User config

If you use CookieCutter frequently, we recommend your own user config ~/cookiecutterrc, e.g.:

default_context:
    full_name: "Veit Schiele"
    email: "veit@cusy.io"
    github_username: "veit"
cookiecutters_dir: "~/.cookiecutters/"
replay_dir: "~/.cookiecutter_replay/"

Replay

When calling cookiecutter a json file is created in /.cookiecutter_replay/, for example ~/.cookiecutter_replay/cookiecutter-namespace-template.json:

{"cookiecutter": {"full_name": "Veit Schiele", "email": "veit@cusy.io", "github_username": "veit", "project_name": "vsc.example", "project_slug": "vsc.example", "namespace": "vsc", "package_name": "example", "project_short_description": "Python Namespace Package contains all you need to create a Python namespace package.", "pypi_username": "veit", "use_pytest": "y", "command_line_interface": "Click", "version": "0.1.0", "create_author_file": "y", "license": "MIT license", "_template": "https://github.com/veit/cookiecutter-namespace-template"}}

If you want to use this information without having to confirm them again in the command line, you can simply enter the following:

$ cookiecutter --replay gh:veit/cookiecutter-namespace-template

Alternatively, the Python API can also be used:

from cookiecutter.main import cookiecutter

cookiecutter("gh:veit/cookiecutter-namespace-template", replay=True)

This function is helpful if you want to create a project from an updated template, for example.

Selection variables

Selection variables offer various options when creating a project. Depending on the user’s choice, the template renders it differently, e.g. if in the cookiecutter.json file the following selection is offered:

{
  "license": ["MIT license", "BSD license", "ISC license", "Apache Software License 2.0", "GNU General Public License v3", "Other/Proprietary License"]
}

This is interpreted in cookiecutter-namespace-template/{{cookiecutter.project_name}}/README.rst

{% set is_open_source = cookiecutter.license != 'Not open source' -%}
{% if is_open_source %}
    …
{%- endif %}

{% if is_open_source %}
    …
{% endif %}

and in cookiecutter-namespace-template/hooks/post_gen_project.py:

if "Not open source" == "{{ cookiecutter.license }}":
    remove_file("LICENSE")