python-boilerplate

KO | EN

gitlite — search

#javascript #react #ai #typescript #golang #android #machine-learning #linux #java #windows #awesome #mcp #openai #open-source

python-boilerplate

(★ 87)

Python boilerplate using uv, pre-commit, prettier, pytest, GitHub Actions, mypy, ruff, bandit & docformatter.

File Explorer

Download Latest Version (.zip)

- - ci.yml
  - codeql.yml
- - __init__.py
  - main.py
- __init__.py
- test_python_boilerplate.py
.editorconfig
.gitattributes
.gitignore
.pre-commit-config.yaml
.python-version
.renovaterc.json5
Dockerfile
LICENSE
pyproject.toml
README.md
uv.lock

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Python boilerplate

[![CodeQL](https://github.com/smarlhens/python-boilerplate/workflows/codeql/badge.svg)](https://github.com/smarlhens/python-boilerplate/actions/workflows/codeql.yml)
[![GitHub CI](https://github.com/smarlhens/python-boilerplate/workflows/ci/badge.svg)](https://github.com/smarlhens/python-boilerplate/actions/workflows/ci.yml)
[![GitHub license](https://img.shields.io/github/license/smarlhens/python-boilerplate)](https://github.com/smarlhens/python-boilerplate)

---

## Table of Contents

- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [What's in the box ?](#whats-in-the-box-)
- [Testing](#testing)
- [Validation](#validation)
- [Docker](#docker)

---

## Prerequisites

- [Python](https://www.python.org/downloads/) **>=3.14.0 <3.15.0** (_tested with 3.14.7_)
- [pre-commit](https://pre-commit.com/#install) **>=3.2.0 <5.0.0** (_tested with 4.6.2_)
- [uv](https://docs.astral.sh/uv/getting-started/installation/) **>=0.12.2** (_tested with 0.12.3_)
- [docker](https://docs.docker.com/get-docker/) (_optional_)

---

## Installation

1. Clone the git repository

```bash
   git clone https://github.com/smarlhens/python-boilerplate.git
   ```

2. Go into the project directory

```bash
   cd python-boilerplate/
   ```

3. Checkout working branch

```bash
   git checkout <branch>
   ```

4. Enable pre-commit hooks

```bash
   pre-commit install
   ```

5. Configure Python environment

```bash
   uv python install
   uv venv
   source .venv/bin/activate
   ```

---

## What's in the box ?

### uv

[uv](https://github.com/astral-sh/uv) is an extremely fast Python package and project manager, written in Rust.

**pyproject.toml file** ([`pyproject.toml`](pyproject.toml)): orchestrate your project and its dependencies
**uv.lock file** ([`uv.lock`](uv.lock)): ensure that the package versions are consistent for everyone
working on your project

For more configuration options and details, see the [configuration docs](https://docs.astral.sh/uv/).

### pre-commit

[pre-commit](https://pre-commit.com/) is a framework for managing and maintaining multi-language pre-commit hooks.

**.pre-commit-config.yaml file** ([`.pre-commit-config.yaml`](.pre-commit-config.yaml)): describes what repositories and
hooks are installed

For more configuration options and details, see the [configuration docs](https://pre-commit.com/).

### ruff

[ruff](https://github.com/astral-sh/ruff) is an extremely fast Python linter, written in Rust.

Rules are defined in the [`pyproject.toml`](pyproject.toml).

For more configuration options and details, see the [configuration docs](https://github.com/astral-sh/ruff#configuration).

### mypy

[mypy](http://mypy-lang.org/) is an optional static type checker for Python that aims to combine the benefits of
dynamic (or "duck") typing and static typing.

Rules are defined in the [`pyproject.toml`](pyproject.toml).

For more configuration options and details, see the [configuration docs](https://mypy.readthedocs.io/).

### ty

[ty](https://github.com/astral-sh/ty) is a fast type checker from Astral, written in Rust. It runs alongside mypy as a second blocking type-checker.

Rules are defined in the [`pyproject.toml`](pyproject.toml).

For more configuration options and details, see the [ty documentation](https://github.com/astral-sh/ty).

---

## Testing

We are using [pytest](https://docs.pytest.org/) & [pytest-cov](https://github.com/pytest-dev/pytest-cov) to write tests.

To run tests:

```bash
uv run pytest tests
```

<summary>Output</summary>

```text
collected 1 item

tests/test_python_boilerplate.py::test_hello_world PASSED
```

</details>

To run tests with coverage:

```bash
uv run pytest tests --cov=src
```

<summary>Output</summary>

```text
collected 1 item

tests/test_python_boilerplate.py::test_hello_world PASSED

---------- coverage: platform linux, python 3.14.6-final-0 -----------
Name                                 Stmts   Miss  Cover
--------------------------------------------------------
src/python_boilerplate/__init__.py       1      0   100%
src/python_boilerplate/main.py           6      2    67%
--------------------------------------------------------
TOTAL                                    7      2    71%
```

</details>

---

## Validation

### Lint & format

To run ruff lint check:

```bash
uv run ruff check src tests
```

To run ruff format check:

```bash
uv run ruff format --check src tests
```

To apply ruff formatting:

```bash
uv run ruff format src tests
```

### Type check

To run mypy:

```bash
uv run mypy
```

### Pre-commit

To run all pre-commit hooks against all files:

```bash
pre-commit run --all-files
```

---

## Docker

### Build

To build the docker `production` image using [`Dockerfile`](Dockerfile):

```bash
docker build . -t my-python-application:latest
```

To build the docker `development` image using [`Dockerfile`](Dockerfile):

```bash
docker build . --target development -t my-python-application:dev
```

### Run

To run the python app example inside Docker:

```bash
docker run -it --rm my-python-application:latest # or :dev for development
```

<summary>Output</summary>

```text
Hello World
```

</details>

### Execute command inside container

```bash
docker run -it --rm my-python-application:latest bash
```

---

python-boilerplate

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

python-boilerplate

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README