Python Packages Project Generator

Your next Python package needs a bleeding-edge project structure.

TL;DR

cookiecutter gh:JensRoland/python-package-template --checkout v1.2.0

Credit, Improvements & TODOs

This cookiecutter is based on the excellent work by Roman Tezikov https://github.com/TezRomacH/python-package-template/ and remains 99% his creation. I have merely added some features and removed others to make it more suitable for my own needs.

Specifically, this repo includes the following changes/improvements:

[x] Added a 'Proprietary' license option.
[x] Moved source code into /src/ folder and changed all linters etc. to target that folder only.
[x] Changed the 'github_name' input to 'github_username' to avoid confusion.
[x] Added virtualenvs.in-project = true (to store virtualenv in project/.venv/)
[x] Fixed a minor bug (incorrect directory) in the post-gen instructions.
[x] Bumped a few package versions.
[x] Added pylint to linters.
[x] isort: Added list of files to skip.
[x] black: Removed color=true setting because it broke black when running in my VS Code using formatOnSave (OS X w. ZSH)
[x] Expanded on the post-gen instructions to include pyenv versioning and GitHub repo creation.
[x] Fixed `make install` so the created virtualenv will use the selected python version.
[x] VS Code settings.json: added python defaultInterpreterPath (to auto-activate virtualenv) and activated the various linters and pytest
[x] VS Code launch.json: enable features for running and debugging code.
[x] Cleaned up the .pre-commit-config.yaml file a bit, e.g. removing the python version because it made commits fail if you were running a higher (but compatible) Python version.
[x] Mypy linting of Python code
[x] Makefile update-dev-deps: black no longer needs prerelease version

And in the future I will add:

