cookiecutter Package

cookiecutter Package

cookiecutter

Main package for 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()[source]

Retrieve config from the user’s ~/.cookiecutterrc, if it exists. Otherwise, return None.

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

Bases: exceptions.Exception

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

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

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.

generate Module

cookiecutter.generate

Functions for generating a project from a project template.

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

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

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.

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(input_dir, checkout=None, no_input=False, extra_context=None)[source]

API equivalent to using Cookiecutter at the command line.

Parameters:
  • input_dir – A directory containing a project template dir, 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.
cookiecutter.main.expand_abbreviations(input_dir, config_dict)[source]

Expand abbreviations in a template name.

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

Entry point for the package, as defined in setup.py.

cookiecutter.main.parse_cookiecutter_args(args)[source]

Parse the command-line arguments to Cookiecutter.

prompt Module

cookiecutter.prompt

Functions for prompting the user for project info.

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.query_yes_no(question, default=u'yes')[source]

Ask a yes/no question via read_response() and return their answer.

Parameters:
  • question – A string that is presented to the user.
  • default – The presumed answer if the user just hits <Enter>. It must be “yes” (the default), “no” or None (meaning an answer is required of the user).

The “answer” return value is one of “yes” or “no”.

Adapted from http://stackoverflow.com/questions/3041986/python-command-line-yes-no-input http://code.activestate.com/recipes/577058/

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.

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.

Parameters:repo_url – Repo URL of unknown type.
Returns:“git”, “hg”, or None.
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.