Getting to Know Cookieninja

Cookieninja is a tool for creating projects from cookieninjas (project templates).

What exactly does this mean? Read on!

Case Study: cookieninja -pypackage

cookieninja-pypackage is a cookieninja 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 cookieninja command, passing in the link to cookieninja-pypackage’s HTTPS clone URL like this:

$ cookieninja https://github.com/audreyfeldroy/cookiecutter-pypackage.git

Local Cloning of Project Template

First, cookieninja-pypackage gets cloned to ~/.cookiecutters/ (or equivalent on Windows). Cookieninja 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 cookieninja-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 cookieninja-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 Cookieninja to generate your first project from a cookieninja project template.

In tutorial 2 (Create a Cookieninja From Scratch), you’ll see how to create cookieninjas of your own, from scratch.