diff options
| -rw-r--r-- | numpy/_globals.py | 16 |
1 files changed, 14 insertions, 2 deletions
diff --git a/numpy/_globals.py b/numpy/_globals.py index 9f44c7729..4a8c266d3 100644 --- a/numpy/_globals.py +++ b/numpy/_globals.py @@ -58,8 +58,20 @@ 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): |