skip to navigation
skip to content

cookiecutter 0.9.1

A command-line utility that creates projects from project templates, e.g. creating a Python package project from a Python package project template.

Latest Version: 1.5.1

A command-line utility that creates projects from cookiecutters (project templates), e.g. creating a Python package project from a Python package project template.

Features

Did someone say features?

  • Cross-platform: Windows, Mac, and Linux are officially supported.

  • Works with Python 2.6, 2.7, 3.3, 3.4, and PyPy. (But you don’t have to know/write Python code to use Cookiecutter.)

  • Project templates can be in any programming language or markup format: Python, JavaScript, Ruby, CoffeeScript, RST, Markdown, CSS, HTML, you name it. You can use multiple languages in the same project template.

  • Simple command line usage:

    # Create project from the cookiecutter-pypackage.git repo template
    # You'll be prompted to enter values.
    # Then it'll create your Python package in the current working directory,
    # based on those values.
    $ cookiecutter https://github.com/audreyr/cookiecutter-pypackage
    # For the sake of brevity, repos on GitHub can just use the 'gh' prefix
    $ cookiecutter gh:audreyr/cookiecutter-pypackage
    
  • Can also use it at the command line with a local template:

    # Create project in the current working directory, from the local
    # cookiecutter-pypackage/ template
    $ cookiecutter cookiecutter-pypackage/
    
  • Or use it from Python:

    from cookiecutter.main import cookiecutter
    
    # Create project from the cookiecutter-pypackage/ template
    cookiecutter('cookiecutter-pypackage/')
    
    # Create project from the cookiecutter-pypackage.git repo template
    cookiecutter('https://github.com/audreyr/cookiecutter-pypackage.git')
    
  • Directory names and filenames can be templated. For example:

    {{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}.py
    
  • Supports unlimited levels of directory nesting.

  • 100% of templating is done with Jinja2. This includes file and directory names.

  • Simply define your template variables in a cookiecutter.json file. For example:

    {
        "full_name": "Audrey Roy",
        "email": "audreyr@gmail.com",
        "project_name": "Complexity",
        "repo_name": "complexity",
        "project_short_description": "Refreshingly simple static site generator.",
        "release_date": "2013-07-10",
        "year": "2013",
        "version": "0.1.1"
    }
    
  • Unless you suppress it with –no-input, you are prompted for input:

    • Prompts are the keys in cookiecutter.json.
    • Default responses are the values in cookiecutter.json.
    • Prompts are shown in order.
  • Cross-platform support for ~/.cookiecutterrc files:

    default_context:
        full_name: "Audrey Roy"
        email: "audreyr@gmail.com"
        github_username: "audreyr"
    cookiecutters_dir: "~/.cookiecutters/"
    
  • Cookiecutters (cloned Cookiecutter project templates) are put into ~/.cookiecutters/ by default, or cookiecutters_dir if specified.

  • You can use local cookiecutters, or remote cookiecutters directly from Git repos or from Mercurial repos on Bitbucket.

  • Default context: specify key/value pairs that you want used as defaults whenever you generate a project

  • Direct access to the Cookiecutter API allows for injection of extra context.

  • Pre- and post-generate hooks: Python or shell scripts to run before or after generating a project.

  • Paths to local projects can be specified as absolute or relative.

  • Projects are always generated to your current directory.

Available Cookiecutters

Here is a list of cookiecutters (aka Cookiecutter project templates) for you to use or fork.

Make your own, then submit a pull request adding yours to this list!

Python

C

C++

  • BoilerplatePP: A simple cmake template with unit testing for projects written in C++.

Common Lisp

JS

LaTeX/XeTeX

  • pandoc-talk: A cookiecutter template for giving talks with pandoc and XeTeX.

Berkshelf-Vagrant

  • slim-berkshelf-vagrant: A simple cookiecutter template with sane cookbook defaults for common vagrant/berkshelf cookbooks.

HTML

Similar projects

  • Paste has a create option that creates a skeleton project.
  • Diecutter: an API service that will give you back a configuration file from a template and variables.
  • Django’s startproject and startapp commands can take in a –template option.
  • python-packager: Creates Python packages from its own template, with configurable options.
  • Yeoman has a Rails-inspired generator system that provides scaffolding for apps.
  • Pyramid’s pcreate command for creating Pyramid projects from scaffold templates.
  • mr.bob is a filesystem template renderer, meant to deprecate tools such as paster and templer.
  • grunt-init used to be built into Grunt and is now a standalone scaffolding tool to automate project creation.
  • scaffolt consumes JSON generators with Handlebars support.
  • init-skeleton clones or copies a repository, executes npm install and bower install and removes the .git directory.
  • Cog python-based code generation toolkit developed by Ned Batchelder

Community

The core committer team is @audreyr, @pydanny, @michaeljoseph, and @pfmoore. We welcome you and invite you to participate.

Stuck? Try one of the following:

  • See the Troubleshooting page.
  • Ask for help on Stack Overflow.
  • You are strongly encouraged to file an issue about the problem, even if it’s just “I can’t get it to work on this cookiecutter” with a link to your cookiecutter. Don’t worry about naming/pinpointing the issue properly.
  • Ask for help in #cookiecutter if you must (but please try one of the other options first, so that others can benefit from the discussion)

Development on Cookiecutter is community-driven:

  • Huge thanks to all the contributors who have pitched in to help make Cookiecutter an even better tool.
  • Everyone is invited to contribute. Read the contributing instructions, then get started.

Connect with other Cookiecutter contributors and users in IRC:

  • #cookiecutter on irc.freenode.net (note: due to work and commitments, a core committer might not always be available)

Encouragement is unbelievably motivating. If you want more work done on Cookiecutter, show support:

Got criticism or complaints?

  • File an issue so that Cookiecutter can be improved. Be friendly and constructive about what could be better. Make detailed suggestions.
  • Keep us in the loop so that we can help. For example, if you are discussing problems with Cookiecutter on a mailing list, file an issue where you link to the discussion thread and/or cc at least 1 core committer on the email.
  • Be encouraging. A comment like “This function ought to be rewritten like this” is much more likely to result in action than a comment like “Eww, look how bad this function is.”

Waiting for a response to an issue/question?

  • Be patient and persistent. All issues are on the core committer team’s radar and will be considered thoughtfully, but we have a lot of issues to work through. If urgent, it’s fine to ping a core committer in the issue with a reminder.
  • Ask others to comment, discuss, review, etc.
  • Search the Cookiecutter repo for issues related to yours.
  • Need a fix/feature/release/help urgently, and can’t wait? @audreyr is available for hire for consultation or custom development.

History

0.9.1 (2015-01-20)

  • Handle non-strings in JSON, thanks to @jacebrowning (#370, #368).

0.9.0 (2015-01-12)

The goals of this release is to add the ability to inja2ify the cookiecutter.json default values, switch to click, and formally launch support for Python 3.4.

Features:

  • Python 3.4 is now a first class citizen, thanks to everyone.
  • Interpret cookiecutter.json values as templates, thanks to @bollwyvl (#291).
  • Move to py.test, thanks to @pfmoore (#319) and @ramiroluz (#310).

Bug Fixes:

  • cookiecutter.json values are now rendered jinja2 templates, thanks to @bollwyvl (#291).
  • Corrected typo in Makefile, thanks to @inglesp (#297).

Other changes:

  • Creation of gitter account for logged chat, thanks to @michaeljoseph.
  • Added ReadTheDocs badge, thanks to @michaeljoseph.
  • Added AppVeyor badge, thanks to @pydanny
  • Documentation and PyPI trove classifier updates, thanks to @thedrow (#323 and #324)

0.8.0 (2014-10-30)

The goal of this release was to allow for injection of extra context via the Cookiecutter API, and to fix minor bugs.

Features:

Bug Fixes:

  • Newlines at the end of files are no longer stripped, thanks to @treyhunner (#183).
  • Cloning prompt suppressed by respecting the no_input flag, thanks to @trustrachel (#285)
  • With Python 3, input is no longer converted to bytes, thanks to @uranusjr (#98).

Other Changes:

0.7.2 (2014-08-05)

The goal of this release was to fix cross-platform compatibility, primarily Windows bugs that had crept in during the addition of new features. As of this release, Windows is a first-class citizen again, now complete with continuous integration.

Bug Fixes:

  • Fixed the contributing file so it displays nicely in Github, thanks to @pydanny.
  • Updates 2.6 requirements to include simplejson, thanks to @saxix.
  • Avoid unwanted extra spaces in string literal, thanks to @merwok.
  • Fix @unittest.skipIf error on Python 2.6.
  • Let sphinx parse :param: properly by inserting newlines #213, thanks to @mineo.
  • Fixed Windows test prompt failure by replacing stdin per @cjrh in #195.
  • Made rmtree remove readonly files, thanks to @pfmoore.
  • Now using tox to run tests on Appveyor, thanks to @pfmoore (#241).
  • Fixed tests that assumed the system encoding was utf-8, thanks to @pfmoore (#242, #244).
  • Added a tox ini file that uses py.test, thanks to @pfmoore (#245).

Other Changes:

0.7.1 (2014-04-26)

Bug fixes:

  • Use the current Python interpreter to run Python hooks, thanks to @coderanger.
  • Include tests and documentation in source distribution, thanks to @vincentbernat.
  • Fix various warnings and missing things in the docs (#129, #130), thanks to @nedbat.
  • Add command line option to get version (#89), thanks to @davedash and @cyberj.

Other changes:

0.7.0 (2013-11-09)

This is a release with significant improvements and changes. Please read through this list before you upgrade.

New features:

  • Support for –checkout argument, thanks to @foobacca.
  • Support for pre-generate and post-generate hooks, thanks to @raphigaziano. Hooks are Python or shell scripts that run before and/or after your project is generated.
  • Support for absolute paths to cookiecutters, thanks to @krallin.
  • Support for Mercurial version control system, thanks to @pokoli.
  • When a cookiecutter contains invalid Jinja2 syntax, you get a better message that shows the location of the TemplateSyntaxError. Thanks to @benjixx.
  • Can now prompt the user to enter values during generation from a local cookiecutter, thanks to @ThomasChiroux. This is now always the default behavior. Prompts can also be supressed with –no-input.
  • Your cloned cookiecutters are stored by default in your ~/.cookiecutters/ directory (or Windows equivalent). The location is configurable. (This is a major change from the pre-0.7.0 behavior, where cloned cookiecutters were deleted at the end of project generation.) Thanks @raphigaziano.
  • User config in a ~/.cookiecutterrc file, thanks to @raphigaziano. Configurable settings are cookiecutters_dir and default_context.
  • File permissions are now preserved during project generation, thanks to @benjixx.

Bug fixes:

  • Unicode issues with prompts and answers are fixed, thanks to @s-m-i-t-a.
  • The test suite now runs on Windows, which was a major effort. Thanks to @pydanny, who collaborated on this with me.

Other changes:

  • Quite a bit of refactoring and API changes.
  • Lots of documentation improvements. Thanks @sloria, @alex, @pydanny, @freakboy3742, @es128, @rolo.
  • Better naming and organization of test suite.
  • A CookiecutterCleanSystemTestCase to use for unit tests affected by the user’s config and cookiecutters directory.
  • Improvements to the project’s Makefile.
  • Improvements to tests. Thanks @gperetin, @s-m-i-t-a.
  • Removal of subprocess32 dependency. Now using non-context manager version of subprocess.Popen for Python 2 compatibility.
  • Removal of cookiecutter’s cleanup module.
  • A bit of setup.py cleanup, thanks to @oubiga.
  • Now depends on binaryornot 0.2.0.

0.6.4 (2013-08-21)

  • Windows support officially added.
  • Fix TemplateNotFound Exception on Windows (#37).

0.6.3 (2013-08-20)

  • Fix copying of binary files in nested paths (#41), thanks to @sloria.

0.6.2 (2013-08-19)

  • Depend on Jinja2>=2.4 instead of Jinja2==2.7.
  • Fix errors on attempt to render binary files. Copy them over from the project template without rendering.
  • Fix Python 2.6/2.7 UnicodeDecodeError when values containing Unicode chars are in cookiecutter.json.
  • Set encoding in Python 3 unicode_open() to always be utf-8.

0.6.1 (2013-08-12)

  • Improved project template finding. Now looks for the occurrence of {{, cookiecutter, and }} in a directory name.
  • Fix help message for input_dir arg at command prompt.
  • Minor edge cases found and corrected, as a result of improved test coverage.

0.6.0 (2013-08-08)

  • Config is now in a single cookiecutter.json instead of in json/.
  • When you create a project from a git repo template, Cookiecutter prompts you to enter custom values for the fields defined in cookiecutter.json.

0.5 (2013-07-28)

  • Friendlier, more simplified command line usage:

    # Create project from the cookiecutter-pypackage/ template
    $ cookiecutter cookiecutter-pypackage/
    
    # Create project from the cookiecutter-pypackage.git repo template
    $ cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git
    
  • Can now use Cookiecutter from Python as a package:

    from cookiecutter.main import cookiecutter
    
    # Create project from the cookiecutter-pypackage/ template
    cookiecutter('cookiecutter-pypackage/')
    
    # Create project from the cookiecutter-pypackage.git repo template
    cookiecutter('https://github.com/audreyr/cookiecutter-pypackage.git')
    
  • Internal refactor to remove any code that changes the working directory.

0.4 (2013-07-22)

  • Only takes in one argument now: the input directory. The output directory is generated by rendering the name of the input directory.
  • Output directory cannot be the same as input directory.

0.3 (2013-07-17)

  • Takes in command line args for the input and output directories.

0.2.1 (2013-07-17)

  • Minor cleanup.

0.2 (2013-07-17)

Bumped to “Development Status :: 3 - Alpha”.

  • Works with any type of text file.
  • Directory names and filenames can be templated.

0.1.0 (2013-07-11)

  • First release on PyPI.
 
File Type Py Version Uploaded on Size
cookiecutter-0.9.1.tar.gz (md5) Source 2015-01-20 113KB