Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.10/site-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 finalize_array_function_like, 

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@finalize_array_function_like 

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 >>> import numpy as np 

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

80 >>> x.flags 

81 C_CONTIGUOUS : True 

82 F_CONTIGUOUS : False 

83 OWNDATA : False 

84 WRITEABLE : True 

85 ALIGNED : True 

86 WRITEBACKIFCOPY : False 

87 

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

89 >>> y.flags 

90 C_CONTIGUOUS : False 

91 F_CONTIGUOUS : True 

92 OWNDATA : True 

93 WRITEABLE : True 

94 ALIGNED : True 

95 WRITEBACKIFCOPY : False 

96 

97 """ 

98 if like is not None: 

99 return _require_with_like( 

100 like, 

101 a, 

102 dtype=dtype, 

103 requirements=requirements, 

104 ) 

105 

106 if not requirements: 

107 return asanyarray(a, dtype=dtype) 

108 

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

110 

111 if 'E' in requirements: 

112 requirements.remove('E') 

113 subok = False 

114 else: 

115 subok = True 

116 

117 order = 'A' 

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

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

120 elif 'F' in requirements: 

121 order = 'F' 

122 requirements.remove('F') 

123 elif 'C' in requirements: 

124 order = 'C' 

125 requirements.remove('C') 

126 

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

128 

129 for prop in requirements: 

130 if not arr.flags[prop]: 

131 return arr.copy(order) 

132 return arr 

133 

134 

135_require_with_like = array_function_dispatch()(require)