From 82da9cf45c21f9b93b48d8ef40ff6005dfc5a53b Mon Sep 17 00:00:00 2001
From: Yueh-Shun Li <shamrocklee@posteo.net>
Date: Mon, 27 Apr 2026 03:13:53 +0800
Subject: [PATCH] python3Packages.buildPythonPackage: ban pytestFlagsArray

---
 doc/release-notes/rl-2605.section.md             |  4 ++++
 .../interpreters/python/mk-python-derivation.nix | 16 ++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/doc/release-notes/rl-2605.section.md b/doc/release-notes/rl-2605.section.md
index 40f605b2315d..cb3c0f28d474 100644
--- a/doc/release-notes/rl-2605.section.md
+++ b/doc/release-notes/rl-2605.section.md
@@ -168,6 +168,10 @@
 
 - the `xorg` package set has been deprecated, packages have moved to the top level.
 
+- `python3Packages.buildPythonPackage` and `python3Packages.buildPythonApplication` now throw errors in the presence of `pytestFlagsArray`.
+  Please use [`pytestFlags` and `(enabled|disabled)(TestPaths|Tests|TestMarks)`](#using-pytestcheckhook) instead.
+  If modifying the Nix expression is not feasible, users can remediate the error by overriding `pytestFlagsArray` with `null` or `[ ]`.
+
 - `python3Packages.pygame` has been been renamed to `python3Packages.pygame-original`, the attribute `python3Packages.pygame` will from python 3.14 default to the more actively maintained `python3Packages.pygame-ce`
 
 - `fastly` has been updated to major version 14. For more information, you can check the [release notes](https://github.com/fastly/cli/releases/tag/v14.0.0)
diff --git a/pkgs/development/interpreters/python/mk-python-derivation.nix b/pkgs/development/interpreters/python/mk-python-derivation.nix
index 5bbde1ab2f97..5f4ac7b84645 100644
--- a/pkgs/development/interpreters/python/mk-python-derivation.nix
+++ b/pkgs/development/interpreters/python/mk-python-derivation.nix
@@ -112,6 +112,9 @@ lib.extendMkDerivation {
     "dependencies"
     "optional-dependencies"
     "build-system"
+
+    # Deprecated arguments
+    "pytestFlagsArray"
   ];
 
   extendDrvArgs =
@@ -439,6 +442,19 @@ lib.extendMkDerivation {
       # Longer-term we should get rid of `checkPhase` and use `installCheckPhase`.
       installCheckPhase = attrs.checkPhase;
     }
+    // (
+      let
+        deprecatedFlagNotEmpty =
+          attrs ? pytestFlagsArray && attrs.pytestFlagsArray != null && attrs.pytestFlagsArray != [ ];
+        pos = builtins.unsafeGetAttrPos "pytestFlagsArray" attrs;
+      in
+      {
+        ${if deprecatedFlagNotEmpty then "pytestFlagsArray" else null} = throw ''
+          buildPythonPackage: Deprecated flag pytestFlagsArray found at ${pos.file}:${toString pos.line}
+            Use pytestFlags or (enabled|disabled)(TestPaths|Tests|TestMarks) instead.
+        '';
+      }
+    )
     //
       lib.mapAttrs
         (