API

This is the Cookiecutter modules API documentation.

cookiecutter.cli module

Main cookiecutter CLI.

cookiecutter.cli.list_installed_templates(default_config, passed_config_file)

List installed (locally cloned) templates. Use cookiecutter –list-installed.

cookiecutter.cli.validate_extra_context(ctx, param, value)

Validate extra context.

cookiecutter.cli.version_msg()

Return the Cookiecutter version, location and Python powering it.

cookiecutter.config module

Global configuration handling.

cookiecutter.config.get_config(config_path)

Retrieve the config from the specified path, returning a config dict.

cookiecutter.config.get_user_config(config_file=None, default_config=False)

Return the user config as a dict.

If default_config is True, ignore config_file and return default values for the config parameters.

If default_config is a dict, merge values with default values and return them for the config parameters.

If a path to a config_file is given, that is different from the default location, load the user config from that.

Otherwise look up the config file path in the COOKIECUTTER_CONFIG environment variable. If set, load the config from this path. This will raise an error if the specified path is not valid.

If the environment variable is not set, try the default config file path before falling back to the default config values.

cookiecutter.config.merge_configs(default, overwrite)

Recursively update a dict with the key/value pair of another.

Dict values that are dictionaries themselves will be updated, whilst preserving existing keys.

cookiecutter.environment module

Jinja2 environment and extensions loading.

class cookiecutter.environment.ExtensionLoaderMixin(**kwargs)

Bases: object

Mixin providing sane loading of extensions specified in a given context.

The context is being extracted from the keyword arguments before calling the next parent class in line of the child.

class cookiecutter.environment.StrictEnvironment(**kwargs)

Bases: ExtensionLoaderMixin, Environment

Create strict Jinja2 environment.

Jinja2 environment will raise error on undefined variable in template- rendering context.

cookiecutter.exceptions module

All exceptions used in the Cookiecutter code base are defined here.

exception cookiecutter.exceptions.ConfigDoesNotExistException

Bases: CookiecutterException

Exception for missing config file.

Raised when get_config() is passed a path to a config file, but no file is found at that path.

exception cookiecutter.exceptions.ContextDecodingException

Bases: CookiecutterException

Exception for failed JSON decoding.

Raised when a project’s JSON context file can not be decoded.

exception cookiecutter.exceptions.CookiecutterException

Bases: Exception

Base exception class.

All Cookiecutter-specific exceptions should subclass this class.

exception cookiecutter.exceptions.FailedHookException

Bases: CookiecutterException

Exception for hook failures.

Raised when a hook script fails.

exception cookiecutter.exceptions.InvalidConfiguration

Bases: CookiecutterException

Exception for invalid configuration file.

Raised if the global configuration file is not valid YAML or is badly constructed.

exception cookiecutter.exceptions.InvalidModeException

Bases: CookiecutterException

Exception for incompatible modes.

Raised when cookiecutter is called with both no_input==True and replay==True at the same time.

exception cookiecutter.exceptions.InvalidZipRepository

Bases: CookiecutterException

Exception for bad zip repo.

Raised when the specified cookiecutter repository isn’t a valid Zip archive.

exception cookiecutter.exceptions.MissingProjectDir

Bases: CookiecutterException

Exception for missing generated project directory.

Raised during cleanup when remove_repo() can’t find a generated project directory inside of a repo.

exception cookiecutter.exceptions.NonTemplatedInputDirException

Bases: CookiecutterException

Exception for when a project’s input dir is not templated.

The name of the input directory should always contain a string that is rendered to something else, so that input_dir != output_dir.

exception cookiecutter.exceptions.OutputDirExistsException

Bases: CookiecutterException

Exception for existing output directory.

Raised when the output directory of the project exists already.

exception cookiecutter.exceptions.RepositoryCloneFailed

Bases: CookiecutterException

Exception for un-cloneable repo.

Raised when a cookiecutter template can’t be cloned.

exception cookiecutter.exceptions.RepositoryNotFound

Bases: CookiecutterException

Exception for missing repo.

Raised when the specified cookiecutter repository doesn’t exist.

exception cookiecutter.exceptions.UndefinedVariableInTemplate(message, error, context)

Bases: CookiecutterException

Exception for out-of-scope variables.

Raised when a template uses a variable which is not defined in the context.

exception cookiecutter.exceptions.UnknownExtension

Bases: CookiecutterException

Exception for un-importable extension.

Raised when an environment is unable to import a required extension.

