Document how to do conditional files/directories

[pydanny]

In the advanced_usage.rst document we should document the following techniques:

1. By default have all the files, then use https://github.com/pydanny/cookiecutter-django/blob/master/hooks/post_gen_project.py#L163-L165 to remove those things not needed. (works everywhere)
2. Use logic in directory names to set whether or not something is created. (Only works in Linux/OSX)

[jamesbassett]

Yeah I needed this a while ago, and came up with an approach similar to 1:

• feature flags (choice) in cookiecutter.json
• templated manifest.yml file that lists all the files that should be removed if a feature is disabled
• post hook to read manifest and delete relevant files

cookiecutter.json

{
    "project": "my-project",
    "feature1": [true, false],
    "feature2": [true, false],
    "feature3": [true, false]
}

manifest.yml (templated file in cookiecutter, i.e. lives beside the rest of your projects templates)

Note:

• name matches entry in cookiecutter.json
• enabled lowercases the value so it's valid YAML (Pythonesque True/False -> true/false)
• resources is a list of files/folders, relative to the generated cookiecutter directory (and may contain templated variables, i.e. for package names etc)

features:
  - name: feature1
    enabled: {{cookiecutter.feature1|lower}}
    resources:
      - path/to/file/Feature1a.txt
      - path/to/file/Feature1b.txt

  - name: feature2
    enabled: {{cookiecutter.feature2|lower}}
    resources:
      - path/to/file/Feature2.txt

  - name: feature3
    enabled: {{cookiecutter.feature3|lower}}
    resources:
      - path/to/file/feature/three/folder

post_gen_project.py

#!/usr/bin/env python
import os
import shutil
import yaml

MANIFEST = "manifest.yml"


def delete_resources_for_disabled_features():
    with open(MANIFEST) as manifest_file:
        manifest = yaml.load(manifest_file)
        for feature in manifest['features']:
            if not feature['enabled']:
                print "removing resources for disabled feature {}...".format(feature['name'])
                for resource in feature['resources']:
                    delete_resource(resource)
    print "cleanup complete, removing manifest..."
    delete_resource(MANIFEST)


def delete_resource(resource):
    if os.path.isfile(resource):
        print "removing file: {}".format(resource)
        os.remove(resource)
    elif os.path.isdir(resource):
        print "removing directory: {}".format(resource)
        shutil.rmtree(resource)

if __name__ == "__main__":
    delete_resources_for_disabled_features()

[gvidon]

@jamesbassett what if you can't know absolute path to project created from template? I digged into cookiecutter source code and found that there is no way for hooks to get to know generated project fs path — https://github.com/audreyr/cookiecutter/blob/master/cookiecutter/hooks.py#L53

What did I miss?

[jamesbassett]

@gvidon the resource paths in my manifest aren't absolute - they're relative to the generated output directory (in my case they look something like src/main/kotlin/my/company/{{cookiecutter.project}}/Feature1a.txt).

As an aside, I believe cookiecutter changes directory to the output directory, so if you need to, you can access the generated directory that way from a hook as well.

[jgonggrijp]

In the OP:

2. Use logic in directory names to set whether or not something is created. (Only works in Linux/OSX)

How does that work, and why does it not work on Windows?

[briancappello]

The solution in this thread wasn't quite clear to me, so for anybody else landing here from google:

$ tree your-cookiecutter
your-cookiecutter
├── cookiecutter.json
├── {{cookiecutter.project_slug}}
│   ├── {{cookiecutter.package_name}}
│   │   ├── file_one.py
│   │   ├── file_two.py
│   ├── README.md
├── hooks
│   └── post_gen_project.py
└── README.rst

// cat cookiecutter.json
{
  "create_readme": "y",
  "create_file_one": "y",
  "create_file_two": "n"
}

# cat post_gen_project.py
import os
import shutil

print(os.getcwd())  # prints /absolute/path/to/{{cookiecutter.project_slug}}

def remove(filepath):
    if os.path.isfile(filepath):
        os.remove(filepath)
    elif os.path.isdir(filepath):
        shutil.rmtree(filepath)

create_readme = '{{cookiecutter.create_readme}}' == 'y'
create_file_one = '{{cookiecutter.create_file_one}}' == 'y'
create_file_two = '{{cookiecutter.create_file_two}}' == 'y'

if not create_readme:
    # remove top-level file inside the generated folder
    remove('README.md')

if not create_file_one:
    # remove absolute path to file nested inside the generated folder
    remove(os.path.join(os.getcwd(), '{{cookiecutter.package_name}}', 'file_one.py'))

if not create_file_two:
    # remove relative file nested inside the generated folder
    remove(os.path.join('{{cookiecutter.package_name}}', 'file_two.py'))

[HT154]

@jgonggrijp I got curious how the conditional files work as well. After a little playing around, it's actually super simple: just use an {% if %} statement in the filename. Filenames templated as blank are omitted.

My guess is this doesn't work on Windows because % is forbidden in filenames. This could be worked around by fiddling with the Jinja block start/end strings, per http://jinja.pocoo.org/docs/2.10/api/#jinja2.Environment. Maybe a cookiecutter.json setting (something like _template_block_character, defaulting to "%") to be overridden to something like "^" for full cross-platform support.

[HT154]

After a little more playing: making entire files conditional using {% if %} in filenames works great if you're targeting *nix platforms. Using it in directory names doesn't work at all and causes errors during rendering.

[dreftymac]

This is just a quick note to indicate:

#723 (comment)

has broken links as of this post (2019-09-28 09:36:00).

Another option that was not enumerated in the referenced post, but is now also available:

3. Use the cookiecutter python API, and handle conditional files and directories before running CC generate.

[ark-]

After a little more playing: making entire files conditional using {% if %} in filenames works great if you're targeting *nix platforms. Using it in directory names doesn't work at all and causes errors during rendering.

Not sure the issue you're finding on Windows. At least on Windows 10 filenames with if conditionals in them do work.

For example I have a file called: {% if cookiecutter.incl_file1== 'y' %}file1.txt{% endif %} which will only be included if incl_file1 is set to y.

Hope this helps others on windows who read the above comment and assume they have to start messing around with post scripts.

[michaeljoseph]

We can also use if-expressions

$ cat conditional/cookiecutter.json; tree conditional; cookiecutter -f --no-input conditional; tree sceletor
{
    "project_name": "sceletor",
    "generate_this": "y"
}

conditional
├── cookiecutter.json
└── {{cookiecutter.project_name}}
    └── {{\ 'test-this.txt'\ if\ cookiecutter.generate_this\ ==\ 'y'\ else\ ''\ }}

sceletor
└── test-this.txt