Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/numpy/_core/_asarray.py: 28%

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 .multiarray import array, asanyarray 

7from .overrides import array_function_dispatch, finalize_array_function_like, set_module 

8 

9__all__ = ["require"] 

10 

11 

12POSSIBLE_FLAGS = { 

13 'C': 'C', 'C_CONTIGUOUS': 'C', 'CONTIGUOUS': 'C', 

14 'F': 'F', 'F_CONTIGUOUS': 'F', 'FORTRAN': 'F', 

15 'A': 'A', 'ALIGNED': 'A', 

16 'W': 'W', 'WRITEABLE': 'W', 

17 'O': 'O', 'OWNDATA': 'O', 

18 'E': 'E', 'ENSUREARRAY': 'E' 

19} 

20 

21 

22@finalize_array_function_like 

23@set_module('numpy') 

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

25 """ 

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

27 

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

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

30 

31 Parameters 

32 ---------- 

33 a : array_like 

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

35 dtype : data-type 

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

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

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

39 requirements : str or sequence of str 

40 The requirements list can be any of the following 

41 

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

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

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

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

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

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

48 ${ARRAY_FUNCTION_LIKE} 

49 

50 .. versionadded:: 1.20.0 

51 

52 Returns 

53 ------- 

54 out : ndarray 

55 Array with specified requirements and type if given. 

56 

57 See Also 

58 -------- 

59 asarray : Convert input to an ndarray. 

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

61 ascontiguousarray : Convert input to a contiguous array. 

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

63 memory order. 

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

65 

66 Notes 

67 ----- 

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

69 by making a copy if needed. 

70 

71 Examples 

72 -------- 

73 >>> import numpy as np 

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

75 >>> x.flags 

76 C_CONTIGUOUS : True 

77 F_CONTIGUOUS : False 

78 OWNDATA : False 

79 WRITEABLE : True 

80 ALIGNED : True 

81 WRITEBACKIFCOPY : False 

82 

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

84 >>> y.flags 

85 C_CONTIGUOUS : False 

86 F_CONTIGUOUS : True 

87 OWNDATA : True 

88 WRITEABLE : True 

89 ALIGNED : True 

90 WRITEBACKIFCOPY : False 

91 

92 """ 

93 if like is not None: 

94 return _require_with_like( 

95 like, 

96 a, 

97 dtype=dtype, 

98 requirements=requirements, 

99 ) 

100 

101 if not requirements: 

102 return asanyarray(a, dtype=dtype) 

103 

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

105 

106 if 'E' in requirements: 

107 requirements.remove('E') 

108 subok = False 

109 else: 

110 subok = True 

111 

112 order = 'A' 

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

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

115 elif 'F' in requirements: 

116 order = 'F' 

117 requirements.remove('F') 

118 elif 'C' in requirements: 

119 order = 'C' 

120 requirements.remove('C') 

121 

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

123 

124 for prop in requirements: 

125 if not arr.flags[prop]: 

126 return arr.copy(order) 

127 return arr 

128 

129 

130_require_with_like = array_function_dispatch()(require)