Skip to content

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

License

Notifications You must be signed in to change notification settings

mariushelf/cookiecutter_python

Repository files navigation

Cookiecutter Python

Tests

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.