A formidable library to build coding project templates

👤 Luca Baggi
💼 ML Engineer @Futura
🐍 Organiser @Python Milano

A formidable library to build coding project templates

👤 Luca Baggi
💼 ML Engineer @Futura
🐍 Organiser @Python Milano

What we’ll cover

❓ What is `cookiecutter`?

✅ When should I use it?

🎬 A demo

💾 How to install

🧑‍🍳 The `cookiecutter` recipe

⏲ Bake your recipe!

🍪 Moar treats!

❓ What is `cookiecutter`?

A Python command line interface (CLI)…
to initialise new coding projects…
in any programming language…
interactively…
using ready-made templates.

✅ When should I use it?

How many boxes do you check?

🏛 I want to put in place architectural decisions

🛠 I need flexible and interactive project templates

🔁 I wish to reduce boilerplate:

pyproject.toml
setup.cfg
setup.py
.pre-commit-config.yaml
Makefile
.env
…

packaging-meme

🎬 Time for a demo!

💾 How to install

cookiecutter should be installed globally

# the old way
pip install -U cookiecutter

# a bit like npx
pipx install cookiecutter
# the old way
pip install -U cookiecutter

# a bit like npx
pipx install cookiecutter

Install pipx

# macos
brew install pipx
pipx ensurepath

# linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# windows
# If you installed python using the app-store, replace `python` with `python3` in the next line.
python -m pip install --user pipx
pipx ensurepath
# macos
brew install pipx
pipx ensurepath

# linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# windows
# If you installed python using the app-store, replace `python` with `python3` in the next line.
python -m pip install --user pipx
pipx ensurepath

🧑‍🍳 The `cookiecutter` recipe

Some minimal scaffolding

Create a new directory, e.g.:

mkdir my-cookiecutter
mkdir my-cookiecutter

Initialise a git repository (recommended):

gh repo create my-cookiecutter
git init
git remote add origin <gh-username>/my-cookiecutter
gh repo create my-cookiecutter
git init
git remote add origin <gh-username>/my-cookiecutter

Create the cookiecutter.json👀:

touch cookiecutter.json
touch cookiecutter.json

Start adding variables to your cookiecutter.json, using ~~vim~~ ~~nvim~~ your favourite editor!

🧑‍🍳 The `cookiecutter` recipe

How to define variables

Define some placeholder variables whose values will be replaced when the project is created:

{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}
{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}

🧑‍🍳 The `cookiecutter` recipe

How to define variables

You can add default values…

{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}
{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}

🧑‍🍳 The `cookiecutter` recipe

How to define variables

… multiple choice variables (the default value is the first of the list)…

{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}
{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}

🧑‍🍳 The `cookiecutter` recipe

How to define variables

… and modify variables using Python string methods:

{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}
{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}

🧑‍🍳 The `cookiecutter` recipe

How to define variables

Finally, you can define private variables:

{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}
{
  "full_name": "",
  "email": "",
  "github_username": "",
  "project_name": "",
  "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0" ],
  "__repo_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "package_name": "{{ cookiecutter.__repo_name.lower().replace('-', '_') }}",
  "package_version": "0.1.0",
  "python_version": "3.9.13",
  "__py_major_minor": "{{ '.'.join(cookiecutter.python_version.split(sep='.')[:-1]) }}",
  "use_pyenv": [ "yes", "no" ],
  "use_jupyter": [ "no", "yes" ],
  "has_documentation": [ "no", "yes" ]
}

⏲ Bake your recipe!

Use {{ cookiecutter.<variable> }} where you want a substitution to happen.

It can be a filename…

