文章详情页您现在的位置是：网站首页>文章详情

工程项目模板工具cookiecutter的使用(一)

Jeyrce.Lu 发表于：2020年4月2日 20:33 分类：【Python】 4732次阅读

cookiecutter是一种用python开发的工程模板工具，通过它可以快速创建一个固定结构的项目结构。

快速开始

（1）安装cookiecutter

pip install --upgrade cookiecutter

（2）下载一个示例模板

git clone git@github.com:audreyr/cookiecutter-pypackage.git

（3）使用模板创建项目

cookiecutter cookiecutter-pypackage/

之后命令行会出现交互式输入，手动输入几项配置之后就能得到一个项目

cookiecutter
├── AUTHORS.rst
├── CONTRIBUTING.rst
├── cookiecutter
│   ├── cookiecutter.py
│   └── __init__.py
├── docs
│   ├── authors.rst
│   ├── conf.py
│   ├── contributing.rst
│   ├── history.rst
│   ├── index.rst
│   ├── installation.rst
│   ├── make.bat
│   ├── Makefile
│   ├── readme.rst
│   └── usage.rst
├── HISTORY.rst
├── LICENSE
├── Makefile
├── MANIFEST.in
├── README.rst
├── requirements_dev.txt
├── setup.cfg
├── setup.py
├── tests
│   ├── __init__.py
│   └── test_cookiecutter.py
└── tox.ini

实际上，上面的一个步骤也可以替换，cookiecutter不仅可以从本地模板文件生成项目，也可直接通过git仓库生成。例如上面的（2）和（3）可以合并为一个步骤：

cookiecutter git@github.com:audreyr/cookiecutter-pypackage.git

之后手动输入关键信息得到的结果和之前一样，但是你会发现这时当前路径下没有cookiecutter-pypackage/这个目录，但是在~/.cookiecutters/下面找见他，通过cookiecutter + 远程地址都会将仓库克隆到这里；知道了这个之后就有一个小技巧，可以重复使用已经克隆下来的模板而不需要每次都从远程拉取，毕竟国内github的速度还是很不友好的。同理，不仅是github的仓库，其他仓库和私有仓库也可以这种通过这种方式创建项目。

编写模板

以上能够按照固定格式创建项目的关键有两个，第一是我们在电脑上安装了一个cookiecutter可执行文件，第二是cookiecutter加载的模板项目。那么问题来了，项目不可能都和这个模板的结构一样，我们实际生产中会需要多种多样的项目结构，因此我们需要自定义自己的项目结构模板。

cookiecutter的原理实际上和我们以前的web开发用到的模板语言类似，采用{{ tag }}包裹的一些变量来渲染项目中的内容、文件名、路径等，{{ tag }}的值来源于我们手动输入或者模板项目中的cookiecutter.json文件，接下来我们就来创建一个自己的cookiecutter模板。

# 创建这样一个项目结构
cookiecutterHello/
├── {{cookiecutter.dir_name}}
│   └── {{cookiecutter.dir_name}}.py
└── cookiecutter.json

在{{cookiecutter.dir_name}}.py中写入如下内容:

# coding: utf-8
"""
Created by Jeeyshe 2020/4/2 下午9:54, contact with jeeyshe@gmail.com or website https://www.lujianxin.com
---------------------------------------------------------------------------------------------------------
>>> popurse of the file
"""

print("Hello {{cookiecutter.author}} !")

在cookiecutter.json中写入如下内容:

{
  "dir_name": "hello",
  "author": "jeeyshe"
}

现在我们就可以使用cookiecutter cookiecutterHello/来创建一个项目了，过程中会提示让你输入dir_name和author两个值，直接回车则会读取cookiecutter.json中的值:

hello/
└── hello.py

# hello.py文件内容已经是替换了之后的
# coding: utf-8
"""
Created by Jeeyshe 2020/4/2 下午9:54, contact with jeeyshe@gmail.com or website https://www.lujianxin.com
---------------------------------------------------------------------------------------------------------
>>> popurse of the file
"""

print("Hello jeeyshe !")

此时一个简单的项目示例就完成了，你也可以将这个项目上传到github，这样一来别人就可以通过cookiecutter + 仓库地址来快速生成项目了。此处我们用python的项目作为例子，实际上cookiecutter是不局限语言的，甚至用它来生成文档材料也是可以的。

模板的Hook机制

hook机制实际上就是允许你定义一些操作，这些操作可以在你使用模板创建项目之前或者之后执行。hook支持python和shell两种脚本，增加hook的模板结构如下:

(python3) jeeyshe@jeeyshe-PC:~/Code/python$ tree cookiecutterHello/
cookiecutterHello/
├── {{cookiecutter.dir_name}}
│   └── {{cookiecutter.dir_name}}.py
├── cookiecutter.json
└── hooks
    ├── post_gen_project.py
    └── pre_gen_project.py
    
# 如果是shell脚本，则将pre_gen_project.py改为pre_gen_project.sh即可

hook脚本执行完退出时必须返回一个0值，否则创建过程会终止，已生成的文件也会被清除。hook脚本中也可以使用模板变量。以下是一个创建项目前检查项目名称合法性的例子。

# coding: utf-8
"""
Created by Jeeyshe 2020/4/2 下午10:23, contact with jeeyshe@gmail.com or website https://www.lujianxin.com
---------------------------------------------------------------------------------------------------------
>>> 创建项目前的验证及操作
"""
import sys
import re


def is_module_name_valid(module_name):
    pattern = re.compile(r"^[a-zA-Z_][a-zA-Z0-9-_]{,20}$")
    return pattern.match(module_name)


if __name__ == '__main__':
    module_name = '{{cookiecutter.dir_name}}'
    if is_module_name_valid(module_name):
        print("Module name `{{cookiecutter.dir_name}}` is valid.")
    else:
        print("Module name must startswith num|letter|_ and fill with num|letter|_|- and no more than 21 length.")
        sys.exit(1)
    sys.exit(0)

基于这样的道理，我们还可以在项目创建的前后做很多事情，比如下载依赖，下载其他工具，做一些其他的验证等。