mariushelf / cookiecutter_python

Very simple project scaffold for Python projects with poetry dependency management and default pre-commit hooks

Cookiecutter Python

A simple cookiecutter for any Python package.

Easily publish to PyPI from your local machine or automated via Github actions.

Automated linting and testing, locally and on Github.

Ready-to-use documentation and api-docs pipeline.

Features

• Ready-to-release:
  • Extensive documentation on how to release your package
  • Github actions to run tests and release to PyPI
  • Makefile targets to test, build and release your code from your local machine
• Easy documentation: ready-to-rumble, Read the Docs compatible sphinx configuration with Markdown support ((almost) no more Restructured Text)
• Poetry dependency management
• Test pipeline with pytest and tox
• Linting and code check pipeline with pre-commit, including:
  • black - the uncompromising code formatter
  • ruff - all in one, super fast linter written in rust. Combines functionality of flake8, isort, pydocstyle and many other tools.
  • mypy - check code, find type errors
  • yamllint - print warnings about badly formatted yaml files

Inspired by cookiecutter-pypackage.

Requirements

• This cookiecutter makes use of new features from Poetry 1.2.0 released on 2022-08-31. Make sure to follow the upgrade process if you are still running an older version of poetry.

Usage

# install cookiecutter and poetry into the current environment for the current user
pip install --user cookiecutter poetry

cookiecutter gh:mariushelf/cookiecutter_python
cd <your_project_slug>

# Write your code and tests now.
# Document everything in Markdown.

# Then run your tests with different Python versions (using tox):
make test

# Generate documentation
make docs

# and publish your code
make publish

# Or push to Github and create a Github release which gets automatically published
# to PyPI.

Troubleshooting

• mypy checking can find a lot of bugs without even running the code, but sometimes it is too strict. There are a lot of things you can configure, but if it's a one of on just one or two lines of your code, you can tell mypy to ignore that specific line by appending # type: ignore to it.
• The required version of poetry is 1.2.0. If you get problems regarding poetry or the pyproject.toml, make sure to check your poetry version and update it if necessary.