API

Submodules

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 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: cookiecutter.environment.ExtensionLoaderMixin, jinja2.environment.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: cookiecutter.exceptions.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: cookiecutter.exceptions.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: cookiecutter.exceptions.CookiecutterException

Exception for hook failures.

Raised when a hook script fails.

exception cookiecutter.exceptions.InvalidConfiguration

Bases: cookiecutter.exceptions.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: cookiecutter.exceptions.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: cookiecutter.exceptions.CookiecutterException

Exception for bad zip repo.

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

exception cookiecutter.exceptions.MissingProjectDir

Bases: cookiecutter.exceptions.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: cookiecutter.exceptions.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: cookiecutter.exceptions.CookiecutterException

Exception for existing output directory.

Raised when the output directory of the project exists already.

exception cookiecutter.exceptions.RepositoryCloneFailed

Bases: cookiecutter.exceptions.CookiecutterException

Exception for un-cloneable repo.

Raised when a cookiecutter template can’t be cloned.

exception cookiecutter.exceptions.RepositoryNotFound

Bases: cookiecutter.exceptions.CookiecutterException

Exception for missing repo.

Raised when the specified cookiecutter repository doesn’t exist.

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

Bases: cookiecutter.exceptions.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: cookiecutter.exceptions.CookiecutterException

Exception for un-importable extention.

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

exception cookiecutter.exceptions.UnknownRepoType

Bases: cookiecutter.exceptions.CookiecutterException

Exception for unknown repo types.

Raised if a repo’s type cannot be determined.

exception cookiecutter.exceptions.UnknownTemplateDirException

Bases: cookiecutter.exceptions.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: cookiecutter.exceptions.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: jinja2.ext.Extension

Jinja2 extension to convert a Python object to JSON.

identifier: ClassVar[str] = 'cookiecutter.extensions.JsonifyExtension'

class cookiecutter.extensions.RandomStringExtension(environment)

Bases: jinja2.ext.Extension

Jinja2 extension to create a random string.

identifier: ClassVar[str] = 'cookiecutter.extensions.RandomStringExtension'

class cookiecutter.extensions.SlugifyExtension(environment)

Bases: jinja2.ext.Extension

Jinja2 Extension to slugify string.

identifier: ClassVar[str] = 'cookiecutter.extensions.SlugifyExtension'

class cookiecutter.extensions.UUIDExtension(environment)

Bases: jinja2.ext.Extension

Jinja2 Extension to generate uuid4 string.

identifier: ClassVar[str] = 'cookiecutter.extensions.UUIDExtension'

cookiecutter.find module

Functions for finding Cookiecutter templates and other components.

cookiecutter.find.find_template(repo_dir)

Determine which child directory of repo_dir is the project template.

Parameters

repo_dir – Local directory of newly cloned repo.

Returns project_template

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)

Modify the given context in place based on the overwrite_context.

cookiecutter.generate.ensure_dir_is_templated(dirname)

Ensure that dirname is a templated directory name.

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)

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.

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

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_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)

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 – Prompt the user at command line for manual configuration?

• 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

• 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.

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

cookiecutter.prompt module

Functions for prompting the user for project info.

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_choice_for_config(cookiecutter_dict, env, key, options, no_input)

Prompt user with a set of options to choose from.

Each of the possible choices is rendered beforehand.

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 – Prompt the user at command line for manual configuration?

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)

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)

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)

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(question, default_value)

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

Note:

Possible choices are ‘true’, ‘1’, ‘yes’, ‘y’ or ‘false’, ‘0’, ‘no’, ‘n’

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 – Prompt the user at command line for manual configuration?

• 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 descriving 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.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 – A directory path.

cookiecutter.utils.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.utils.rmtree(path)

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

Parameters

path – A directory path.

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 – Repo URL of unknown type.

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

• clone_to_dir – The directory to clone to. Defaults to the current directory.

• no_input – Suppress all user prompts when calling via API.

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 – The URI for the zipfile.

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

• clone_to_dir – The cookiecutter repository directory to put the archive into.

• no_input – Suppress any prompts

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

Module contents

Main package for Cookiecutter.