.
├── {{ cookiecutter.__repo_name }}
│  ├── docs
│  ├── notebooks
│  ├── src
│  │  └── {{ cookiecutter.package_name }}
│  ├── tests
│  │  └── __init__.py
│  ├── .env.template
│  ├── .gitignore
│  ├── .pre-commit-config.yaml
│  ├── .python-version
│  ├── LICENSE
│  ├── pyproject.toml
│  └── README.md
└── cookiecutter.json
.
├── {{ cookiecutter.__repo_name }}
│  ├── docs
│  ├── notebooks
│  ├── src
│  │  └── {{ cookiecutter.package_name }}
│  ├── tests
│  │  └── __init__.py
│  ├── .env.template
│  ├── .gitignore
│  ├── .pre-commit-config.yaml
│  ├── .python-version
│  ├── LICENSE
│  ├── pyproject.toml
│  └── README.md
└── cookiecutter.json

⏲ Bake your recipe!

Use {{ cookiecutter.<variable> }} where you want a substitution to happen.

…or text inside a filename:

# pyproject.toml
[project]
name = "{{ cookiecutter.package_name }}"
authors = [
    {name = "{{ cookiecutter.full_name }}", email = "{{ cookiecutter.email }}"},
]
description = ""
license = {text = "{{ cookiecutter.license }}"}
readme = "README.md"
dynamic = ["version"]
requires-python = ">={{ cookiecutter.__py_major_minor }}"

[tool.pdm]
version = {source = "file", path = "src/{{ cookiecutter.package_name }}/__init__.py"}
# pyproject.toml
[project]
name = "{{ cookiecutter.package_name }}"
authors = [
    {name = "{{ cookiecutter.full_name }}", email = "{{ cookiecutter.email }}"},
]
description = ""
license = {text = "{{ cookiecutter.license }}"}
readme = "README.md"
dynamic = ["version"]
requires-python = ">={{ cookiecutter.__py_major_minor }}"

[tool.pdm]
version = {source = "file", path = "src/{{ cookiecutter.package_name }}/__init__.py"}

⏲ Bake your recipe!

Use {{ cookiecutter.<variable> }} where you want a substitution to happen.

It even supports conditional statements:

{%- if cookiecutter.license == "MIT" -%}
The MIT License (MIT)

{%- elif cookiecutter.license == "BSD-3"  -%}
The BSD3 License (BSD3)

{%- elif cookiecutter.license ==  "GNU GPL v3.0" -%}
The GPLv3 License (GPLv3)

{%- elif cookiecutter.license ==   "Apache Software License 2.0" -%}
The APACHE License (APACHE)

{% endif %}
{%- if cookiecutter.license == "MIT" -%}
The MIT License (MIT)

{%- elif cookiecutter.license == "BSD-3"  -%}
The BSD3 License (BSD3)

{%- elif cookiecutter.license ==  "GNU GPL v3.0" -%}
The GPLv3 License (GPLv3)

{%- elif cookiecutter.license ==   "Apache Software License 2.0" -%}
The APACHE License (APACHE)

{% endif %}

(That’s a bunch of Jinja under the hood!)

🍪 Moar treats!

Configure cookiecutter

Add to your .zshenv/.zshrc:

if hash cookiecutter 2>/dev/null; then
    export COOKIECUTTER_CONFIG="$XDG_CONFIG_HOME/cookiecutter.yaml"
fi
if hash cookiecutter 2>/dev/null; then
    export COOKIECUTTER_CONFIG="$XDG_CONFIG_HOME/cookiecutter.yaml"
fi

🍪 Moar treats!

Configure cookiecutter

Edit your cookiecutter.yaml configs:

default_context: # default values for commonly used variables
  full_name: "<Name Surname>"
  email: "<your-github-email>"
  github_username: "<your-github-username>"
cookiecutters_dir: "$XDG_CACHE_HOME/cookiecutters/" # where cookiecutters will be stored
abbreviations:
  # gh (github), bb (bitbucket), and gl (gitlab) abbreviations are builtin
  gh: https://github.com/{0}.git
  py: https://github.com/baggiponte/cookiecutter-python.git
