Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

""" 

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

 

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

""" 

from .overrides import set_module 

from .multiarray import array 

 

 

__all__ = [ 

"asarray", "asanyarray", "ascontiguousarray", "asfortranarray", "require", 

] 

 

@set_module('numpy') 

def asarray(a, dtype=None, order=None): 

"""Convert the input to an array. 

 

Parameters 

---------- 

a : array_like 

Input data, in any form that can be converted to an array. This 

includes lists, lists of tuples, tuples, tuples of tuples, tuples 

of lists and ndarrays. 

dtype : data-type, optional 

By default, the data-type is inferred from the input data. 

order : {'C', 'F'}, optional 

Whether to use row-major (C-style) or 

column-major (Fortran-style) memory representation. 

Defaults to 'C'. 

 

Returns 

------- 

out : ndarray 

Array interpretation of `a`. No copy is performed if the input 

is already an ndarray with matching dtype and order. If `a` is a 

subclass of ndarray, a base class ndarray is returned. 

 

See Also 

-------- 

asanyarray : Similar function which passes through subclasses. 

ascontiguousarray : Convert input to a contiguous array. 

asfarray : Convert input to a floating point ndarray. 

asfortranarray : Convert input to an ndarray with column-major 

memory order. 

asarray_chkfinite : Similar function which checks input for NaNs and Infs. 

fromiter : Create an array from an iterator. 

fromfunction : Construct an array by executing a function on grid 

positions. 

 

Examples 

-------- 

Convert a list into an array: 

 

>>> a = [1, 2] 

>>> np.asarray(a) 

array([1, 2]) 

 

Existing arrays are not copied: 

 

>>> a = np.array([1, 2]) 

>>> np.asarray(a) is a 

True 

 

If `dtype` is set, array is copied only if dtype does not match: 

 

>>> a = np.array([1, 2], dtype=np.float32) 

>>> np.asarray(a, dtype=np.float32) is a 

True 

>>> np.asarray(a, dtype=np.float64) is a 

False 

 

Contrary to `asanyarray`, ndarray subclasses are not passed through: 

 

>>> issubclass(np.recarray, np.ndarray) 

True 

>>> a = np.array([(1.0, 2), (3.0, 4)], dtype='f4,i4').view(np.recarray) 

>>> np.asarray(a) is a 

False 

>>> np.asanyarray(a) is a 

True 

 

""" 

return array(a, dtype, copy=False, order=order) 

 

 

@set_module('numpy') 

def asanyarray(a, dtype=None, order=None): 

"""Convert the input to an ndarray, but pass ndarray subclasses through. 

 

Parameters 

---------- 

a : array_like 

Input data, in any form that can be converted to an array. This 

includes scalars, lists, lists of tuples, tuples, tuples of tuples, 

tuples of lists, and ndarrays. 

dtype : data-type, optional 

By default, the data-type is inferred from the input data. 

order : {'C', 'F'}, optional 

Whether to use row-major (C-style) or column-major 

(Fortran-style) memory representation. Defaults to 'C'. 

 

Returns 

------- 

out : ndarray or an ndarray subclass 

Array interpretation of `a`. If `a` is an ndarray or a subclass 

of ndarray, it is returned as-is and no copy is performed. 

 

See Also 

-------- 

asarray : Similar function which always returns ndarrays. 

ascontiguousarray : Convert input to a contiguous array. 

asfarray : Convert input to a floating point ndarray. 

asfortranarray : Convert input to an ndarray with column-major 

memory order. 

asarray_chkfinite : Similar function which checks input for NaNs and 

Infs. 

fromiter : Create an array from an iterator. 

fromfunction : Construct an array by executing a function on grid 

positions. 

 

Examples 

-------- 

Convert a list into an array: 

 

>>> a = [1, 2] 

>>> np.asanyarray(a) 

array([1, 2]) 

 

Instances of `ndarray` subclasses are passed through as-is: 

 

>>> a = np.array([(1.0, 2), (3.0, 4)], dtype='f4,i4').view(np.recarray) 

>>> np.asanyarray(a) is a 

True 

 

""" 

return array(a, dtype, copy=False, order=order, subok=True) 

 

 

@set_module('numpy') 

def ascontiguousarray(a, dtype=None): 

