cookiecutter package¶
Submodules¶
cookiecutter.cli module¶
Main cookiecutter CLI.
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.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¶
cookiecutter.exceptions¶
All exceptions used in the Cookiecutter code base are defined here.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when get_config() is passed a path to a config file, but no file is found at that path.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when a project’s JSON context file can not be decoded.
Bases:
Exception
Base exception class. All Cookiecutter-specific exceptions should subclass this class.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when a hook script fails
Bases:
cookiecutter.exceptions.CookiecutterException
Raised if the global configuration file is not valid YAML or is badly constructed.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when cookiecutter is called with both no_input==True and replay==True at the same time.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when the specified cookiecutter repository isn’t a valid Zip archive.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised during cleanup when remove_repo() can’t find a generated project directory inside of a repo.
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.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when the output directory of the project exists already.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when a cookiecutter template can’t be cloned.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when the specified cookiecutter repository doesn’t exist.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when a template uses a variable which is not defined in the context.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised when an environment is unable to import a required extension.
Bases:
cookiecutter.exceptions.CookiecutterException
Raised if a repo’s type cannot be determined.
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.
Bases:
cookiecutter.exceptions.CookiecutterException
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.
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.
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¶
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.
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.
- default_config – Use default values rather than a config file.
- password – The password to use when extracting the repository.
Param: overwrite_if_exists: Overwrite the contents of output directory if it exists
cookiecutter.prompt module¶
cookiecutter.prompt¶
Functions for prompting the user for project info.
Prompt the user which option to choose from the given. Each of the possible choices is rendered beforehand.
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?
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.
Parameters: Returns: Exactly one item of
options
that has been chosen by the user
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 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
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
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: Returns: The rendered value for the default variable.
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.
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. Returns: True if the repo_directory is valid, else False.
cookiecutter.utils module¶
cookiecutter.utils¶
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
Makes script_path executable
Parameters: script_path – The file to change
Ensures that a directory exists.
Parameters: path – A directory path.
Ask the user whether 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
Removes a directory and all its contents. Like rm -rf on Unix.
Parameters: path – A directory path.
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.
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.
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 –