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ยค
In your template configuration, first add our loader extension, then add your templates extensions using relative file paths, and the class name after a colon:
_jinja_extensions:
- copier_templates_extensions.TemplateExtensionLoader
- extensions/context.py:ContextUpdater
- extensions/slugify.py:SlugifyExtension
With this example, you are supposed to have an extensions
directory at the root of your template containing two modules:
context.py
and slugify.py
.
๐ template_root
โโโ ๐ abc.txt.jinja
โโโ ๐ copier.yml
โโโ ๐ extensions
ย ย โโโ ๐ context.py
ย ย โโโ ๐ slugify.py
See Context hook extension
to see how the ContextUpdater
class can be written.
The SlugifyExtension
class could be written like this:
import re
import unicodedata
from jinja2.ext import Extension
# taken from Django
# https://github.com/django/django/blob/main/django/utils/text.py
def slugify(value, allow_unicode=False):
"""
Convert to ASCII if 'allow_unicode' is False. Convert spaces or repeated
dashes to single dashes. Remove characters that aren't alphanumerics,
underscores, or hyphens. Convert to lowercase. Also strip leading and
trailing whitespace, dashes, and underscores.
"""
value = str(value)
if allow_unicode:
value = unicodedata.normalize('NFKC', value)
else:
value = unicodedata.normalize('NFKD', value).encode('ascii', 'ignore').decode('ascii')
value = re.sub(r'[^\w\s-]', '', value.lower())
return re.sub(r'[-\s]+', '-', value).strip('-_')
class SlugifyExtension(Extension):
def __init__(self, environment):
super().__init__(environment)
environment.filters["slugify"] = slugify
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"]
In your Jinja templates, you will now have access
to the {{ say }}
variable directly.
This can be extremely useful in template projects where you don't want to ask too many questions to the users and instead infer some values from their answers.
Consider the following example:
you ask your users if they want to generate
a CLI app or a web API.
Depending on their answer,
the main Python module should be named
cli.py
or app.py
.
Without the context hook, you would need to write a Jinja macro somewhere, or update the context directly in Jinja, and import this file (still using Jinja) in the filename of the module:
{# using macros #}
{%- macro module_name() %}
{%- if project_type == "webapi" %}app{% else %}cli{% endif %}
{%- endmacro %}
{# or enhancing the context #}
{#- Initiate context with a copy of Copier answers -#}
{%- set ctx = _copier_answers.copy() -%}
{#- Populate our new variables -#}
{%- set _ = ctx.update({"module_name": ("app" if project_type == "webapi" else "cli") -%}
๐ template_root
โโโ ๐ copier.yml
โโโ ๐ macros # the macros file
โโโ ๐ context # the context file
โโโ ๐ extensions
โย ย โโโ ๐ slugify.py
โโโ ๐ {{project_name|slugify}}
โ
โ # using the macros
โโโ ๐ {% import 'macros' as macros with context %}{{macros.module_name()}}.py.jinja
โ
โ # or using the enhanced context
โโโ ๐ {% from 'context' import ctx with context %}{{ctx.module_name}}.py.jinja
As you can see, both forms are really ugly to write:
- the
macros
orcontext
can only be placed in the root, as slashes/
are not allowed in filenames - you must use spaces and single-quotes (double-quotes are not valid filename characters on Windows) in your templated filenames, which is not clean
- filenames are very long
Using our context hook instead makes it so easy and clean!
from copier_templates_extensions import ContextHook
class ContextUpdater(ContextHook):
def hook(self, context):
return {"module_name": "app" if context["project_type"] == "webapi" else "cli"}
๐ template_root
โโโ ๐ copier.yml
โโโ ๐ extensions
โย ย โโโ ๐ slugify.py
โย ย โโโ ๐ context.py
โโโ ๐ {{project_name|slugify}}
โโโ ๐ {{module_name}}.py.jinja
How does it work?ยค
Beware the ugly hack!
Upon loading the special loader 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.
The file system loader of the Jinja environment
and its searchpaths
attribute are used to
find the local clone of the template and determine
the absolute path of the extensions to load.