Getting to Know Cookiecutter
Note
Before you begin, please install Cookiecutter 0.7.0 or higher. Instructions are in Installation.
Cookiecutter is a tool for creating projects from cookiecutters (project templates).
What exactly does this mean? Read on!
Case Study: cookiecutter-pypackage
cookiecutter-pypackage is a cookiecutter template that creates the starter boilerplate for a Python package.
Note
There are several variations of it, but for this tutorial we’ll use the original version at https://github.com/audreyfeldroy/cookiecutter-pypackage/.
Step 1: Generate a Python Package Project
Open your shell and cd into the directory where you’d like to create a starter Python package project.
At the command line, run the cookiecutter command, passing in the link to cookiecutter-pypackage’s HTTPS clone URL like this:
$ cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage.git
Local Cloning of Project Template
First, cookiecutter-pypackage gets cloned to ~/.cookiecutters/ (or equivalent on Windows). Cookiecutter does this for you, so sit back and wait.
Local Generation of Project
When cloning is complete, you will be prompted to enter a bunch of values, such as full_name, email, and project_name. Either enter your info, or simply press return/enter to accept the default values.
This info will be used to fill in the blanks for your project. For example, your name and the year will be placed into the LICENSE file.
Step 2: Explore What Got Generated
In your current directory, you should see that a project got generated:
$ ls
boilerplate
Looking inside the boilerplate/ (or directory corresponding to your project_slug) directory, you should see something like this:
$ ls boilerplate/
AUTHORS.rst MANIFEST.in docs tox.ini
CONTRIBUTING.rst Makefile requirements.txt
HISTORY.rst README.rst setup.py
LICENSE boilerplate tests
That’s your new project!
If you open the AUTHORS.rst file, you should see something like this:
=======
Credits
=======
Development Lead
----------------
* Audrey Roy <audreyr@gmail.com>
Contributors
------------
None yet. Why not be the first?
Notice how it was auto-populated with your (or my) name and email.
Also take note of the fact that you are looking at a ReStructuredText file. Cookiecutter can generate a project with text files of any type.
Great, you just generated a skeleton Python package. How did that work?
Step 3: Observe How It Was Generated
Let’s take a look at cookiecutter-pypackage together. Open https://github.com/audreyfeldroy/cookiecutter-pypackage in a new browser window.
{{ cookiecutter.project_slug }}
Find the directory called {{ cookiecutter.project_slug }}. Click on it. Observe the files inside of it. You should see that this directory and its contents corresponds to the project that you just generated.
This happens in find.py, where the find_template() method looks for the first jinja-like directory name that starts with cookiecutter.
AUTHORS.rst
Look at the raw version of {{ cookiecutter.project_slug }}/AUTHORS.rst, at https://raw.github.com/audreyfeldroy/cookiecutter-pypackage/master/%7B%7Bcookiecutter.project_slug%7D%7D/AUTHORS.rst.
Observe how it corresponds to the AUTHORS.rst file that you generated.
cookiecutter.json
Now navigate back up to cookiecutter-pypackage/ and look at the cookiecutter.json file.
You should see JSON that corresponds to the prompts and default values shown earlier during project generation:
{
"full_name": "Audrey Roy Greenfeld",
"email": "aroy@alum.mit.edu",
"github_username": "audreyr",
"project_name": "Python Boilerplate",
"project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_') }}",
"project_short_description": "Python Boilerplate contains all the boilerplate you need to create a Python package.",
"pypi_username": "{{ cookiecutter.github_username }}",
"version": "0.1.0",
"use_pytest": "n",
"use_pypi_deployment_with_travis": "y",
"create_author_file": "y",
"open_source_license": ["MIT", "BSD", "ISCL", "Apache Software License 2.0", "Not open source"]
}
Questions?
If anything needs better explanation, please take a moment to file an issue at https://github.com/audreyfeldroy/cookiecutter/issues with what could be improved about this tutorial.
Summary
You have learned how to use Cookiecutter to generate your first project from a cookiecutter project template.
In tutorial 2 (Create a Cookiecutter From Scratch), you’ll see how to create cookiecutters of your own, from scratch.