Guide: Rendering CookieCutter templates#
Fabricius ships with the ability to process CookieCutter templates (Or so called, cookiecutters by themselves). This mean that all of the work you’ve already done using CookieCutter is 100% supported in Fabricius! (yes! hooks work too!)
Using the CLI#
TBD
Using the API#
You can also use Fabricius’s API to generate your CookieCutter template.
from fabricius.readers.cookiecutter.setup import setup, run
def main():
template_path = "path/to/template"
output_path = "path/to/output"
template = setup(template_path, output_path)
# This method has been specially created for CookieCutter's solution.
# See below for explanations.
run(template)
API#
The following functions are available as part of the little API you can use to generate fabricius.models.template.Template
objects from a CookieCutter repo.
The setup
function will:
Get the template path
Create the Template object and add the extensions, if the project templates specify any others, add them too.
Add
_template
,_repo_dir
and_output_dir
to the contextObtain the questions in the project template and begin to ask to the users those questions.
Once all answered, add the extra context the user’s default context, then add the answers to the final context.
Obtain all the files that must be rendered/copied, and add them to the Template object, and push the data to the Template object.
Connect the hooks to the
before_template_commit
andafter_template_commit
signals, then return the Template object.
While you can just simply do Template.commit()
, there is a few things to considerate first since you’re rendering a CookieCutter project, and not a Fabricius one.
Thus, we have made the run
function to handle a few edge cases that could happens with CookieCutter.
The run
function will:
First attempt to commit the project
If fail, due to a file that already exist, ask the user if overwriting files should be used.
If fail, due to a hook failing, see if the exception gives an exit code, if it does, exit using the exit code, if not, print the exception and exit.
Return the list of file commit result.
- fabricius.readers.cookiecutter.setup.setup(base_folder: str | os.PathLike[str] | pathlib.Path, output_folder: str | os.PathLike[str] | pathlib.Path, *, extra_context: dict[str, Any] | None = None, no_prompt: bool = False) → Template[type[fabricius.renderers.jinja_renderer.JinjaRenderer]]
Setup a template that will be able to be ran once created.
- Parameters:
base_folder (
PathStrOrPath
) – The folder where the template is located. (Choose the folder where thecookiecutter.json
is located, not the template itself)output_folder (
PathStrOrPath
) – The folder where the template/files will be created once rendered.extra_context (
Data
, optional) – Any extra context to pass to the template. It will override the user’s prompt.no_prompt (bool, optional) – If set to True, no questions will be asked to the user. By default False
- Returns:
The Template that has been generated. It is ready to be committed, and everything has been setup.
- Return type:
- Raises:
fabricius.exceptions.TemplateError – Exception raised when there’s an issue with the template that is most probably due to the template’s misconception.
- fabricius.readers.cookiecutter.setup.run(template: Template[type[fabricius.renderers.jinja_renderer.JinjaRenderer]]) → list[fabricius.types.FileCommitResult]
Run the CookieCutter template generated using
setup()
- Parameters:
template (Type of
fabricius.models.template.Template
) – The template to render.