Python Packages Project Generator

TL;DR

cookiecutter gh:mrwegs/python-package-template --checkout master

Features

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

Development features

• Supports Python 3.9 and higher.
• Poetry as a dependencies manager. See configuration in pyproject.toml.
• Automatic codestyle with black
• Linting with ruff
• Type checks with mypy, security checks with safety.
• Testing with pytest and coverage.
• Ready-to-use pre-commit hooks with code-formatting.
• Ready-to-use .editorconfig, .dockerignore, and .gitignore.

Deployment features

• Github Actions with linters and tests in the workflow.
• Gitlab CI with linters and tests in the pipeline.
• Ready-to-use Makefile with formatting, linting, and testing. More details in makefile-usage.
• Dockerfile for your package.
• docker-compose.yml for local developement in Docker.

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:mrwegs/python-package-template --checkout master

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.
package_name	based on the project_name	Name of the python package with source code
git_platform	github	Git platform (Github/Gitlab)
username	username	User or organization name for Git platform
git_repo_url	based on git_platform, project_name and username	URL to the git repository
email	based on the username	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.
python_version	3.9	Python version. One of 3.9, 3.10, 3.11, 3.12. It is used for builds, CI and formatters.
line_length	88	The max length per line (used for codestyle with black and isort). NOTE: This value must be between 50 and 300.

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.

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 coulb be installed after git init via

make pre-commit-install

3. Codestyle

Automatic formatting uses black and ruff

make codestyle

# or use synonym
make format

Codestyle checks only, without rewriting files:

make check-codestyle

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

make check-safety

5. Type checks

Run mypy static type checker

make mypy

6. Tests with coverage

Run pytest

make test

7. All linters

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

make lint

8. Docker

make docker-build

which is equivalent to:

make docker-build VERSION=latest

Remove docker image with

make docker-remove

Run with docker compose

make docker-up

9. Cleanup

Delete cache and build files:

make cleanup

🏅 Acknowledgements

This template was initially forked from the following template:

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