diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..c410254 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,38 @@ +name: ci + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + nix: + name: nix build + run + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: DeterminateSystems/determinate-nix-action@v3 + - name: Evaluate flake outputs + run: nix flake show + - name: Build the closed world + run: nix build --print-build-logs + - name: Run the product (network-free) + run: nix run .# + - name: Import inside the declared env + run: | + nix develop --command python -c \ + "import python_gate, rich; print(python_gate.greet())" + + uv: + name: uv sync --locked + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: astral-sh/setup-uv@v6 + - name: Sync from uv.lock (packages, not a closure) + run: uv sync --locked + - name: Run via the uv-managed env + run: uv run python-gate diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a8657a9 --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +.venv/ +result +result-* +__pycache__/ +*.py[cod] +*.egg-info/ +.direnv/ +dist/ +build/ +.python-version diff --git a/README.md b/README.md index eeb0e27..c2c96b7 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,119 @@ # python-gate -Nix as Python's missing gate: uv owns the expression, Nix closes the world, nix run is the product. + +**This is a GitHub template.** Use it as *Use this template*, or: + +```bash +nix flake new -t github:Hedronite/python-gate ./my-app +``` + +Nix is the gate. uv owns the expression. `nix run` is the product. + +`mkVirtualEnv` / `withPackages` builds a world; `mkApplication` / `wrapProgram` locks the door; nix-ld is the FHS lie (unsafe, Level 2). + +A Python shop that is not on NixOS still `uv sync`s from `uv.lock`. A Nix user or CI `nix develop`s and `nix run .#`s the same closure. Two proofs: `uv.lock` (packages) and `flake.lock` (builders). **A lockfile is not a closure.** + +This repository is the working example *and* the cloneable template. v1 is Level 3: no CUDA, no PyO3, no native extensions. + +## The ladder + +| Level | What you have | What you do not have | +| --- | --- | --- | +| 0 | Host Python, `pip install` | A lock, a world, a product | +| 1 | `uv.lock` / `poetry.lock` | A closure. Builders are the host | +| 2 | nix-ld / steam-run / `LD_LIBRARY_PATH` | Bit-identity. This is the FHS lie | +| **3** | **uv2nix `mkVirtualEnv` + `mkApplication`. This template** | CUDA, PyO3, native extensions | +| 4 | Native/FFI bits patched into the store | (out of scope for v1) | + +Level 2 can run a wheel. It is not a closed world. Do not claim it is bit-identical. + +## Init + +```bash +# GitHub template, or: +nix flake new -t github:Hedronite/python-gate ./my-app +cd ./my-app + +# Rename the project: pyproject.toml [project] name, [project.scripts], +# src//, and `projectName` in flake.nix. Then: +uv lock +``` + +Without Nix (inner loop): + +```bash +uv sync +uv run python-gate +``` + +With Nix (same world, locked door): + +```bash +nix develop # store venv + peace treaty +nix run .# # the product; network-free +``` + +## Add a dependency + +uv writes the expression. Nix consumes it. Do not hand-translate `uv.lock` into `python3Packages`. + +```bash +uv add httpx # or any pure-Python wheel uv2nix can eat +git add uv.lock pyproject.toml +nix run .# # rebuilds the world from the new lock +git add flake.lock # only if flake inputs moved +git commit +``` + +Commit **both** lockfiles. `uv.lock` pins packages. `flake.lock` pins builders. Either one alone is a story, not a closure. + +## Peace treaty (dev shell) + +The Nix shell and uv share one interpreter. They do not share authority over the environment. + +| Variable | Value | Why | +| --- | --- | --- | +| `UV_NO_SYNC` | `1` | uv must not provision a second venv | +| `UV_PYTHON` | the Nix interpreter | one Python set | +| `UV_PYTHON_DOWNLOADS` | `never` | Nix owns the interpreter | +| `PYTHONPATH` | unset in `shellHook` | kill nixpkgs `PYTHONPATH` leakage | + +On NixOS, if you must run an **unpatched** FHS binary, set `NIX_LD` and `NIX_LD_LIBRARY_PATH` (nix-ld). **Never set `LD_LIBRARY_PATH` as the default.** That is a Level 2 leak into a Level 3 world. + +## Must not + +- Keep a second venv (`.venv`) beside the store venv. `uv run` inside `nix develop` is how you grow a second world. +- Use poetry2nix. It is unmaintained. This template is uv + uv2nix. +- Claim Level 2 (nix-ld / `LD_LIBRARY_PATH`) is bit-identical. +- Edit `uv.lock` or `flake.lock` by hand. +- Hand-translate `uv.lock` into `python3Packages`. +- Set `LD_LIBRARY_PATH` as the default on NixOS. + +## Agent grading + +A change is done when all of these pass: + +1. **Flake eval.** `nix flake show` lists `packages..default`, `devShells..default`, and `templates.default`. Systems: `x86_64-linux`, `aarch64-linux`, `aarch64-darwin` (nixos-unstable dropped Intel Macs). +2. **Import inside the declared env.** `nix develop --command python -c "import python_gate, rich"` succeeds. +3. **`uv sync --locked`.** The non-Nix inner loop still reproduces from `uv.lock`. +4. **Same closure.** `nix run .#` and `nix develop` use the same Python set (same interpreter, same uv2nix overlay). The product is the wrapped application, not a hope. + +CI on `ubuntu-latest` runs `nix build` / `nix run` (Determinate Nix) and `uv sync --locked` (setup-uv). Green means both proofs held, not that one was skipped. + +## Example app + +`src/python_gate` is a console script plus `rich`. `nix run .#` prints versions and `square(12)` — a pure function, no HTTP. That is the point: the closure is enough. + +## Further reading + +Short doctrine: [`docs/theses.md`](docs/theses.md). + +Upstream builders (2026 map — do not use last year's): + +- [uv](https://docs.astral.sh/uv/) +- [uv2nix](https://pyproject-nix.github.io/uv2nix/) +- [pyproject.nix](https://pyproject-nix.github.io/pyproject.nix/) +- [pyproject-build-systems](https://github.com/pyproject-nix/build-system-pkgs) + +## License + +MIT. Copyright Hedronite 2026. diff --git a/docs/theses.md b/docs/theses.md new file mode 100644 index 0000000..641bbc2 --- /dev/null +++ b/docs/theses.md @@ -0,0 +1,25 @@ +# Twelve theses + +1. **The Python environment is part of the program.** An interpreter, a set of wheels, and a script are one artifact. Shipping the script alone is a wish. + +2. **A lockfile is not a closure.** `uv.lock` pins packages. `flake.lock` pins builders. The closure is the store paths those two proofs evaluate to. + +3. **uv owns the expression.** Add, remove, and pin through `pyproject.toml` / `uv.lock`. Do not hand-translate the lock into `python3Packages`. Do not edit lockfiles by hand. + +4. **Nix is the gate.** Nothing enters the world except through evaluation. If it does not evaluate, it is not a dependency. + +5. **`mkVirtualEnv` / `withPackages` builds a world.** Individual packages are not a product. The aggregated environment is. + +6. **`mkApplication` / `wrapProgram` locks the door.** The virtualenv is an implementation detail. The product is a wrapped binary. + +7. **Wrapping is FFI.** The ABI of the program is the store path, not `LD_LIBRARY_PATH`, not the host `libstdc++`, not a hope that the wheel matches the machine. + +8. **Eval is the critic.** Tests that run against a second venv are reviewing a different play. `nix flake show`, import inside the declared env, `nix run`. + +9. **The product is `nix run`.** A green `uv sync` is a proof of packages. The product is the closed world a stranger can run without becoming you. + +10. **nix-ld is the FHS lie.** It is Level 2: useful for unpatched binaries, unsafe as a default, and never bit-identical. On NixOS use `NIX_LD` / `NIX_LD_LIBRARY_PATH`. Never set `LD_LIBRARY_PATH` as the default. + +11. **One Python set.** `devShells.default` and `packages.default` share the same interpreter and the same uv2nix overlay. Editables on the shell are a lens, not a second world. The peace treaty (`UV_NO_SYNC`, `UV_PYTHON`, `UV_PYTHON_DOWNLOADS=never`, unset `PYTHONPATH`) is how they stay one. + +12. **This template is Level 3.** No CUDA, no PyO3, no native extension in v1. Level 4 is a different door. Do not pretend Level 2 is this one. diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..08e5150 --- /dev/null +++ b/flake.lock @@ -0,0 +1,99 @@ +{ + "nodes": { + "nixpkgs": { + "locked": { + "lastModified": 1788039129, + "narHash": "sha256-pa4Q0qErvCvzCaaUph7Sm37RhR4xvPrYI8Lgz6k85+A=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "d2f67949798825fe853f7c5d0492b8bf016d3f88", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "pyproject-build-systems": { + "inputs": { + "nixpkgs": [ + "nixpkgs" + ], + "pyproject-nix": [ + "pyproject-nix" + ], + "uv2nix": [ + "uv2nix" + ] + }, + "locked": { + "lastModified": 1788149501, + "narHash": "sha256-XKJP4KvhawV3pyVfraX3sflz05Rp7KP74gRt6QqKjNE=", + "owner": "pyproject-nix", + "repo": "build-system-pkgs", + "rev": "150839ac67b5a34db56a55e8f6b7099a4e7878ab", + "type": "github" + }, + "original": { + "owner": "pyproject-nix", + "repo": "build-system-pkgs", + "type": "github" + } + }, + "pyproject-nix": { + "inputs": { + "nixpkgs": [ + "nixpkgs" + ] + }, + "locked": { + "lastModified": 1786031528, + "narHash": "sha256-cROiHKO3UbIKqF5FG5NikvydzlfIj4EcR1Cty9qOVt4=", + "owner": "pyproject-nix", + "repo": "pyproject.nix", + "rev": "1b1485546d85f6f6c7aadb10c4923dbc09633263", + "type": "github" + }, + "original": { + "owner": "pyproject-nix", + "repo": "pyproject.nix", + "type": "github" + } + }, + "root": { + "inputs": { + "nixpkgs": "nixpkgs", + "pyproject-build-systems": "pyproject-build-systems", + "pyproject-nix": "pyproject-nix", + "uv2nix": "uv2nix" + } + }, + "uv2nix": { + "inputs": { + "nixpkgs": [ + "nixpkgs" + ], + "pyproject-nix": [ + "pyproject-nix" + ] + }, + "locked": { + "lastModified": 1788001239, + "narHash": "sha256-AELmsXPI546MhbC/ZXC7WRUkCz7d4rqKTHUmliIgPpI=", + "owner": "pyproject-nix", + "repo": "uv2nix", + "rev": "7f9c6b613d2e749e54854b1d60ab6a2192db889e", + "type": "github" + }, + "original": { + "owner": "pyproject-nix", + "repo": "uv2nix", + "type": "github" + } + } + }, + "root": "root", + "version": 7 +} diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..e4caacd --- /dev/null +++ b/flake.nix @@ -0,0 +1,162 @@ +{ + description = "Closed-world Python: Nix is the gate, uv owns the expression"; + + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + + pyproject-nix = { + url = "github:pyproject-nix/pyproject.nix"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + + uv2nix = { + url = "github:pyproject-nix/uv2nix"; + inputs.pyproject-nix.follows = "pyproject-nix"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + + pyproject-build-systems = { + url = "github:pyproject-nix/build-system-pkgs"; + inputs.pyproject-nix.follows = "pyproject-nix"; + inputs.uv2nix.follows = "uv2nix"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + }; + + outputs = + { + self, + nixpkgs, + pyproject-nix, + uv2nix, + pyproject-build-systems, + ... + }: + let + inherit (nixpkgs) lib; + + # nixos-unstable (26.11+) dropped x86_64-darwin. Intel Macs: stay on + # `uv sync` (Level 1) or pin nixpkgs-26.05-darwin. + systems = [ + "x86_64-linux" + "aarch64-linux" + "aarch64-darwin" + ]; + forAllSystems = lib.genAttrs systems; + + # Rename this (and src/, and [project.scripts]) when you clone the template. + projectName = "python-gate"; + + workspace = uv2nix.lib.workspace.loadWorkspace { workspaceRoot = ./.; }; + + overlay = workspace.mkPyprojectOverlay { + # Wheels "just work" more often than sdists. Per-package overrides still win. + sourcePreference = "wheel"; + }; + + # Same Python set for packages.default and (editable overlay on top) devShells.default. + pythonSets = forAllSystems ( + system: + let + pkgs = nixpkgs.legacyPackages.${system}; + python = pkgs.python3; + in + (pkgs.callPackage pyproject-nix.build.packages { + inherit python; + }).overrideScope + ( + lib.composeManyExtensions [ + pyproject-build-systems.overlays.wheel + overlay + ] + ) + ); + in + { + # `nix flake new -t github:Hedronite/python-gate` + templates.default = { + path = ./.; + description = "Closed-world Python: Nix is the gate, uv owns the expression"; + welcomeText = '' + # python-gate + + Nix is the gate. uv owns the expression. `nix run` is the product. + + - Non-Nix: `uv sync` then `uv run python-gate` + - Nix / CI: `nix develop` and `nix run .#` + + Commit both lockfiles. A lockfile is not a closure. + See README.md for the ladder, the peace treaty, and agent grading. + ''; + }; + + packages = forAllSystems ( + system: + let + pkgs = nixpkgs.legacyPackages.${system}; + pythonSet = pythonSets.${system}; + inherit (pkgs.callPackages pyproject-nix.build.util { }) mkApplication; + in + { + # mkVirtualEnv builds the world; mkApplication locks the door. + default = mkApplication { + venv = pythonSet.mkVirtualEnv "${projectName}-env" workspace.deps.default; + package = pythonSet.${projectName}; + }; + } + ); + + apps = forAllSystems (system: { + default = { + type = "app"; + program = "${self.packages.${system}.default}/bin/${projectName}"; + }; + }); + + devShells = forAllSystems ( + system: + let + pkgs = nixpkgs.legacyPackages.${system}; + pythonSet = pythonSets.${system}.overrideScope ( + workspace.mkEditablePyprojectOverlay { root = "$REPO_ROOT"; } + ); + virtualenv = pythonSet.mkVirtualEnv "${projectName}-dev-env" workspace.deps.all; + in + { + default = pkgs.mkShell { + packages = [ + virtualenv + pkgs.uv + pkgs.git + ]; + + # Peace treaty: Nix owns the interpreter and the world. + # uv may rewrite uv.lock; it must not invent a second venv. + env = { + UV_NO_SYNC = "1"; + UV_PYTHON = pythonSet.python.interpreter; + UV_PYTHON_DOWNLOADS = "never"; + }; + + shellHook = '' + unset PYTHONPATH + export REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) + ''; + }; + } + ); + + checks = forAllSystems ( + system: + let + pkgs = nixpkgs.legacyPackages.${system}; + app = self.packages.${system}.default; + in + { + "${projectName}-runs" = pkgs.runCommand "${projectName}-runs" { } '' + ${app}/bin/${projectName} > $out + ''; + } + ); + }; +} diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..3cfd92f --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,18 @@ +[project] +name = "python-gate" +version = "0.1.0" +description = "Closed-world Python: Nix is the gate, uv owns the expression" +readme = "README.md" +requires-python = ">=3.12" +license = "MIT" +authors = [{ name = "Hedronite" }] +dependencies = [ + "rich>=13", +] + +[project.scripts] +python-gate = "python_gate:main" + +[build-system] +requires = ["uv_build>=0.11.0,<0.13.0"] +build-backend = "uv_build" diff --git a/src/python_gate/__init__.py b/src/python_gate/__init__.py new file mode 100644 index 0000000..7060133 --- /dev/null +++ b/src/python_gate/__init__.py @@ -0,0 +1,25 @@ +"""Tiny closed-world example. The product is `nix run`; this module is the payload.""" + +from importlib.metadata import version + +from rich.console import Console +from rich.table import Table + + +def square(n: int) -> int: + """A pure function. `nix run` must not need the network.""" + return n * n + + +def greet() -> str: + return f"{version('python-gate')} · rich {version('rich')} · square(12)={square(12)}" + + +def main() -> None: + table = Table(title="python-gate · closed world") + table.add_column("proof") + table.add_column("value") + table.add_row("python-gate", version("python-gate")) + table.add_row("rich", version("rich")) + table.add_row("square(12)", str(square(12))) + Console().print(table) diff --git a/uv.lock b/uv.lock new file mode 100644 index 0000000..887f7fe --- /dev/null +++ b/uv.lock @@ -0,0 +1,57 @@ +version = 1 +revision = 3 +requires-python = ">=3.12" + +[[package]] +name = "markdown-it-py" +version = "4.2.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mdurl" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" }, +] + +[[package]] +name = "mdurl" +version = "0.1.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" }, +] + +[[package]] +name = "pygments" +version = "2.21.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/49/2e/ced460408999b33da6b31b0021b0f37d329e202d4169aeb164493778f25b/pygments-2.21.0.tar.gz", hash = "sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c", size = 5005329, upload-time = "2026-08-17T08:02:48.824Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/71/46/17f022dd3e953bf20a04a028a21ec746d942f8d2af30fa0f124fa0e6a684/pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9", size = 1250147, upload-time = "2026-08-17T08:02:44.912Z" }, +] + +[[package]] +name = "python-gate" +version = "0.1.0" +source = { editable = "." } +dependencies = [ + { name = "rich" }, +] + +[package.metadata] +requires-dist = [{ name = "rich", specifier = ">=13" }] + +[[package]] +name = "rich" +version = "15.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown-it-py" }, + { name = "pygments" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" }, +]