buildPythonPackage: mark unsupported interpreter with meta.problems.unsupportedPython (#540720)

doc/languages-frameworks/python.section.md

@@ -163,8 +163,85 @@ following are specific to `buildPythonPackage`:
 
 * `catchConflicts ? true`: If `true`, abort package build if a package name
   appears more than once in dependency tree. Default is `true`.
-* `disabled ? false`: If `true`, package is not built for the particular Python
-  interpreter version.
+* `disabled ? false`:
+  If set to `true` for a particular Python interpreter version or implementation, the package is marked with `meta.problems.unsupportedPython`, and will throw an error message complaining the Python interpreter being unsupported during package instantiation.
+
+  ```nix
+  {
+    lib,
+    pythonAtLeast,
+    buildPythonPackage,
+    fetchFromGitHub,
+    setuptools,
+  }:
+  buildPythonPackage (finalAttrs: {
+    pname = "coconut";
+    version = "3.1.2";
+    pyproject = true;
+
+    src = fetchFromGitHub {
+      owner = "evhub";
+      repo = "coconut";
+      tag = "v${finalAttrs.version}";
+      hash = "sha256-Vd6ZY3PlbPOy63/0/0YJ1U2PpsVdctOoInyKftj//cM=";
+    };
+
+    disabled = pythonAtLeast "3.13";
+
+    build-system = [
+      setuptools
+    ];
+
+    meta = {
+      homepage = "http://coconut-lang.org/";
+    };
+  })
+  ```
+
+  One can also choose to mark a package with `meta.problems.unsupportedPython` providing a custom `message` and optional `urls`:
+
+  ```nix
+  {
+    lib,
+    python,
+    pythonAtLeast,
+    buildPythonPackage,
+    fetchFromGitHub,
+    setuptools,
+  }:
+  buildPythonPackage (finalAttrs: {
+    pname = "coconut";
+    version = "3.1.2";
+    pyproject = true;
+
+    src = fetchFromGitHub {
+      owner = "evhub";
+      repo = "coconut";
+      tag = "v${finalAttrs.version}";
+      hash = "sha256-Vd6ZY3PlbPOy63/0/0YJ1U2PpsVdctOoInyKftj//cM=";
+    };
+
+    build-system = [
+      setuptools
+    ];
+
+    meta = {
+      homepage = "http://coconut-lang.org/";
+      problems.unsupportedPython = lib.optionalAttrs (pythonAtLeast "3.13") {
+        message = lib.removePrefix (python.libPrefix + "-") finalAttrs.name + " requires Python <3.13";
+        urls = [
+          "https://github.com/evhub/coconut/issues/873"
+        ];
+      };
+    };
+  })
+  ```
+
+  ::: {.note}
+  Referencing `<pkg>.disabled` or `finalAtts.disabled` for Python packages are deprecated.
+  Use `<pkg> ? meta.problems.unsupportedPython` instead (the same goes with `finalAttrs`).
+  :::
+
 * `dontWrapPythonPrograms ? false`: Skip wrapping of Python programs.
 * `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment
   variable in wrapped programs.