feat: init

Author: pg56714

.github/workflows/ci.yaml

@@ -0,0 +1,27 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality-check:
+    name: Lint, Format, Type Check, Test
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Lint (ruff)
+        run: uv run ruff check . --fix
+      - name: Format (ruff format)
+        run: uv run ruff format .
+      - name: Type check (pyright)
+        run: uv run pyright
+      - name: Run unit tests
+        run: uv run pytest

.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+# See https://pre-commit.com for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: trailing-whitespace
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.1
+    hooks:
+      - id: ruff
+        args:
+          - --fix
+      - id: ruff-format
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.8.20
+    hooks:
+      - id: uv-lock
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.405
+    hooks:
+      - id: pyright
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.9.1
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+      - id: commitizen-branch
+        stages: [pre-push]
+      # pre-commit install --hook-type commit-msg --hook-type pre-push

.python-version

@@ -0,0 +1 @@
+3.12

Dockerfile

@@ -0,0 +1,26 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+# Use 'code' to avoid confusion with the 'app' directory
+WORKDIR /code
+
+# Compile bytecode and avoid symlinks
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+
+# ---------- layer 1: heavy dependencies ----------
+# Cache only invalidates when these two files change
+COPY pyproject.toml uv.lock ./
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev
+
+# ---------- layer 2: application code ----------
+COPY . /code
+
+# Put the venv at the beginning of PATH
+ENV PATH="/code/.venv/bin:$PATH"
+
+# Do not use uv as the entrypoint
+ENTRYPOINT []
+
+CMD ["uv", "run", "main.py"]

README.md

@@ -1,2 +1,63 @@
 # uv-python-workflow
