# A jinja2 extension for optionally including files in cookiecutter templates
It's a well known and documented issue that cookiecutter does not support
conditionally included files and directories. See
[this post on github](https://github.com/cookiecutter/cookiecutter/issues/723).
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
## Setup
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`:
```bash
$ 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:
```json
{
"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:
```json
{
"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](https://github.com/cookiecutter/cookiecutter/issues/1518)
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:
```python
from cutout import cleanup
cleanup()
```
That's it. You should be ready to make some cookies now!
## Using cut-out-cookies stencils
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
```
### Optionally including a file
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
### Optionally including a directory
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](https://github.com/cookiecutter/cookiecutter/issues/1518). 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:
```python
from cutout import cleanup
cleanup()
```
Then the non-matching directories will be removed after project generation.
### Optionally include a block of text
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 %}
```
### Optionally include text inline
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
Raw data
{
"_id": null,
"home_page": "https://github.com/dusktreader/cut-out-cookies",
"name": "cut-out-cookies",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Tucker Beck",
"author_email": "tucker.beck@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/12/42/4f4632475e0ecbaaad75d912d6664266921879d62218a5dff723b4a41cc7/cut_out_cookies-0.3.1.tar.gz",
"platform": null,
"description": "# A jinja2 extension for optionally including files in cookiecutter templates\n\nIt's a well known and documented issue that cookiecutter does not support\nconditionally included files and directories. See\n[this post on github](https://github.com/cookiecutter/cookiecutter/issues/723).\n\nThis package unlocks that feature with simple jinja2 filters that can be\napplied to:\n* optional file inclusion\n* optional directory inclusion\n* optional inclusion of blocks within templates\n* optional inclusion of in-line text\n\n\n## Setup\n\nThis assumes that you have cookiecutter installed already and have a project\nthat you are building into a template. This also assumes you are managing\nyour environment in your preferred way.\n\nFirst, install `cut-out-cookies`:\n```bash\n$ pip install cut-out-cookies\n```\nIf you are using poetry, pipenv, flit, etc you will need to convert the\ncommand for your setup.\n\nAdd the extension to your `cookiecutter.json` file like so:\n```json\n{\n \"full_name\": \"Tucker Beck\",\n \"email\": \"tucker.beck@gmail.com\",\n \"project_name\": \"Sugar Cookies Project\",\n \"version\": \"0.1.0\",\n \"_extensions\": [\"cutout.Stencil\"]\n}\n```\nThe only important line here is where the extension is being added. The\nreset is just for example context.\n\nNext, you should add some 'patterns' to your `cookiecutter.json` that you\nwill use to 'decorate' your optional cookies with:\n```json\n{\n \"full_name\": \"Tucker Beck\",\n \"email\": \"tucker.beck@gmail.com\",\n \"project_name\": \"Sugar Cookies Project\",\n \"version\": \"0.1.0\",\n \"_extensions\": [\"cutout.Stencil\"],\n \"include_sprinkles\": false,\n \"include_frosting\": false\n}\n```\nThis indicates that, by default, any cookies decorated with 'sprinkles' or\n'frosting' should not be included in the generated project. The user will\nnow be prompted if they want to include the optional features 'sprinkles'\nand 'frosting'\n\nFinally, due to [this issue on the cookiecutter github repo](https://github.com/cookiecutter/cookiecutter/issues/1518)\nyou will need to install a post-gen project hook to cleanup the directories\nthat you intend to omit. Add a `hooks` directory in your template with a\nfile called `post_gen_project.py`. That file needs to contain this:\n```python\nfrom cutout import cleanup\n\ncleanup()\n```\n\nThat's it. You should be ready to make some cookies now!\n\n\n## Using cut-out-cookies stencils\n\nFor a case study, let's suppose you are building a project stencil called\n'Sugar Cookies' that starts out looking like this:\n```\nsugar-cookies/\n\u251c\u2500\u2500 cookiecutter.json\n\u2514\u2500\u2500 {{cookiecutter.project_name}}\n \u2514\u2500\u2500 README.md\n```\n\n\n### Optionally including a file\n\nTo indicate that a file should only be included if a certain pattern is\nincluded, you use the `stencil` filter in its template filename.\n\nLet's create a file called 'tasty.py' that should only be included if the\n'sprinkles' pattern is applied. To do that, we'll apply the `stencil`\nfilter like so:\n```\nexamples/\n\u251c\u2500\u2500 cookiecutter.json\n\u2514\u2500\u2500 {{cookiecutter.project_name}}\n \u251c\u2500\u2500 README.md\n \u2514\u2500\u2500 {{'tasty.py'|stencil('sprinkles')}}\n```\n\nNow if the `include_sprinkles` setting is enabled in cookiecutter, the rendered\nproject will have a file called `tasty.py`. If it is not enabled, the `tasty.py`\nsource file will be omitted altogether\n\n\n### Optionally including a directory\n\nTo indicate that a directory should only be included if a certain pattern is\nincluded, you use the `stencil_path` filter in its name. Unfortunately, the\n`stencil` filter cannot be used for directories due to\n[this issue](https://github.com/cookiecutter/cookiecutter/issues/1518). The\n`stencil_path` causes non-matching directories to be Prefixed with a special\nflag value ('OBSCURATA_LAMINA_INTERRASILIS'). Then, a post-gen hook can be used\nto remove these directories. This approach is a bit of a hack, but until the\nmentioned issue is fixed, we've tried to make it as painless as possible by\nincluding a `cleanup` function that can be easily added to a `post_gen_project`\nhook.\n\nLet's create a diretory called 'batch' that should only be included if the\n'frosting' pattern is included. To do that, we'll apply the `stencil_path` filter\nlike so:\n```\nexamples/\n\u251c\u2500\u2500 cookiecutter.json\n\u251c\u2500\u2500 hooks/\n\u2502\u00a0 \u2514\u2500\u2500 post_gen_project.py\n\u2514\u2500\u2500 {{cookiecutter.project_name}}\n \u251c\u2500\u2500 README.md\n \u2514\u2500\u2500 {{'batch'|stencil_path('frosting')}}\n \u251c\u2500\u2500 star_shaped.py\n \u2514\u2500\u2500 heart_shaped.py\n```\n\nNow if the `include_frosting` setting is enabled in cookiecutter, the rendered\nproject will have a directory called `batch` that includes two file called\n`star_shaped.py` and `heart_shaped.py`. If it is not enabled, the directory will\nbe named 'OBSCURATA_LAMINA_INTERRASILIS--batch' in the generated project. If you\nhave the `post_gen_project` hook defined like this:\n\n```python\nfrom cutout import cleanup\ncleanup()\n```\n\nThen the non-matching directories will be removed after project generation.\n\n\n### Optionally include a block of text\n\nTo indicate that a block of text should only be included if a cerain pattern\nis included, you use the `stencil` filter block like so:\n```\nThis text will always be included\n{%- filter stencil('glitter') }\nThis text will only be inlcuded if the glitter pattern is included in the\ncookiecutter config\n{% endfilter %}\n```\n\n\n### Optionally include text inline\n\nTo indicate that a bit of in-line text should only be included if a cerain pattern\nis included, you use the `stencil` filter like so:\n```\nThis text includes {{ 'whipped cream' | stencil('creamy') }} frosting\n```\nThe text above will only include 'whipped cream' if the `creamy` pattern in included\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Jinja extension for optionally including files and directories",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/dusktreader/cut-out-cookies",
"Repository": "https://github.com/dusktreader/cut-out-cookies"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5bd926fbf47f8040fa9f835bf2291ca3b2d99ef8c4272d1c3868798aa52f02b3",
"md5": "dc7d83ac4d43d2c48d742dba93ed9bff",
"sha256": "50f6c2c21dcb6e97ee0091243c1fe25eb709cd6a5074bca90e58ae9315e23fe1"
},
"downloads": -1,
"filename": "cut_out_cookies-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc7d83ac4d43d2c48d742dba93ed9bff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 5214,
"upload_time": "2024-01-10T23:49:37",
"upload_time_iso_8601": "2024-01-10T23:49:37.884904Z",
"url": "https://files.pythonhosted.org/packages/5b/d9/26fbf47f8040fa9f835bf2291ca3b2d99ef8c4272d1c3868798aa52f02b3/cut_out_cookies-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "12424f4632475e0ecbaaad75d912d6664266921879d62218a5dff723b4a41cc7",
"md5": "10049a37d4ef0f88fd06166e5433a092",
"sha256": "b13367578aebff30bab3d7779de4d9f1f6beeab2ed823385b29cc1055dd73cd7"
},
"downloads": -1,
"filename": "cut_out_cookies-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "10049a37d4ef0f88fd06166e5433a092",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 4330,
"upload_time": "2024-01-10T23:49:39",
"upload_time_iso_8601": "2024-01-10T23:49:39.632638Z",
"url": "https://files.pythonhosted.org/packages/12/42/4f4632475e0ecbaaad75d912d6664266921879d62218a5dff723b4a41cc7/cut_out_cookies-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-10 23:49:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dusktreader",
"github_project": "cut-out-cookies",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cut-out-cookies"
}
JSON
