Skip to content

Latest commit

 

History

History
829 lines (617 loc) · 40.7 KB

README.rst

File metadata and controls

829 lines (617 loc) · 40.7 KB
Raw

Cookiecutter

https://travis-ci.org/audreyr/cookiecutter.svg?branch=master https://ci.appveyor.com/api/projects/status/github/audreyr/cookiecutter?branch=master https://codecov.io/github/audreyr/cookiecutter/coverage.svg?branch=master Documentation Status Code Health Scrutinizer Code Quality

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/3ac078356adf5a1a72042dfe72ebfa4a9cd5ef38/logo/cookiecutter_medium.png

We are proud to be an open source sponsor of PyCon 2016.

Features

Did someone say features?

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

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

  • 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": "[email protected]",
    "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: "[email protected]"
    github_username: "audreyr"
cookiecutters_dir: "~/.cookiecutters/"

  • Cookiecutters (cloned Cookiecutter project templates) are put into ~/.cookiecutters/ by default, or cookiecutters_dir if specified.

  • If you have already cloned a cookiecutter into ~/.cookiecutters/, you can reference it by directory name:

    # Clone cookiecutter-pypackage
$ cookiecutter gh:audreyr/cookiecutter-pypackage
# Now you can use the already cloned cookiecutter by name
$ cookiecutter cookiecutter-pypackage

  • 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

  • Inject extra context with command-line arguments:

    $ cookiecutter --no-input gh:msabramo/cookiecutter-supervisor program_name=foobar startsecs=10

  • 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

Making great cookies takes a lot of cookiecutters and contributors. We're so pleased that there are many Cookiecutter project templates to choose from. We hope you find a cookiecutter that is just right for your needs.

Cookiecutter Specials

These Cookiecutters are maintained by the cookiecutter team:

Categories of Cookiecutters

Python | Python-Django | Python-Pyramid | Cookiecutter (meta) | Ansible | Git | C | C++ | C# | Common Lisp | Elm | Golang | Java | JS | Kotlin | LaTeX/XeTeX | PHP | Berkshelf-Vagrant | HTML | Scala | 6502 Assembly | Data Science | Tornado | Reproducible Science | Continuous Delivery

If you don't find a cookiecutter that suits your needs here, please consider writing or suggesting one. We wish for our users to find a solution for their use cases, and we provide a list of other projects that we do not maintain for your convenience (please see the Similar Projects section).

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 on Gitter 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 on Gitter:

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.

Support This Project

This project is run by volunteers. Please support them in their efforts to maintain and improve Cookiecutter:

You can also support this project by taking our Python packaging course:

Creating and Distributing Python Packages

Also available in Spanish:

Creating and Distributing Python Packages ES

Backers

We would like to thank the following people for supporting us:

  • Alex DeBrie
  • Alexandre Y. Harano
  • Bruno Alla
  • Carol Willing
  • Russell Keith-Magee

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.

A Pantry Full of 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

Python-Pyramid

  • pyramid-cookiecutter-alchemy: A Cookiecutter (project template) for creating a Pyramid project using SQLite for persistent storage, SQLAlchemy for an ORM, URL dispatch for routing, and Jinja2 for templating.
  • pyramid-cookiecutter-starter: A Cookiecutter (project template) for creating a Pyramid starter project using URL dispatch for routing and either Jinja2, Chameleon, or Mako for templating.
  • pyramid-cookiecutter-zodb: A Cookiecutter (project template) for creating a Pyramid project using ZODB for persistent storage, traversal for routing, and Chameleon for templating.
  • substanced-cookiecutter: A cookiecutter (project template) for creating a Substance D starter project. Substance D is built on top of Pyramid.
  • cookiecutter-pyramid-talk-python-starter: An opinionated Cookiecutter template for creating Pyramid web applications starting way further down the development chain. This cookiecutter template will create a new Pyramid web application with email, sqlalchemy, rollbar, and way more integrated.

Cookiecutter (meta)

Meta-templates for generating Cookiecutter project templates.

Ansible

  • cookiecutter-molecule: Create Molecule roles following community best practices, with an already implemented test infrastructure leveraging Molecule, Docker and Testinfra.
  • cookiecutter-ansible-role: A template to create ansible roles. Forget about file creation and focus on actions.
  • cookiecutter-ansible-role-ci: Create Ansible roles following best practices, with an already implemented test infrastructure leveraging Test-kitchen, Docker and InSpec.

Git

C

C++

C#

Common Lisp

Elm

Golang

Java

JS

Kotlin

LaTeX/XeTeX

PHP

Sublime Text

Berkshelf-Vagrant

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

HTML

Scala

6502 Assembly

Data Science

Reproducible Science

  • cookiecutter-reproducible-science: A cookiecutter template to start a reproducible and transparent science project including data, models, analysis, and reports (i.e., your scientific paper) with close resemblances to the philosophy of Cookiecutter Data Science.

Data Driven Journalism

  • cookiecutter-data-driven-journalism: A cookiecutter template to facilitate transparency in data journalism with consistant organisation of data journalism projects and some pre-populated files (including .gitignore, README, AUTHORS)

Continuous Delivery

  • painless-continuous-delivery: A cookiecutter template for software development setups with continuous delivery baked in. Python (Django, Flask), and experimental PHP support.
  • cookiecutter-devenv: A template to add a development and ci environment to an existing project.

Cloud Tools

Tornado

Other

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.