cookiecutter Package

cookiecutter Package

cookiecutter

Main package for Cookiecutter.

config Module

cookiecutter.config

Global configuration handling

cookiecutter.config.get_config(config_path)

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

cookiecutter.config.get_user_config()

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

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

Bases: exceptions.Exception

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

exception cookiecutter.exceptions.InvalidConfiguration

Bases: cookiecutter.exceptions.CookiecutterException

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

exception cookiecutter.exceptions.MissingProjectDir

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

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

Bases: cookiecutter.exceptions.CookiecutterException

Raised if a repo’s type cannot be determined.

exception cookiecutter.exceptions.UnknownTemplateDirException

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)

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)

Ensures that dirname is a templated directory name.

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

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.
• config_dict – Dict containing any config to take into account.

cookiecutter.generate.generate_file(project_dir, infile, context, env)

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

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)

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

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)

Try and find a script mapped to hook_name in the current working directory, and execute it from project_dir.

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)

API equivalent to using Cookiecutter at the command line.

Parameters:

• input_dir – A directory containing a project template dir, or a URL to git repo.
• checkout – The branch, tag or commit ID to checkout after clone

cookiecutter.main.main()

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

cookiecutter.main.parse_cookiecutter_args(args)

Parse the command-line arguments to Cookiecutter.

prompt Module

cookiecutter.prompt

Functions for prompting the user for project info.

cookiecutter.prompt.iteritems(d)

cookiecutter.prompt.prompt_for_config(context)

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

cookiecutter.prompt.query_yes_no(question, default=u'yes')

Ask a yes/no question via raw_input() 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)

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

cookiecutter.utils.make_sure_path_exists(path)

Ensures that a directory exists.

Parameters:path – A directory path.

cookiecutter.utils.rmtree(path)

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

Parameters:path – A directory path.

cookiecutter.utils.work_in(*args, **kwds)

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

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

cookiecutter.vcs.identify_repo(repo_url)

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)

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.