exception cookiecutter.exceptions.UnknownRepoType

Bases: CookiecutterException

Exception for unknown repo types.

Raised if a repo’s type cannot be determined.

exception cookiecutter.exceptions.UnknownTemplateDirException

Bases: CookiecutterException

Exception for ambiguous project template directory.

Raised when Cookiecutter cannot determine which directory is the project template, e.g. more than one dir appears to be a template dir.

exception cookiecutter.exceptions.VCSNotInstalled

Bases: CookiecutterException

Exception when version control is unavailable.

Raised if the version control system (git or hg) is not installed.

cookiecutter.extensions module

Jinja2 extensions.

class cookiecutter.extensions.JsonifyExtension(environment)

Bases: Extension

Jinja2 extension to convert a Python object to JSON.

identifier = 'cookiecutter.extensions.JsonifyExtension'

class cookiecutter.extensions.RandomStringExtension(environment)

Bases: Extension

Jinja2 extension to create a random string.

identifier = 'cookiecutter.extensions.RandomStringExtension'

class cookiecutter.extensions.SlugifyExtension(environment)

Bases: Extension

Jinja2 Extension to slugify string.

identifier = 'cookiecutter.extensions.SlugifyExtension'

class cookiecutter.extensions.TimeExtension(environment)

Bases: Extension

Jinja2 Extension for dates and times.

parse(parser)

Parse datetime template and add datetime value.

identifier = 'cookiecutter.extensions.TimeExtension'

tags = {'now'}

if this extension parses this is the list of tags it’s listening to.

class cookiecutter.extensions.UUIDExtension(environment)

Bases: Extension

Jinja2 Extension to generate uuid4 string.

identifier = 'cookiecutter.extensions.UUIDExtension'

cookiecutter.find module

Functions for finding Cookiecutter templates and other components.

cookiecutter.find.find_template(repo_dir, env)

Determine which child directory of repo_dir is the project template.

Parameters:

repo_dir (PathLike[str]) – Local directory of newly cloned repo.

Return type:

Path

Returns:

Relative path to project template.

cookiecutter.generate module

Functions for generating a project from a project template.

cookiecutter.generate.apply_overwrites_to_context(context, overwrite_context, *, in_dictionary_variable=False)

Modify the given context in place based on the overwrite_context.

cookiecutter.generate.generate_context(context_file='cookiecutter.json', default_context=None, extra_context=None)

Generate the context for a Cookiecutter project template.

Loads the JSON file as a Python object, with key being the JSON filename.

Parameters:

• context_file – JSON file containing key/value pairs for populating the cookiecutter’s variables.

• default_context – Dictionary containing config to take into account.

• extra_context – Dictionary containing configuration overrides

cookiecutter.generate.generate_file(project_dir, infile, context, env, skip_if_file_exists=False)

Render filename of infile as name of outfile, handle infile correctly.

Dealing with infile appropriately:

1. If infile is a binary file, copy it over without rendering.

2. If infile is a text file, render its contents and write the rendered infile to outfile.

Precondition:

When calling generate_file(), the root template dir must be the current working directory. Using utils.work_in() is the recommended way to perform this directory change.

Parameters:

• project_dir – Absolute path to the resulting generated project.

• infile – Input file to generate the file from. Relative to the root template dir.

• context – Dict for populating the cookiecutter’s variables.

• env – Jinja2 template execution environment.

cookiecutter.generate.generate_files(repo_dir, context=None, output_dir='.', overwrite_if_exists=False, skip_if_file_exists=False, accept_hooks=True, keep_project_on_failure=False)

Render the templates and saves them to files.

Parameters:

• repo_dir – Project template input directory.

• context – Dict for populating the template’s variables.

• output_dir – Where to output the generated project dir into.

• overwrite_if_exists – Overwrite the contents of the output directory if it exists.

• skip_if_file_exists – Skip the files in the corresponding directories if they already exist

• accept_hooks – Accept pre and post hooks if set to True.

• keep_project_on_failure – If True keep generated project directory even when generation fails

cookiecutter.generate.is_copy_only_path(path, context)

Check whether the given path should only be copied and not rendered.

Returns True if path matches a pattern in the given context dict, otherwise False.

Parameters:

• path – A file-system path referring to a file or dir that should be rendered or just copied.

• context – cookiecutter context.

cookiecutter.generate.render_and_create_dir(dirname, context, output_dir, environment, overwrite_if_exists=False)

Render name of a directory, create the directory, return its path.

