13.4 【项目生成】cookiecutter 的使用 ==================================== 转载自：https://note.qidong.name/2018/10/cookiecutter/ IDE都会有一套生成新项目的向导（Wizard），通过点点点，就可以得到一个可以运行的某类程序。 这样的程序，具备了推荐的项目结构，配置的基本的编译、打包、测试，尽管功能只是一个\ ``helloworld``\ 。 这个功能，极大地降低了初学者的进入门槛，也统一了某类项目的文件结构，是一个了不起的进步。 最早使用这类手段的，似乎是Visual Studio。 令人惋惜的是，Python的IDE——PyCharm并不自带这个功能。 这其中，也有Python项目千变万化的因素。 Python的适用范围太广，从桌面到服务器，从游戏到数据分析，都做一套显然投入太大。 而Python又是一门解释型语言，随便写个文件也能直接执行，似乎没有这个必要。 然而，我要说，还是有必要的！ 因为Python系缺失一个Wizard，也缺少项目结构的标准，于是出现了\ `cookiecutter `__\ 。 这是一个项目生成器，也可称为引擎，因为它只完成了最核心的功能。 真正决定一个项目长什么样的模板，却可以自由定制。 也因此，它能生成任何一种语言的项目。 1. 快速安装 ----------- .. code:: sh $ pip install cookiecutter `cookiecutter `__\ 就是一个已经发布的Python包，因此用Python的手段可以直接安装。 对于非Python系的程序员来说，也可以使用包管理器的方式安装。 .. code:: sh # For Mac $ brew install cookiecutter # For Debian/Ubuntu $ sudo apt install cookiecutter 2. 如何使用 ----------- 首先，寻找一个合适的\ `cookiecutter `__\ 项目。 最主要的方式，就是访问其GitHub主页的\ `A Pantry Full of Cookiecutters `__\ 。 如果挑选完毕（这里以\ `cookiecutter-pypackage `__\ 为例），则可直接执行\ ``cookiecutter``\ 生成项目。 .. code:: sh $ 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``\ ，基本都选默认的一个结果。 查看项目结构： .. code:: sh $ 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，还可以用以下的等效形式： .. code:: sh cookiecutter gh:audreyr/cookiecutter-pypackage `cookiecutter `__\ 的简短形式，支持以下三种平台。 ====================================== ============ Platform abbreviation ====================================== ============ `GitHub `__ ``gh`` `BitBucket `__ ``bb`` `GitLab `__ ``gl`` ====================================== ============ `cookiecutter `__\ 也支持Mercurial（\ ``hg``\ ）。 .. code:: sh cookiecutter hg+ssh://hg@bitbucket.org/audreyr/cookiecutter-pypackage 使用过模板的项目，默认都已经被下载到\ ``~/.cookiecutter``\ 目录下。 如果需要再次使用，而又无需更新，可以直接用项目名。 .. code:: sh cookiecutter cookiecutter-pypackage 利用这个特点，可以先用各种手段，把模板项目下载到\ ``~/.cookiecutter``\ 目录下，再来使用。 参考：\ `Usage — cookiecutter 1.6.0 documentation `__ 4. 配置文件 ----------- 默认情况下，\ ``~/.cookiecutterrc``\ 就是配置文件。 它实际上是一个YAML文件。 以下是孤的配置文件示例。 .. code:: 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项目，还有很多其它语言的项目模板。 它可以极大地省去一个项目初始化的重复劳动，也可以帮助菜鸟程序员成长。 当然，如果不满意，还是可以自己修改、定制模板的。