-A modern Python workflow powered by uv — includes CI/CD, Docker, pre-commit, and Pyright type checking.
+
+A modern Python workflow powered by [uv](https://github.com/astral-sh/uv).
+This template integrates **CI/CD, Docker, pre-commit hooks, and Pyright type checking** for a reproducible and maintainable development setup.
+
+## ✨ Features
+
+- 🚀 **uv** for fast, reliable dependency management
+- ✅ **pre-commit** hooks (lint, format, type-check) (uv add --dev pre-commit)
+- 🔎 **Pyright** for static type checking (uv add --dev "pyright[nodejs]")
+- 🐳 **Dockerfile** for reproducible environments
+- 🔄 **CI/CD (GitHub Actions)** with linting, formatting, type checking, and tests
+
+## 📦 Getting Started
+
+```bash
+# Install dependencies
+uv sync
+
+# Run app
+uv run main.py
+```
+
+## 🧹 Pre-commit Hooks
+
+Configured with [pre-commit](https://pre-commit.com/):
+
+```bash
+pre-commit install --install-hooks --hook-type pre-commit --hook-type commit-msg --hook-type pre-push
+pre-commit run --all-files  # Run all hooks on all files (only needed once after installation)
+```
+
+## 🐳 Docker
+
+```bash
+docker build -t uv-python-workflow .
+docker run --rm uv-python-workflow
+```
+
+## 🔄 CI/CD
+
+GitHub Actions workflow (`.github/workflows/ci.yml`) runs:
+
+- Dependency install with `uv`
+- Linting & formatting with `ruff`
+- Type checking with `pyright`
+- Tests with `pytest`
+
+## 🧭 Commitizen (Conventional Commits)
+
+```powershell
+# Install (dev)
+uv add --dev commitizen
+
+# Stage changes
+git add .
+
+# Interactive commit
+cz commit or cz c
+
+# Semantic version bump + tag (optional)
+cz bump --yes
+```

main.py

@@ -0,0 +1,19 @@
+"""
+Entry point demonstrating usage of the calculator module.
+
+Runs a simple example that prints the result of adding two numbers using the
+``src.calculator`` module.
+"""
+
+from src.calculator import add
+
+
+def main() -> None:
+    """Run the example and print a simple addition result."""
+
+    result = add(1, 2)
+    print(f"Example: 1 + 2 = {result}")
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,122 @@
+[project]
+dependencies = []
+description = "Add your description here"
+name = "uv-python-workflow"
+readme = "README.md"
+requires-python = ">=3.12"
+version = "0.1.0"
+
+[dependency-groups]
+dev = [
+  "commitizen>=4.9.1",
+  "pre-commit>=4.3.0",
+  "pyright[nodejs]>=1.1.405",
+  "pytest>=8.4.2",
+  "pytest-cov>=7.0.0",
+  "pytest-sugar>=1.1.1",
+]
+
+[tool.commitizen]
+major_version_zero = true
+name = "cz_conventional_commits"
+tag_format = "v$version"
+update_changelog_on_bump = true
+version_provider = "pyproject"
+version_scheme = "pep440"
+
+[tool.ruff] # https://docs.astral.sh/ruff/settings/#top-level
+exclude = [".venv"]
+line-length = 100
+
+[tool.ruff.lint] # https://docs.astral.sh/ruff/settings/#lint
+extend-select = [
+  "FAST001", # fast-api-redundant-response-model
+  "FAST002", # fast-api-non-annotated-dependency
+  "D100", # missing-module-docstring
+  "D101", # undocumented-public-class
+  "D102", # missing-class-docstring
+  "D103", # undocumented-public-function
+  "D213", # multi-line-summary-second-line
+  "D400", # missing-trailing-period
+  "ERA001", # commented-out-code
+]
+select = [
+  "B", # flake8-bugbear
+  "E", # pycodestyle
+  "F", # pyflakes
+  "I", # isort
+  "S", # bandit
+  "W", # pycodestyle
+  "UP", # pyupgrade
+  "C4", # flake8-comprehensions
+  "ANN", # flake8-annotations
+  "TRY", # tryceratops
+  "PERF", # perflint
+  "ASYNC", # flake8-async
+]
+
+# Globally ignore noisy rules (example)
+ignore = [
+  "E402", # module level import not at top of file
+  "TRY003", # Avoid specifying long messages outside the exception class
+  "TRY301", # Abstract `raise` to an inner function
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+  "S101", # Allow use of assert statements in tests
+  "S105", # hardcoded-password-string
+  "S106", # hardcoded-password-func-arg
+]
+
+[tool.ruff.format] # https://docs.astral.sh/ruff/settings/#format
+quote-style = "double" # Quote style, double quotes are default
+
+[tool.coverage.run]
+branch = true
+omit = [
+  "tests/*",
+  ".venv/*",
+]
+source = ["src"]
+
+[tool.coverage.report]
+exclude_also = [
+  "def __repr__",
+  "if self\\.debug",
+  "raise AssertionError",
+  "raise NotImplementedError",
+  "if 0:",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+  "class .*\\bProtocol\\):",
+  "@(abc\\.)?abstractmethod",
+]
+ignore_errors = true
+show_missing = true
+# skip_covered = true
+
+[tool.coverage.xml]
+output = "coverage.xml"
+
+[tool.coverage.html] #  pytest --cov=src --cov-report=html
+directory = "coverage_html_report"
+show_contexts = true
+title = "Coverage Report"
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-config --strict-markers --cov=src --cov-report=xml --cov-report=term-missing"
+filterwarnings = ["error"]
+markers = [
+  "asyncio: marks tests as asyncio tests",
+]
+python_files = ["test_*.py"]
+testpaths = ["tests"]
+
+[tool.pyright]
+exclude = [
+  ".venv",
+]
+typeCheckingMode = "basic"
+venv = ".venv"
+venvPath = "."

src/__init__.py

@@ -0,0 +1,10 @@
+"""
+Public API for the calculator example package.
+
+This module re-exports arithmetic functions for convenient imports:
+``from src import add, subtract, multiply, divide``.
+"""
+
+from .calculator import add, divide, multiply, subtract
+
+__all__ = ["add", "subtract", "multiply", "divide"]

src/calculator.py

@@ -0,0 +1,45 @@
+# Enable postponed evaluation of type annotations (PEP 563)
+"""
+Calculator module providing basic arithmetic functions.
+
+This module exposes four operations: addition, subtraction, multiplication, and
+division. All functions accept integers or floats and return the corresponding
+numeric result. Division by zero raises ``ZeroDivisionError``.
+"""
+
+from __future__ import annotations
+
+Number = int | float
+
+
+def add(a: Number, b: Number) -> Number:
+    """Return the sum of ``a`` and ``b``."""
+
+    return a + b
+
+
+def subtract(a: Number, b: Number) -> Number:
+    """Return the difference of ``a`` minus ``b``."""
+
+    return a - b
+
+
+def multiply(a: Number, b: Number) -> Number:
+    """Return the product of ``a`` and ``b``."""
+
+    return a * b
+
+
+def divide(a: Number, b: Number) -> Number:
+    """
+    Return the quotient of ``a`` divided by ``b``.
+
+    Raises
+    ------
+    ZeroDivisionError
+        If ``b`` equals 0.
+    """
+
+    if b == 0:
+        raise ZeroDivisionError("division by zero")
+    return a / b

tests/conftest.py

@@ -0,0 +1,13 @@
+"""
+Pytest configuration to ensure `src.*` imports work during tests.
+
+This adds the project root directory to ``sys.path`` so that the ``src``
+directory is importable as a top-level package in tests.
+"""
+
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))