cookiecutter.hooks module

Functions for discovering and executing various cookiecutter hooks.

cookiecutter.hooks.find_hook(hook_name, hooks_dir='hooks')

Return a dict of all hook scripts provided.

Must be called with the project template as the current working directory. Dict’s key will be the hook/script’s name, without extension, while values will be the absolute path to the script. Missing scripts will not be included in the returned dict.

Parameters:

• hook_name – The hook to find

• hooks_dir – The hook directory in the template

Returns:

The absolute path to the hook script or None

cookiecutter.hooks.run_hook(hook_name, project_dir, context)

Try to find and execute a hook from the specified project directory.

Parameters:

• hook_name – The hook to execute.

• project_dir – The directory to execute the script from.

• context – Cookiecutter project context.

cookiecutter.hooks.run_hook_from_repo_dir(repo_dir, hook_name, project_dir, context, delete_project_on_failure)

Run hook from repo directory, clean project directory if hook fails.

Parameters:

• repo_dir – Project template input directory.

• hook_name – The hook to execute.

• project_dir – The directory to execute the script from.

• context – Cookiecutter project context.

• delete_project_on_failure – Delete the project directory on hook failure?

cookiecutter.hooks.run_pre_prompt_hook(repo_dir)

Run pre_prompt hook from repo directory.

Parameters:

repo_dir (PathLike[str]) – Project template input directory.

Return type:

Path

cookiecutter.hooks.run_script(script_path, cwd='.')

Execute a script from a working directory.

Parameters:

• script_path – Absolute path to the script to run.

• cwd – The directory to run the script from.

cookiecutter.hooks.run_script_with_context(script_path, cwd, context)

Execute a script after rendering it with Jinja.

Parameters:

• script_path – Absolute path to the script to run.

• cwd – The directory to run the script from.

• context – Cookiecutter project template context.

cookiecutter.hooks.valid_hook(hook_file, hook_name)

Determine if a hook file is valid.

Parameters:

• hook_file – The hook file to consider for validity

• hook_name – The hook to find

Returns:

The hook file validity

cookiecutter.log module

Module for setting up logging.

cookiecutter.log.configure_logger(stream_level='DEBUG', debug_file=None)

Configure logging for cookiecutter.

Set up logging to stdout with given level. If debug_file is given set up logging to file with DEBUG level.

cookiecutter.main module

Main entry point for the cookiecutter command.

The code in this module is also a good example of how to use Cookiecutter as a library rather than a script.

cookiecutter.main.cookiecutter(template, checkout=None, no_input=False, extra_context=None, replay=None, overwrite_if_exists=False, output_dir='.', config_file=None, default_config=False, password=None, directory=None, skip_if_file_exists=False, accept_hooks=True, keep_project_on_failure=False)

Run Cookiecutter just as if using it from the command line.

Parameters:

• template – A directory containing a project template directory, or a URL to a git repository.

• checkout – The branch, tag or commit ID to checkout after clone.

• no_input – Do not prompt for user input. Use default values for template parameters taken from cookiecutter.json, user config and extra_dict. Force a refresh of cached resources.

• extra_context – A dictionary of context that overrides default and user configuration.

• replay – Do not prompt for input, instead read from saved json. If True read from the replay_dir. if it exists

• overwrite_if_exists – Overwrite the contents of the output directory if it exists.

• output_dir – Where to output the generated project dir into.

• config_file – User configuration file path.

• default_config – Use default values rather than a config file.

• password – The password to use when extracting the repository.

• directory – Relative path to a cookiecutter template in a repository.

• skip_if_file_exists – Skip the files in the corresponding directories if they already exist.

• accept_hooks – Accept pre and post hooks if set to True.

• keep_project_on_failure – If True keep generated project directory even when generation fails

cookiecutter.prompt module

Functions for prompting the user for project info.

class cookiecutter.prompt.JsonPrompt(prompt='', *, console=None, password=False, choices=None, show_default=True, show_choices=True)

Bases: PromptBase[dict]

A prompt that returns a dict from JSON string.

response_type

alias of dict

process_response(value)

Convert choices to a dict.

Return type:

dict

default = None

validate_error_message = '[prompt.invalid]  Please enter a valid JSON string'

class cookiecutter.prompt.YesNoPrompt(prompt='', *, console=None, password=False, choices=None, show_default=True, show_choices=True)

Bases: Confirm

A prompt that returns a boolean for yes/no questions.

process_response(value)

Convert choices to a bool.

