CookieCutter Python Package

Awesome Cookiecutter template for creating Python Packages.

Example

Table of Contents

• Primary Features
  • At-a-glance
  • GitHub
  • PyPI
  • Development
• Usage
  • Necessary manual post-setup steps
• Generic Features of this 🍪
  • Documentation
  • Development
  • GitHub

Primary Features

At-a-glance

• Formatting with black, docformatter and prettier

• Import sorting with reorder-python-imports (isort alternative)

• Static typing with mypy

• Linting with flake8

• Git hooks that run all the above with pre-commit

---

• Continuous Integration with GitHub Actions on MacOS, Window and Ubuntu. Testing Matrix includes CPython 3.7/3.8/3.9/3.10/3.11 as well as PyPy 3.7 with previous (21.*), latest (upgradeable) and main (devel) version of pip for each OS - resulting in 26~ Jobs with a base Total Duration of 4-5 minutes.

• Testing with pytest (preferred) or unittest (optional) and tox

• Code Coverage Reporting with Codecov through CI

---

• Assumes Minimum Python Version of 3.7

• Offers command line interface using argparse or Click (optional)

---

• Automatic build-and-release to PyPI when pushing a new tag to master

• Deployment / Execution ready through Dockerfile that follows all best-practices (1, 2)

GitHub

• Includes a GitHub Workflow to automatically build, tag and push the Project’s Dockerfile to DockerHub

  ℹ️	Requires the secrets DOCKERHUB_TOKEN and DOCKERHUB_PASSWORD to be present in the GitHub repository or organization!

  ℹ️

  The docker image is automatically tagged using docker/metadata-action in below format (based on the SemVer example): Event Ref (Action Input) Docker Tags pull_request refs/pull/2/merge pr-2 push refs/heads/master master push refs/heads/releases/v1 releases-v1 push tag refs/tags/v1.2.3 1.2.3, 1.2, latest push tag refs/tags/v2.0.8-beta.67 2.0.8-beta.67 ℹ️ Tags not starting with v are not processed by this GitHub Workflow.

PyPI

• Includes a GitHub Workflow to automatically build and upload the package to PyPI.

  ℹ️	Requires the secrets PYPI_API_KEY to be present in the GitHub repository or organization!

Development

• Versions are managed through tags which can be simply bumped using bump2version.

Usage

First, get Cruft. It’s a tool built in Cookiecutter that will allow you to keep up-to-date with the changes made to this cookiecutter.

$ python3 -m pip install cruft

Now run it against this repo:

$ cruft create https://github.com/JonasPammer/cookiecutter-pypackage.git

Answer the prompts with your own desired options.

Enter the project and take a look around (replace "my-python-project" with your project slug):

$ cd my-python-project
~/my-python-project$ ls

Create a git repo and push it there (replace "YourGitHubName" with your github profile name and "my-python-project" with your project slug):

~/my-python-project$ git init
~/my-python-project$ git add .
~/my-python-project$ git commit -m "chore: create from cookiecutter"
~/my-python-project$ git remote add origin [email protected]:YourGitHubName/my-python-project.git
~/my-python-project$ git push -u origin master

Now take a look at your repo. Don’t forget to carefully look at the generated README - It contains all relevant Development Documentation.

Awesome, right?

Necessary manual post-setup steps

$ python3 -m venv venv
$ source venv/bin/activate
(venv)$ python3 -m pip install -r requirements-dev.txt
(venv)$ pip-compile --resolver=backtracking --generate-hashes
(venv)$ pip-compile --resolver=backtracking requirements-dev.in
(venv)$ pip-compile --resolver=backtracking requirements-build.in

GitHub

ℹ️	This CookieCutter does not configure your GitHub Repository. Please read the notes found in this README and perform the documented manual steps (e.g., Creating GitHub Action Secrets).

Generic Features of this 🍪

I maintain several CookieCutter’s. Many of them share a similiar set of boilerplate files. You will find this section to be the same in most of them.

Documentation

• Includes an Awesome README

  ℹ️

  Because github/markup#1095 (support include directives for other asciidoc files) is still not fixed, the following measures were taken: README.orig.adoc is the actual README that must be edited. A GitHub Workflow takes care of generating the actual README.adoc using the official tool ascidoctor-reducer. [optional] The README also exists as an automatically published GitHub Page, of which the HTML was generated by Asciidoctor (= done right). ℹ️ For this to work, you need to activate the Pages feature on a per-repository basis. To do so, go to the Settings page of your GitHub repository. Under Pages / Source, select [gh-pages] [/ (root)], and click Save.

• Includes a Beginner-Friendly Development Documentation file

• Includes a Beginner-Friendly generic Contribution Documentation file, inspired by Auth0’s Open Source Template.

• Includes ability to select and generate any of the Licenses found on https://choosealicense.com/licenses/.

• Includes a generic security policy file that states that only the current major version of the project is actively supported with patches and that problems should be sent to the e-mail address specified when the cookiecutter was created. The file also contains a template that may be used for such inqueries.

Development

• Changelog is assumed to be managed through the use of GitHub Releases.

• Includes numerous pre-commit hooks to automatically find linting issues, format your files, and find common issues of version control and source code

• Includes a very much standard yamllint configuration (enforced through pre-commit and checked by CI)

• Assumes enforcement of Conventional Commit (checked by a pre-commit hook if activated)

  ❗	The resulting projects mentions that this is completely optional for casual contributors, as it is assumed that pull requests are squash-merged by maintainers.

• Includes a exhaustive .gitignore file generated by gitignore.io

• Includes a copy of the Contributor Covenant Code of Conduct as generated automatically by GitHub.

GitHub

ℹ️	The resulting projects mentions that pre-commit installation is optional, as it is assumed that the project is included in your pre-commit.ci account projects.

• Includes a .gitattributes file, ensuring LF line endings

• Includes GitHub Issue Form Templates for filing bug reports and feature requests using HTML forms

• Includes a GitHub Pull Request Template

• Includes a GitHub Workflow to denote size of pull requests by automagically labelling them

• Includes a pretty standard Renovate configuration file for dependency update automation (similiar to dependabot, but better).

  ℹ️	To enable Renovate, you need to enable it for your repositories, e.g. by using the recommended Way of installing the Renovate GitHub App to your GitHub profile (for free)!

• Includes a GitHub Workflow to declaratively manage labels

  • The predefined labels definition is inspired by the kubernetes project