feat: give new projects a typed, testable core from day one

yujeongdev · yujeongdev · commit 08c36673094b · 2026-03-27T01:52:22.000+09:00
A template only helps if the first commit already behaves like a real package.
This adds a modern pyproject-based package layout, small robotics/ML-oriented
primitives, example entrypoints, and regression tests so downstream work starts
from executable structure instead of an empty repo.

Constraint: The base template must stay light enough for generic Python use while still feeling robotics/ML-ready
Rejected: Start with a notebook-first scaffold | weak packaging and test discipline for long-lived projects
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep the core package importable without optional extras; push heavyweight stacks to extras and adapters
Tested: uv lock; uv sync --group dev; make check; make build; make run-example-ml; make run-example-robotics; make audit
Not-tested: Real ROS 2 integration and GPU framework installation paths
diff --git a/LICENSE b/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.
diff --git a/docs/ml.md b/docs/ml.md
@@ -0,0 +1,11 @@
+# ML profile
+
+Use the ML profile when you want to keep the repository package-first while still supporting
+training, evaluation, and experiment artifacts.
+
+## Suggested conventions
+
+- Keep notebooks exploratory; keep source of truth in `src/`, `examples/`, and `scripts/`.
+- Store datasets outside the repo and track references/configs in code.
+- Log experiment outputs into `artifacts/` or your external experiment tracker.
+- Install ML extras with `uv sync --group dev --extra ml`.
diff --git a/docs/robotics.md b/docs/robotics.md
@@ -0,0 +1,11 @@
+# Robotics profile
+
+Use the robotics profile when you want the core package to stay pure Python while enabling ROS 2,
+simulation, or hardware-specific integrations as optional layers.
+
+## Suggested conventions
+
+- Treat `src/` as the portable core and place ROS 2 bindings/adapters behind optional modules.
+- Keep control-safe interfaces typed and small.
+- Use `.devcontainer/` when teammates need a reproducible Linux environment.
+- Install robotics extras with `uv sync --group dev --extra robotics`.
diff --git a/examples/ml/train_stub.py b/examples/ml/train_stub.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from python_template.ml import seed_everything, summarize_metrics
+
+
+def main() -> None:
+    seed_everything(42)
+    losses = [0.91, 0.63, 0.42, 0.28]
+    summary = summarize_metrics(losses)
+    print("ML training stub summary")
+    for name, value in summary.items():
+        print(f"- {name}: {value:.4f}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/robotics/pipeline_stub.py b/examples/robotics/pipeline_stub.py
@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from python_template.robotics import CommandFrame, SensorFrame, run_control_loop
+
+
+def proportional_controller(frame: SensorFrame) -> CommandFrame:
+    heading_error = frame.values["heading_error"]
+    return CommandFrame(linear_x=0.3, angular_z=-0.8 * heading_error)
+
+
+def main() -> None:
+    frames = [
+        SensorFrame(timestamp_s=0.0, values={"heading_error": 0.4}),
+        SensorFrame(timestamp_s=0.1, values={"heading_error": 0.1}),
+        SensorFrame(timestamp_s=0.2, values={"heading_error": -0.2}),
+    ]
+    commands = run_control_loop(frames, proportional_controller)
+    print("Robotics pipeline stub")
+    for index, command in enumerate(commands, start=1):
+        print(f"- tick {index}: vx={command.linear_x:.2f}, wz={command.angular_z:.2f}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,93 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-template"
+dynamic = ["version"]
+description = "A modern Python template for robotics and ML projects."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Yujeong" },
+]
+keywords = ["python", "template", "ml", "robotics", "uv", "github-actions"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[project.optional-dependencies]
+ml = [
+  "numpy>=2.3.0",
+  "pandas>=2.3.0",
+  "scikit-learn>=1.7.0",
+]
+robotics = [
+  "numpy>=2.3.0",
+  "pyyaml>=6.0.2",
+  "typing-extensions>=4.14.0; python_version < '3.13'",
+]
+viz = [
+  "matplotlib>=3.10.0",
+  "rich>=14.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/techhouse-looper/python-template"
+Repository = "https://github.com/techhouse-looper/python-template"
+Issues = "https://github.com/techhouse-looper/python-template/issues"
+
+[dependency-groups]
+dev = [
+  "build>=1.3.0",
+  "pip-audit>=2.9.0",
+  "pre-commit>=4.3.0",
+  "pyright>=1.1.405",
+  "pytest>=8.4.0",
+  "pytest-cov>=7.0.0",
+  "ruff>=0.12.0",
+]
+
+[tool.hatch.version]
+path = "src/python_template/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/python_template"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-config --strict-markers"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "C4", "PIE"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pyright]
+pythonVersion = "3.11"
+include = ["src", "tests", "examples"]
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+
+[tool.coverage.run]
+source = ["python_template"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
diff --git a/src/python_template/__about__.py b/src/python_template/__about__.py
@@ -0,0 +1 @@
+__version__ = "0.1.0"
diff --git a/src/python_template/__init__.py b/src/python_template/__init__.py
@@ -0,0 +1,16 @@
+"""Reusable primitives for the python-template project scaffold."""
+
+from python_template.__about__ import __version__
+from python_template.config import ProjectProfile
+from python_template.ml import seed_everything, summarize_metrics
+from python_template.robotics import CommandFrame, SensorFrame, run_control_loop
+
+__all__ = [
+    "CommandFrame",
+    "ProjectProfile",
+    "SensorFrame",
+    "__version__",
+    "run_control_loop",
+    "seed_everything",
+    "summarize_metrics",
+]
diff --git a/src/python_template/__main__.py b/src/python_template/__main__.py
@@ -0,0 +1,14 @@
+from python_template import __version__
+from python_template.config import ProjectProfile
+
+
+def main() -> None:
+    profile = ProjectProfile(name="python-template")
+    print(f"python-template {__version__}")
+    print("Default tasks:")
+    for task in profile.default_tasks:
+        print(f"- {task}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/python_template/config.py b/src/python_template/config.py
@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectProfile:
+    """Minimal typed metadata for a robotics/ML project scaffold."""
+
+    name: str
+    python: str = "3.11+"
+    default_tasks: tuple[str, ...] = field(
+        default_factory=lambda: ("make sync-dev", "make check", "make build"),
+    )
+    optional_extras: tuple[str, ...] = field(
+        default_factory=lambda: ("ml", "robotics", "viz"),
+    )
diff --git a/src/python_template/ml.py b/src/python_template/ml.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import random
+from collections.abc import Iterable
+from statistics import mean
+
+MetricSummary = dict[str, float]
+
+
+def seed_everything(seed: int) -> int:
+    """Seed Python's built-in RNG for deterministic stubs and tests."""
+
+    random.seed(seed)
+    return seed
+
+
+def summarize_metrics(values: Iterable[float]) -> MetricSummary:
+    """Compute a small metric summary for stub training and evaluation loops."""
+
+    observations = [float(value) for value in values]
+    if not observations:
+        msg = "summarize_metrics requires at least one value"
+        raise ValueError(msg)
+
+    return {
+        "count": float(len(observations)),
+        "min": min(observations),
+        "max": max(observations),
+        "mean": mean(observations),
+    }
diff --git a/src/python_template/robotics.py b/src/python_template/robotics.py
@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class SensorFrame:
+    timestamp_s: float
+    values: Mapping[str, float]
+
+
+@dataclass(frozen=True, slots=True)
+class CommandFrame:
+    linear_x: float
+    angular_z: float
+
+
+Policy = Callable[[SensorFrame], CommandFrame]
+
+
+def run_control_loop(frames: Iterable[SensorFrame], policy: Policy) -> list[CommandFrame]:
+    """Map sensor frames to command frames using a simple synchronous policy."""
+
+    return [policy(frame) for frame in frames]
diff --git a/tests/test_cli.py b/tests/test_cli.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def test_module_cli_runs() -> None:
+    result = subprocess.run(
+        [sys.executable, "-m", "python_template"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    assert "python-template" in result.stdout
+    assert "make check" in result.stdout
diff --git a/tests/test_config.py b/tests/test_config.py
@@ -0,0 +1,9 @@
+from python_template.config import ProjectProfile
+
+
+def test_project_profile_defaults() -> None:
+    profile = ProjectProfile(name="demo")
+
+    assert profile.name == "demo"
+    assert profile.default_tasks[0] == "make sync-dev"
+    assert profile.optional_extras == ("ml", "robotics", "viz")
diff --git a/tests/test_ml.py b/tests/test_ml.py
@@ -0,0 +1,26 @@
+import random
+
+import pytest
+
+from python_template.ml import seed_everything, summarize_metrics
+
+
+def test_seed_everything_is_deterministic() -> None:
+    seed_everything(7)
+    first = random.random()
+
+    seed_everything(7)
+    second = random.random()
+
+    assert first == second
+
+
+def test_summarize_metrics_returns_expected_values() -> None:
+    summary = summarize_metrics([1.0, 2.0, 5.0])
+
+    assert summary == {"count": 3.0, "min": 1.0, "max": 5.0, "mean": 8.0 / 3.0}
+
+
+def test_summarize_metrics_rejects_empty_input() -> None:
+    with pytest.raises(ValueError, match="at least one value"):
+        summarize_metrics([])
diff --git a/tests/test_robotics.py b/tests/test_robotics.py
@@ -0,0 +1,19 @@
+from python_template.robotics import CommandFrame, SensorFrame, run_control_loop
+
+
+def test_run_control_loop_applies_policy_to_all_frames() -> None:
+    frames = [
+        SensorFrame(timestamp_s=0.0, values={"heading_error": 0.2}),
+        SensorFrame(timestamp_s=0.1, values={"heading_error": -0.1}),
+    ]
+
+    def policy(frame: SensorFrame) -> CommandFrame:
+        error = frame.values["heading_error"]
+        return CommandFrame(linear_x=0.5, angular_z=-error)
+
+    commands = run_control_loop(frames, policy)
+
+    assert commands == [
+        CommandFrame(linear_x=0.5, angular_z=-0.2),
+        CommandFrame(linear_x=0.5, angular_z=0.1),
+    ]
