Python Packages Project Generator

TL;DR

cookiecutter gh:a1d4r/python-project-template --checkout main

Features

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

Development features

• Supports Python 3.9 - 3.13
• uv as a package manager.
• Automatic codestyle with ruff formatter
• Linting with ruff
• Type checks with mypy, security checks with safety.
• Dependencies check with deptry
• 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. Click here for a detailed overview.
• Ready-to-use Makefile with formatting, linting, and testing. More details in makefile-usage.
• Dockerfile for your package.
• docker-compose.yml for local development 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:a1d4r/python-project-template --checkout main

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.
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
python_version	3.9	Python version. One of 3.9, 3.10, 3.11, 3.12, 3.13. It is used for builds, CI and formatters.
line_length	88	The max length per line. Must be between 50 and 300.
install_pydantic	true	If pydantic with mypy plugin should be installed

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

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 uv

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 uv

To download and install uv run:

make uv-install

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 ruff formatter

make codestyle

# or use synonym
make format

Codestyle checks only, without rewriting files:

make check-codestyle

Update all libraries to the latest version using one command

make update

4. Code security

This command 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

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.