python3Packages.mkPythonEditablePackage: init

doc/languages-frameworks/python.section.md

@@ -374,6 +374,50 @@ mkPythonMetaPackage {
 }
 ```
 
+#### `mkPythonEditablePackage` function {#mkpythoneditablepackage-function}
+
+When developing Python packages it's common to install packages in [editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html).
+Like `mkPythonMetaPackage` this function exists to create an otherwise empty package, but also containing a pointer to an impure location outside the Nix store that can be changed without rebuilding.
+
+The editable root is passed as a string. Normally `.pth` files contains absolute paths to the mutable location. This isn't always ergonomic with Nix, so environment variables are expanded at runtime.
+This means that a shell hook setting up something like a `$REPO_ROOT` variable can be used as the relative package root.
+
+As an implementation detail, the [PEP-518](https://peps.python.org/pep-0518/) `build-system` specified won't be used, but instead the editable package will be built using [hatchling](https://pypi.org/project/hatchling/).
+The `build-system`'s provided will instead become runtime dependencies of the editable package.
+
+Note that overriding packages deeper in the dependency graph _can_ work, but it's not the primary use case and overriding existing packages can make others break in unexpected ways.
+
+``` nix
+{ pkgs ? import <nixpkgs> { } }:
+
+let
+  pyproject = pkgs.lib.importTOML ./pyproject.toml;
+
+  myPython = pkgs.python.override {
+    self = myPython;
+    packageOverrides = pyfinal: pyprev: {
+      # An editable package with a script that loads our mutable location
+      my-editable = pyfinal.mkPythonEditablePackage {
+        # Inherit project metadata from pyproject.toml
+        pname = pyproject.project.name;
+        inherit (pyproject.project) version;
+
+        # The editable root passed as a string
+        root = "$REPO_ROOT/src"; # Use environment variable expansion at runtime
+
+        # Inject a script (other PEP-621 entrypoints are also accepted)
+        inherit (pyproject.project) scripts;
+      };
+    };
+  };
+
+  pythonEnv =  testPython.withPackages (ps: [ ps.my-editable ]);
+
+in pkgs.mkShell {
+  packages = [ pythonEnv ];
+}
+```
+
 #### `python.buildEnv` function {#python.buildenv-function}
 
 Python environments can be created using the low-level `pkgs.buildEnv` function.