cookiecutter package¶
Subpackages¶
- cookiecutter.operators package
- Submodules
- cookiecutter.operators.aws module
- cookiecutter.operators.block module
- cookiecutter.operators.checkbox module
- cookiecutter.operators.command module
- cookiecutter.operators.confirm module
- cookiecutter.operators.dicts module
- cookiecutter.operators.editor module
- cookiecutter.operators.expand module
- cookiecutter.operators.input module
- cookiecutter.operators.jinja module
- cookiecutter.operators.json module
- cookiecutter.operators.list module
- cookiecutter.operators.listdir module
- cookiecutter.operators.nukikata module
- cookiecutter.operators.password module
- cookiecutter.operators.path module
- cookiecutter.operators.print module
- cookiecutter.operators.rawlist module
- cookiecutter.operators.return module
- cookiecutter.operators.split module
- cookiecutter.operators.stat module
- cookiecutter.operators.table module
- cookiecutter.operators.terraform module
- cookiecutter.operators.yaml module
- Module contents
Submodules¶
cookiecutter.cli module¶
Main cookiecutter CLI.
List installed (locally cloned) templates. Use cookiecutter –list-installed.
Validate extra context.
Return the Cookiecutter version, location and Python powering it.
cookiecutter.config module¶
Global configuration handling.
Retrieve the config from the specified path, returning a config dict.
Return the user config as a dict.
If
default_config
is True, ignoreconfig_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.
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.context_manager module¶
Function to handle directory context.
Context manager version of os.chdir.
When exited, returns to the working directory prior to entering.
cookiecutter.environment module¶
Jinja2 environment and extensions loading.
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.
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.
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.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for failed JSON decoding.
Raised when a project’s JSON context file can not be decoded.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for missing context file.
Raised when the specified context file doesn’t exist.
Bases:
Exception
Base exception class.
All Cookiecutter-specific exceptions should subclass this class.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for bad zip repo.
Raised when the specified cookiecutter repository isn’t a valid Zip archive.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for hook failures.
Raised when a hook script fails.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for invalid configuration file.
Raised if the global configuration file is not valid YAML or is badly constructed.
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.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for bad zip repo.
Raised when the specified cookiecutter repository isn’t a valid Zip archive.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for bad zip repo.
Raised when the specified cookiecutter repository isn’t a valid Zip archive.
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.
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.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for existing output directory.
Raised when the output directory of the project exists already.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for un-cloneable repo.
Raised when a cookiecutter template can’t be cloned.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for missing repo.
Raised when the specified cookiecutter repository doesn’t exist.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for out-of-scope variables.
Raised when a template uses a variable which is not defined in the context.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for un-importable extention.
Raised when an environment is unable to import a required extension.
Bases:
cookiecutter.exceptions.CookiecutterException
Exception for unknown repo types.
Raised if a repo’s type cannot be determined.
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.
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.
Bases:
jinja2.ext.Extension
Jinja2 extension to convert a Python object to JSON.
Bases:
jinja2.ext.Extension
Jinja2 extension to create a random string.
Bases:
jinja2.ext.Extension
Jinja2 Extension to slugify string.
cookiecutter.find module¶
Functions for finding Cookiecutter templates and other components.
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.
Modify the given context in place based on the overwrite_context.
Ensure that dirname is a templated directory name.
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
Render filename of infile as name of outfile, handle infile correctly.
Dealing with infile appropriately:
If infile is a binary file, copy it over without rendering.
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.
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.
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.
Render name of a directory, create the directory, return its path.
cookiecutter.hooks module¶
Functions for discovering and executing various cookiecutter 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
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.
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.
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.
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.
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.
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?
context_file – The file to load to set the context, ie list of prompts. Defaults to nuki.yaml, nukikata.yml, then cookiecutter.json.
context_key – The key to all the context under - defaults to the name of the context file minus the file extension.
existing_context – An additional dictionary to use in rendering additional prompts.
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 thereplay_dir
. if it existsoutput_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.
:return Dictionary of output
cookiecutter.operator module¶
Functions for discovering and executing various cookiecutter operators.
Parse input dict for loop and when logic and calls hooks.
- Returns
cookiecutter_dict
Run operator.
cookiecutter.prompt module¶
Functions for prompting the user for project info.
Parse the context and iterate over values.
- Parameters
context (dict) – Source for field names and sample values.
env – Jinja environment to render values with.
context_key – The key to insert all the outputs under in the context dict.
no_input – Prompt the user at command line for manual configuration.
existing_context – A dictionary of values to use during rendering.
- Returns
cookiecutter_dict
Load user-supplied value as a JSON dict.
- Parameters
user_value (str) – User-supplied value to load as a JSON dict
Prompt user with a set of options to choose from.
Each of the possible choices is rendered beforehand.
Prompt user to enter values.
Function sets the jinja environment and brings in extensions.
- Parameters
context (dict) – Source for field names and sample values.
no_input – Prompt the user at command line for manual configuration.
context_key – The key to insert all the outputs under in the context dict.
existing_context – A dictionary of values to use during rendering.
Prompt the user to enter a password.
- Parameters
question (str) – Question to the user
Prompt the user to choose from several options for the given variable.
The first item will be returned if no input happens.
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.
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
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.render module¶
Functions to perform rendering.
Get special variables.
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.
Write json data to file.
Get the name of file.
Read json data from file.
cookiecutter.repository module¶
Cookiecutter repository functions.
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.
Expand abbreviations in a template name.
- Parameters
template – The project template name.
abbreviations – Abbreviation definitions.
Return True if value is a repository URL.
Return True if value is a zip file.
Determine if repo_directory contains a cookiecutter.json file.
- Parameters
repo_directory – The candidate repository directory.
context_file –
- Returns
True if the repo_directory is valid, else False.
cookiecutter.utils module¶
Helper functions used throughout Cookiecutter.
Error handler for shutil.rmtree() equivalent to rm -rf.
Usage: shutil.rmtree(path, onerror=force_delete) From stackoverflow.com/questions/1889597
Make script_path executable.
- Parameters
script_path – The file to change
Ensure that a directory exists.
- Parameters
path – A directory path.
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
Read files into objects.
Remove a directory and all its contents. Like rm -rf on Unix.
- Parameters
path – A directory path.
cookiecutter.vcs module¶
Helper functions for working with version control systems.
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.
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.
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.
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.