Cookiecutter templates with PyScaffold¶
Cookiecutter is a flexible utility that allows the definition of templates
for a diverse range of software projects.
On the other hand, PyScaffold is focused in a good out-of-the-box
experience for developing distributable Python packages (exclusively).
Despite the different objectives, it is possible to combine the power of both
tools to create a custom Python project setup. For instance, the following
command creates a new package named mypkg
, that uses a Cookiecutter template,
but is enhanced by PyScaffold’s features:
$ putup mypkg --cookiecutter gh:audreyr/cookiecutter-pypackage
This is roughly equivalent to first create a project using the Cookiecutter template and convert it to PyScaffold afterwards:
$ cookiecutter --no-input gh:audreyr/cookiecutter-pypackage project_name=mypkg
$ putup mypkg --force
Note
For complex Cookiecutter templates calling cookiecutter
and putup
separately may be a better option, since it is possible to answer
specific template questions or at least set values for Cookiecutter
variables.
Warning
Although using Cookiecutter templates is a viable solution to customize a project that was set up with PyScaffold, the recommended way is to help improve PyScaffold by contributing an extension.
Suitable templates¶
Note that PyScaffold will overwrite some files generated by Cookiecutter,
like setup.py
, the __init__.py
file under the package folder
and most of the docs
folder, in order to provide setuptools_scm
and sphinx integration.
Therefore not all Cookiecutter templates are suitable for this approach.
Ideally, interoperable templates should focus on the file structure inside the
src
folder instead of packaging or distributing, since PyScaffold already
handles it under-the-hood. This also means that your template should adhere to
the src-layout if you want to generate files within your Python package.
In addition, PyScaffold runs Cookiecutter with the --no-input
flag
activated and thus the user is not prompted for manual configuration. Instead,
PyScaffold injects the following parameters:
author
email
project_name
package_name
project_short_description
Accordingly, the template file structure should be similar to:
cookiecutter-something/
└── {{cookiecutter.project_name}}/
└── src/
└── {{cookiecutter.package_name}}/
└── ...
See Cookiecutter for more information about template creation.