#1 - init repo

.docker/python/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.13.3
+ARG PACKAGE="core"
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+WORKDIR /app
+
+COPY ../../shared/utils /app/shared/utils
+
+RUN --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev --package=$PACKAGE
+
+COPY src/$PACKAGE /app/src/$PACKAGE
+
+RUN --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-dev --package=$PACKAGE
+
+ENV PATH="/app/.venv/bin:$PATH"
+
+ENTRYPOINT [ "uv", "run" ]

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/check-pr-title.yml

@@ -0,0 +1,11 @@
+name: Check PR Title
+on:
+  workflow_call:
+
+jobs:
+  check-pr-title:
+    name: Check PR title
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: blumilksoftware/[email protected]

.github/workflows/code-quality.yml

@@ -0,0 +1,39 @@
+name: Code Quality Analysis
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-24.04
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/python.yml

@@ -0,0 +1,61 @@
+name: Test&Lint Python Codebase
+
+on:
+  pull_request:
+    branches:
+      - "**"
+
+env:
+  UV_VERSION: "0.6.5"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    env:
+      UV_CACHE_DIR: /tmp/.uv-cache
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
+
+      - name: Set up python
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Set up uv
+        run: curl -LsSf https://astral.sh/uv/${{ env.UV_VERSION }}/install.sh | sh
+
+      - name: Restore uv cache
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.uv-cache
+          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+            uv-${{ runner.os }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev --frozen
+
+      - name: Set up pre-commit cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: |
+            pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+            pre-commit-${{ runner.os }}
+
+      - name: Run pre-commit checks
+        run: uv run pre-commit run --all-files
+
+      - name: Test with pytest
+        run: uv run pytest tests --cov=src
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

.pre-commit-config.yaml

@@ -0,0 +1,79 @@
+ci:
+  skip: [pytest]
+
+default_language_version:
+  python: python3.13
+
+repos:
+  # general checks (see here: https://pre-commit.com/hooks.html)
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  # ruff - linting + formatting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.9.10"
+    hooks:
+      - id: ruff
+        name: ruff
+      - id: ruff-format
+        name: ruff-format
+
+  # mypy - lint-like type checking
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        name: mypy
+
+  # docformatter - formats docstrings to follow PEP 257
+  - repo: https://github.com/pycqa/docformatter
+    # todo: replace when >v1.7.5 will be published
+    rev: 06907d0267368b49b9180eed423fae5697c1e909
+    hooks:
+      - id: docformatter
+        name: docformatter
+        args:
+          [
+            -r,
+            -i,
+            --pre-summary-newline,
+            --make-summary-multi-line,
+            --wrap-summaries,
+            "90",
+            --wrap-descriptions,
+            "90",
+            src,
+            tests,
+          ]
+
+  # bandit - find common security issues
+  - repo: https://github.com/pycqa/bandit
+    rev: 1.8.3
+    hooks:
+      - id: bandit
+        name: bandit
+        exclude: ^tests/
+        args:
+          - -r
+          - src
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: uv run pytest tests --cov=src
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  # prettier - formatting JS, CSS, JSON, Markdown, ...
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    hooks:
+      - id: prettier
+        exclude: ^uv.lock

.python-version

@@ -0,0 +1 @@
+3.13.2

.renovaterc.json5

@@ -0,0 +1,22 @@
+{
+  $schema: "https://docs.renovatebot.com/renovate-schema.json",
+  extends: [
+    "config:recommended",
+    "schedule:daily",
+    "group:all",
+    ":prConcurrentLimitNone",
+    ":prHourlyLimitNone",
+    ":prImmediately",
+  ],
+  labels: ["dependencies"],
+  enabledManagers: [
+    "dockerfile",
+    "github-actions",
+    "pre-commit",
+    "pep621",
+    "pyenv",
+  ],
+  "pre-commit": {
+    enabled: true,
+  },
+}

README.md

@@ -1,2 +1,109 @@
-# python-boilerplate
-Minimal Python boilerplate using uv for fast dependency management, isolated virtual environments, and modern project structure.
+# Python boilerplate
+
+<p align="center">
+  <a href="https://github.com/astral-sh/uv" target="blank"><img src="https://github.com/astral-sh/uv/blob/8674968a17e5f2ee0dda01d17aaf609f162939ca/docs/assets/logo-letter.svg" height="60" alt="uv logo" /></a>
+</p>
+
+[![CodeQL](https://github.com/MrHDOLEK/python-boilerplate/actions/workflows/code-quality.yml/badge.svg?branch=main)](https://github.com/MrHDOLEK/python-boilerplate/actions/workflows/code-quality.yml)
+[![GitHub CI](https://github.com/MrHDOLEK/python-boilerplate/actions/workflows/python.yml/badge.svg?branch=main)](https://github.com/MrHDOLEK/python-boilerplate/actions/workflows/python.yml)
+[![GitHub license](https://img.shields.io/github/license/MrHDOLEK/python-boilerplate)](https://github.com/MrHDOLEK/python-boilerplate)
+[![Python](https://img.shields.io/badge/python-3.13-blue.svg?logo=python&logoColor=white)](https://www.python.org/)
+
+---
+
+#### A Python boilerplate using modern dev tools
+
+## Project setup
+
+### Development environment
+
+```bash
+# Clone the repository
+git clone https://github.com/MrHDOLEK/python-boilerplate.git
+
+# Navigate to project directory
+cd python-boilerplate/
+
+# Checkout working branch
+git checkout <branch>
+
+# Setup Python environment
+uv python install
+uv venv
+source .venv/bin/activate
+
+# Install dependencies
+uv sync
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+## Tools & Features
+
+### uv
+
+Fast Python package manager, written in Rust. Configuration in `pyproject.toml` and dependencies locked in `uv.lock`.
+
+```bash
+# Install a package
+uv pip install <package>
+
+# Run a command in the environment
+uv run pytest tests
+```
+
+### pre-commit
+
+Framework for managing git hooks. Configuration in `.pre-commit-config.yaml`.
+
+```bash
+# Run against all files
+pre-commit run --all-files
+```
+
+### ruff
+
+Fast Python linter and formatter. Rules defined in `pyproject.toml`.
+
+```bash
+# Format code
+uv run ruff format .
+
+# Check code
+uv run ruff check .
+```
+
+### Testing
+
+Using pytest for tests:
+
+```bash
+# Run tests
+uv run pytest tests
+
+# Run tests with coverage
+uv run pytest tests --cov=src
+```
+
+### Docker
+
+```bash
+# Login to GitHub Container Registry
+echo $GITHUB_TOKEN | docker login ghcr.io -u $GITHUB_USERNAME --password-stdin
+# Build production image
+docker buildx build -f .docker/python/Dockerfile -t my-python-application:latest .
+# Run the application
+docker run -it --rm my-python-application:latest
+```
+
+## Documentation
+
+Learn more at these links:
+
+- [uv](https://github.com/astral-sh/uv)
+- [pre-commit](https://pre-commit.com/)
+- [ruff](https://github.com/astral-sh/ruff)
+- [mypy](http://mypy-lang.org/)
+- [bandit](https://bandit.readthedocs.io/)
+- [pytest](https://docs.pytest.org/)