cookiecutter package¶
Submodules¶
cookiecutter.config module¶
cookiecutter.config¶
Global configuration handling
Retrieve the config from the specified path, returning it as a config dict.
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.environment module¶
Bases:
object
Mixin that provides a sane way of loading 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
Jinja2 environment that raises an error when it hits a variable which is not defined in the context used to render a template.
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:
exceptions.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 contructed.
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 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 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.find module¶
cookiecutter.find¶
Functions for finding Cookiecutter templates and other components.
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.
Modify the given context in place based on the overwrite_context.
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.
Ensures that dirname is a templated directory name.
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
Render the filename of infile as the name of outfile.
Deal 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.
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
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.
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.
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.
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.
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.
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
Expand abbreviations in a template name.
Parameters: - template – The project template name.
- config_dict – The user config, which will contain abbreviation definitions.
Return True if value is a repository URL.
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 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
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
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.
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¶
cookiecutter.vcs¶
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.
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.
Check if the version control system for a repo type is installed.
Parameters: repo_type –
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.