Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/numpy/core/_add_newdocs_scalars.py: 92%

1""" 

2This file is separate from ``_add_newdocs.py`` so that it can be mocked out by 

3our sphinx ``conf.py`` during doc builds, where we want to avoid showing 

4platform-dependent information. 

5""" 

6import sys 

7import os 

8from numpy.core import dtype 

9from numpy.core import numerictypes as _numerictypes 

10from numpy.core.function_base import add_newdoc 

11 

12############################################################################## 

13# 

14# Documentation for concrete scalar classes 

15# 

16############################################################################## 

17 

18def numeric_type_aliases(aliases): 

19 def type_aliases_gen(): 

20 for alias, doc in aliases: 

21 try: 

22 alias_type = getattr(_numerictypes, alias) 

23 except AttributeError: 

24 # The set of aliases that actually exist varies between platforms 

25 pass 

26 else: 

27 yield (alias_type, alias, doc) 

28 return list(type_aliases_gen()) 

29 

30 

31possible_aliases = numeric_type_aliases([ 

32 ('int8', '8-bit signed integer (``-128`` to ``127``)'), 

33 ('int16', '16-bit signed integer (``-32_768`` to ``32_767``)'), 

34 ('int32', '32-bit signed integer (``-2_147_483_648`` to ``2_147_483_647``)'), 

35 ('int64', '64-bit signed integer (``-9_223_372_036_854_775_808`` to ``9_223_372_036_854_775_807``)'), 

36 ('intp', 'Signed integer large enough to fit pointer, compatible with C ``intptr_t``'), 

37 ('uint8', '8-bit unsigned integer (``0`` to ``255``)'), 

38 ('uint16', '16-bit unsigned integer (``0`` to ``65_535``)'), 

39 ('uint32', '32-bit unsigned integer (``0`` to ``4_294_967_295``)'), 

40 ('uint64', '64-bit unsigned integer (``0`` to ``18_446_744_073_709_551_615``)'), 

41 ('uintp', 'Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``'), 

42 ('float16', '16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits mantissa'), 

43 ('float32', '32-bit-precision floating-point number type: sign bit, 8 bits exponent, 23 bits mantissa'), 

44 ('float64', '64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa'), 

45 ('float96', '96-bit extended-precision floating-point number type'), 

46 ('float128', '128-bit extended-precision floating-point number type'), 

47 ('complex64', 'Complex number type composed of 2 32-bit-precision floating-point numbers'), 

48 ('complex128', 'Complex number type composed of 2 64-bit-precision floating-point numbers'), 

49 ('complex192', 'Complex number type composed of 2 96-bit extended-precision floating-point numbers'), 

50 ('complex256', 'Complex number type composed of 2 128-bit extended-precision floating-point numbers'), 

51 ]) 

52 

53 

54def _get_platform_and_machine(): 

55 try: 

56 system, _, _, _, machine = os.uname() 

57 except AttributeError: 

58 system = sys.platform 

59 if system == 'win32': 

60 machine = os.environ.get('PROCESSOR_ARCHITEW6432', '') \ 

61 or os.environ.get('PROCESSOR_ARCHITECTURE', '') 

62 else: 

63 machine = 'unknown' 

64 return system, machine 

65 

66 

67_system, _machine = _get_platform_and_machine() 

68_doc_alias_string = f":Alias on this platform ({_system} {_machine}):" 

69 

70 

71def add_newdoc_for_scalar_type(obj, fixed_aliases, doc): 

72 # note: `:field: value` is rST syntax which renders as field lists. 

73 o = getattr(_numerictypes, obj) 

74 

75 character_code = dtype(o).char 

76 canonical_name_doc = "" if obj == o.__name__ else \ 

77 f":Canonical name: `numpy.{obj}`\n " 

78 if fixed_aliases: 

79 alias_doc = ''.join(f":Alias: `numpy.{alias}`\n " 

80 for alias in fixed_aliases) 

81 else: 

82 alias_doc = '' 

83 alias_doc += ''.join(f"{_doc_alias_string} `numpy.{alias}`: {doc}.\n " 

84 for (alias_type, alias, doc) in possible_aliases if alias_type is o) 

85 

86 docstring = f""" 

87 {doc.strip()} 

88 

89 :Character code: ``'{character_code}'`` 

90 {canonical_name_doc}{alias_doc} 

91 """ 

92 

93 add_newdoc('numpy.core.numerictypes', obj, docstring) 

94 

95 

96add_newdoc_for_scalar_type('bool_', [], 

97 """ 

98 Boolean type (True or False), stored as a byte. 

99 

100 .. warning:: 

101 

102 The :class:`bool_` type is not a subclass of the :class:`int_` type 

103 (the :class:`bool_` is not even a number type). This is different 

104 than Python's default implementation of :class:`bool` as a 

105 sub-class of :class:`int`. 

106 """) 

