Rename template to drc-python

Author: cmccomb

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run local CI gate
+        run: make ci

.github/workflows/docs-pages.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  id-token: write
+  pages: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Build docs
+        run: make docs
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -173,7 +173,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # Abstra
 # Abstra is an AI-powered process automation framework.
@@ -191,6 +191,9 @@ cython_debug/
 # Ruff stuff:
 .ruff_cache/
 
+# Project-local generated artifacts
+artifacts/
+
 # PyPI configuration file
 .pypirc
 

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+# Pre-commit configuration
+
+default_stages: [pre-commit]
+
+repos:
+  - repo: local
+    hooks:
+      - id: make-ci
+        name: make ci
+        entry: make ci
+        language: system
+        pass_filenames: false

.python-version

@@ -0,0 +1 @@
+3.12.12

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+## Purpose
+
+This repository is a reusable Python 3.12+ package template for small,
+well-tested libraries. Keep changes focused, keep the public API intentional,
+and prefer standard-library solutions unless a third-party dependency clearly
+improves the maintenance story.
+
+## Setup
+
+- Create and activate a virtual environment:
+  - `python -m venv .venv`
+  - `source .venv/bin/activate`
+- The reproducible interpreter target lives in `.python-version` (`3.12.12`).
+- Install local tooling with `make dev`.
+- For a frozen environment based on `uv.lock`, use `make repro`.
+
+## Testing And Validation
+
+Use the smallest useful check while iterating, then run the full gate before
+merging.
+
+- Fast local loop:
+  - `make fmt`
+  - `make lint`
+  - `make type`
+  - `make test`
+- If docs changed:
+  - `make docs-check`
+  - `make docs`
+- If the example changed:
+  - `make run-example`
+- Pre-merge baseline:
+  - `make ci`
+- Pre-publish baseline:
+  - `make release-check`
+
+## Public Vs Private Boundaries
+
+- The supported public surface is whatever is re-exported from
+  `src/design_research_python_template/__init__.py`.
+- Prefer adding new public behavior to stable top-level modules before creating
+  deeper internal package trees.
+- If you add internal helper modules later, prefix them with `_` and keep them
+  out of the top-level exports unless there is a deliberate API decision.
+
+## Behavioral Guardrails
+
+- Keep tests deterministic and offline by default.
+- Update tests, docs, and examples alongside behavior changes.
+- Avoid broad dependency growth in the base install.
+- Keep this template easy to fork: simple defaults beat clever abstractions.
+
+## Keep This File Up To Date
+
+Update this file whenever the contributor workflow changes, especially when
+setup commands, validation commands, or the public API expectations change.

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+## Development Setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+make dev
+```
+
+For a reproducible install based on `uv.lock`:
+
+```bash
+make lock
+make repro
+```
+
+## Local Quality Checks
+
+Run these before opening a pull request:
+
+```bash
+make fmt
+make lint
+make type
+make docstrings-check
+make test
+make docs-check
+make docs
+```
+
+Optional but useful:
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+## Pull Request Guidelines
+
+- Keep changes small enough to review quickly.
+- Add or update tests for behavior changes.
+- Update docs and examples when interfaces change.
+- Describe what changed and how you validated it.
+
+## Code Style
+
+- Python 3.12+ target
+- Ruff for linting and formatting
+- Mypy for type checking
+- Pytest for tests
+- Google-style docstrings in `src/`, `examples/`, and `scripts/`

Makefile

@@ -0,0 +1,96 @@
+PYTHON ?= $(if $(wildcard .venv/bin/python),.venv/bin/python,$(shell if command -v python3.12 >/dev/null 2>&1; then echo python3.12; else echo python3; fi))
+PIP ?= $(PYTHON) -m pip
+PYTEST ?= $(PYTHON) -m pytest
+RUFF ?= $(PYTHON) -m ruff
+MYPY ?= $(PYTHON) -m mypy
+SPHINX ?= $(PYTHON) -m sphinx
+BUILD ?= $(PYTHON) -m build
+TWINE ?= $(PYTHON) -m twine
+UV ?= $(if $(wildcard .venv/bin/uv),.venv/bin/uv,uv)
+REPRO_PYTHON ?= $(shell cat .python-version 2>/dev/null || echo 3.12.12)
+REPRO_EXTRAS ?= dev
+
+.PHONY: help check-python check-uv dev install-dev repro lock \
+	lint fmt fmt-check type test qa coverage docstrings-check \
+	run-example docs docs-build docs-check docs-linkcheck \
+	release-check ci clean
+
+help:
+	@echo "Common targets:"
+	@echo "  dev              Install the project in editable mode with dev dependencies."
+	@echo "  repro            Frozen reproducible install using uv.lock."
+	@echo "  lock             Regenerate uv.lock."
+	@echo "  test             Run the pytest suite."
+	@echo "  qa               Run lint, fmt-check, type, and test."
+	@echo "  run-example      Execute the bundled example script."
+	@echo "  docs             Build the HTML docs."
+	@echo "  ci               Run the main local CI checks."
+
+check-python:
+	@$(PYTHON) -c "import pathlib, sys; print(f'Using Python {sys.version.split()[0]} at {pathlib.Path(sys.executable)}'); raise SystemExit(0 if sys.version_info >= (3, 12) else 1)" || (echo "Python >= 3.12 is required by pyproject.toml"; exit 1)
+
+check-uv:
+	@command -v $(UV) >/dev/null 2>&1 || (echo "uv is required for lock/repro targets. Install it from https://docs.astral.sh/uv/getting-started/installation/"; exit 1)
+
+dev:
+	$(PIP) install --upgrade pip setuptools wheel
+	$(PIP) install -e ".[dev]"
+
+install-dev: dev
+
+repro: check-uv
+	$(UV) sync --frozen --python $(REPRO_PYTHON) $(foreach extra,$(REPRO_EXTRAS),--extra $(extra))
+
+lock: check-uv
+	$(UV) lock --python $(REPRO_PYTHON)
+
+lint: check-python
+	$(RUFF) check .
+
+fmt: check-python
+	$(RUFF) format .
+
+fmt-check: check-python
+	$(RUFF) format --check .
+
+type: check-python
+	$(MYPY) src
+
+test: check-python
+	PYTHONPATH=src $(PYTEST) -q
+
+qa: lint fmt-check type test
+
+coverage: check-python
+	mkdir -p artifacts/coverage
+	PYTHONPATH=src $(PYTEST) --cov=src/design_research_python_template --cov-report=term --cov-report=json:artifacts/coverage/coverage.json -q
+	$(PYTHON) scripts/check_coverage_thresholds.py --coverage-json artifacts/coverage/coverage.json
+
+docstrings-check: check-python
+	$(PYTHON) scripts/check_google_docstrings.py
+
+run-example: check-python
+	PYTHONPATH=src $(PYTHON) examples/basic_usage.py
+
+docs-build: check-python
+	PYTHONPATH=src $(SPHINX) -b html docs docs/_build/html -n -W --keep-going -E
+
+docs-check: check-python
+	$(PYTHON) scripts/check_docs_consistency.py
+
+docs-linkcheck: check-python
+	PYTHONPATH=src $(SPHINX) -b linkcheck docs docs/_build/linkcheck -W --keep-going -E
+
+docs: docs-build
+
+release-check: check-python
+	rm -rf build dist
+	$(BUILD) --no-isolation
+	$(TWINE) check dist/*
+
+ci: qa coverage docstrings-check docs-check run-example release-check
+
+clean:
+	rm -rf .coverage .mypy_cache .pytest_cache .ruff_cache artifacts build dist docs/_build src/design_research_python_template.egg-info
+	find . -type d -name "__pycache__" -prune -exec rm -rf {} + 2>/dev/null || true
+	find . -type f \( -name "*.pyc" -o -name ".coverage.*" \) -exec rm -f {} + 2>/dev/null || true