Skip to main content

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

Project description

https://img.shields.io/pypi/v/cookiecutter.svg https://travis-ci.org/audreyr/cookiecutter.png?branch=master https://ci.appveyor.com/api/projects/status/github/audreyr/cookiecutter?branch=master https://img.shields.io/pypi/dm/cookiecutter.svg https://codecov.io/github/audreyr/cookiecutter/coverage.svg?branch=master https://badges.gitter.im/JoinChat.svg Documentation Status Code Health

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

https://raw.github.com/audreyr/cookiecutter/aa309b73bdc974788ba265d843a65bb94c2e608e/cookiecutter_medium.png

Features

Did someone say features?

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

  • Works with Python 2.7, 3.3, 3.4, 3.5, 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

Python-Django

C

C++

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

C#

Common Lisp

JS

LaTeX/XeTeX

Berkshelf-Vagrant

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

HTML

Scala

6502 Assembly

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

  • Skaffold python and json config based django/MVC generator, with some add-ons and integrations.

Community

The core committer team is @audreyr, @pydanny, @michaeljoseph, @pfmoore, and @hackebrot. 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.

Code of Conduct

Everyone interacting in the Cookiecutter project’s codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct.

History

1.1.0 (2015-09-26) Snickerdoodle

The primary goal of this release was to add copy without render and a few additional command-line options such as –overwrite-if-exists, —replay, and output-dir.

Features:

  • Added copy without render feature, making it much easier for developers of Ansible, Salt Stack, and other recipe-based tools to work with Cookiecutter. Thanks to @osantana and @LucianU for their innovation, as well as @hackebrot for fixing the Windows problems (#132, #184, #425).

  • Added specify output directory, thanks to @tony and @hackebrot (#531, #452),

  • Abort template rendering if the project output directory already exists, thanks to @lgp171188 (#470, #471).

  • Add a flag to overwrite existing output directory, thanks to @lgp171188 for the implementation (#495) and @schacki, @ionelmc, @pydanny and @hackebrot for submitting issues and code reviews (#475, #493).

  • Remove test command in favor of tox, thanks to @hackebrot (#480).

  • Allow cookiecutter invocation, even without installing it, via python -m cookiecutter.cli, thanks to @vincentbernat and @hackebrot (#449, #487).

  • Improve the type detection handler for online and offline repositories, thanks to @charlax (#490).

  • Add replay feature, thanks to @hackebrot (#501).

  • Be more precise when raising an error for an invalid user config file, thanks to @vaab and @hackebrot (#378, #528).

  • Added official Python 3.5 support, thanks to @pydanny and @hackebrot (#522).

Other Changes:

1.0.0 (2015-03-13) Chocolate Chip

The goals of this release was to formally remove support for Python 2.6 and continue the move to using py.test.

Features:

  • Convert the unittest suite to py.test for the sake of comprehensibility, thanks to @hackebrot (#322, #332, #334, #336, #337, #338, #340, #341, #343, #345, #347, #351, #412, #413, #414).

  • Generate pytest coverage, thanks to @michaeljoseph (#326).

  • Documenting of Pull Request merging and HISTORY.rst maintenance, thanks to @michaeljoseph (#330).

  • Large expansions to the tutorials thanks to @hackebrot (#384)

  • Switch to using Click for command-line options, thanks to @michaeljoseph (#391, #393).

  • Added support for working with private repos, thanks to @marctc (#265).

  • Wheel configuration thanks to @michaeljoseph (#118).

Other Changes:

0.9.0 (2015-01-13)

The goals of this release were to add the ability to Jinja2ify the cookiecutter.json default values, and formally launch support for Python 3.4.

Features:

  • Python 3.4 is now a first class citizen, thanks to everyone.

  • cookiecutter.json values are now rendered Jinja2 templates, thanks to @bollwyvl (#291).

  • Move to py.test, thanks to @pfmoore (#319) and @ramiroluz (#310).

  • Add PendingDeprecation warning for users of Python 2.6, as support for it is gone in Python 2.7, thanks to @michaeljoseph (#201).

Bug Fixes:

  • Corrected typo in Makefile, thanks to @inglesp (#297).

  • Raise an exception when users don’t have git or hg installed, thanks to @pydanny (#303).

Other changes:

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.

Roadmap

https://github.com/audreyr/cookiecutter/milestones?direction=desc&sort=due_date&state=open

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cookiecutter-1.1.0.tar.gz (138.4 kB view hashes)

Uploaded Source

Built Distribution

cookiecutter-1.1.0-py2.py3-none-any.whl (42.8 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page