Python Project Template

This is a comprehensive repo template for a Python ≥3.7 project. Read through the list of features and prune as desired - at least one of the LICENSE files has to go 😉 and pyproject.toml then edited accordingly. If you don't go for the AGPL, you should also modify the copyright blurb in the source files.

This template repository itself is licensed under the Creative Commons “No Rights Reserved” CC0 1.0 Universal Public Domain Dedication.

Table of Contents

1. Features
2. TODO
3. Project Layout
4. Getting Started
5. Creating a New Release
6. Handy Developer References
7. A Selection of Badges

---

✨ 1: Features

• Project setup with flit for building and distributing as a PyPi package.
• GitHub workflows for CI (lint, test, coverage) and building a release with a Windows executable.
• Community files (code of conduct, contributing, support etc.) that will integrate nicely with GitHub as well.
• EditorConfig support.
• Standardized commit messages plus changelog/release notes workflow, courtesy of commitizen.
• Linting with flake8 and friends, code formatting with black and static analysis with mypy - both as linter scripts and git pre-commit hooks.
• Speaking of git, there's a comprehensive .gitignore file.
• Easy logging with loguru.
• Integration with pre-commit.ci for auto-fixing pull requests.
• Pytest setup with codecov.io integration.

👷 2: TODO

• [#2] Ensure pipx compatibility by setting up flit entrypoints.
• [#3] Set up tox.
• [#4] Add sample GitHub workflow step to upload package to PyPi.

🗺️ 3: Project Layout

python-project-template
│
├── .github
│   ├── workflows
│   │   ├── build.yml               ← CI workflow
│   │   └── release.yml             ← Release workflow for Windows .exe
│   │
│   ├── CODE_OF_CONDUCT.md          ← Code of Conduct
│   ├── CONTRIBUTING.md             ← Instructions for contributing
│   ├── FUNDING.yml                 ← GitHub funding integration
│   ├── SECURITY.md                 ← How to submit bug reports
│   └── SUPPORT.md                  ← How to get support
│
├── dist
│   ├── python_project_template.cfg ← Config file to include in release
│   └── README.txt                  ← Readme file to include in release
│
├── img
│   └── python-project-template.ico ← Icon for Windows .exe
│
├── release-notes
│   └── v0.0.1.md                   ← Release notes per version
│
├── scripts
│   └── lint.py                     ← Cleans up your code
│
├── src
│   └── python_project_template
│       ├── __init__.py             ← Module definition
│       ├── __main__.py             ← Package entrypoint
│       └── ppt.py                  ← Actual application code
│
├── tests
│   └── test_ppt.py                 ← A simple test
│
├── .editorconfig                   ← Editor settings
├── .flake8                         ← Linter settings
├── .gitignore                      ← List of ignored files
├── .markdownlint.json              ← Markdown lint settings
├── .pre-commit-config.yaml         ← Git pre-commit hooks
├── CHANGELOG.md                    ← Changelog
├── LICENSE                         ← Actual license for this repo
├── LICENSE.AGPLv3.md               ← AGPLv3 license template
├── LICENSE.MIT.md                  ← MIT license template
├── Pipfile                         ← Dependencies and scripts
├── pyproject.toml                  ← Project metadata and settings
├── README.md                       ← This file
└── version.yml                     ← File info for Windows .exe

Note that Pipfile.lock is not included but should be committed once generated.

🎬 4: Getting Started

• Create a new repo on GitHub using this repo as a template. (HOWTO)
• Make sure to turn off git autocrlf:
  git config core.autocrlf false
• Make it your own project. Search and replace the following strings with your project/repo/real name as applicable:
  python-project-template
python_project_template
Python Project Template
Kristian Thy
PyXY
pyxy.dk
• Initialize a virtualenv and install dependencies:
  $ pipenv update --dev
• If you want to publish to PyPi at some point, remember to fill in your ~/.pypirc as per these instructions.
• Start the pipenv shell and:
  • Install the package locally using one of:
    flit install --symlink (*nix, privileged Windows accounts)
    flit install --pth-file (Windows, if the above doesn't work)
  • Install Git hooks:
    pre-commit install --hook-type pre-commit --hook-type commit-msg

📦 5: Creating a New Release

1. Commit the code to be released as a new version using cz commit.
2. Push and verify that the CI build completed without errors.
3. Commit a new Markdown file in ./release-notes/ named after the new version's number, e.g. ./release-notes/v1.2.3.md. The text in this file will be displayed as release notes on GitHub.
4. Run cz bump, which will
   1. Tag the latest commit with the new version name, e.g. 1.2.3.
   2. Update CHANGELOG.md.
   3. Update the version number in src/python_project_template/__init__.py.
   4. Update the version number in pyproject.toml

Do not change the 0.0.0.0 in version.yml - it will be autofilled by the release workflow.

📜 6: Handy Developer References

• pytest - good integration practices
• Python packaging pitfalls
• Python 3 Type Hints Cheat Sheet

🥇 7: A Selection of Badges

Not all of these work or even make sense for this template, but they may serve as inspiration for which scout marks you want to display for your own project.

---