Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/numpy/core/_asarray.py: 15%
34 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
1"""
2Functions in the ``as*array`` family that promote array-likes into arrays.
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
14__all__ = ["require"]
18def _require_dispatcher(a, dtype=None, requirements=None, *, like=None):
19 return (like,)
22@set_array_function_like_doc
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.
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).
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 list of str
40 The requirements list can be any of the following
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}
50 .. versionadded:: 1.20.0
52 Returns
53 -------
54 out : ndarray
55 Array with specified requirements and type if given.
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.
66 Notes
67 -----
68 The returned array will be guaranteed to have the listed requirements
69 by making a copy if needed.
71 Examples
72 --------
73 >>> x = np.arange(6).reshape(2,3)
74 >>> x.flags
75 C_CONTIGUOUS : True
76 F_CONTIGUOUS : False
77 OWNDATA : False
78 WRITEABLE : True
79 ALIGNED : True
80 WRITEBACKIFCOPY : False
82 >>> y = np.require(x, dtype=np.float32, requirements=['A', 'O', 'W', 'F'])
83 >>> y.flags
84 C_CONTIGUOUS : False
85 F_CONTIGUOUS : True
86 OWNDATA : True
87 WRITEABLE : True
88 ALIGNED : True
89 WRITEBACKIFCOPY : False
91 """
92 if like is not None:
93 return _require_with_like(
94 a,
95 dtype=dtype,
96 requirements=requirements,
97 like=like,
98 )
100 possible_flags = {'C': 'C', 'C_CONTIGUOUS': 'C', 'CONTIGUOUS': 'C',
101 'F': 'F', 'F_CONTIGUOUS': 'F', 'FORTRAN': 'F',
102 'A': 'A', 'ALIGNED': 'A',
103 'W': 'W', 'WRITEABLE': 'W',
104 'O': 'O', 'OWNDATA': 'O',
105 'E': 'E', 'ENSUREARRAY': 'E'}
106 if not requirements:
107 return asanyarray(a, dtype=dtype)
108 else:
109 requirements = {possible_flags[x.upper()] for x in requirements}
111 if 'E' in requirements:
112 requirements.remove('E')
113 subok = False
114 else:
115 subok = True
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')
127 arr = array(a, dtype=dtype, order=order, copy=False, subok=subok)
129 for prop in requirements:
130 if not arr.flags[prop]:
131 arr = arr.copy(order)
132 break
133 return arr
136_require_with_like = array_function_dispatch(
137 _require_dispatcher
138)(require)