使用 Cookiecutter 建立專案模版

本篇介紹使用Cookiecutter來建立專案/項目模板。

Cookiecutter是一個用來建立專案模板(project template)的命令列工具。所謂的專案模板是指由特定目錄、檔案及內容所組成的專案結構。

Cookiecutter是Python的一個套件，因此要使用Cookiecutter前必須在環境裝好Python。注意Cookiecutter僅支援Python 2.7、3.5、3.6、3.7、3.8、PyPy、PyPy3。

本範例參考Learn the Basics of Cookiecutter by Creating a Cookiecutter

範例環境：

• macOS Big Sur
• Python 3.9

安裝

安裝Cookiecutter只要在終端機輸入$ pip3 install cookiecutter即可。

$ pip3 install cookiecutter
Collecting cookiecutter
  Downloading cookiecutter-1.7.3-py2.py3-none-any.whl (34 kB)
Collecting python-slugify>=4.0.0
  Downloading python_slugify-5.0.2-py2.py3-none-any.whl (6.7 kB)
...

安裝好後輸入cookiecutter --version確認是否安裝成功。

$ cookiecutter --version
Cookiecutter 1.7.3 from /Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages (Python 3.9)

設定模板

在任意目錄建立一個資料夾，本範例建立的資料夾名稱為hellocookiecutter，而此名稱將會是Cookiecutter的模板名稱。例如模板是用來建立Python專案可能會命名為cookiecutter-python、用來建立Flask專案可能命名為cookiecutter-flask。

在hellocookiecutter目錄下建立一個目錄名稱為{{cookiecutter.directory_name}}。
然後在{{cookiecutter.directory_name}}目錄中建立一個Python檔名為{{cookiecutter.file_name}}.py。

~/../hellocookiecutter$ mkdir {{cookiecutter.directory_name}}
~/../hellocookiecutter$ touch {{cookiecutter.file_name}}.py

以文字編輯器開啟{{cookiecutter.file_name}}.py並加入以下內容。

{{cookiecutter.file_name}}.py

print("Hello, {{cookiecutter.greeting}}!")

上面建立的目錄、檔案及內容中的{{...}}是Cookiecutter的模板標籤(template tags)，模板標籤中的內容會被Cookiecutter模板配置檔中對應的屬性內容給替換；而套用的模版配置檔名稱即為模板標籤內開頭的cookiecutter。因此上面範例的模板配置檔會是cookiecutter.json。

在hellocookiecutter目錄下建立模板配置檔cookiecutter.json並使用編輯器設定內容如下。裡面的屬性對應到模板標籤cookiecutter.後的名稱，屬性值則用來替換標籤模板的內容。

cookiecutter.json

{
  "directory_name": "demo",
  "file_name": "hello",
  "greeting": "Cookiecutter"
}

到此便完成Cookiecutter的模板設定。

建立專案

接著使用Cookiecutter命令$ cookiecutter <template_dir>建立專案，<template_dir>要使用的模板路徑及名稱，本範例的模板為hellocookiecutter。例如專案要建立在與hellocookiecutter目錄中的project目錄下，因此在project中以命令列輸入$ cookiecutter ../hellocookiecutter開始建立專案。

~/../project$ cookiecutter ../hellocookiecutter
directory_name [demo]:
file_name [hello]:
greeting [Cookiecutter]:

執行中會提示模板配置檔cookiecutter.json替換模板標籤內容的屬性值，在此可另外輸入要替換的內容，或是直接按Enter略過。

執行後便可在project目錄中看到Cookiecutter依模板及配置檔生成的專案目錄、檔案及內容。模板標籤{{...}}中的內容皆被cookiecutter.json的對應屬性值替換了。

~/../project$ ls
demo
~/../project$ cd demo
~/../project/demo$ ls
hello.py
~/../project/demo$ python3 hello.py
Hello, Cookiecutter!

範例中建立的目錄及檔案結構如下：

~/../
├── hellocookiecutter/
│   └── {{cookiecutter.directory_name}}/
│      └── {{cookiecutter.file_name}}.py
└── project/
    └── demo/
        └── hello.py

使用Git Repository模板

除了使用檔案目錄中的模板，也可以把模板放在git repository如GitHub或GitLab上，並在命令列輸入cookiecutter <git_repo>來建立專案，<git_repo>為存放模板的git repository位址。

例如我把上面範例放到https://github.com/matthung0807/hellocookiecutter.git，並使用Cookiecutter在建立轉案如下，執行中一樣會提示輸入替換模板標籤的屬性值。

$ cookiecutter https://github.com/matthung0807/hellocookiecutter
directory_name [demo]:
file_name [hello]:
greeting [Cookiecutter]: