Scaffold Python repository

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Checks
+    runs-on: ubuntu-latest
+    env:
+      UV_DEFAULT_INDEX: https://pypi.org/simple
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Check lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Run type checks
+        run: uv run pyright
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files

.gitignore

@@ -0,0 +1,59 @@
+# Byte-compiled / optimized Python files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Native extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+*.egg-info/
+installed.cfg
+MANIFEST
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test and coverage artifacts
+.coverage
+.coverage.*
+coverage.xml
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+
+# Type-checking and linting caches
+.mypy_cache/
+.pyre/
+.pytype/
+.pyright/
+.ruff_cache/
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDEs and editors
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Operating system files
+.DS_Store
+Thumbs.db

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+default_language_version:
+  python: python3.14
+
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff lint
+        entry: uv run ruff check .
+        language: system
+        pass_filenames: false
+
+      - id: ruff-format
+        name: Ruff format
+        entry: uv run ruff format --check .
+        language: system
+        pass_filenames: false
+
+      - id: pyright
+        name: Pyright
+        entry: uv run pyright
+        language: system
+        pass_filenames: false

.python-version

@@ -0,0 +1 @@
+3.14

README.md

@@ -2,11 +2,48 @@
 A project to explore the details of "[Balancing Coupling in Software Design][coupling:book]",
 a book by [Vlad Khononov][coupling:author].
 
+## Development setup
+
+This repository uses [uv][uv] for Python installation, dependency management, and
+running development tools.
+
+Install uv by following the [official installation instructions][uv:install].
+Then install Python 3.14 and the project dependencies:
+
+```sh
+uv python install 3.14
+uv sync --dev
+```
+
+Install the pre-commit hooks after syncing the dependencies:
+
+```sh
+uv run pre-commit install
+```
+
+Run the checks locally with:
+
+```sh
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run pre-commit run --all-files
+```
+
+The pre-commit configuration runs formatting, linting, type checking, and the
+test suite, so it covers more than tests alone.
+
+The project uses a `src` layout for application code and a `tests` directory for
+the test suite.
+
 ## Goal
-The goal of this project is to acquire hands-on experience with the concepts from [the book][coupling:book].
+The goal of this project is to acquire hands-on experience with the concepts from
+[the book][coupling:book].
 We intent to develop software and critique it through the lens of coupling.
 
-Since the purpose is to explore, a lot of knowledge will not be in code. So do not forget to checkout:
+Since the purpose is to explore, a lot of knowledge will not be in code.
+So do not forget to checkout:
 
 * [discussions][project:discussions]
 * [issues][project:issues]
@@ -19,3 +56,5 @@ Since the purpose is to explore, a lot of knowledge will not be in code. So do n
 [project:issues]: https://github.com/fifth-postulate/coupling/issues
 [project:projects]: https://github.com/fifth-postulate/coupling/projects
 [project:wiki]: https://github.com/fifth-postulate/coupling/wiki
+[uv]: https://docs.astral.sh/uv/
+[uv:install]: https://docs.astral.sh/uv/getting-started/installation/

pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "coupling"
+version = "0.1.0"
+description = "Explorations of coupling in software design."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14,<3.15"
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.3.0",
+    "pyright>=1.1.404",
+    "pytest>=8.4.0",
+    "ruff>=0.12.10",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = ["-ra"]
+testpaths = ["tests"]
+
+[tool.pyright]
+include = ["src", "tests"]
+exclude = [".venv"]
+pythonVersion = "3.14"
+typeCheckingMode = "strict"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]

src/coupling/__init__.py

@@ -0,0 +1 @@
+"""Coupling project package."""

tests/test_package.py

@@ -0,0 +1,8 @@
+"""Tests for the coupling package."""
+
+import coupling
+
+
+def test_package_imports() -> None:
+    """The package can be imported."""
+    assert coupling.__name__ == "coupling"