Build a practical Python starter template

.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+- What changed?
+- Why does it matter?
+
+## Testing
+
+- [ ] `make check`
+- [ ] `make build`
+- [ ] Other:
+
+## Checklist
+
+- [ ] Scope is small and reviewable
+- [ ] Docs updated if needed
+- [ ] No unrelated changes included
+
+## Notes
+
+- Breaking changes:
+- Follow-ups:

.github/workflows/build.yml

@@ -0,0 +1,35 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version-file: .python-version
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Build wheel and sdist
+        run: make build
+      - name: Smoke-test built wheel
+        run: |
+          python -m venv /tmp/python-template-wheel-test
+          /tmp/python-template-wheel-test/bin/pip install dist/*.whl
+          /tmp/python-template-wheel-test/bin/python-template --help
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-dist
+          path: dist/

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: quality (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync --group dev --frozen
+      - name: Run quality gate
+        run: make check

.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release-artifacts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version-file: .python-version
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Build release artifacts
+        run: make build
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-template-release-${{ github.ref_name }}
+          path: dist/

.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# Virtual environments
+.venv/
+venv/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Test and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Type checking and lint caches
+.pyright/
+.ruff_cache/
+.mypy_cache/
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store
+
+# AI assistant local state
+.claude/
+.claude.json
+.claude.json.backup*
+CLAUDE.local.md
+.codex/.codex-global-state.json
+.codex/.omx/
+.codex/archived_sessions/
+.codex/history.jsonl
+.codex/log/
+.codex/logs_*.sqlite
+.codex/logs_*.sqlite-*
+.codex/session_index.jsonl
+.codex/sessions/
+.codex/shell_snapshots/
+.codex/sqlite/
+.codex/state_*.sqlite
+.codex/tmp/
+
+# Local env
+.env
+.env.*
+!.env.example
+
+# Project-local automation state
+.omx/

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]

.python-version

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

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yujeong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,51 @@
+PACKAGE ?= python_template
+SRC_DIRS := src tests
+
+.PHONY: help setup setup-dev lock update format format-check lint lint-fix typecheck test test-cov check build clean
+
+.DEFAULT_GOAL := help
+
+help: ## Show available tasks
+	@awk 'BEGIN {FS = ":.*##"; printf "\nAvailable tasks:\n\n"} /^[a-zA-Z0-9_.-]+:.*##/ {printf "  %-20s %s\n", $$1, $$2} END {print ""}' $(MAKEFILE_LIST)
+
+setup: ## Install the base project environment
+	uv sync
+
+setup-dev: ## Install developer dependencies
+	uv sync --group dev
+
+lock: ## Refresh uv.lock without upgrading pinned packages
+	uv lock
+
+update: ## Upgrade dependencies and refresh uv.lock
+	uv lock --upgrade
+
+format: ## Format the codebase with Ruff
+	uv run ruff format $(SRC_DIRS)
+
+format-check: ## Check formatting without modifying files
+	uv run ruff format --check $(SRC_DIRS)
+
+lint: ## Run Ruff lint checks
+	uv run ruff check $(SRC_DIRS)
+
+lint-fix: ## Run Ruff lint checks and apply safe fixes
+	uv run ruff check --fix $(SRC_DIRS)
+
+typecheck: ## Run Pyright type checking
+	uv run pyright
+
+test: ## Run tests
+	PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run pytest
+
+test-cov: ## Run tests with coverage
+	PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run pytest --cov=$(PACKAGE) --cov-report=term-missing
+
+check: format-check lint typecheck test ## Run the full local quality gate
+
+build: ## Build wheel and sdist artifacts
+	uv build
+
+clean: ## Remove local build and tool caches
+	rm -rf .venv .pytest_cache .pyright .ruff_cache .mypy_cache build dist htmlcov .coverage .coverage.*
+	find . -type d -name '__pycache__' -prune -exec rm -rf {} +

README.md

@@ -1 +1,84 @@
-# python-template
+# python-template 🐍
+
+A small Python starter with strict defaults, fast feedback, and a package layout that scales past
+the first weekend.
+
+The goal is simple: start from a clean baseline, keep the toolchain boring, and make quality checks
+cheap enough to run all the time.
+
+## Defaults
+
+- `uv` for dependency and lockfile management
+- `src/` layout with Hatchling packaging
+- Click for a minimal CLI entry point
+- Ruff, Pyright, and pytest as the default quality bar
+- GitHub Actions for CI, build validation, and release artifacts
+
+## Quickstart
+
+```bash
+make setup-dev
+make check
+uv run python -m python_template --help
+uv run python -m python_template hello
+```
+
+Sample output:
+
+```text
+Let's build something fun, Yujeong.
+```
+
+## Core commands
+
+| Command | Purpose |
+| --- | --- |
+| `make setup` | Install runtime dependencies |
+| `make setup-dev` | Install runtime and development dependencies |
+| `make format` | Format the codebase with Ruff |
+| `make lint` | Run Ruff lint checks |
+| `make lint-fix` | Run Ruff and apply safe fixes |
+| `make typecheck` | Run Pyright in strict mode |
+| `make test` | Run pytest |
+| `make test-cov` | Run pytest with coverage |
+| `make check` | Run format, lint, typecheck, and tests |
+| `make build` | Build the wheel and sdist |
+| `make lock` | Refresh `uv.lock` without upgrading |
+| `make update` | Upgrade dependencies and refresh `uv.lock` |
+
+## Project layout
+
+```text
+.
+├── .github/workflows/
+├── src/python_template/
+├── tests/
+├── .pre-commit-config.yaml
+├── Makefile
+├── pyproject.toml
+└── uv.lock
+```
+
+## Quality defaults
+
+This template is intentionally strict by default:
+
+- **Ruff** enforces formatting, imports, docstrings, naming, typing hygiene, and common bug-prone
+  patterns.
+- **Pyright** runs in `strict` mode.
+- **pytest** is the default regression layer.
+
+If a real project constraint justifies relaxing a rule, change it deliberately. The default posture
+is to keep the baseline tight.
+
+## GitHub Actions
+
+The repository ships with three focused workflows:
+
+- `ci.yml` — lint, typecheck, and test on Python 3.11–3.13
+- `build.yml` — build the package and smoke-test the generated wheel
+- `release.yml` — build and upload release artifacts for version tags
+
+## License
+
+MIT.