1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
Metadata-Version: 2.1
Name: cookiecutter
Version: 2.1.1
Summary: A command-line utility that creates projects from project templates, e.g. creating a Python package project from a Python package project template.
Home-page: https://github.com/cookiecutter/cookiecutter
Author: Audrey Feldroy
Author-email: audreyr@gmail.com
License: BSD
Keywords: cookiecutter,Python,projects,project templates,Jinja2,skeleton,scaffolding,project directory,package,packaging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: binaryornot (>=0.4.4)
Requires-Dist: Jinja2 (<4.0.0,>=2.7)
Requires-Dist: click (<9.0.0,>=7.0)
Requires-Dist: pyyaml (>=5.3.1)
Requires-Dist: jinja2-time (>=0.2.0)
Requires-Dist: python-slugify (>=4.0.0)
Requires-Dist: requests (>=2.23.0)
# Cookiecutter
[](https://pypi.org/project/cookiecutter/)
[](https://pypi.org/project/cookiecutter/)
[](https://github.com/cookiecutter/cookiecutter/actions)
[](https://codecov.io/github/cookiecutter/cookiecutter?branch=master)
[](https://discord.gg/9BrxzPKuEW)
[](https://readthedocs.org/projects/cookiecutter/?badge=latest)
[](https://scrutinizer-ci.com/g/cookiecutter/cookiecutter/?branch=master)
A command-line utility that creates projects from **cookiecutters** (project templates), e.g. creating a Python package project from a Python package project template.
- Documentation: [https://cookiecutter.readthedocs.io](https://cookiecutter.readthedocs.io)
- GitHub: [https://github.com/cookiecutter/cookiecutter](https://github.com/cookiecutter/cookiecutter)
- PyPI: [https://pypi.org/project/cookiecutter/](https://pypi.org/project/cookiecutter/)
- Free and open source software: [BSD license](https://github.com/cookiecutter/cookiecutter/blob/master/LICENSE)
## Features
- Cross-platform: Windows, Mac, and Linux are officially supported.
- You don't have to know/write Python code to use Cookiecutter.
- Works with Python 3.7, 3.8, 3.9., 3.10
- 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.
### For users of existing templates
- Simple command line usage:
```bash
# 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/audreyfeldroy/cookiecutter-pypackage
# For the sake of brevity, repos on GitHub can just use the 'gh' prefix
$ cookiecutter gh:audreyfeldroy/cookiecutter-pypackage
```
- Use it at the command line with a local template:
```bash
# Create project in the current working directory, from the local
# cookiecutter-pypackage/ template
$ cookiecutter cookiecutter-pypackage/
```
- Or use it from Python:
```py
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/audreyfeldroy/cookiecutter-pypackage.git')
```
- 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:
```yaml
default_context:
full_name: "Audrey Roy Greenfeld"
email: "audreyr@gmail.com"
github_username: "audreyfeldroy"
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:
```bash
# Clone cookiecutter-pypackage
$ cookiecutter gh:audreyfeldroy/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:
```bash
cookiecutter --no-input gh:msabramo/cookiecutter-supervisor program_name=foobar startsecs=10
```
- Direct access to the Cookiecutter API allows for injection of extra context.
- Paths to local projects can be specified as absolute or relative.
- Projects generated to your current directory or to target directory if specified with `-o` option.
### For template creators
- Supports unlimited levels of directory nesting.
- 100% of templating is done with Jinja2.
- Both, directory names and filenames can be templated.
For example:
```py
{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}.py
```
- Simply define your template variables in a `cookiecutter.json` file.
For example:
```json
{
"full_name": "Audrey Roy Greenfeld",
"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"
}
```
- Pre- and post-generate hooks: Python or shell scripts to run before or after generating a project.
## 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.
### A Pantry Full of Cookiecutters
The best place to start searching for specific and ready to use cookiecutter template is [Github search](https://github.com/search?q=cookiecutter&type=Repositories).
Just type `cookiecutter` and you will discover over 4000 related repositories.
We also recommend you to check related GitHub topics.
For general search use [cookiecutter-template](https://github.com/topics/cookiecutter-template).
For specific topics try to use `cookiecutter-yourtopic`, like `cookiecutter-python` or `cookiecutter-datascience`.
This is a new GitHub feature, so not all active repositories use it at the moment.
If you are template developer please add related [topics](https://help.github.com/en/github/administering-a-repository/classifying-your-repository-with-topics) with `cookiecutter` prefix to you repository.
We believe it will make it more discoverable.
You are almost not limited in topics amount, use it!
### Cookiecutter Specials
These Cookiecutters are maintained by the cookiecutter team:
- [cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage):
ultimate Python package project template by [@audreyfeldroy's](https://github.com/audreyfeldroy).
- [cookiecutter-django](https://github.com/pydanny/cookiecutter-django):
a framework for jumpstarting production-ready Django projects quickly.
It is bleeding edge with Bootstrap 5, customizable users app, starter templates, working user registration, celery setup, and much more.
- [cookiecutter-pytest-plugin](https://github.com/pytest-dev/cookiecutter-pytest-plugin):
Minimal Cookiecutter template for authoring [pytest](https://docs.pytest.org/) plugins that help you to write better programs.
## Community
The core committer team can be found in [authors section](AUTHORS.md).
We are always welcome and invite you to participate.
Stuck? Try one of the following:
- See the [Troubleshooting](https://cookiecutter.readthedocs.io/en/latest/troubleshooting.html) page.
- Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/cookiecutter).
- You are strongly encouraged to [file an issue](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) about the problem.
Do it 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 [Discord](https://discord.gg/9BrxzPKuEW) 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](AUTHORS.md) who have pitched in to help make Cookiecutter an even better tool.
- Everyone is invited to contribute.
Read the [contributing instructions](CONTRIBUTING.md), then get started.
- Connect with other Cookiecutter contributors and users on [Discord](https://discord.gg/9BrxzPKuEW)
(note: due to work and other commitments, a core committer might not always be available)
Encouragement is unbelievably motivating.
If you want more work done on Cookiecutter, show support:
- Thank a core committer for their efforts.
- Star [Cookiecutter on GitHub](https://github.com/cookiecutter/cookiecutter).
- [Support this project](#support-this-project)
Got criticism or complaints?
- [File an issue](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) 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](https://github.com/cookiecutter/cookiecutter/issues?q=is%3Aopen) 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?
[@audreyfeldroy](https://github.com/audreyfeldroy) is available for hire for consultation or custom development.
## Support This Project
This project is run by volunteers.
Shortly we will be providing means for organizations and individuals to support the project.
## Code of Conduct
Everyone interacting in the Cookiecutter project's codebases and documentation is expected to follow the [PyPA Code of Conduct](https://www.pypa.io/en/latest/code-of-conduct/).
This includes, but is not limited to, issue trackers, chat rooms, mailing lists, and other virtual or in real life communication.
## Creator / Leader
This project was created and is led by [Audrey Roy Greenfeld](https://github.com/audreyfeldroy).
She is supported by a team of maintainers.
|