[ ] Makefile -> [`Invoke`](http://www.pyinvoke.org/) / [`Nox`](https://nox.thea.codes/en/stable/)?
[ ] Auto-documentation with [`MkDocs`](https://www.mkdocs.org/) and possibly [Material Design theme](https://github.com/squidfunk/mkdocs-material) and [`mkdocstrings`](https://github.com/pawamoy/mkdocstrings).
[ ] Pytest-xdist for parallelized unit test running.
[ ] CDK constructs ready for deployment to AWS.
[ ] Code metrics with [`Radon`](https://github.com/rubik/radon).

🚀 Features

In this cookiecutter 🍪 template we combine state-of-the-art libraries and best development practices for Python.

Development features

• Supports Python 3.7 and higher.
• Poetry as a dependencies manager. See configuration in pyproject.toml and setup.cfg.
• Automatic codestyle with black, isort, pylint and pyupgrade.
• Ready-to-use pre-commit hooks with code-formatting.
• Type checks with mypy; docstring checks with darglint; security checks with safety and bandit
• Testing with pytest.
• Ready-to-use .editorconfig, .dockerignore, and .gitignore.
• VS Code settings for automatic virtualenv activation, formatting & linting on save, as well as testing and debugging.

Deployment features

• GitHub integration: issue and pr templates.
• Github Actions with predefined build workflow as the default CI/CD.
• Everything is already set up for security checks, codestyle checks, code formatting, testing, linting, docker builds, etc with Makefile. More details in makefile-usage.
• Dockerfile for your package.
• Always up-to-date dependencies with @dependabot. You only need to enable it.
• Automatic release notes with Release Drafter. You may see the list of labels in release-drafter.yml. Works perfectly with Semantic Versions specification.

Open source community features

• Ready-to-use Pull Requests templates and several Issue templates.
• Files such as: LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md are generated automatically.
• Stale bot that closes abandoned issues after a period of inactivity. (You will only need to setup free plan). Configuration is here.
• Semantic Versions specification with Release Drafter.

🤯 How to use it

Installation

To begin using the template consider updating cookiecutter

pip install -U cookiecutter

then go to a directory where you want to create your project and run:

cookiecutter gh:JensRoland/python-package-template --checkout v1.2.0

Input variables

Template generator will ask you to fill some variables.

The input variables, with their default values:

Parameter	Default value	Description
project_name	python-project	Check the availability of possible name before creating the project.
project_description	based on the project_name	Brief description of your project.
organization	based on the project_name	Name of the organization. Used to generate LICENSE and to specify ownership in pyproject.toml.
license	MIT	One of MIT, BSD-3, GNU GPL v3.0, Apache Software License 2.0, and Proprietary.
minimum_python_version	3.7	Minimum Python version. One of 3.7, 3.8, 3.9 and 3.10. It is used for builds, GitHub workflow and formatters (black, isort and pyupgrade).
github_username	based on the organization	GitHub username for hosting. Also used to set up README.md, pyproject.toml and template files for GitHub.
email	based on the organization	Email for CODE_OF_CONDUCT.md, SECURITY.md files and to specify the ownership of the project in pyproject.toml.
version	0.1.0	Initial version of the package. Make sure it follows the Semantic Versions specification.
line_length	120	The max length per line (used for codestyle with black and isort). NOTE: This value must be between 50 and 300.
create_example_template	none	If cli is chosen generator will create simple CLI application with Typer and Rich libraries. One of cli, none

All input values will be saved in the cookiecutter-config-file.yml file so that you won't lose them. 😉

Demo

More details

Your project will contain README.md file with instructions for development, deployment, etc. You can read the project README.md template before.

Initial set up

Initialize poetry

By running make install

After you create a project, it will appear in your directory, and will display a message about how to initialize the project.

Initialize pre-commit

By running make pre-commit-install. Make sure to set up git first via git init.

Package example

Want to know more about Poetry? Check its documentation.

Details about Poetry

Poetry's commands are very intuitive and easy to learn, like:

• poetry add numpy@latest
• poetry run pytest
• poetry publish --build

etc.

CLI example

If you set create_example_template to be cli the template comes with a cute little CLI application example. It utilises Typer and Rich for CLI input validation and beautiful formatting in the terminal.

After installation via make install (preferred) or poetry install you can try to play with the example:

poetry run <project_name> --help

poetry run <project_name> --name Jens

Building and releasing your package

Building a new version of the application contains steps:

• Bump the version of your package poetry version <version>. You can pass the new version explicitly, or a rule such as major, minor, or patch. For more details, refer to the Semantic Versions standard.
• Make a commit to GitHub.
• Create a GitHub release.
• And... publish 🙂 poetry publish --build

Makefile usage

Makefile contains a lot of functions for faster development.

1. Download and remove Poetry

To download and install Poetry run:

make poetry-download

To uninstall

make poetry-remove

2. Install all dependencies and pre-commit hooks

Install requirements:

make install

Pre-commit hooks can be installed after git init via:

make pre-commit-install

3. Codestyle

Automatic formatting uses pyupgrade, isort, and black.

make codestyle

# or use synonym
make formatting

Codestyle checks only, without rewriting files:

make check-codestyle

Note: check-codestyle uses isort, black, darglint, and pylint.

Update all dev libraries to the latest version using one comand

make update-dev-deps

4. Code security

make check-safety

This command launches Poetry integrity checks as well as identifies security issues with Safety and Bandit.

make check-safety

5. Type checks

Run mypy static type checker

make mypy

6. Tests with coverage badges

Run pytest

make test

7. Making badges

make extrabadges

8. All linters

Of course there is a command to rule run all linters in one:

make lint

the same as:

make test && make check-codestyle && make mypy && make check-safety

9. Docker

make docker-build

which is equivalent to:

make docker-build VERSION=latest

Remove docker image with

make docker-remove

More information about docker.

10. Cleanup

Delete pycache files

make pycache-remove

Remove package build

make build-remove

Delete .DS_STORE files

make dsstore-remove

Remove .mypycache

make mypycache-remove

Or to remove all above run:

make cleanup

🎯 What's next

Well, that's up to you 💪🏻. I can only recommend the packages and articles that helped me.

• Typer is great for creating CLI applications.
• Rich makes it easy to add beautiful formatting in the terminal.
• Pydantic – data validation and settings management using Python type hinting.
• Loguru makes logging (stupidly) simple.
• tqdm – fast, extensible progress bar for Python and CLI.
• IceCream is a little library for sweet and creamy debugging.
• orjson – ultra fast JSON parsing library.
• Returns makes you function's output meaningful, typed, and safe!
• Hydra is a framework for elegantly configuring complex applications.
• FastAPI is a type-driven asynchronous web framework.

Articles:

• Open Source Guides.
• A handy guide to financial support for open source
• GitHub Actions Documentation.
• Maybe you would like to add gitmoji to commit names. This is really funny. 😄

📈 Releases

You can see the list of available releases on the GitHub Releases page.

We follow Semantic Versions specification.

We use Release Drafter. As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish when you’re ready. With the categories option, you can categorize pull requests in release notes using labels.

List of labels and corresponding titles

Label	Title in Releases
enhancement, feature	🚀 Features
bug, refactoring, bugfix, fix	🔧 Fixes & Refactoring
build, ci, testing	📦 Build System & CI/CD
breaking	💥 Breaking Changes
documentation	📝 Documentation
dependencies	⬆️ Dependencies updates

🛡 License

This project is licensed under the terms of the MIT license. See LICENSE for more details.

🏅 Acknowledgements

This template was inspired by several great articles:

• Hypermodern Python
• Ultimate Setup for Your Next Python Project
• Nine simple steps for better-looking python code
• Modern Python developer's toolkit

and repositories:

• Cookiecutter
• wemake-python-package
• Audreyr's cookiecutter-pypackage
• Full Stack FastAPI and PostgreSQL - Base Project Generator
• Cookiecutter Data Science Template: cdst

Give them your ⭐️, these resources are amazing! 😉