Rework Flake templates & add impure development template

This separates documentation from user-level templates & provides a little bit more scaffolding with handling of `system`.

Author: adisbladis

doc/src/SUMMARY.md

@@ -17,6 +17,9 @@
     - [hacks](./builders/hacks.md)
   - [ecosystem](./builders/ecosystem.md)
 
+# [Templates](./templates.md)
+- [Flake Templates](./templates.md)
+
 # Meta
 - [FAQ](./FAQ.md)
 

doc/src/templates.md

@@ -0,0 +1,35 @@
+# Flake templates
+
+Pyproject.nix offers a number of Flake templates to quickly get started with developing
+
+To get started with any of the listed templates run (replace `name` with the template name):
+
+## pyproject
+
+Using nixpkgs for Python development based on a PEP-621 `pyproject.toml` file.
+A quickstart & production version of [use-cases/pyproject](./use-cases/pyproject.html).
+
+```
+nix flake init --template github:pyproject-nix/pyproject.nix#pyproject
+```
+
+## requirements
+
+Use a `requirements.txt` to create a Python environment using nixpkgs Python packages.
+A quickstart & production version of [use-cases/requirements](./use-cases/requirements.html).
+
+```
+nix flake init --template github:pyproject-nix/pyproject.nix#requirements
+```
+
+## impure
+
+Simple no frills best practices development shell to develop Python projects with Nix, but without using Nix tooling for Python packages.
+
+Does not depend on `pyproject.nix`.
+
+Uses `uv` for Python package management.
+
+```
+nix flake init --template github:pyproject-nix/pyproject.nix#impure
+```

doc/src/use-cases/pyproject.md

