Package: pyscaffoldext-cookiecutter
pyscaffoldext-cookiecutterExtension that combines the flexibility ofCookiecuttertemplates
with the power ofPyScaffold.Cookiecutteris a flexible utility that allows the definition of templates
for a diverse range of software projects.
On the other hand,PyScaffoldis 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.QuickstartThis extension can be directly installed withpip:pipinstallpyscaffoldext-cookiecutterOr, if you preferpipx:pipxinstallpyscaffold# if you haven't installed pyscaffold yetpipxinjectpyscaffoldpyscaffoldext-cookiecutterNote that, after the installation,putup-hwill show a new option--cookiecutterTEMPLATE.
Use this option to point out which template you want to use (path or url).
The file structure created byCookiecutterwill be refined by PyScaffold
afterwards.
For example:putupmy-proj1--cookiecutter~/my-templates/defaultputupmy-proj2--cookiecuttergh:something/from-githubPlease refer toCookiecutterdocumentation for more details on possible URLs
and abbreviations.An additional option--cookiecutter-paramsis also added, so you can have
more control over the valuesCookiecutteruses when rendering the templates
(PyScaffold will not run Cookiecutter’s interactive prompt).
This option takes the form of a space separated list ofNAME=VALUEarguments as showed in the example bellow:putupmypkg\--cookiecuttergh:pyscaffold/cookiecutter-pypackage\--cookiecutter-paramscommand_line_interface=Argparseuse_pytest=yCheck thecookiecutter.jsonfile in the repository (or directory) of the template you are
using to see the available parameters.
Please notice PyScaffold already add some default parameters, as indicated in
the sectionSuitable Templatesbellow.Cookiecutter templates with PyScaffoldThe following example shows how to create a new package namedmypkg,
that uses a Cookiecutter template, but is enhanced by PyScaffold’s features:putupmypkg--cookiecuttergh:pyscaffold/cookiecutter-pypackageThis is roughly equivalent to first create a project using the Cookiecutter
template and convert it to PyScaffold afterwards:cookiecutter--no-inputgh:pyscaffold/cookiecutter-pypackageproject_name=mypkgputupmypkg--forceNoteFor complex Cookiecutter templates callingcookiecutterandputupseparately may be a better option, since it is possible to answer
specific template questions or at least set values for Cookiecutter
variables.WarningAlthough 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 anextension.Suitable templatesNote that PyScaffold will overwrite some files generated by Cookiecutter,
likesetup.py, the__init__.pyfile under the package folder
and most of thedocsfolder, in order to providesetuptools_scmandsphinxintegration.
Therefore not all Cookiecutter templates are suitable for this approach.Ideally, interoperable templates should focus on the file structure inside thesrcfolder 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-inputflag
activated and thus the user is not prompted for manual configuration. Instead,
PyScaffold injects the following parameters:author
email
full_name => same as author
project_name => the name of the folder where the project will be generated
repo_name => same as project_name
package_name => putup's --package (as in `import`)
namespace => putup's --namespace (if any)
installable_name => putup's --name (an installable name, like in PyPI/pip install)
project_short_description => putup's description
release_date => equivalent to the day you are running putup
year => equivalent to the year you are running putupAny extra parameter should be passed using the--cookiecutter-paramsoption.Accordingly, the template file structure should be similar to:cookiecutter-something/
└── {{cookiecutter.project_name}}/
    └── src/
        └── {{cookiecutter.package_name}}/
            └── ...SeeCookiecutterfor more information about template creation.NotePyScaffold uses Cookiecutter only for its ability to create files.
Pre/post hooks that perform any other kind of side effect are not
guaranteed to work.Making Changes & ContributingThis project usespre-commit, please make sure to install it before making any
changes:pip install pre-commit
cd pyscaffoldext-cookiecutter
pre-commit installIt is a good idea to update the hooks to the latest version:pre-commit autoupdatePlease also check PyScaffold’scontribution guidelines,NoteThis project has been set up using PyScaffold 4.0a2. For details and usage
information on PyScaffold seehttps://pyscaffold.org/.