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 features:

$ putup mypkg --cookiecutter gh:audreyr/cookiecutter-pypackage

Note

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 package folder instead of packaging or distributing, since PyScaffold already handles it under-the-hood. However, the following files can be safely generated by a template (will not be overwritten):

<project root>/docs/index.rst
<project root>/tests/conftest.py
<project root>/README.rst
<project root>/AUTHORS.rst
<project root>/LICENSE.txt
<project root>/CHANGES.rst
<project root>/setup.cfg
<project root>/requirements.txt
<project root>/test-requirements.txt
<project root>/.coveragerc

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}}/
    └── {{cookiecutter.package_name}}/
        └── ...

See Cookiecutter for more information about template creation.