Enable stdenv customization through (buildPython*.override { inherit stdenv; })

doc/languages-frameworks/python.section.md

@@ -557,6 +557,19 @@ are used in [`buildPythonPackage`](#buildpythonpackage-function).
   with the `pipInstallHook`.
 - `unittestCheckHook` will run tests with `python -m unittest discover`. See [example usage](#using-unittestcheckhook).
 
+#### Overriding build helpers {#overriding-python-build-helpers}
+
+Like many of the build helpers provided by Nixpkgs, Python build helpers typically provide a `<function>.override` attribute.
+It works like [`<pkg>.override`](#sec-pkg-override), and can be used to override the dependencies of each build helper.
+
+This allows specifying the stdenv to be used by `buildPythonPackage` or `buildPythonApplication`. The default (`python.stdenv`) can be overridden as follows:
+
+```nix
+buildPythonPackage.override { stdenv = customStdenv; } {
+  # package attrs...
+}
+```
+
 ## User Guide {#user-guide}
 
 ### Using Python {#using-python}

doc/redirects.json

@@ -3807,6 +3807,9 @@
   "buildpythonpackage-parameters": [
     "index.html#buildpythonpackage-parameters"
   ],
+  "overriding-python-build-helpers": [
+    "index.html#overriding-python-build-helpers"
+  ],
   "overriding-python-packages": [
     "index.html#overriding-python-packages"
   ],

doc/release-notes/rl-2511.section.md

@@ -314,6 +314,10 @@
 
 - `emacs` now disables the GC mark trace buffer by default. This improves GC performance by 5%, but can make GC issues harder to debug. This is configurable with `withGcMarkTrace`.
 
+- Passing `stdenv` to `buildPythonPackage` or `buildPythonApplication` has been deprecated and will trigger an error in a future release.
+  Instead, you should _override_ the python build helper, e.g., `(buildPythonPackage.override { stdenv = customStdenv; })`.
+  See [](#overriding-python-build-helpers).
+
 - `buildPythonPackage` and `buildPythonApplication` now default to `nix-update-script` as their default `updateScript`. This should improve automated updates, since nix-update is better maintained than the in-tree update script and has more robust fetcher support.
 
 - `plasma6`: Fixed the `ksycoca` cache not being re-built when `$XDG_CACHE_HOME` is set to something that isn't `$HOME/.cache`.

pkgs/development/interpreters/python/mk-python-derivation.nix

@@ -4,6 +4,8 @@
   lib,
   config,
   python,
+  # Allow passing in a custom stdenv to buildPython*.override
+  stdenv,
   wrapPython,
   unzip,
   ensureNewerSourcesForZipFilesHook,
@@ -192,9 +194,6 @@ in
 
   doCheck ? true,
 
-  # Allow passing in a custom stdenv to buildPython*
-  stdenv ? python.stdenv,
-
   ...
 }@attrs:
 

pkgs/development/interpreters/python/python-packages-base.nix

@@ -45,21 +45,44 @@ let
       override = lib.mirrorFunctionArgs f.override (fdrv: makeOverridablePythonPackage (f.override fdrv));
     };
 
+  overrideStdenvCompat =
+    f:
+    lib.setFunctionArgs (
+      args:
+      if !(lib.isFunction args) && (args ? stdenv) then
+        lib.warnIf (lib.oldestSupportedReleaseIsAtLeast 2511) ''
+          Passing `stdenv` directly to `buildPythonPackage` or `buildPythonApplication` is deprecated. You should use their `.override` function instead, e.g:
+            buildPythonPackage.override { stdenv = customStdenv; } { }
+        '' (f.override { stdenv = args.stdenv; } args)
+      else
+        f args
+    ) (removeAttrs (lib.functionArgs f) [ "stdenv" ])
+    // {
+      # Intentionally drop the effect of overrideStdenvCompat when calling `buildPython*.override`.
+      inherit (f) override;
+    };
+
   mkPythonDerivation =
     if python.isPy3k then ./mk-python-derivation.nix else ./python2/mk-python-derivation.nix;
 
   buildPythonPackage = makeOverridablePythonPackage (
-    callPackage mkPythonDerivation {
-      inherit namePrefix; # We want Python libraries to be named like e.g. "python3.6-${name}"
-      inherit toPythonModule; # Libraries provide modules
-    }
+    overrideStdenvCompat (
+      callPackage mkPythonDerivation {
+        inherit namePrefix; # We want Python libraries to be named like e.g. "python3.6-${name}"
+        inherit toPythonModule; # Libraries provide modules
+        inherit (python) stdenv;
+      }
+    )
   );
 
   buildPythonApplication = makeOverridablePythonPackage (
-    callPackage mkPythonDerivation {
-      namePrefix = ""; # Python applications should not have any prefix
-      toPythonModule = x: x; # Application does not provide modules.
-    }
+    overrideStdenvCompat (
+      callPackage mkPythonDerivation {
+        namePrefix = ""; # Python applications should not have any prefix
+        toPythonModule = x: x; # Application does not provide modules.
+        inherit (python) stdenv;
+      }
+    )
   );
 
   # Check whether a derivation provides a Python module.

pkgs/development/interpreters/python/python2/mk-python-derivation.nix

@@ -4,6 +4,8 @@
   lib,
   config,
   python,
+  # Allow passing in a custom stdenv to buildPython*.override
+  stdenv,
   wrapPython,
   unzip,
   ensureNewerSourcesForZipFilesHook,
@@ -101,8 +103,6 @@
 }@attrs:
 
 let
-  inherit (python) stdenv;
-
   withDistOutput = lib.elem format [
     "pyproject"
     "setuptools"

pkgs/development/python-modules/torch/source/default.nix

@@ -275,14 +275,16 @@ let
 
   stdenv' = if cudaSupport then cudaPackages.backendStdenv else stdenv;
 in
-buildPythonPackage rec {
+let
+  # From here on, `stdenv` shall be `stdenv'`.
+  stdenv = stdenv';
+in
+buildPythonPackage.override { inherit stdenv; } rec {
   pname = "torch";
   # Don't forget to update torch-bin to the same version.
   version = "2.8.0";
   pyproject = true;
 
-  stdenv = stdenv';
-
   outputs = [
     "out" # output standard python package
     "dev" # output libtorch headers