Languages: four for glue, Python for programs

The long form of rule 24.

The policy (21/10/2026, revised 22/10/2026)Copy Anchor Link

Configuration and glue are written in, by priority:

Python is the ONE language allowed past these four, and only for a PROGRAM. Third-party code the repo only PACKAGES (an upstream Python app built with buildPythonApplication) is not code the repo writes, and is not counted.

How to chooseCopy Anchor Link

Walk the steps in order and stop at the FIRST one that fits. The order is the point: each step is cheaper to keep than the next.

0. No code. Look for a NixOS or home-manager option, or a tool already in nixpkgs, before writing anything (rules 1 and 3). The best script is the one that does not exist.

1. Nix, when the job is data, validation or generation that can happen at evaluation or build: a list of ports, a config file rendered from options, an assertion.

2. The host's language, when a program only accepts extensions in one language: Lua for Hyprland, QML for Quickshell, Python for a kitty kitten, TypeScript for a Vicinae extension.

3. Shell, when the job is GLUE: each line runs another program and passes its output on, and the control flow is sequence, a case on a subcommand, an exit code checked, a retry. jq, sed, awk and rg belong here only as ONE-LINE filters (jq -r '.name', rg -c pattern). Examples: moonlight-stats (journalctl into one jq filter), data-syntax (three parsers called per file), the local WoL paths (socat).

4. Python, when ANY of these signals shows. One is enough:

Examples: the calendar registry (dates and the computus, with tests), razer-dpi (ioctls), Vicinae's icons (fontTools' pen API), eval-metrics (number formatting and budgets).

The 100-line limit is a smell before it is a verdict. A basic job that needs more than 100 lines of logic, in ANY language, usually means a missing tool (back to step 0) or a design doing too much (split it, or cut it). Only when neither holds is it a program, and then it is Python. A Python file past about 200 lines of logic splits into modules (eval-metrics warns past its budget).

5. Never. A program written in jq, awk, sed or Perl; TypeScript for the repo's own tooling; a sixth language for any reason. router-ssot is the example of what this step forbids: a jq program of 139 lines with functions and IP arithmetic.

Everything outside the four is registered in the table below with its reason and a review date (rule 22): each Python file, and each host-imposed language.

Why the policy was revised (22/10/2026)Copy Anchor Link

The first version allowed four languages and nothing else, and its plan moved every Python program to shell. Phase A (the six pre-commit checkers) and part of phase C went that way, one commit each, each MEASURED against the Python it replaced. Two measurements changed the plan:

• Speed was not the gain. Every checker runs under half a second either way; docs-links went from 0.07s to 0.14s, since bash spawning rg costs more than a Python already running.
• The cost was silent bugs. Six showed up only because each port was diffed against the Python, and none of them can exist in Python: a jq A + B as $x binding that dropped 8 of 11 findings, a . rebound inside a jq pipe, an exit inside $(...) that would have turned a failed ssh into "in sync", an ssh that swallowed its loop's input, a thousands separator grouped from the left (28,328 printed as 283), and a NUL byte bash cannot hold.

And the language count it bought was partly an illusion: router-ssot and dead-config became jq programs of 50 to 130 lines with functions and IP arithmetic, so one language was traded for four dialects (bash, jq, PCRE, sed). Glue in shell is shorter and clearer than Python; a program in shell is neither.

The registered exceptionsCopy Anchor Link

Known debt, by the steps aboveCopy Anchor Link

MEASURED on 22/10/2026 in lines of logic (comments and blank lines excluded). Each one is past the limit or a jq program, so by step 4 or 5 it is a program in the wrong language. A debt is paid the day its file is touched for a real change, the way rule 17 handles en-US, never in a separate sweep:

What was migrated, and stays shellCopy Anchor Link

Each one MEASURED against the Python it replaced; the detail is in each tool's note.

MEASURED on 22/10/2026: 930 lines left in .py files (1,183 before router-sync.py and zen/lab.py left), and about 520 in writePython3 bodies, down from about 1,578.

What only Python needsCopy Anchor Link

The ruff hook stays, since loose .py files remain. python3 and uv in modules/nixos/packages.nix are my own tools for other projects, not this repo's code, and are not governed by this rule.