cookiecutter package

Submodules

cookiecutter.cli module

cookiecutter.cli

Main cookiecutter CLI.

cookiecutter.cli.version_msg()[source]

cookiecutter.config module

cookiecutter.config

Global configuration handling

cookiecutter.config.get_config(config_path)[source]

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

cookiecutter.config.get_user_config(config_file=u'/home/buildd/.cookiecutterrc')[source]

Retrieve the config from a file or return the defaults if None is passed. If an environment variable COOKIECUTTER_CONFIG is set up, try to load its value. Otherwise fall back to a default file or config.

cookiecutter.exceptions module

cookiecutter.exceptions

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

exception cookiecutter.exceptions.ConfigDoesNotExistException[source]

Bases: cookiecutter.exceptions.CookiecutterException

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

exception cookiecutter.exceptions.ContextDecodingException[source]

Bases: cookiecutter.exceptions.CookiecutterException

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

exception cookiecutter.exceptions.CookiecutterException[source]

Bases: exceptions.Exception

Base exception class. All Cookiecutter-specific exceptions should subclass this class.

exception cookiecutter.exceptions.FailedHookException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when a hook script fails

exception cookiecutter.exceptions.InvalidConfiguration[source]

Bases: cookiecutter.exceptions.CookiecutterException

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

exception cookiecutter.exceptions.InvalidModeException[source]

Bases: cookiecutter.exceptions.CookiecutterException

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

exception cookiecutter.exceptions.MissingProjectDir[source]

Bases: cookiecutter.exceptions.CookiecutterException

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

exception cookiecutter.exceptions.NonTemplatedInputDirException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised 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[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when the output directory of the project exists already.

exception cookiecutter.exceptions.UnknownRepoType[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised if a repo’s type cannot be determined.

exception cookiecutter.exceptions.UnknownTemplateDirException[source]

Bases: cookiecutter.exceptions.CookiecutterException

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[source]

Bases: cookiecutter.exceptions.CookiecutterException

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

cookiecutter.find module

cookiecutter.find

Functions for finding Cookiecutter templates and other components.

cookiecutter.find.find_template(repo_dir)[source]

Determines 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

cookiecutter.generate

Functions for generating a project from a project template.

cookiecutter.generate.apply_overwrites_to_context(context, overwrite_context)[source]

Modify the given context in place based on the overwrite_context.

cookiecutter.generate.copy_without_render(path, context)[source]

Returns True if path matches some pattern in the _copy_without_render context setting.

Parameters:
  • path – A file-system path referring to a file or dir that should be rendered or just copied.
  • context – cookiecutter context.
cookiecutter.generate.ensure_dir_is_templated(dirname)[source]

Ensures that dirname is a templated directory name.

cookiecutter.generate.generate_context(context_file=u'cookiecutter.json', default_context=None, extra_context=None)[source]

Generates 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)[source]

  1. Render the filename of infile as the name of outfile.

  2. Deal 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=u'.', overwrite_if_exists=False)[source]

Renders 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
cookiecutter.generate.render_and_create_dir(dirname, context, output_dir, overwrite_if_exists=False)[source]

Renders the name of a directory, creates the directory, and returns its path.

cookiecutter.hooks module

cookiecutter.hooks

Functions for discovering and executing various cookiecutter hooks.

cookiecutter.hooks.find_hooks()[source]

Must be called with the project template as the current working directory. Returns a dict of all hook scripts provided. 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.

cookiecutter.hooks.run_hook(hook_name, project_dir, context)[source]

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='.')[source]

Executes 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)[source]

Executes a script after rendering with it 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.main module

cookiecutter.main

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=False, overwrite_if_exists=False, output_dir=u'.', config_file=u'/home/buildd/.cookiecutterrc')[source]

API equivalent to using Cookiecutter at 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.
  • output_dir – Where to output the generated project dir into.
  • config_file – User configuration file path.
Param:

overwrite_if_exists: Overwrite the contents of output directory if it exists
cookiecutter.main.expand_abbreviations(template, config_dict)[source]

Expand abbreviations in a template name.

Parameters:
  • template – The project template name.
  • config_dict – The user config, which will contain abbreviation definitions.
cookiecutter.main.is_repo_url(value)[source]

Return True if value is a repository URL.

cookiecutter.prompt module

cookiecutter.prompt

Functions for prompting the user for project info.

cookiecutter.prompt.prompt_choice_for_config(cookiecutter_dict, env, key, options, no_input)[source]

Prompt the user which option to choose from the given. Each of the possible choices is rendered beforehand.

cookiecutter.prompt.prompt_for_config(context, no_input=False)[source]

Prompts the user to enter new config, using context as a source for the field names and sample values.

Parameters:no_input – Prompt the user at command line for manual configuration?
cookiecutter.prompt.read_user_choice(var_name, options)[source]

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_variable(var_name, default_value)[source]

Prompt the user for the given variable and return the entered value or the 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)[source]

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)[source]

cookiecutter.replay module

cookiecutter.replay

cookiecutter.replay.dump(template_name, context)[source]
cookiecutter.replay.get_file_name(replay_dir, template_name)[source]
cookiecutter.replay.load(template_name)[source]

cookiecutter.utils module

cookiecutter.utils

Helper functions used throughout Cookiecutter.

cookiecutter.utils.force_delete(func, path, exc_info)[source]

Error handler for shutil.rmtree() equivalent to rm -rf Usage: shutil.rmtree(path, onerror=force_delete) From stackoverflow.com/questions/1889597

cookiecutter.utils.make_executable(script_path)[source]

Makes script_path executable

Parameters:script_path – The file to change
cookiecutter.utils.make_sure_path_exists(path)[source]

Ensures that a directory exists.

Parameters:path – A directory path.
cookiecutter.utils.rmtree(path)[source]

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

Parameters:path – A directory path.
cookiecutter.utils.work_in(*args, **kwds)[source]

Context manager version of os.chdir. When exited, returns to the working directory prior to entering.

cookiecutter.vcs module

cookiecutter.vcs

Helper functions for working with version control systems.

cookiecutter.vcs.clone(repo_url, checkout=None, clone_to_dir=u'.', no_input=False)[source]

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.
cookiecutter.vcs.identify_repo(repo_url)[source]

Determines if repo_url should be treated as a URL to a git or hg repo. Repos can be identified prepeding “hg+” or “git+” to 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)[source]

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

Parameters:repo_type –
cookiecutter.vcs.prompt_and_delete_repo(repo_dir, no_input=False)[source]

Asks the user whether it’s okay to delete the previously-cloned repo. If yes, deletes it. Otherwise, Cookiecutter exits.

Parameters:
  • repo_dir – Directory of previously-cloned repo.
  • no_input – Suppress prompt to delete repo and just delete it.

Module contents

cookiecutter

Main package for Cookiecutter.