Return type:

bool

no_choices = ['0', 'false', 'f', 'no', 'n', 'off']

yes_choices = ['1', 'true', 't', 'yes', 'y', 'on']

cookiecutter.prompt.choose_nested_template(context, repo_dir, no_input=False)

Prompt user to select the nested template to use.

Parameters:

• context (dict) – Source for field names and sample values.

• repo_dir (str) – Repository directory.

• no_input (bool) – Do not prompt for user input and use only values from context.

Return type:

str

Returns:

Path to the selected template.

cookiecutter.prompt.process_json(user_value, default_value=None)

Load user-supplied value as a JSON dict.

Parameters:

user_value (str) – User-supplied value to load as a JSON dict

cookiecutter.prompt.prompt_and_delete(path, no_input=False)

Ask user if it’s okay to delete the previously-downloaded file/directory.

If yes, delete it. If no, checks to see if the old version should be reused. If yes, it’s reused; otherwise, Cookiecutter exits.

Parameters:

• path – Previously downloaded zipfile.

• no_input – Suppress prompt to delete repo and just delete it.

Returns:

True if the content was deleted

cookiecutter.prompt.prompt_choice_for_config(cookiecutter_dict, env, key, options, no_input, prompts=None, prefix='')

Prompt user with a set of options to choose from.

Parameters:

no_input – Do not prompt for user input and return the first available option.

cookiecutter.prompt.prompt_choice_for_template(key, options, no_input)

Prompt user with a set of options to choose from.

Parameters:

no_input – Do not prompt for user input and return the first available option.

cookiecutter.prompt.prompt_for_config(context, no_input=False)

Prompt user to enter a new config.

Parameters:

• context (dict) – Source for field names and sample values.

• no_input – Do not prompt for user input and use only values from context.

cookiecutter.prompt.read_repo_password(question)

Prompt the user to enter a password.

Parameters:

question (str) – Question to the user

cookiecutter.prompt.read_user_choice(var_name, options, prompts=None, prefix='')

Prompt the user to choose from several options for the given variable.

The first item will be returned if no input happens.

Parameters:

• var_name (str) – Variable as specified in the context

• options (list) – Sequence of options that are available to select from

Returns:

Exactly one item of options that has been chosen by the user

cookiecutter.prompt.read_user_dict(var_name, default_value, prompts=None, prefix='')

Prompt the user to provide a dictionary of data.

Parameters:

• var_name (str) – Variable as specified in the context

• default_value – Value that will be returned if no input is provided

Returns:

A Python dictionary to use in the context.

cookiecutter.prompt.read_user_variable(var_name, default_value, prompts=None, prefix='')

Prompt user for variable and return the entered value or given default.

Parameters:

• var_name (str) – Variable of the context to query the user

• default_value – Value that will be returned if no input happens

cookiecutter.prompt.read_user_yes_no(var_name, default_value, prompts=None, prefix='')

Prompt the user to reply with ‘yes’ or ‘no’ (or equivalent values).

• These input values will be converted to True: “1”, “true”, “t”, “yes”, “y”, “on”

• These input values will be converted to False: “0”, “false”, “f”, “no”, “n”, “off”

Actual parsing done by prompt(); Check this function codebase change in case of unexpected behaviour.

Parameters:

• question (str) – Question to the user

• default_value – Value that will be returned if no input happens

cookiecutter.prompt.render_variable(env, raw, cookiecutter_dict)

Render the next variable to be displayed in the user prompt.

Inside the prompting taken from the cookiecutter.json file, this renders the next variable. For example, if a project_name is “Peanut Butter Cookie”, the repo_name could be be rendered with:

{{ cookiecutter.project_name.replace(” “, “_”) }}.

This is then presented to the user as the default.

Parameters:

• env (Environment) – A Jinja2 Environment object.

• raw – The next value to be prompted for by the user.

• cookiecutter_dict (dict) – The current context as it’s gradually being populated with variables.

Returns:

The rendered value for the default variable.

cookiecutter.replay module

cookiecutter.replay.

---

cookiecutter.replay.dump(replay_dir, template_name, context)

Write json data to file.

cookiecutter.replay.get_file_name(replay_dir, template_name)

Get the name of file.

cookiecutter.replay.load(replay_dir, template_name)

Read json data from file.

cookiecutter.repository module

Cookiecutter repository functions.

cookiecutter.repository.determine_repo_dir(template, abbreviations, clone_to_dir, checkout, no_input, password=None, directory=None)