@@ -7,7 +7,7 @@ This example loads `pyproject.toml` to create an environment using [`python.with
 ## flake.nix
 
 ```nix
-{{#include ../../../templates/pyproject/flake.nix}}
+{{#include ./pyproject/flake.nix}}
 ```
 
 ## pyproject.toml

doc/src/use-cases/pyproject/flake.nix

@@ -0,0 +1,60 @@
+{
+  description = "A basic flake using pyproject.toml project metadata";
+
+  inputs.pyproject-nix.url = "github:pyproject-nix/pyproject.nix";
+  inputs.pyproject-nix.inputs.nixpkgs.follows = "nixpkgs";
+
+  outputs =
+    { nixpkgs, pyproject-nix, ... }:
+    let
+      # Loads pyproject.toml into a high-level project representation
+      # Do you notice how this is not tied to any `system` attribute or package sets?
+      # That is because `project` refers to a pure data representation.
+      project = pyproject-nix.lib.project.loadPyproject {
+        # Read & unmarshal pyproject.toml relative to this project root.
+        # projectRoot is also used to set `src` for renderers such as buildPythonPackage.
+        projectRoot = ./.;
+      };
+
+      # This example is only using x86_64-linux
+      pkgs = nixpkgs.legacyPackages.x86_64-linux;
+
+      # We are using the default nixpkgs Python3 interpreter & package set.
+      #
+      # This means that you are purposefully ignoring:
+      # - Version bounds
+      # - Dependency sources (meaning local path dependencies won't resolve to the local path)
+      #
+      # To use packages from local sources see "Overriding Python packages" in the nixpkgs manual:
+      # https://nixos.org/manual/nixpkgs/stable/#reference
+      #
+      # Or use an overlay generator such as uv2nix:
+      # https://github.com/pyproject-nix/uv2nix
+      python = pkgs.python3;
+
+    in
+    {
+      # Create a development shell containing dependencies from `pyproject.toml`
+      devShells.x86_64-linux.default =
+        let
+          # Returns a function that can be passed to `python.withPackages`
+          arg = project.renderers.withPackages { inherit python; };
+
+          # Returns a wrapped environment (virtualenv like) with all our packages
+          pythonEnv = python.withPackages arg;
+
+        in
+        # Create a devShell like normal.
+        pkgs.mkShell { packages = [ pythonEnv ]; };
+
+      # Build our package using `buildPythonPackage
+      packages.x86_64-linux.default =
+        let
+          # Returns an attribute set that can be passed to `buildPythonPackage`.
+          attrs = project.renderers.buildPythonPackage { inherit python; };
+        in
+        # Pass attributes to buildPythonPackage.
+        # Here is a good spot to add on any missing or custom attributes.
+        python.pkgs.buildPythonPackage (attrs // { env.CUSTOM_ENVVAR = "hello"; });
+    };
+}

doc/src/use-cases/requirements.md

@@ -7,5 +7,5 @@ This example loads `requirements.txt` to create an environment using [`python.wi
 ## flake.nix
 
 ```nix
-{{#include ../../../templates/requirements-txt/flake.nix}}
+{{#include ./requirements/flake.nix}}
 ```

doc/src/use-cases/requirements/flake.nix

@@ -0,0 +1,30 @@
+{
+  description = "Construct development shell from requirements.txt";
+
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+
+  inputs.pyproject-nix.url = "github:pyproject-nix/pyproject.nix";
+
+  outputs =
+    { nixpkgs, pyproject-nix, ... }:
+    let
+      # Load/parse requirements.txt
+      project = pyproject-nix.lib.project.loadRequirementsTxt { projectRoot = ./.; };
+
+      pkgs = nixpkgs.legacyPackages.x86_64-linux;
+      python = pkgs.python3;
+
+      pythonEnv =
+        # Assert that versions from nixpkgs matches what's described in requirements.txt
+        # In projects that are overly strict about pinning it might be best to remove this assertion entirely.
+        assert project.validators.validateVersionConstraints { inherit python; } == { };
+        (
+          # Render requirements.txt into a Python withPackages environment
+          pkgs.python3.withPackages (project.renderers.withPackages { inherit python; })
+        );
+
+    in
+    {
+      devShells.x86_64-linux.default = pkgs.mkShell { packages = [ pythonEnv ]; };
+    };
+}

templates/impure/flake.nix

@@ -0,0 +1,34 @@
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+  };
+
+  outputs =
+    { nixpkgs, ... }:
+    let
+      inherit (nixpkgs) lib;
+      forAllSystems = lib.genAttrs lib.systems.flakeExposed;
+    in
+    {
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = nixpkgs.legacyPackages.${system};
+        in
+        {
+          default = pkgs.mkShell {
+            packages = [
+              pkgs.python3
+              pkgs.uv
+            ];
+
+            shellHook = ''
+              unset PYTHONPATH
+              uv sync
+              . .venv/bin/activate
+            '';
+          };
+        }
+      );
+    };
+}

templates/impure/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "impure-package"
+version = "0.1.0"
+description = "Add your description here"
+authors = [ ]
+requires-python = ">=3.13"
+dependencies = []

templates/pyproject/flake.nix

@@ -1,60 +1,41 @@
 {
-  description = "A basic flake using pyproject.toml project metadata";
+  description = "Flake using pyproject.toml metadata";
 
   inputs.pyproject-nix.url = "github:pyproject-nix/pyproject.nix";
   inputs.pyproject-nix.inputs.nixpkgs.follows = "nixpkgs";
 
   outputs =
     { nixpkgs, pyproject-nix, ... }:
     let
-      # Loads pyproject.toml into a high-level project representation
-      # Do you notice how this is not tied to any `system` attribute or package sets?
-      # That is because `project` refers to a pure data representation.
+      inherit (nixpkgs) lib;
+      forAllSystems = lib.genAttrs lib.systems.flakeExposed;
+
       project = pyproject-nix.lib.project.loadPyproject {
-        # Read & unmarshal pyproject.toml relative to this project root.
-        # projectRoot is also used to set `src` for renderers such as buildPythonPackage.
         projectRoot = ./.;
       };
 
-      # This example is only using x86_64-linux
-      pkgs = nixpkgs.legacyPackages.x86_64-linux;
-
-      # We are using the default nixpkgs Python3 interpreter & package set.
-      #
-      # This means that you are purposefully ignoring:
-      # - Version bounds
-      # - Dependency sources (meaning local path dependencies won't resolve to the local path)
-      #
-      # To use packages from local sources see "Overriding Python packages" in the nixpkgs manual:
-      # https://nixos.org/manual/nixpkgs/stable/#reference
-      #
-      # Or use an overlay generator such as uv2nix:
-      # https://github.com/pyproject-nix/uv2nix
-      python = pkgs.python3;
-
+      pythonAttr = "python3";
     in
     {
-      # Create a development shell containing dependencies from `pyproject.toml`
-      devShells.x86_64-linux.default =
-        let
-          # Returns a function that can be passed to `python.withPackages`
-          arg = project.renderers.withPackages { inherit python; };
-
-          # Returns a wrapped environment (virtualenv like) with all our packages
-          pythonEnv = python.withPackages arg;
-
-        in
-        # Create a devShell like normal.
-        pkgs.mkShell { packages = [ pythonEnv ]; };
-
-      # Build our package using `buildPythonPackage
-      packages.x86_64-linux.default =
+      devShells = forAllSystems (system: {
+        default =
+          let
+            pkgs = nixpkgs.legacyPackages.${system};
+            python = pkgs.${pythonAttr};
+            pythonEnv = python.withPackages (project.renderers.withPackages { inherit python; });
+          in
+          pkgs.mkShell { packages = [ pythonEnv ]; };
+      });
+
+      packages = forAllSystems (
+        system:
         let
-          # Returns an attribute set that can be passed to `buildPythonPackage`.
-          attrs = project.renderers.buildPythonPackage { inherit python; };
+          pkgs = nixpkgs.legacyPackages.${system};
+          python = pkgs.${pythonAttr};
         in
-        # Pass attributes to buildPythonPackage.
-        # Here is a good spot to add on any missing or custom attributes.
-        python.pkgs.buildPythonPackage (attrs // { env.CUSTOM_ENVVAR = "hello"; });
+        {
+          default = python.pkgs.buildPythonPackage (project.renderers.buildPythonPackage { inherit python; });
+        }
+      );
     };
 }

templates/pyproject/pyproject.toml

@@ -1,47 +1,7 @@
 [project]
-name = "spam"
-version = "2020.0.0"
-description = "Lovely Spam! Wonderful Spam!"
-readme = "README.rst"
-requires-python = ">=3.8"
-license = {file = "LICENSE.txt"}
-keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
-authors = [
-  {email = "[email protected]"},
-  {name = "Tzu-ping Chung"}
-]
-maintainers = [
-  {name = "Brett Cannon", email = "[email protected]"}
-]
-classifiers = [
-  "Development Status :: 4 - Beta",
-  "Programming Language :: Python"
-]
-
-dependencies = [
-  "httpx",
-  "gidgethub[httpx]>4.0.0",
-  "django>2.1; os_name != 'nt'",
-  "django>2.0; os_name == 'nt'"
-]
-
-[project.optional-dependencies]
-test = [
-  "pytest < 5.0.0",
-  "pytest-cov[all]"
-]
-
-[project.urls]
-homepage = "https://example.com"
-documentation = "https://readthedocs.org"
-repository = "https://github.com"
-changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
-
-[project.scripts]
-spam-cli = "spam:main_cli"
-
-[project.gui-scripts]
-spam-gui = "spam:main_gui"
-
-[project.entry-points."spam.magical"]
-tomatoes = "spam:main_tomatoes"
+name = "hello-python"
+version = "0.1.0"
+description = "A minimal pyproject.toml"
+authors = [ ]
+requires-python = ">=3.13"
+dependencies = []