copier-templates-extensions 0.1.0

Special Jinja2 extension for Copier that allows to load extensions using file paths relative to the template root instead of Python dotted paths.

Copier Templates Extensions

Special Jinja2 extension for Copier that allows to load extensions using file paths relative to the template root instead of Python dotted paths.

Requirements

Copier Templates Extensions requires Python 3.6 or above.

To install Python 3.6, I recommend using pyenv.

# install pyenv
git clone https://github.com/pyenv/pyenv ~/.pyenv

# setup pyenv (you should also put these three lines in .bashrc or similar)
export PATH="${HOME}/.pyenv/bin:${PATH}"
export PYENV_ROOT="${HOME}/.pyenv"
eval "$(pyenv init -)"

# install Python 3.6
pyenv install 3.6.12

# make it available globally
pyenv global system 3.6.12

Installation

With pip:

pip install copier-templates-extensions

With pipx:

pip install --user pipx

pipx install copier
pipx inject copier copier-templates-extensions

Usage

:warning: This is not yet functional. We need something from Copier first: a way to get the path to the template on the disk. For example, Copier could set an environment variable with the path to the temporary cloned template as value.

---

In your template configuration, first add this extension, then add your templates extensions using relative file paths, and the class name after a colon:

_extensions:
- copier_templates_extensions.Ext
- extensions/context.py:ContextUpdateExtension
- extensions/slugify.py:SlugifyExtension

Context hook extension

This package also provides a convenient extension class allowing template writers to update the context used to render templates, in order to add, modify or remove items of the context.

In one of your relative path extensions modules, create a class that inherits from ContextHook, and override its hook method:

from copier_templates_extensions import ContextHook


class ContextUpdater(ContextHook):
    def hook(self, context):
        new_context = {}
        new_context["say"] = "hello " + context["name"]
        return new_context

Using the above example, your context will be updated with the new_context returned by the method. If you prefer to modify the context in-place instead, for example to remove items from it, set the update class attribute to False:

from copier_templates_extensions import ContextHook


class ContextUpdater(ContextHook):
    update = False

    def hook(self, context):
        context["say"] = "hello " + context["name"]
        del context["name"]

How does it work?

Beware the ugly hack! Upon loading this special extension, the function responsible for importing a Python object using its dotted-path (a string) is patched in the jinja.environment module, where it's used to load extensions. The patched version adds support for loading extensions using relative file paths.