107 

108add_newdoc_for_scalar_type('byte', [], 

109 """ 

110 Signed integer type, compatible with C ``char``. 

111 """) 

112 

113add_newdoc_for_scalar_type('short', [], 

114 """ 

115 Signed integer type, compatible with C ``short``. 

116 """) 

117 

118add_newdoc_for_scalar_type('intc', [], 

119 """ 

120 Signed integer type, compatible with C ``int``. 

121 """) 

122 

123add_newdoc_for_scalar_type('int_', [], 

124 """ 

125 Signed integer type, compatible with Python `int` and C ``long``. 

126 """) 

127 

128add_newdoc_for_scalar_type('longlong', [], 

129 """ 

130 Signed integer type, compatible with C ``long long``. 

131 """) 

132 

133add_newdoc_for_scalar_type('ubyte', [], 

134 """ 

135 Unsigned integer type, compatible with C ``unsigned char``. 

136 """) 

137 

138add_newdoc_for_scalar_type('ushort', [], 

139 """ 

140 Unsigned integer type, compatible with C ``unsigned short``. 

141 """) 

142 

143add_newdoc_for_scalar_type('uintc', [], 

144 """ 

145 Unsigned integer type, compatible with C ``unsigned int``. 

146 """) 

147 

148add_newdoc_for_scalar_type('uint', [], 

149 """ 

150 Unsigned integer type, compatible with C ``unsigned long``. 

151 """) 

152 

153add_newdoc_for_scalar_type('ulonglong', [], 

154 """ 

155 Signed integer type, compatible with C ``unsigned long long``. 

156 """) 

157 

158add_newdoc_for_scalar_type('half', [], 

159 """ 

160 Half-precision floating-point number type. 

161 """) 

162 

163add_newdoc_for_scalar_type('single', [], 

164 """ 

165 Single-precision floating-point number type, compatible with C ``float``. 

166 """) 

167 

168add_newdoc_for_scalar_type('double', ['float_'], 

169 """ 

170 Double-precision floating-point number type, compatible with Python `float` 

171 and C ``double``. 

172 """) 

173 

174add_newdoc_for_scalar_type('longdouble', ['longfloat'], 

175 """ 

176 Extended-precision floating-point number type, compatible with C 

177 ``long double`` but not necessarily with IEEE 754 quadruple-precision. 

178 """) 

179 

180add_newdoc_for_scalar_type('csingle', ['singlecomplex'], 

181 """ 

182 Complex number type composed of two single-precision floating-point 

183 numbers. 

184 """) 

185 

186add_newdoc_for_scalar_type('cdouble', ['cfloat', 'complex_'], 

187 """ 

188 Complex number type composed of two double-precision floating-point 

189 numbers, compatible with Python `complex`. 

190 """) 

191 

192add_newdoc_for_scalar_type('clongdouble', ['clongfloat', 'longcomplex'], 

193 """ 

194 Complex number type composed of two extended-precision floating-point 

195 numbers. 

196 """) 

197 

198add_newdoc_for_scalar_type('object_', [], 

199 """ 

200 Any Python object. 

201 """) 

202 

203add_newdoc_for_scalar_type('str_', ['unicode_'], 

204 r""" 

205 A unicode string. 

206 

207 This type strips trailing null codepoints. 

208 

209 >>> s = np.str_("abc\x00") 

210 >>> s 

211 'abc' 

212 

213 Unlike the builtin `str`, this supports the :ref:`python:bufferobjects`, exposing its 

214 contents as UCS4: 

215 

216 >>> m = memoryview(np.str_("abc")) 

217 >>> m.format 

218 '3w' 

219 >>> m.tobytes() 

220 b'a\x00\x00\x00b\x00\x00\x00c\x00\x00\x00' 

221 """) 

222 

223add_newdoc_for_scalar_type('bytes_', ['string_'], 

224 r""" 

225 A byte string. 

226 

227 When used in arrays, this type strips trailing null bytes. 

228 """) 

229 

