13.4 【项目生成】cookiecutter 的使用

IDE都会有一套生成新项目的向导(Wizard),通过点点点,就可以得到一个可以运行的某类程序。 这样的程序,具备了推荐的项目结构,配置的基本的编译、打包、测试,尽管功能只是一个helloworld。 这个功能,极大地降低了初学者的进入门槛,也统一了某类项目的文件结构,是一个了不起的进步。 最早使用这类手段的,似乎是Visual Studio。

令人惋惜的是,Python的IDE——PyCharm并不自带这个功能。 这其中,也有Python项目千变万化的因素。 Python的适用范围太广,从桌面到服务器,从游戏到数据分析,都做一套显然投入太大。 而Python又是一门解释型语言,随便写个文件也能直接执行,似乎没有这个必要。

然而,我要说,还是有必要的!

因为Python系缺失一个Wizard,也缺少项目结构的标准,于是出现了cookiecutter。 这是一个项目生成器,也可称为引擎,因为它只完成了最核心的功能。 真正决定一个项目长什么样的模板,却可以自由定制。 也因此,它能生成任何一种语言的项目。

1. 快速安装

$ pip install cookiecutter

cookiecutter就是一个已经发布的Python包,因此用Python的手段可以直接安装。

对于非Python系的程序员来说,也可以使用包管理器的方式安装。

# For Mac
$ brew install cookiecutter
# For Debian/Ubuntu
$ sudo apt install cookiecutter

2. 如何使用

首先,寻找一个合适的cookiecutter项目。 最主要的方式,就是访问其GitHub主页的A Pantry Full of Cookiecutters

如果挑选完毕(这里以cookiecutter-pypackage为例),则可直接执行cookiecutter生成项目。

$ cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git
full_name [Yan QiDong]:
email [yanqd0@outlook.com]:
github_username [yanqd0]:
project_name [Python Boilerplate]: trycookie
project_slug [trycookie]:
project_short_description [Python Boilerplate contains all the boilerplate you need to create a Python package.]: A description
pypi_username [yanqd0]:
version [0.1.0]:
use_pytest [n]:
use_pypi_deployment_with_travis [y]:
add_pyup_badge [n]:
Select command_line_interface:
1 - Click
2 - No command-line interface
Choose from 1, 2 (1, 2) [1]:
create_author_file [y]:
Select open_source_license:
1 - MIT license
2 - BSD license
3 - ISC license
4 - Apache Software License 2.0
5 - GNU General Public License v3
6 - Not open source
Choose from 1, 2, 3, 4, 5, 6 (1, 2, 3, 4, 5, 6) [1]:

在项目生成过程中,会产生一些提示,需要输入对应信息。 这和各类Wizard的GUI中,填写项目名、包名什么的,是同类操作。 以上是,除了项目名叫trycookie,基本都选默认的一个结果。

查看项目结构:

$ tree -a trycookie
trycookie
├── .editorconfig
├── .github
│   └── ISSUE_TEMPLATE.md
├── .gitignore
├── .travis.yml
├── AUTHORS.rst
├── CONTRIBUTING.rst
├── HISTORY.rst
├── LICENSE
├── MANIFEST.in
├── Makefile
├── README.rst
├── docs
│   ├── Makefile
│   ├── authors.rst
│   ├── conf.py
│   ├── contributing.rst
│   ├── history.rst
│   ├── index.rst
│   ├── installation.rst
│   ├── make.bat
│   ├── readme.rst
│   └── usage.rst
├── requirements_dev.txt
├── setup.cfg
├── setup.py
├── tests
│   ├── __init__.py
│   └── test_trycookie.py
├── tox.ini
└── trycookie
    ├── __init__.py
    ├── cli.py
    └── trycookie.py

4 directories, 30 files

如此庞大而复杂的一个项目结构,融合了作者audreyr对一个开源PyPI项目的理解。 虽然未必适用于任何一个人,但对于什么也不懂的菜鸟来说,却无疑是福音。

3. 基本原理

cookiecutter的工作原理,是先下载一个模板项目,然后替换模板项目的某些内容,生成新的项目。 在以上的示例中,https://github.com/audreyr/cookiecutter-pypackage.git就是一个项目的Git链接。 这可以换成任何一个可以用git clone来下载的链接,包括各种私有Git托管平台。

如果是GitHub,还可以用以下的等效形式:

cookiecutter gh:audreyr/cookiecutter-pypackage

cookiecutter的简短形式,支持以下三种平台。

Platform

abbreviation

GitHub

gh

BitBucket

bb

GitLab

gl

cookiecutter也支持Mercurial(hg)。

cookiecutter hg+ssh://hg@bitbucket.org/audreyr/cookiecutter-pypackage

使用过模板的项目,默认都已经被下载到~/.cookiecutter目录下。 如果需要再次使用,而又无需更新,可以直接用项目名。

cookiecutter cookiecutter-pypackage

利用这个特点,可以先用各种手段,把模板项目下载到~/.cookiecutter目录下,再来使用。

参考:Usage — cookiecutter 1.6.0 documentation

4. 配置文件

默认情况下,~/.cookiecutterrc就是配置文件。 它实际上是一个YAML文件。 以下是孤的配置文件示例。

# vim: set filetype=yaml:

default_context:
  full_name: "Yan QiDong"
  email: "yanqd0@outlook.com"
  github_username: "yanqd0"
cookiecutters_dir: "~/.cookiecutters/"
abbreviations:
    pp: https://github.com/audreyr/cookiecutter-pypackage.git
    gh: https://github.com/{0}.git

可配置项中,default_context是设置生成项目时,一些提示信息的默认参数。 cookiecutters_dir则是项目的下载位置,一般默认就好。 abbreviations是自定义简短形式,属于高级定制功能,仅适用于重度用户。 通常,填一填default_context就好。

如果对~/.cookiecutterrc这个配置文件的名称和位置不满意, 可以通过环境变量COOKIECUTTER_CONFIG, 或者在命令行指定参数--config-file来指定新的配置文件。

参考:User Config (0.7.0+) — cookiecutter 1.6.0 documentation

5. 总结一下

cookiecutter是一个简单好用的项目生成器引擎,并且已经有很多各种类型的模板。 除了Python项目,还有很多其它语言的项目模板。 它可以极大地省去一个项目初始化的重复劳动,也可以帮助菜鸟程序员成长。

当然,如果不满意,还是可以自己修改、定制模板的。