Welcome to cookiecutter-pytask-project’s documentation!

MIT license image image image pre-commit.ci status image

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"

Contents: