1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
.. _`template extensions`:
Template Extensions
-------------------
*New in Cookiecutter 1.4*
A template may extend the Cookiecutter environment with custom `Jinja2 extensions`_.
It can add extra filters, tests, globals or even extend the parser.
To do so, a template author must specify the required extensions in ``cookiecutter.json`` as follows:
.. code-block:: json
{
"project_slug": "Foobar",
"year": "{% now 'utc', '%Y' %}",
"_extensions": ["jinja2_time.TimeExtension"]
}
On invocation Cookiecutter tries to import the extensions and add them to its environment respectively.
In the above example, Cookiecutter provides the additional tag `now`_, after installing the `jinja2_time.TimeExtension`_ and enabling it in ``cookiecutter.json``.
Please note that Cookiecutter will **not** install any dependencies on its own!
As a user you need to make sure you have all the extensions installed, before running Cookiecutter on a template that requires custom Jinja2 extensions.
By default Cookiecutter includes the following extensions:
- ``cookiecutter.extensions.JsonifyExtension``
- ``cookiecutter.extensions.RandomStringExtension``
- ``cookiecutter.extensions.SlugifyExtension``
- ``cookiecutter.extensions.TimeExtension``
- ``cookiecutter.extensions.UUIDExtension``
.. warning::
The above is just an example to demonstrate how this is used. There is no
need to require ``jinja2_time.TimeExtension``, since its functionality is
included by default (by ``cookiecutter.extensions.TimeExtension``) without
needing an extra install.
Jsonify extension
~~~~~~~~~~~~~~~~~
The ``cookiecutter.extensions.JsonifyExtension`` extension provides a ``jsonify`` filter in templates that converts a Python object to JSON:
.. code-block:: jinja
{% {'a': True} | jsonify %}
Would output:
.. code-block:: json
{"a": true}
Random string extension
~~~~~~~~~~~~~~~~~~~~~~~
*New in Cookiecutter 1.7*
The ``cookiecutter.extensions.RandomStringExtension`` extension provides a ``random_ascii_string`` method in templates that generates a random fixed-length string, optionally with punctuation.
Generate a random n-size character string.
Example for n=12:
.. code-block:: jinja
{{ random_ascii_string(12) }}
Outputs:
.. code-block:: text
bIIUczoNvswh
The second argument controls if punctuation and special characters ``!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~`` should be present in the result:
.. code-block:: jinja
{{ random_ascii_string(12, punctuation=True) }}
Outputs:
.. code-block:: text
fQupUkY}W!)!
Slugify extension
~~~~~~~~~~~~~~~~~
The ``cookiecutter.extensions.SlugifyExtension`` extension provides a ``slugify`` filter in templates that converts string into its dashed ("slugified") version:
.. code-block:: jinja
{% "It's a random version" | slugify %}
Would output:
::
it-s-a-random-version
It is different from a mere replace of spaces since it also treats some special characters differently such as ``'`` in the example above.
The function accepts all arguments that can be passed to the ``slugify`` function of `python-slugify`_.
For example to change the output from ``it-s-a-random-version``` to ``it_s_a_random_version``, the ``separator`` parameter would be passed: ``slugify(separator='_')``.
.. _`Jinja2 extensions`: https://jinja.palletsprojects.com/en/latest/extensions/
.. _`now`: https://github.com/hackebrot/jinja2-time#now-tag
.. _`jinja2_time.TimeExtension`: https://github.com/hackebrot/jinja2-time
.. _`python-slugify`: https://pypi.org/project/python-slugify
UUID4 extension
~~~~~~~~~~~~~~~~~~~~~~~
*New in Cookiecutter 1.x*
The ``cookiecutter.extensions.UUIDExtension`` extension provides a ``uuid4()``
method in templates that generates a uuid4.
Generate a uuid4 string:
.. code-block:: jinja
{{ uuid4() }}
Outputs:
.. code-block:: text
83b5de62-31b4-4a1e-83fa-8c548de65a11
|
