Cookiecutter PyPackage

Cookiecutter template for a Python package.

• GitHub repo (fork): https://github.com/Ouranosinc/cookiecutter-pypackage/
• Documentation (upstream): https://cookiecutter-pypackage.readthedocs.io/
• Free software: BSD license
• Discord: https://discord.gg/PWXJr3upUE

Features

• Testing setup with unittest with coverage run or pytest
• pyproject.toml with the flit backend for PEP 517/621-compliant packaging.
• GitHub Actions: Ready for GitHub Actions Continuous Integration testing and Deployment.
• Conda environment file: Optionally use conda env create -f environment-dev.yml to create a new environment with the correct Python version.
• Tox testing: Setup to easily test for Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, and PyPy3.
• Sphinx docs: Documentation ready for generation with, for example, Read the Docs
• pre-commit hook: Run your tests and linting (e.g. black, flake8, pylint, etc.) before you commit your code!
• pre-commit.ci: Automate pre-commit checks and corrections in your Pull Requests.
• bump-my-version: Pre-configured SemVer-2.0-compliant version bumping with a single command.
• dependabot for automated dependency updates of both project dependencies and GitHub Actions.
• sphinx-intl for French internationalization (i18n) and localization (l10n) of Sphinx docs (optional)
• Auto-release to TestPyPI and PyPI when you push a new tag to main (optional)
• Command line interface using Click (optional)

Build Status

Upstream (audreyfeldroy/cookiecutter-pypackage):

Quickstart

Install the latest Cookiecutter if you haven't installed it yet

$ pip install -U cookiecutter

Or, if using Conda:

$ conda install -c conda-forge cookiecutter

Generate a Python package project:

$ cookiecutter https://github.com/Ouranosinc/cookiecutter-pypackage.git

Then:

• Create a repo and put it there.

• Install the development requirements into an environment:

  $ pip install -e ".[dev]"
  

Or, if using Conda:

$ conda env create -f environment-dev.yml
$ pip install -e . --no-deps

• Register your project with PyPI.
• Enable GitHub Actions and Workflows (see below).
• Activate automated deployment with Trusted Publishing to PyPI when you push a new tag to the main branch.
• Add the repo to your Read the Docs account and turn on the ReadTheDocs service hook.
• Release your package by pushing a new tag to main.
• Update the dependencies field of your pyproject.toml file that specifies the packages you will need for your project and their versions. For more info see the pip docs for requirements files.
• Register your project with pre-commit.ci.
• Activate dependabot for your project.

For more details, see the cookiecutter-pypackage tutorial.

GitHub Actions

In order to use GitHub Actions, you will need to enable them in your repo. To do so, go to the Actions tab of your repo and click the green button to enable them. Afterwards, you will need to ~generate a few Personal Access Tokens (PATs) <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens>`_ to allow the workflows to run. To do so, go to the Settings tab of your repo and click on Secrets in the left sidebar. Then, click on the New repository secret button and add the following secrets:

• BUMP_VERSION_TOKEN with the following privileges:

  • Contents: Read and Write
  • Metadata: Read-Only
  • Pull Requests: Read and Write

• OPENSSF_SCORECARD_TOKEN with the following privileges:

  • Administration: Read-Only
  • Metadata: Read-Only
  • Webhooks: Read-Only

Trusted Publishing

For Trusted Publishing with PyPI and TestPyPI, you will need to create deployment environments in your repo. To do so, go to the Settings tab of your repo and click on Environments in the left sidebar. Then, click on the New environment button and add the following environments:

• staging
• production

Afterwards, you will need to configure your project on both PyPI and TestPyPI to accept uploads from GitHub Actions. To do so, go to the Manage tab of your project on PyPI and click on Publishing in the left sidebar. Then, click on the Add a new publisher button and fill in the following information:

• Owner: my_username
• Repository name: my_project

• Workflow name:

  • For TestPyPI: tag-testpypi.yml
  • For PyPI: publish-pypi.yml

• Environment name:

  • For TestPyPI: staging
  • For PyPI: production

Once this is configured, all you need to do is push a new tag to the main branch and your package will be automatically published to TestPyPI, while performing a release on GitHub will then trigger an upload to PyPI.

Not Exactly What You Want?

Don't worry, you have options:

Similar Cookiecutter Templates

• Nekroze/cookiecutter-pypackage: A fork of this with a PyTest test runner, strict flake8 checking with Travis/Tox, and some docs and setup.py differences.
• tony/cookiecutter-pypackage-pythonic: Fork with py2.7+3.3 optimizations. Flask/Werkzeug-style test runner, _compat module and module/doc conventions. See README.rst or the GitHub comparison view for an exhaustive list of additions and modifications.
• ardydedase/cookiecutter-pypackage: A fork with separate requirements files rather than a requirements list in the setup.py file.
• lgiordani/cookiecutter-pypackage: A fork of Cookiecutter that uses Punch instead of bump2version and with separate requirements files.
• briggySmalls/cookiecutter-pypackage: A fork using Poetry for neat package management and deployment, with linting, formatting, no makefiles and more.
• veit/cookiecutter-namespace-template: A cookiecutter template for python modules with a namespace
• zillionare/cookiecutter-pypackage: A template containing Poetry, Mkdocs, Github CI and many more. It's a template and a package also (can be installed with pip)
• waynerv/cookiecutter-pypackage: A fork using Poetry, Mkdocs, Pre-commit, Black and Mypy. Run test, staging and release workflows with GitHub Actions, automatically generate release notes from CHANGELOG.
• 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.