From d3731cb5376dd38e29fc201aba0c68c73310fffb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20Sch=C3=BCtz?= <nix@dotlambda.de>
Date: Mon, 27 Jul 2026 11:06:28 -0700
Subject: [PATCH] python3Packages.pythonMetadataCheckHook: improve error
 message for mismatched pname

---
 .../interpreters/python/hooks/default.nix           |  1 +
 .../hooks/python-metadata-check-hook-retrieve.py    | 13 +++++++++++++
 .../python/hooks/python-metadata-check-hook.sh      |  2 +-
 3 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 pkgs/development/interpreters/python/hooks/python-metadata-check-hook-retrieve.py

diff --git a/pkgs/development/interpreters/python/hooks/default.nix b/pkgs/development/interpreters/python/hooks/default.nix
index 4982332e88d1..183bc7af3592 100644
--- a/pkgs/development/interpreters/python/hooks/default.nix
+++ b/pkgs/development/interpreters/python/hooks/default.nix
@@ -368,6 +368,7 @@ in
       substitutions = {
         inherit pythonInterpreter pythonSitePackages;
         pythonWithPackaging = lib.getExe (pythonOnBuildForHost.withPackages (ps: [ ps.packaging ]));
+        retrieveMetadata = ./python-metadata-check-hook-retrieve.py;
       };
       meta = {
         maintainers = [ lib.maintainers.dotlambda ];
diff --git a/pkgs/development/interpreters/python/hooks/python-metadata-check-hook-retrieve.py b/pkgs/development/interpreters/python/hooks/python-metadata-check-hook-retrieve.py
new file mode 100644
index 000000000000..4d4f5198eeb1
--- /dev/null
+++ b/pkgs/development/interpreters/python/hooks/python-metadata-check-hook-retrieve.py
@@ -0,0 +1,13 @@
+from importlib.metadata import PackageNotFoundError, version
+from sys import argv, exit, stderr
+
+
+pname = argv[1]
+try:
+    print(version(pname))
+except PackageNotFoundError as e:
+    print(e, file=stderr)
+    print("This usually means that the derivation's pname does not correspond to the project name, as found on PyPI, in pyproject.toml, or in setup.{py,cfg}.", file=stderr)
+    print("Use the normalized name for the derivation's pname and its attribute name in python3Packages.", file=stderr)
+    print("See https://packaging.python.org/en/latest/specifications/name-normalization/.", file=stderr)
+    exit(1)
diff --git a/pkgs/development/interpreters/python/hooks/python-metadata-check-hook.sh b/pkgs/development/interpreters/python/hooks/python-metadata-check-hook.sh
index de61a8228940..2f2dfd126f9c 100644
--- a/pkgs/development/interpreters/python/hooks/python-metadata-check-hook.sh
+++ b/pkgs/development/interpreters/python/hooks/python-metadata-check-hook.sh
@@ -19,7 +19,7 @@ pythonMetadataCheckPhase() {
   # `python -P` avoids picking up egg-info dirs in $PWD
   local metadataVersion
   metadataVersion="$(PYTHONPATH="$pythonMetadataCheckOutput/@pythonSitePackages@:$PYTHONPATH" \
-    @pythonInterpreter@ -P -c 'from importlib.metadata import version; import sys; print(version(sys.argv[1]))' "$derivationPname")"
+    @pythonInterpreter@ -P @retrieveMetadata@ "$derivationPname")"
 
   # check that both versions can be parsed
   @pythonWithPackaging@ -c "from packaging.version import Version; from sys import argv; Version(argv[1]); Version(argv[2])" "$derivationVersion" "$metadataVersion"