nanopynix

Eval Nix from Python — a fast, async-first Python binding for the Nix evaluator.

Contents

• Workers vs in-process
  • What's the same
  • What's different
  • When to pick which
• Architecture principles
  • Public versus internal
  • Native resource ownership
  • Process ownership
  • Cancellation reaches Nix, or the evaluator is abandoned
  • Error taxonomy
  • Logging must not hold Nix back
  • Transport-independent domain models
  • The in-process and RPC behavioural contract
  • Sync and async policy
  • Compatibility and versioning
• Quality gates
  • Every commit — fast, hermetic, no Nix daemon needed
  • Every pull request — the correctness gate
  • Every pull request — the drift gate (new)
  • Merge to the default branch — the expensive matrix
  • Platform-specific, opt-in
  • What deliberately stays out
• Decisions: rejected ideas and open questions
  • Rejected or deferred ideas
  • Open questions
• Examples
  • Evaluating Nix expressions
  • Evaluating a flake
  • Querying the Nix store
  • Nix settings
  • Custom primops and YAML
  • In-process (L2) API
• API reference
  • Worker (L3)
  • Inproc (L2)
  • Process setup
  • Namespaced workers and the overlay store
  • Settings
  • Stores
  • Models
  • Protocols
  • Exceptions
  • YAML primops
  • The compiled bindings

Quick start

import asyncio

import nanopynix


async def main() -> None:
    async with (
        nanopynix.rpc.Session() as session,
        session.store() as store,
        session.eval(store) as evaluator,
    ):
        hello = await evaluator.string('"hello, world"')
        print(await hello.to_python())


if __name__ == "__main__":
    asyncio.run(main())

The if __name__ guard is required rather than conventional. The rpc engine starts its worker with the multiprocessing forkserver, which refuses to start a child while the main module is still importing.