""" 

Return a contiguous array (ndim >= 1) in memory (C order). 

 

Parameters 

---------- 

a : array_like 

Input array. 

dtype : str or dtype object, optional 

Data-type of returned array. 

 

Returns 

------- 

out : ndarray 

Contiguous array of same shape and content as `a`, with type `dtype` 

if specified. 

 

See Also 

-------- 

asfortranarray : Convert input to an ndarray with column-major 

memory order. 

require : Return an ndarray that satisfies requirements. 

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

 

Examples 

-------- 

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

>>> np.ascontiguousarray(x, dtype=np.float32) 

array([[0., 1., 2.], 

[3., 4., 5.]], dtype=float32) 

>>> x.flags['C_CONTIGUOUS'] 

True 

 

Note: This function returns an array with at least one-dimension (1-d)  

so it will not preserve 0-d arrays.  

 

""" 

return array(a, dtype, copy=False, order='C', ndmin=1) 

 

 

@set_module('numpy') 

def asfortranarray(a, dtype=None): 

""" 

Return an array (ndim >= 1) laid out in Fortran order in memory. 

 

Parameters 

---------- 

a : array_like 

Input array. 

dtype : str or dtype object, optional 

By default, the data-type is inferred from the input data. 

 

Returns 

------- 

out : ndarray 

The input `a` in Fortran, or column-major, order. 

 

See Also 

-------- 

ascontiguousarray : Convert input to a contiguous (C order) array. 

asanyarray : Convert input to an ndarray with either row or 

column-major memory order. 

require : Return an ndarray that satisfies requirements. 

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

 

Examples 

-------- 

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

>>> y = np.asfortranarray(x) 

>>> x.flags['F_CONTIGUOUS'] 

False 

>>> y.flags['F_CONTIGUOUS'] 

True 

 

Note: This function returns an array with at least one-dimension (1-d)  

so it will not preserve 0-d arrays.  

 

""" 

return array(a, dtype, copy=False, order='F', ndmin=1) 

 

 

@set_module('numpy') 

def require(a, dtype=None, requirements=None): 

""" 

Return an ndarray of the provided type that satisfies requirements. 

 

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

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

 

Parameters 

---------- 

a : array_like 

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

dtype : data-type 

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

application requires the data to be in native byteorder, include 

a byteorder specification as a part of the dtype specification. 

requirements : str or list of str 

The requirements list can be any of the following 

 

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

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

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

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

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

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

 

Returns 

------- 

out : ndarray 

Array with specified requirements and type if given. 

 

See Also 

-------- 

asarray : Convert input to an ndarray. 

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

ascontiguousarray : Convert input to a contiguous array. 

asfortranarray : Convert input to an ndarray with column-major 

memory order. 

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

 

Notes 

----- 

The returned array will be guaranteed to have the listed requirements 

by making a copy if needed. 

 

Examples 

-------- 

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

>>> x.flags 

C_CONTIGUOUS : True 

F_CONTIGUOUS : False 

OWNDATA : False 

WRITEABLE : True 

ALIGNED : True 

WRITEBACKIFCOPY : False 

UPDATEIFCOPY : False 

 

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

>>> y.flags 

C_CONTIGUOUS : False 

F_CONTIGUOUS : True 

OWNDATA : True 

WRITEABLE : True 

ALIGNED : True 

WRITEBACKIFCOPY : False 

UPDATEIFCOPY : False 

 

""" 

possible_flags = {'C': 'C', 'C_CONTIGUOUS': 'C', 'CONTIGUOUS': 'C', 

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

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

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

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

'E': 'E', 'ENSUREARRAY': 'E'} 

if not requirements: 

return asanyarray(a, dtype=dtype) 

else: 

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

 

if 'E' in requirements: 

requirements.remove('E') 

subok = False 

else: 

subok = True 

 

order = 'A' 

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

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

elif 'F' in requirements: 

order = 'F' 

requirements.remove('F') 

elif 'C' in requirements: 

order = 'C' 

requirements.remove('C') 

 

arr = array(a, dtype=dtype, order=order, copy=False, subok=subok) 

 

for prop in requirements: 

if not arr.flags[prop]: 

arr = arr.copy(order) 

break 

return arr