It's a well known and documented issue that cookiecutter does not support conditionally included files and directories. See this post on github.
This package unlocks that feature with simple jinja2 filters that can be applied to:
- optional file inclusion
- optional directory inclusion
- optional inclusion of blocks within templates
- optional inclusion of in-line text
This assumes that you have cookiecutter installed already and have a project that you are building into a template. This also assumes you are managing your environment in your preferred way.
First, install cut-out-cookies
:
$ pip install cut-out-cookies
If you are using poetry, pipenv, flit, etc you will need to convert the command for your setup.
Add the extension to your cookiecutter.json
file like so:
{
"full_name": "Tucker Beck",
"email": "tucker.beck@gmail.com",
"project_name": "Sugar Cookies Project",
"version": "0.1.0",
"_extensions": ["cutout.Stencil"]
}
The only important line here is where the extension is being added. The reset is just for example context.
Next, you should add some 'patterns' to your cookiecutter.json
that you
will use to 'decorate' your optional cookies with:
{
"full_name": "Tucker Beck",
"email": "tucker.beck@gmail.com",
"project_name": "Sugar Cookies Project",
"version": "0.1.0",
"_extensions": ["cutout.Stencil"],
"include_sprinkles": false,
"include_frosting": false
}
This indicates that, by default, any cookies decorated with 'sprinkles' or 'frosting' should not be included in the generated project. The user will now be prompted if they want to include the optional features 'sprinkles' and 'frosting'
Finally, due to this issue on the cookiecutter github repo
you will need to install a post-gen project hook to cleanup the directories
that you intend to omit. Add a hooks
directory in your template with a
file called post_gen_project.py
. That file needs to contain this:
from cutout import cleanup
cleanup()
That's it. You should be ready to make some cookies now!
For a case study, let's suppose you are building a project stencil called 'Sugar Cookies' that starts out looking like this:
sugar-cookies/
├── cookiecutter.json
└── {{cookiecutter.project_name}}
└── README.md
To indicate that a file should only be included if a certain pattern is
included, you use the stencil
filter in its template filename.
Let's create a file called 'tasty.py' that should only be included if the
'sprinkles' pattern is applied. To do that, we'll apply the stencil
filter like so:
examples/
├── cookiecutter.json
└── {{cookiecutter.project_name}}
├── README.md
└── {{'tasty.py'|stencil('sprinkles')}}
Now if the include_sprinkles
setting is enabled in cookiecutter, the rendered
project will have a file called tasty.py
. If it is not enabled, the tasty.py
source file will be omitted altogether
To indicate that a directory should only be included if a certain pattern is
included, you use the stencil_path
filter in its name. Unfortunately, the
stencil
filter cannot be used for directories due to
this issue. The
stencil_path
causes non-matching directories to be Prefixed with a special
flag value ('OBSCURATA_LAMINA_INTERRASILIS'). Then, a post-gen hook can be used
to remove these directories. This approach is a bit of a hack, but until the
mentioned issue is fixed, we've tried to make it as painless as possible by
including a cleanup
function that can be easily added to a post_gen_project
hook.
Let's create a diretory called 'batch' that should only be included if the
'frosting' pattern is included. To do that, we'll apply the stencil_path
filter
like so:
examples/
├── cookiecutter.json
├── hooks/
│ └── post_gen_project.py
└── {{cookiecutter.project_name}}
├── README.md
└── {{'batch'|stencil_path('frosting')}}
├── star_shaped.py
└── heart_shaped.py
Now if the include_frosting
setting is enabled in cookiecutter, the rendered
project will have a directory called batch
that includes two file called
star_shaped.py
and heart_shaped.py
. If it is not enabled, the directory will
be named 'OBSCURATA_LAMINA_INTERRASILIS--batch' in the generated project. If you
have the post_gen_project
hook defined like this:
from cutout import cleanup
cleanup()
Then the non-matching directories will be removed after project generation.
To indicate that a block of text should only be included if a cerain pattern
is included, you use the stencil
filter block like so:
This text will always be included
{%- filter stencil('glitter') }
This text will only be inlcuded if the glitter pattern is included in the
cookiecutter config
{% endfilter %}
To indicate that a bit of in-line text should only be included if a cerain pattern
is included, you use the stencil
filter like so:
This text includes {{ 'whipped cream' | stencil('creamy') }} frosting
The text above will only include 'whipped cream' if the creamy
pattern in included