Using and Mastering Cookiecutter Transcripts
Chapter: Creating Cookiecutter templates
Lecture: A bare template
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
So let's start this chapter by building some kind of template. And this won't really be so much programming language template,
0:09
it's just to manage some files, we'll just distribute text files as you saw on the data science repeatable data science thing,
0:15
these can be all sorts of stuff, HTML files, and LaTeX and Whatnot, so just to keep things simple and neutral,
0:22
we'll just sort of manage a bunch of files here, so notice there is nothing in this directory, but it's chapter 5
0:27
from the source code repository so you will be able to go and check this out. So let's start over here, by just creating some structure,
0:35
so the first thing that we're going to need to do, so we want to create a folder,
0:38
and in this folder, this has a subset as a subdirectory and subcontent of this folder, this is where the thing we give to the users goes.
0:48
Now, we have to give it a funky name, it has to be {{cookiecutter.something}} and notice this project name here is going to appear again.
0:57
Okay, and then next to this, we're going to need, right next to this one, we are going to need to create a cookiecutter.json so we can say touch okay,
1:09
so here we have a cookiecutter.json and let me put this into Visual Studio Code, we want to make some more files in here, so let's go in here
1:21
and we're going to make a file, I'll call this colors.txt, we'll play with that throughout this section and we'll make another file called summary
1:30
and this called readme.md, md for Markdown, it's pretty common, so the first thing we need to pay attention to is this cookicutter.json
1:39
so here what we put is basically a key value JSON object. Okay, and the JSON object is going to contain some keys,
1:50
those keys both specify the default values and the prompt we're going to actually run,
1:55
so let's start like this, and it already knows it's JSON, okay, that's good,
2:00
so we're going to come in here and we'll put things like project_name and then, we could leave it blank, which is probably not a great idea,
2:07
let's give it a little default here, I'll call it my_proj for now that is going to be the default,
2:13
they can change this name but that is what the default is, let's also put in here creator, and I'll just put something like this, like your name.
2:21
We saw that we could put this into our default file, and have this change and insert our name there, so we can go ahead and do that in a little bit.
2:31
Let's just have one more thing, favorite_color, and let's just say everybody's favorite color is blue but they can enter whatever they want.
2:41
So we have our project name here, let's go back to our readme, and we'll say project and then in here we can use what is in our template,
2:49
so we can use these names as you can see in file structure, and here is a directory, we can have a file named, whatever that is,
2:57
let's actually do that, that would be cool, so if we come in here,
2:59
create a file and call this project_name, we'd like to have it this way but of course,
3:04
it's going to be {{cookiecutter.project_name}}.txt and it will also be project summary or something like that and again, inside these files,
3:15
we can have {{cookiecutter.project_name}}, project is like this creator it's going to be similar but it's going to be creator, and so on.
3:26
So this projects will get named based on what we call the project name,
3:29
this file will be named as well, its contents will be changed so I'll have this over here,
3:34
let's put this like that in our readme and let's make this our little header and we'll have this is the description of the project.
3:43
The creator, we'll put a little creator here, favorite color is, and we'll do favorite color, okay, so I think we're pretty good,
3:58
I don't have anything in colors let's just put the favorite color here again,
4:01
just to make it appear in some places, you can have content that are unchanged,
4:05
you can just have plain text like this is plain text, so whatever we put here, it'll just get copied over but it finds a Jinja2 expression
4:12
it's going to grab that and evaluate it. Okay, so I think we have our basic project, let's have a look.
4:21
So if we look at it like this, we've got our cookicutter.json. we've in our main project, now our main project is called just this,
4:29
is that right, let's move that really quick, that is probably not the best place,
4:33
so let's call this cookiecutter that is a convention to start a cookiecutter and we'll call this colors, okay, and put that as a subdirectory,
4:41
okay, so this would be the root of our git repo, we could point to it or we could actually just work with the project structure here,
4:50
so it looks like this and if we have let's say go to that cookicutter thing, and just copy this directory here, we should be able to run this,
5:02
alright, so let's- so you don't want to run this in the cookicutter template, that's not going to be good at all, what we got to do is we can run it,
5:10
actually I could create the project right next to it, not very common but that is what we're going to do,
5:15
so we come over here and say cookiecutter and then I just give it the path to the template, so I could say ./cookicutter-colors
5:22
I could give it that full directory, I copied if it was somewhere remote like on GitHub, I could give it the URL and then we'd clone it
5:29
and then I wouldn't have to know its path anymore. So let's go ahead and run this, clear the screen, go,
5:34
it's going to ask what is my project let's just call it the_first_color,
5:38
okay, that is going to be the name of our project, my name I'll type it in for now, we'll see that we can change this creator here, and then,
5:48
let's just go with the default blue, I could put something else, but blue seems fine. Great, now if we look at the tree, you can see
5:54
we have two sort of top subdirectories here, and we have this one which has this Jinja expression project name,
6:03
colors, readme and this file whose name is also the Jinja expression for the project name, and look what we actually created,
6:10
here is the directory named like that, and here is that file.txt that it was named.
6:14
So, let's have a look at the first, so if we come down, here, if we look at colors, you can see this says blue and this is plain text
6:20
so blue is the expression I put that is the default value, and this is plain that was unmodified text, this one was just an empty file,
6:28
and this one if we look at it, it will say project the_first_name, we could even preview, project the first color, this is the description of project,
6:35
the creator Michael Kenendy's favorite color is blue. So you see how all this works, so let's go back here to our JSON file and notice,
6:42
if I put this next to the thing we ran here, notice the three values we ask here, project name, creator and favorite color, and notice right here,
6:51
those were the three prompts and their values with the default we were given,
6:55
so it's really this cookicutter.json that derives the user input and then after that, it's handed off to basically just the folder structure
7:03
and the static files themselves, now, it turns out, that we can actually have like in here you saw we had a Jinja expression,
7:10
for the creator and the project name, you could actually have expressions that are evaluated in these things as well,
7:17
so you could do sort of conditional stuff that you can do with Jinja and so we can get more advanced in what happens inside those files
7:23
and have further control over that, But, even already, we have a very powerful creation mechanism, right,
7:31
we can create these files and rename them, move them around, fill in default values, conditionally include or exclude fragments of code
7:38
using Jinja conditional statements, things like that. So there you go, we've created our first template,
7:46
I suggest that if you want to practice this, go and create a template for some project that you typically do, try to create this folder
7:53
it always has cookicutter-the name of the template and then the cookicutter.json
7:57
and then the subdirectory is always named as something to do with the project or very often is named something to do with the project
8:05
and then you have all of your pieces underneath. Okay, so give this a shot and we'll keep digging into this
8:11
to see many more cool features that Cookiecutter has in store for us.