11.2. Using Cookiecutter to Create New Python Projects¶
We call the folder that contains all the source code, documentation, tests, and other files related to a project the working directory or working tree in Git parlance, and project folder more generally. The files in the working directory are collectively called the working copy. Before we create our Git repo, let’s create the files for a Python project.
Every programmer has a preferred method for doing so. Even so, Python projects follow conventions for folder names and hierarchies. Your simpler programs might consist of a single .py file. But as you tackle more sophisticated projects, you’ll start to include additional .py files, data files, documentation, unit tests, and more. Typically, the root of the project folder contains a src folder for the .py source code files, a tests folder for unit tests, and a docs folder for any documentation (such as those generated by the Sphinx documentation tool). Other files contain project information and tool configuration: README.md for general information, .coveragerc for code coverage configuration, LICENSE.txt for the project’s software license, and so on. These tools and files are beyond the scope of this book, but they’re worth investigating. As you gain more coding experience, re-creating the same basic files for new programming projects becomes tedious. To speed up your coding tasks, you can use the cookiecutter Python module to create these files and folders automatically. You’ll find the full documentation for both the module and the Cookiecutter command line program at https:// cookiecutter.readthedocs.io/.
To install Cookiecutter, run pip install –user cookiecutter (on Windows) or pip3 install –user cookiecutter (on macOS and Linux). This installa- tion includes the Cookiecutter command line program and the cookiecutter Python module. The output might warn you that the command line program is installed to a folder not listed in the PATH environment variable:
Installing collected packages: cookiecutter WARNING: The script cookiecutter.exe is installed in 'C:UsersAlAppDataRoamingPythonPython38Scripts' which is not on PATH. Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
In this chapter, we’ll create a repo for a module named wizcoin , which handles the galleon, sickle, and knut coins of a fictional wizarding currency. The cookiecutter module uses templates to create the starting files for several different kinds of projects. Often, the template is simply a GitHub.com link. For example, from a C::raw-latex:`\Users`:raw-latex:`\Al `folder, you could enter the following in a Terminal window to create a C::raw-latex:`Users`:raw-latex:Al:raw-latex:`wizcoin `folder with the boilerplate files for a basic Python project. The cookiecutter module downloads the tem- plate from GitHub and asks you a series of questions about the project you want to create:
C:UsersAl>cookiecutter gh:asweigart/cookiecutter-basicpythonproject project_name [Basic Python Project]: WizCoin module_name [basicpythonproject]: wizcoin author_name [Susie Softwaredeveloper]: Al Sweigart author_email [susie@example.com]: al@inventwithpython.com github_username [susieexample]: asweigart project_version [0.1.0]: project_short_description [A basic Python project.]: A Python module to represent the galleon, sickle, and knut coins of wizard currency.
If you get an error, you can also run python -m cookiecutter instead of cookiecutter . This command downloads a template I’ve created from https:// github.com/asweigart/cookiecutter-basicpythonproject. You’ll find templates for many programming languages at https://github.com/cookiecutter/cookiecutter. Because Cookiecutter templates are often hosted on GitHub, you could also enter gh: as a shortcut for https://github.com/ in the command line argument.
As Cookiecutter asks you questions, you can either enter a response or simply press ENTER to use the default response shown in between square brackets. For example, project_name [Basic Python Project]: asks you to name your project. If you enter nothing, Cookiecutter will use “Basic Python Project” as the project name. These defaults also hint at what sort of response is expected. The project_name [Basic Python Project]: prompt shows you a capitalized project name that includes spaces, whereas the module_name [basicpythonproject]: prompt shows you that the module name is lower- case and has no spaces. We didn’t enter a response for the project_version [0.1.0]: prompt, so the response defaults to “0.1.0.”
After answering the questions, Cookiecutter creates a wizcoin folder in the current working directory with the basic files you’ll need for a Python project, as shown in Figure 12-1.
Figure 12-1: The files in the wizcoin folder created by Cookiecutter
It’s okay if you don’t understand the purpose of these files. A full explanation of each is beyond the scope of this book, but https://github.com/ asweigart/cookiecutter-basicpythonproject has links and descriptions for fur- ther reading. Now that we have our starting files, let’s keep track of them using Git.