Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/numpy/_core/_asarray.py: 26%

1""" 

2Functions in the ``as*array`` family that promote array-likes into arrays. 

3 

4`require` fits this category despite its name not matching this pattern. 

5""" 

6from .overrides import ( 

7 array_function_dispatch, 

8 set_array_function_like_doc, 

9 set_module, 

10) 

11from .multiarray import array, asanyarray 

12 

13 

14__all__ = ["require"] 

15 

16 

17POSSIBLE_FLAGS = { 

18 'C': 'C', 'C_CONTIGUOUS': 'C', 'CONTIGUOUS': 'C', 

19 'F': 'F', 'F_CONTIGUOUS': 'F', 'FORTRAN': 'F', 

20 'A': 'A', 'ALIGNED': 'A', 

21 'W': 'W', 'WRITEABLE': 'W', 

22 'O': 'O', 'OWNDATA': 'O', 

23 'E': 'E', 'ENSUREARRAY': 'E' 

24} 

25 

26 

27@set_array_function_like_doc 

28@set_module('numpy') 

29def require(a, dtype=None, requirements=None, *, like=None): 

30 """ 

31 Return an ndarray of the provided type that satisfies requirements. 

32 

33 This function is useful to be sure that an array with the correct flags 

34 is returned for passing to compiled code (perhaps through ctypes). 

35 

36 Parameters 

37 ---------- 

38 a : array_like 

39 The object to be converted to a type-and-requirement-satisfying array. 

40 dtype : data-type 

41 The required data-type. If None preserve the current dtype. If your 

42 application requires the data to be in native byteorder, include 

43 a byteorder specification as a part of the dtype specification. 

44 requirements : str or sequence of str 

45 The requirements list can be any of the following 

46 

47 * 'F_CONTIGUOUS' ('F') - ensure a Fortran-contiguous array 

48 * 'C_CONTIGUOUS' ('C') - ensure a C-contiguous array 

49 * 'ALIGNED' ('A') - ensure a data-type aligned array 

50 * 'WRITEABLE' ('W') - ensure a writable array 

51 * 'OWNDATA' ('O') - ensure an array that owns its own data 

52 * 'ENSUREARRAY', ('E') - ensure a base array, instead of a subclass 

53 ${ARRAY_FUNCTION_LIKE} 

54 

55 .. versionadded:: 1.20.0 

56 

57 Returns 

58 ------- 

59 out : ndarray 

60 Array with specified requirements and type if given. 

61 

62 See Also 

63 -------- 

64 asarray : Convert input to an ndarray. 

65 asanyarray : Convert to an ndarray, but pass through ndarray subclasses. 

66 ascontiguousarray : Convert input to a contiguous array. 

67 asfortranarray : Convert input to an ndarray with column-major 

68 memory order. 

69 ndarray.flags : Information about the memory layout of the array. 

70 

71 Notes 

72 ----- 

73 The returned array will be guaranteed to have the listed requirements 

74 by making a copy if needed. 

75 

76 Examples 

77 -------- 

78 >>> x = np.arange(6).reshape(2,3) 

79 >>> x.flags 

80 C_CONTIGUOUS : True 

81 F_CONTIGUOUS : False 

82 OWNDATA : False 

83 WRITEABLE : True 

84 ALIGNED : True 

85 WRITEBACKIFCOPY : False 

86 

87 >>> y = np.require(x, dtype=np.float32, requirements=['A', 'O', 'W', 'F']) 

88 >>> y.flags 

89 C_CONTIGUOUS : False 

90 F_CONTIGUOUS : True 

91 OWNDATA : True 

92 WRITEABLE : True 

93 ALIGNED : True 

94 WRITEBACKIFCOPY : False 

95 

96 """ 

97 if like is not None: 

98 return _require_with_like( 

99 like, 

100 a, 

101 dtype=dtype, 

102 requirements=requirements, 

103 ) 

104 

105 if not requirements: 

106 return asanyarray(a, dtype=dtype) 

107 

108 requirements = {POSSIBLE_FLAGS[x.upper()] for x in requirements} 

109 

110 if 'E' in requirements: 

111 requirements.remove('E') 

112 subok = False 

113 else: 

114 subok = True 

115 

116 order = 'A' 

117 if requirements >= {'C', 'F'}: 

118 raise ValueError('Cannot specify both "C" and "F" order') 

119 elif 'F' in requirements: 

120 order = 'F' 

121 requirements.remove('F') 

122 elif 'C' in requirements: 

123 order = 'C' 

124 requirements.remove('C') 

125 

126 arr = array(a, dtype=dtype, order=order, copy=None, subok=subok) 

127 

128 for prop in requirements: 

129 if not arr.flags[prop]: 

130 return arr.copy(order) 

131 return arr 

132 

133 

134_require_with_like = array_function_dispatch()(require)