diff options
Diffstat (limited to 'numpy/_globals.py')
| -rw-r--r-- | numpy/_globals.py | 18 |
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 |