Cookiecutter Poetry

Cookiecutter template for a Python package using Poetry.

• GitHub repo: https://github.com/elbakramer/cookiecutter-poetry/
• Documentation: https://elbakramer.github.io/cookiecutter-poetry/
• Free software: MIT License

Features

• Package and dependency management using Poetry
  • Has option to stick with setuptools (setup.py)
• Github Actions: Ready for GitHub Actions
  • Build and test on push or pull request for continuous integration (CI) (+badge)
  • Build documentation on push, publish the built documentation to Github Pages (+badge)
  • Draft release on push, this draft can be published manually or even automatically when new tag is pushed
  • Build and release Python package to PyPI when new release tag is published on github
• Many pre-commit hook based formatting, linting, testing tools
  • Upgrade syntax for newer python with pyupgrade
  • Formatting with black
  • Import sorting with isort
  • Linting with flake8 and pylint
  • Static typing with mypy
  • Testing with pytest
  • Git hooks that run all the above with pre-commit
• Other integrations to external sites/services
  • Sphinx docs serving with ReadTheDocs (+badge)
  • Coverage report with Codecov (+badge)
  • Monitoring depedency version updates with Requires.io or PyUp (+badge)
• Version bumping using bump2version
• Dynamic versioning using dunamai
• Command line interface using Click

Quickstart

Install the latest Cookiecutter if you haven't installed it yet (this requires Cookiecutter 1.4.0 or higher):

# Install pipx
$ pip install pipx
$ pipx ensurepath

# Install cookiecutter using pipx
$ pipx install cookiecutter

Generate a Python package project:

cookiecutter https://github.com/elbakramer/cookiecutter-poetry.git

Then, if you choose to try poetry:

# Install pipx
$ pip install pipx
$ pipx ensurepath

# Install poetry using pipx
$ pipx install poetry

# Run `poetry install` to install dependencies
$ cd {{ cookiecutter.github_repository_name }}/
$ poetry install

# Initialize git
$ git init

# Install pre-commit hooks
$ poetry run pre-commit install

# Do initial commit
$ git add --all
$ git commit -m "Initial commit"

Or, if you choose to stick with setuptools:

# Install dependencies using pip
$ cd {{ cookiecutter.github_repository_name }}/
$ pip install --editable .[dev]

# Initialize git
$ git init

# Install pre-commit hooks
$ pre-commit install

# Do initial commit
$ git add --all
$ git commit -m "Initial commit"

Lastly, you can:

• Create a github repo and push there.
• Add the repo to your ReadTheDocs account + turn on the ReadTheDocs service hook.
• Release your package by pushing a new tag to master.

Not Exactly What You Want?

Don't worry, you have options:

Similar Cookiecutter Templates

• johanvergeer/cookiecutter-poetry: Direct ancestor of this package, using poetry as package manager.
• sourcery-ai/python-best-practices-cookiecutter: Features many useful development tools with pre-commit hooks, took as reference during development.
• Also see the network and family tree for this repo. (If you find anything that should be listed here, please add it and send a pull request!)

Fork This / Create Your Own

If you have differences in your preferred setup, I encourage you to fork this to create your own version. Or create your own; it doesn't strictly have to be a fork.

• Once you have your own version working, add it to the Similar Cookiecutter Templates list above with a brief description.
• It's up to you whether or not to rename your fork/own version. Do whatever you think sounds good.

Or Submit a Pull Request

I also accept pull requests on this, if they're small, atomic, and if they make my own packaging experience better.