Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/numpy/_globals.py: 74%

1""" 

2Module defining global singleton classes. 

3 

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:: 

8 

9 def foo(arg=np._NoValue): 

10 if arg is np._NoValue: 

11 ... 

12 

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. 

16 

17""" 

18import enum 

19 

20from ._utils import set_module as _set_module 

21 

22__all__ = ['_NoValue', '_CopyMode'] 

23 

24 

25# Disallow reloading this module so as to preserve the identities of the 

26# classes defined here. 

27if '_is_loaded' in globals(): 

28 raise RuntimeError('Reloading numpy._globals is not allowed') 

29_is_loaded = True 

30 

31 

32class _NoValueType: 

33 """Special keyword value. 

34 

35 The instance of this class may be used as the default value assigned to a 

36 keyword if no other obvious default (e.g., `None`) is suitable, 

37 

38 Common reasons for using this keyword are: 

39 

40 - A new keyword is added to a function, and that function forwards its 

41 inputs to another function or method which can be defined outside of 

42 NumPy. For example, ``np.std(x)`` calls ``x.std``, so when a ``keepdims`` 

43 keyword was added that could only be forwarded if the user explicitly 

44 specified ``keepdims``; downstream array libraries may not have added 

45 the same keyword, so adding ``x.std(..., keepdims=keepdims)`` 

46 unconditionally could have broken previously working code. 

47 - A keyword is being deprecated, and a deprecation warning must only be 

48 emitted when the keyword is used. 

49 

50 """ 

51 __instance = None 

52 

53 def __new__(cls): 

54 # ensure that only one instance exists 

55 if not cls.__instance: 

56 cls.__instance = super().__new__(cls) 

57 return cls.__instance 

58 

59 def __repr__(self): 

60 return "<no value>" 

61 

62 

63_NoValue = _NoValueType() 

64 

65 

66@_set_module("numpy") 

67class _CopyMode(enum.Enum): 

68 """ 

69 An enumeration for the copy modes supported 

70 by numpy.copy() and numpy.array(). The following three modes are supported, 

71 

72 - ALWAYS: This means that a deep copy of the input 

73 array will always be taken. 

74 - IF_NEEDED: This means that a deep copy of the input 

75 array will be taken only if necessary. 

76 - NEVER: This means that the deep copy will never be taken. 

77 If a copy cannot be avoided then a `ValueError` will be 

78 raised. 

79 

80 Note that the buffer-protocol could in theory do copies. NumPy currently 

81 assumes an object exporting the buffer protocol will never do this. 

82 """ 

83 

84 ALWAYS = True 

85 NEVER = False 

86 IF_NEEDED = 2 

87 

88 def __bool__(self): 

89 # For backwards compatibility 

90 if self == _CopyMode.ALWAYS: 

91 return True 

92 

93 if self == _CopyMode.NEVER: 

94 return False 

95 

96 raise ValueError(f"{self} is neither True nor False.")