default_context: # default values for commonly used variables
  full_name: "<Name Surname>"
  email: "<your-github-email>"
  github_username: "<your-github-username>"
cookiecutters_dir: "$XDG_CACHE_HOME/cookiecutters/" # where cookiecutters will be stored
abbreviations:
  # gh (github), bb (bitbucket), and gl (gitlab) abbreviations are builtin
  gh: https://github.com/{0}.git
  py: https://github.com/baggiponte/cookiecutter-python.git

🍪 Moar treats!

Add pre- and post-generation hooks

Just create a hooks level folder at the same level of the cookiecutter.json:

.
├── hooks
│  └── post_gen_project.py
├── {{ cookiecutter.__repo_name }}
└── cookiecutter.json
.
├── hooks
│  └── post_gen_project.py
├── {{ cookiecutter.__repo_name }}
└── cookiecutter.json

🍪 Moar treats!

Add pre- and post-generation hooks

Just create a hooks level folder at the same level of the cookiecutter.json:

#!/usr/bin/env python

import os
import shutil

PROJECT_DIRECTORY = os.path.realpath(os.path.curdir)

def remove_dir(filepath):
    shutil.rmtree(os.path.join(PROJECT_DIRECTORY, filepath))

if __name__ == '__main__':

    if '{{ cookiecutter.has_documentation }}' != 'yes':
        remove_dir('docs')

    if '{{ cookiecutter.use_jupyter }}' != 'yes':
        remove_dir('notebooks')
#!/usr/bin/env python

import os
import shutil

PROJECT_DIRECTORY = os.path.realpath(os.path.curdir)

def remove_dir(filepath):
    shutil.rmtree(os.path.join(PROJECT_DIRECTORY, filepath))

if __name__ == '__main__':

    if '{{ cookiecutter.has_documentation }}' != 'yes':
        remove_dir('docs')

    if '{{ cookiecutter.use_jupyter }}' != 'yes':
        remove_dir('notebooks')

🙋 Questions?

🙏 Thank you!

🎉 Special thanks to MIRTA & PyMi!

Please share your feedback! My address is lucabaggi [at] duck.com

A formidable library to build coding project templates

What we’ll cover

❓ What is cookiecutter?

✅ When should I use it?

🎬 A demo

💾 How to install

🧑‍🍳 The cookiecutter recipe

⏲ Bake your recipe!

🍪 Moar treats!

A formidable library to build coding project templates

What we’ll cover

❓ What is cookiecutter?

✅ When should I use it?

🎬 A demo

💾 How to install

🧑‍🍳 The cookiecutter recipe

⏲ Bake your recipe!

🍪 Moar treats!

❓ What is cookiecutter?

✅ When should I use it?

🎬 Time for a demo!

💾 How to install

🧑‍🍳 The cookiecutter recipe

🧑‍🍳 The cookiecutter recipe

🧑‍🍳 The cookiecutter recipe

🧑‍🍳 The cookiecutter recipe

🧑‍🍳 The cookiecutter recipe

🧑‍🍳 The cookiecutter recipe

⏲ Bake your recipe!

⏲ Bake your recipe!

⏲ Bake your recipe!

🍪 Moar treats!

🍪 Moar treats!

🍪 Moar treats!

🍪 Moar treats!

🙋 Questions?

🙏 Thank you!

🎉 Special thanks to MIRTA & PyMi!

❓ What is `cookiecutter`?

🧑‍🍳 The `cookiecutter` recipe

❓ What is `cookiecutter`?

🧑‍🍳 The `cookiecutter` recipe

❓ What is `cookiecutter`?

🧑‍🍳 The `cookiecutter` recipe

🧑‍🍳 The `cookiecutter` recipe

🧑‍🍳 The `cookiecutter` recipe

🧑‍🍳 The `cookiecutter` recipe

🧑‍🍳 The `cookiecutter` recipe

🧑‍🍳 The `cookiecutter` recipe