Locate the repository directory from a template reference.

Applies repository abbreviations to the template reference. If the template refers to a repository URL, clone it. If the template is a path to a local repository, use it.

Parameters:

• template – A directory containing a project template directory, or a URL to a git repository.

• abbreviations – A dictionary of repository abbreviation definitions.

• clone_to_dir – The directory to clone the repository into.

• checkout – The branch, tag or commit ID to checkout after clone.

• no_input – Do not prompt for user input and eventually force a refresh of cached resources.

• password – The password to use when extracting the repository.

• directory – Directory within repo where cookiecutter.json lives.

Returns:

A tuple containing the cookiecutter template directory, and a boolean describing whether that directory should be cleaned up after the template has been instantiated.

Raises:

RepositoryNotFound if a repository directory could not be found.

cookiecutter.repository.expand_abbreviations(template, abbreviations)

Expand abbreviations in a template name.

Parameters:

• template – The project template name.

• abbreviations – Abbreviation definitions.

cookiecutter.repository.is_repo_url(value)

Return True if value is a repository URL.

cookiecutter.repository.is_zip_file(value)

Return True if value is a zip file.

cookiecutter.repository.repository_has_cookiecutter_json(repo_directory)

Determine if repo_directory contains a cookiecutter.json file.

Parameters:

repo_directory – The candidate repository directory.

Returns:

True if the repo_directory is valid, else False.

cookiecutter.utils module

Helper functions used throughout Cookiecutter.

cookiecutter.utils.create_env_with_context(context)

Create a jinja environment using the provided context.

cookiecutter.utils.create_tmp_repo_dir(repo_dir)

Create a temporary dir with a copy of the contents of repo_dir.

Return type:

Path

cookiecutter.utils.force_delete(func, path, exc_info)

Error handler for shutil.rmtree() equivalent to rm -rf.

Usage: shutil.rmtree(path, onerror=force_delete) From https://docs.python.org/3/library/shutil.html#rmtree-example

cookiecutter.utils.make_executable(script_path)

Make script_path executable.

Parameters:

script_path – The file to change

cookiecutter.utils.make_sure_path_exists(path)

Ensure that a directory exists.

Parameters:

path (PathLike[str]) – A directory tree path for creation.

Return type:

None

cookiecutter.utils.rmtree(path)

Remove a directory and all its contents. Like rm -rf on Unix.

Parameters:

path – A directory path.

cookiecutter.utils.simple_filter(filter_function)

Decorate a function to wrap it in a simplified jinja2 extension.

cookiecutter.utils.work_in(dirname=None)

Context manager version of os.chdir.

When exited, returns to the working directory prior to entering.

cookiecutter.vcs module

Helper functions for working with version control systems.

cookiecutter.vcs.clone(repo_url, checkout=None, clone_to_dir='.', no_input=False)

Clone a repo to the current directory.

Parameters:

• repo_url (str) – Repo URL of unknown type.

• checkout (Optional[str]) – The branch, tag or commit ID to checkout after clone.

• clone_to_dir (PathLike[str]) – The directory to clone to. Defaults to the current directory.

• no_input (bool) – Do not prompt for user input and eventually force a refresh of cached resources.

Returns:

str with path to the new directory of the repository.

cookiecutter.vcs.identify_repo(repo_url)

Determine if repo_url should be treated as a URL to a git or hg repo.

Repos can be identified by prepending “hg+” or “git+” to the repo URL.

Parameters:

repo_url – Repo URL of unknown type.

Returns:

(‘git’, repo_url), (‘hg’, repo_url), or None.

cookiecutter.vcs.is_vcs_installed(repo_type)

Check if the version control system for a repo type is installed.

Parameters:

repo_type –

cookiecutter.zipfile module

Utility functions for handling and fetching repo archives in zip format.

cookiecutter.zipfile.unzip(zip_uri, is_url, clone_to_dir='.', no_input=False, password=None)

Download and unpack a zipfile at a given URI.

This will download the zipfile to the cookiecutter repository, and unpack into a temporary directory.

Parameters:

• zip_uri (str) – The URI for the zipfile.

• is_url (bool) – Is the zip URI a URL or a file?

• clone_to_dir (PathLike[str]) – The cookiecutter repository directory to put the archive into.

• no_input (bool) – Do not prompt for user input and eventually force a refresh of cached resources.

• password (Optional[str]) – The password to use when unpacking the repository.

Module contents

Main package for Cookiecutter.