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:

  1. Get the template path

  2. Create the Template object and add the extensions, if the project templates specify any others, add them too.

  3. Add _template, _repo_dir and _output_dir to the context

  4. Obtain the questions in the project template and begin to ask to the users those questions.

  5. Once all answered, add the extra context the user’s default context, then add the answers to the final context.

  6. Obtain all the files that must be rendered/copied, and add them to the Template object, and push the data to the Template object.

  7. Connect the hooks to the before_template_commit and after_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:

  1. First attempt to commit the project

  2. If fail, due to a file that already exist, ask the user if overwriting files should be used.

  3. 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.

  4. 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 the cookiecutter.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:

Type of fabricius.models.template.Template

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.