Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/numpy/_globals.py: 79%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Module defining global singleton classes.
4This module raises a RuntimeError if an attempt to reload it is made. In that
5way the identities of the classes defined here are fixed and will remain so
6even if numpy itself is reloaded. In particular, a function like the following
7will still work correctly after numpy is reloaded::
9 def foo(arg=np._NoValue):
10 if arg is np._NoValue:
11 ...
13That was not the case when the singleton classes were defined in the numpy
14``__init__.py`` file. See gh-7844 for a discussion of the reload problem that
15motivated this module.
17"""
18import enum
20__ALL__ = [
21 'ModuleDeprecationWarning', 'VisibleDeprecationWarning',
22 '_NoValue', '_CopyMode'
23 ]
26# Disallow reloading this module so as to preserve the identities of the
27# classes defined here.
28if '_is_loaded' in globals():
29 raise RuntimeError('Reloading numpy._globals is not allowed')
30_is_loaded = True
33class ModuleDeprecationWarning(DeprecationWarning):
34 """Module deprecation warning.
36 The nose tester turns ordinary Deprecation warnings into test failures.
37 That makes it hard to deprecate whole modules, because they get
38 imported by default. So this is a special Deprecation warning that the
39 nose tester will let pass without making tests fail.
41 """
44ModuleDeprecationWarning.__module__ = 'numpy'
47class VisibleDeprecationWarning(UserWarning):
48 """Visible deprecation warning.
50 By default, python will not show deprecation warnings, so this class
51 can be used when a very visible warning is helpful, for example because
52 the usage is most likely a user bug.
54 """
57VisibleDeprecationWarning.__module__ = 'numpy'
60class _NoValueType:
61 """Special keyword value.
63 The instance of this class may be used as the default value assigned to a
64 keyword if no other obvious default (e.g., `None`) is suitable,
66 Common reasons for using this keyword are:
68 - A new keyword is added to a function, and that function forwards its
69 inputs to another function or method which can be defined outside of
70 NumPy. For example, ``np.std(x)`` calls ``x.std``, so when a ``keepdims``
71 keyword was added that could only be forwarded if the user explicitly
72 specified ``keepdims``; downstream array libraries may not have added
73 the same keyword, so adding ``x.std(..., keepdims=keepdims)``
74 unconditionally could have broken previously working code.
75 - A keyword is being deprecated, and a deprecation warning must only be
76 emitted when the keyword is used.
78 """
79 __instance = None
80 def __new__(cls):
81 # ensure that only one instance exists
82 if not cls.__instance:
83 cls.__instance = super().__new__(cls)
84 return cls.__instance
86 def __repr__(self):
87 return "<no value>"
90_NoValue = _NoValueType()
93class _CopyMode(enum.Enum):
94 """
95 An enumeration for the copy modes supported
96 by numpy.copy() and numpy.array(). The following three modes are supported,
98 - ALWAYS: This means that a deep copy of the input
99 array will always be taken.
100 - IF_NEEDED: This means that a deep copy of the input
101 array will be taken only if necessary.
102 - NEVER: This means that the deep copy will never be taken.
103 If a copy cannot be avoided then a `ValueError` will be
104 raised.
106 Note that the buffer-protocol could in theory do copies. NumPy currently
107 assumes an object exporting the buffer protocol will never do this.
108 """
110 ALWAYS = True
111 IF_NEEDED = False
112 NEVER = 2
114 def __bool__(self):
115 # For backwards compatibility
116 if self == _CopyMode.ALWAYS:
117 return True
119 if self == _CopyMode.IF_NEEDED:
120 return False
122 raise ValueError(f"{self} is neither True nor False.")
125_CopyMode.__module__ = 'numpy'