230add_newdoc_for_scalar_type('void', [], 

231 r""" 

232 np.void(length_or_data, /, dtype=None) 

233 

234 Create a new structured or unstructured void scalar. 

235 

236 Parameters 

237 ---------- 

238 length_or_data : int, array-like, bytes-like, object 

239 One of multiple meanings (see notes). The length or 

240 bytes data of an unstructured void. Or alternatively, 

241 the data to be stored in the new scalar when `dtype` 

242 is provided. 

243 This can be an array-like, in which case an array may 

244 be returned. 

245 dtype : dtype, optional 

246 If provided the dtype of the new scalar. This dtype must 

247 be "void" dtype (i.e. a structured or unstructured void, 

248 see also :ref:`defining-structured-types`). 

249 

250 ..versionadded:: 1.24 

251 

252 Notes 

253 ----- 

254 For historical reasons and because void scalars can represent both 

255 arbitrary byte data and structured dtypes, the void constructor 

256 has three calling conventions: 

257 

258 1. ``np.void(5)`` creates a ``dtype="V5"`` scalar filled with five 

259 ``\0`` bytes. The 5 can be a Python or NumPy integer. 

260 2. ``np.void(b"bytes-like")`` creates a void scalar from the byte string. 

261 The dtype itemsize will match the byte string length, here ``"V10"``. 

262 3. When a ``dtype=`` is passed the call is roughly the same as an 

263 array creation. However, a void scalar rather than array is returned. 

264 

265 Please see the examples which show all three different conventions. 

266 

267 Examples 

268 -------- 

269 >>> np.void(5) 

270 void(b'\x00\x00\x00\x00\x00') 

271 >>> np.void(b'abcd') 

272 void(b'\x61\x62\x63\x64') 

273 >>> np.void((5, 3.2, "eggs"), dtype="i,d,S5") 

274 (5, 3.2, b'eggs') # looks like a tuple, but is `np.void` 

275 >>> np.void(3, dtype=[('x', np.int8), ('y', np.int8)]) 

276 (3, 3) # looks like a tuple, but is `np.void` 

277 

278 """) 

279 

280add_newdoc_for_scalar_type('datetime64', [], 

281 """ 

282 If created from a 64-bit integer, it represents an offset from 

283 ``1970-01-01T00:00:00``. 

284 If created from string, the string can be in ISO 8601 date 

285 or datetime format. 

286 

287 >>> np.datetime64(10, 'Y') 

288 numpy.datetime64('1980') 

289 >>> np.datetime64('1980', 'Y') 

290 numpy.datetime64('1980') 

291 >>> np.datetime64(10, 'D') 

292 numpy.datetime64('1970-01-11') 

293 

294 See :ref:`arrays.datetime` for more information. 

295 """) 

296 

297add_newdoc_for_scalar_type('timedelta64', [], 

298 """ 

299 A timedelta stored as a 64-bit integer. 

300 

301 See :ref:`arrays.datetime` for more information. 

302 """) 

303 

304add_newdoc('numpy.core.numerictypes', "integer", ('is_integer', 

305 """ 

306 integer.is_integer() -> bool 

307 

308 Return ``True`` if the number is finite with integral value. 

309 

310 .. versionadded:: 1.22 

311 

312 Examples 

313 -------- 

314 >>> np.int64(-2).is_integer() 

315 True 

316 >>> np.uint32(5).is_integer() 

317 True 

318 """)) 

319 

320# TODO: work out how to put this on the base class, np.floating 

321for float_name in ('half', 'single', 'double', 'longdouble'): 

322 add_newdoc('numpy.core.numerictypes', float_name, ('as_integer_ratio', 

323 """ 

324 {ftype}.as_integer_ratio() -> (int, int) 

325 

326 Return a pair of integers, whose ratio is exactly equal to the original 

327 floating point number, and with a positive denominator. 

328 Raise `OverflowError` on infinities and a `ValueError` on NaNs. 

329 

330 >>> np.{ftype}(10.0).as_integer_ratio() 

331 (10, 1) 

332 >>> np.{ftype}(0.0).as_integer_ratio() 

333 (0, 1) 

334 >>> np.{ftype}(-.25).as_integer_ratio() 

335 (-1, 4) 

336 """.format(ftype=float_name))) 

337 

338 add_newdoc('numpy.core.numerictypes', float_name, ('is_integer', 

339 f""" 

340 {float_name}.is_integer() -> bool 

341 

342 Return ``True`` if the floating point number is finite with integral 

343 value, and ``False`` otherwise. 

344 

345 .. versionadded:: 1.22 

346 

347 Examples 

348 -------- 

349 >>> np.{float_name}(-2.0).is_integer() 

350 True 

351 >>> np.{float_name}(3.2).is_integer() 

352 False 

353 """)) 

354 

355for int_name in ('int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 

356 'int64', 'uint64', 'int64', 'uint64', 'int64', 'uint64'): 

357 # Add negative examples for signed cases by checking typecode 

358 add_newdoc('numpy.core.numerictypes', int_name, ('bit_count', 

359 f""" 

360 {int_name}.bit_count() -> int 

361 

362 Computes the number of 1-bits in the absolute value of the input. 

363 Analogous to the builtin `int.bit_count` or ``popcount`` in C++. 

364 

365 Examples 

366 -------- 

367 >>> np.{int_name}(127).bit_count() 

368 7""" + 

369 (f""" 

370 >>> np.{int_name}(-127).bit_count() 

371 7 

372 """ if dtype(int_name).char.islower() else "")))