Welcome to cookiecutter-pytask-project’s documentation!¶
This repository contains a minimal cookiecutter template for a project with pytask.
Installation¶
The template uses pixi as the package and environment manager which is the successor of conda/mamba/micromamba. Please, install it.
Note
Of course, the template can be used with any other package manager. But, we recommend pixi which can install packages from conda, PyPI, etc.. or rye for PyPI-only projects.
Then, install cookiecutter.
pixi global install cookiecutter
Now, set up the template with
pixi run cookiecutter https://github.com/pytask-dev/cookiecutter-pytask-project
Many formatting issues exist after the project is created. Run pre-commit to polish the template.
pixi global install pre-commit
pixi run pre-commit run -a
Features¶
Here is a feature list of the template.
pixi as the environment and package manager.
Supports pre-commit and some popular hooks like ruff and refurb.
Initialized documentation in
docs
.Preconfigured GitHub actions and dependabot.
Preconfigured readthedocs.
Preconfigured CodeCov.
FAQ¶
Q: Why are the source files nested in src/<project_slug>
?
A: This is called the src layout and the advantages are discussed in this article by Hynek Schlawack.
Although the article discusses the src layout in terms of Python packages, it is also
beneficial to structure a project the same way. Next to the reasons discussed there, it
is possible to use a single Python environment for multiple projects without messing
with your PYTHONPATH (via pip install -e .
or conda develop .
) each time and still
import modules.
Q: My project is a Python package, but it does not seem to have a version. Where is it?
A: The cookiecutter uses setuptools_scm to
manage the version number. When you install your created project as a Python package
with pip install -e .
, setuptools_scm tries to infer the version number from the tags
created on the repo.
For example, if you have switched to a commit associated with the tag v0.2.0
,
setuptools_scm will create a src/<package_slug>/_version.py
with a variable containing
version = '0.2.0'
which you can use in your src/<package_slug>/__init__.py
. If you
are one commit ahead of the tag, you version will be something like 0.2.0.dev1+...
indicating you are one commit ahead of the tag v0.2.0
.
If you want to switch to the tradition setup, replace the following code in your
pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.0"]
with
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"