Merge branch 'main' into matrix_rank-doc-fix

1 files changed, 15 insertions, 3 deletions

diff --git a/numpy/_globals.py b/numpy/_globals.py
index 9f44c7729..0b715c870 100644
--- a/numpy/_globals.py
+++ b/numpy/_globals.py
@@ -58,14 +58,26 @@ class _NoValueType:
     """Special keyword value.
 
     The instance of this class may be used as the default value assigned to a
-    deprecated keyword in order to check if it has been given a user defined
-    value.
+    keyword if no other obvious default (e.g., `None`) is suitable,
+
+    Common reasons for using this keyword are:
+
+    - A new keyword is added to a function, and that function forwards its
+      inputs to another function or method which can be defined outside of
+      NumPy. For example, ``np.std(x)`` calls ``x.std``, so when a ``keepdims``
+      keyword was added that could only be forwarded if the user explicitly
+      specified ``keepdims``; downstream array libraries may not have added
+      the same keyword, so adding ``x.std(..., keepdims=keepdims)``
+      unconditionally could have broken previously working code.
+    - A keyword is being deprecated, and a deprecation warning must only be
+      emitted when the keyword is used.
+
     """
     __instance = None
     def __new__(cls):
         # ensure that only one instance exists
         if not cls.__instance:
-            cls.__instance = super(_NoValueType, cls).__new__(cls)
+            cls.__instance = super().__new__(cls)
         return cls.__instance
 
     # needed for python 2 to preserve identity through a pickle