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

1import os 

2import sys 

3import textwrap 

4import types 

5import re 

6import warnings 

7 

8from numpy.core.numerictypes import issubclass_, issubsctype, issubdtype 

9from numpy.core.overrides import set_module 

10from numpy.core import ndarray, ufunc, asarray 

11import numpy as np 

12 

13# getargspec and formatargspec were removed in Python 3.6 

14from numpy.compat import getargspec, formatargspec 

15 

16__all__ = [ 

17 'issubclass_', 'issubsctype', 'issubdtype', 'deprecate', 

18 'deprecate_with_doc', 'get_include', 'info', 'source', 'who', 

19 'lookfor', 'byte_bounds', 'safe_eval' 

20 ] 

21 

22def get_include(): 

23 """ 

24 Return the directory that contains the NumPy \\*.h header files. 

25 

26 Extension modules that need to compile against NumPy should use this 

27 function to locate the appropriate include directory. 

28 

29 Notes 

30 ----- 

31 When using ``distutils``, for example in ``setup.py``. 

32 :: 

33 

34 import numpy as np 

35 ... 

36 Extension('extension_name', ... 

37 include_dirs=[np.get_include()]) 

38 ... 

39 

40 """ 

41 import numpy 

42 if numpy.show_config is None: 

43 # running from numpy source directory 

44 d = os.path.join(os.path.dirname(numpy.__file__), 'core', 'include') 

45 else: 

46 # using installed numpy core headers 

47 import numpy.core as core 

48 d = os.path.join(os.path.dirname(core.__file__), 'include') 

49 return d 

50 

51 

52def _set_function_name(func, name): 

53 func.__name__ = name 

54 return func 

55 

56 

57class _Deprecate: 

58 """ 

59 Decorator class to deprecate old functions. 

60 

61 Refer to `deprecate` for details. 

62 

63 See Also 

64 -------- 

65 deprecate 

66 

67 """ 

68 

69 def __init__(self, old_name=None, new_name=None, message=None): 

70 self.old_name = old_name 

71 self.new_name = new_name 

72 self.message = message 

73 

74 def __call__(self, func, *args, **kwargs): 

75 """ 

76 Decorator call. Refer to ``decorate``. 

77 

78 """ 

79 old_name = self.old_name 

80 new_name = self.new_name 

81 message = self.message 

82 

83 if old_name is None: 

84 try: 

85 old_name = func.__name__ 

86 except AttributeError: 

87 old_name = func.__name__ 

88 if new_name is None: 

89 depdoc = "`%s` is deprecated!" % old_name 

90 else: 

91 depdoc = "`%s` is deprecated, use `%s` instead!" % \ 

92 (old_name, new_name) 

93 

94 if message is not None: 

95 depdoc += "\n" + message 

96 

97 def newfunc(*args,**kwds): 

98 """`arrayrange` is deprecated, use `arange` instead!""" 

99 warnings.warn(depdoc, DeprecationWarning, stacklevel=2) 

100 return func(*args, **kwds) 

101 

102 newfunc = _set_function_name(newfunc, old_name) 

103 doc = func.__doc__ 

104 if doc is None: 

105 doc = depdoc 

106 else: 

107 lines = doc.expandtabs().split('\n') 

108 indent = _get_indent(lines[1:]) 

109 if lines[0].lstrip(): 

110 # Indent the original first line to let inspect.cleandoc() 

111 # dedent the docstring despite the deprecation notice. 

112 doc = indent * ' ' + doc 

113 else: 

114 # Remove the same leading blank lines as cleandoc() would. 

115 skip = len(lines[0]) + 1 

116 for line in lines[1:]: 

117 if len(line) > indent: 

118 break 

119 skip += len(line) + 1 

120 doc = doc[skip:] 

121 depdoc = textwrap.indent(depdoc, ' ' * indent) 

122 doc = '\n\n'.join([depdoc, doc]) 

123 newfunc.__doc__ = doc 

124 try: 

125 d = func.__dict__ 

126 except AttributeError: 

127 pass 

128 else: 

129 newfunc.__dict__.update(d) 

130 return newfunc 

131 

132 

133def _get_indent(lines): 

134 """ 

135 Determines the leading whitespace that could be removed from all the lines. 

136 """ 

137 indent = sys.maxsize 

138 for line in lines: 

139 content = len(line.lstrip()) 

140 if content: 

141 indent = min(indent, len(line) - content) 

142 if indent == sys.maxsize: 

143 indent = 0 

144 return indent 

145 

146 

147def deprecate(*args, **kwargs): 

148 """ 

149 Issues a DeprecationWarning, adds warning to `old_name`'s 

150 docstring, rebinds ``old_name.__name__`` and returns the new 

151 function object. 

152 

153 This function may also be used as a decorator. 

154 

155 Parameters 

156 ---------- 

157 func : function 

158 The function to be deprecated. 

159 old_name : str, optional 

160 The name of the function to be deprecated. Default is None, in 

161 which case the name of `func` is used. 

162 new_name : str, optional 

163 The new name for the function. Default is None, in which case the 

164 deprecation message is that `old_name` is deprecated. If given, the 

165 deprecation message is that `old_name` is deprecated and `new_name` 

166 should be used instead. 

167 message : str, optional 

168 Additional explanation of the deprecation. Displayed in the 

169 docstring after the warning. 

170 

171 Returns 

172 ------- 

173 old_func : function 

174 The deprecated function. 

175 

176 Examples 

177 -------- 

178 Note that ``olduint`` returns a value after printing Deprecation 

179 Warning: 

180 

181 >>> olduint = np.deprecate(np.uint) 

182 DeprecationWarning: `uint64` is deprecated! # may vary 

183 >>> olduint(6) 

184 6 

185 

186 """ 

187 # Deprecate may be run as a function or as a decorator 

188 # If run as a function, we initialise the decorator class 

189 # and execute its __call__ method. 

190 

191 if args: 

192 fn = args[0] 

193 args = args[1:] 

194 

195 return _Deprecate(*args, **kwargs)(fn) 

196 else: 

197 return _Deprecate(*args, **kwargs) 

198 

199deprecate_with_doc = lambda msg: _Deprecate(message=msg) 

200 

201 

202#-------------------------------------------- 

203# Determine if two arrays can share memory 

204#-------------------------------------------- 

205 

206def byte_bounds(a): 

207 """ 

208 Returns pointers to the end-points of an array. 

209 

210 Parameters 

211 ---------- 

212 a : ndarray 

213 Input array. It must conform to the Python-side of the array 

214 interface. 

215 

216 Returns 

217 ------- 

218 (low, high) : tuple of 2 integers 

219 The first integer is the first byte of the array, the second 

220 integer is just past the last byte of the array. If `a` is not 

221 contiguous it will not use every byte between the (`low`, `high`) 

222 values. 

223 

224 Examples 

225 -------- 

226 >>> I = np.eye(2, dtype='f'); I.dtype 

227 dtype('float32') 

228 >>> low, high = np.byte_bounds(I) 

229 >>> high - low == I.size*I.itemsize 

230 True 

231 >>> I = np.eye(2); I.dtype 

232 dtype('float64') 

233 >>> low, high = np.byte_bounds(I) 

234 >>> high - low == I.size*I.itemsize 

235 True 

236 

237 """ 

238 ai = a.__array_interface__ 

239 a_data = ai['data'][0] 

240 astrides = ai['strides'] 

241 ashape = ai['shape'] 

242 bytes_a = asarray(a).dtype.itemsize 

243 

244 a_low = a_high = a_data 

245 if astrides is None: 

246 # contiguous case 

247 a_high += a.size * bytes_a 

248 else: 

249 for shape, stride in zip(ashape, astrides): 

250 if stride < 0: 

251 a_low += (shape-1)*stride 

252 else: 

253 a_high += (shape-1)*stride 

254 a_high += bytes_a 

255 return a_low, a_high 

256 

257 

258#----------------------------------------------------------------------------- 

259# Function for output and information on the variables used. 

260#----------------------------------------------------------------------------- 

261 

262 

263def who(vardict=None): 

264 """ 

265 Print the NumPy arrays in the given dictionary. 

266 

267 If there is no dictionary passed in or `vardict` is None then returns 

268 NumPy arrays in the globals() dictionary (all NumPy arrays in the 

269 namespace). 

270 

271 Parameters 

272 ---------- 

273 vardict : dict, optional 

274 A dictionary possibly containing ndarrays. Default is globals(). 

275 

276 Returns 

277 ------- 

278 out : None 

279 Returns 'None'. 

280 

281 Notes 

282 ----- 

283 Prints out the name, shape, bytes and type of all of the ndarrays 

284 present in `vardict`. 

285 

286 Examples 

287 -------- 

288 >>> a = np.arange(10) 

289 >>> b = np.ones(20) 

290 >>> np.who() 

291 Name Shape Bytes Type 

292 =========================================================== 

293 a 10 80 int64 

294 b 20 160 float64 

295 Upper bound on total bytes = 240 

296 

297 >>> d = {'x': np.arange(2.0), 'y': np.arange(3.0), 'txt': 'Some str', 

298 ... 'idx':5} 

299 >>> np.who(d) 

300 Name Shape Bytes Type 

301 =========================================================== 

302 x 2 16 float64 

303 y 3 24 float64 

304 Upper bound on total bytes = 40 

305 

306 """ 

307 if vardict is None: 

308 frame = sys._getframe().f_back 

309 vardict = frame.f_globals 

310 sta = [] 

311 cache = {} 

312 for name in vardict.keys(): 

313 if isinstance(vardict[name], ndarray): 

314 var = vardict[name] 

315 idv = id(var) 

316 if idv in cache.keys(): 

317 namestr = name + " (%s)" % cache[idv] 

318 original = 0 

319 else: 

320 cache[idv] = name 

321 namestr = name 

322 original = 1 

323 shapestr = " x ".join(map(str, var.shape)) 

324 bytestr = str(var.nbytes) 

325 sta.append([namestr, shapestr, bytestr, var.dtype.name, 

326 original]) 

327 

328 maxname = 0 

329 maxshape = 0 

330 maxbyte = 0 

331 totalbytes = 0 

332 for k in range(len(sta)): 

333 val = sta[k] 

334 if maxname < len(val[0]): 

335 maxname = len(val[0]) 

336 if maxshape < len(val[1]): 

337 maxshape = len(val[1]) 

338 if maxbyte < len(val[2]): 

339 maxbyte = len(val[2]) 

340 if val[4]: 

341 totalbytes += int(val[2]) 

342 

343 if len(sta) > 0: 

344 sp1 = max(10, maxname) 

345 sp2 = max(10, maxshape) 

346 sp3 = max(10, maxbyte) 

347 prval = "Name %s Shape %s Bytes %s Type" % (sp1*' ', sp2*' ', sp3*' ') 

348 print(prval + "\n" + "="*(len(prval)+5) + "\n") 

349 

350 for k in range(len(sta)): 

351 val = sta[k] 

352 print("%s %s %s %s %s %s %s" % (val[0], ' '*(sp1-len(val[0])+4), 

353 val[1], ' '*(sp2-len(val[1])+5), 

354 val[2], ' '*(sp3-len(val[2])+5), 

355 val[3])) 

356 print("\nUpper bound on total bytes = %d" % totalbytes) 

357 return 

358 

359#----------------------------------------------------------------------------- 

360 

361 

362# NOTE: pydoc defines a help function which works similarly to this 

363# except it uses a pager to take over the screen. 

364 

365# combine name and arguments and split to multiple lines of width 

366# characters. End lines on a comma and begin argument list indented with 

367# the rest of the arguments. 

368def _split_line(name, arguments, width): 

369 firstwidth = len(name) 

370 k = firstwidth 

371 newstr = name 

372 sepstr = ", " 

373 arglist = arguments.split(sepstr) 

374 for argument in arglist: 

375 if k == firstwidth: 

376 addstr = "" 

377 else: 

378 addstr = sepstr 

379 k = k + len(argument) + len(addstr) 

380 if k > width: 

381 k = firstwidth + 1 + len(argument) 

382 newstr = newstr + ",\n" + " "*(firstwidth+2) + argument 

383 else: 

384 newstr = newstr + addstr + argument 

385 return newstr 

386 

387_namedict = None 

388_dictlist = None 

389 

390# Traverse all module directories underneath globals 

391# to see if something is defined 

392def _makenamedict(module='numpy'): 

393 module = __import__(module, globals(), locals(), []) 

394 thedict = {module.__name__:module.__dict__} 

395 dictlist = [module.__name__] 

396 totraverse = [module.__dict__] 

397 while True: 

398 if len(totraverse) == 0: 

399 break 

400 thisdict = totraverse.pop(0) 

401 for x in thisdict.keys(): 

402 if isinstance(thisdict[x], types.ModuleType): 

403 modname = thisdict[x].__name__ 

404 if modname not in dictlist: 

405 moddict = thisdict[x].__dict__ 

406 dictlist.append(modname) 

407 totraverse.append(moddict) 

408 thedict[modname] = moddict 

409 return thedict, dictlist 

410 

411 

412def _info(obj, output=sys.stdout): 

413 """Provide information about ndarray obj. 

414 

415 Parameters 

416 ---------- 

417 obj : ndarray 

418 Must be ndarray, not checked. 

419 output 

420 Where printed output goes. 

421 

422 Notes 

423 ----- 

424 Copied over from the numarray module prior to its removal. 

425 Adapted somewhat as only numpy is an option now. 

426 

427 Called by info. 

428 

429 """ 

430 extra = "" 

431 tic = "" 

432 bp = lambda x: x 

433 cls = getattr(obj, '__class__', type(obj)) 

434 nm = getattr(cls, '__name__', cls) 

435 strides = obj.strides 

436 endian = obj.dtype.byteorder 

437 

438 print("class: ", nm, file=output) 

439 print("shape: ", obj.shape, file=output) 

440 print("strides: ", strides, file=output) 

441 print("itemsize: ", obj.itemsize, file=output) 

442 print("aligned: ", bp(obj.flags.aligned), file=output) 

443 print("contiguous: ", bp(obj.flags.contiguous), file=output) 

444 print("fortran: ", obj.flags.fortran, file=output) 

445 print( 

446 "data pointer: %s%s" % (hex(obj.ctypes._as_parameter_.value), extra), 

447 file=output 

448 ) 

449 print("byteorder: ", end=' ', file=output) 

450 if endian in ['|', '=']: 

451 print("%s%s%s" % (tic, sys.byteorder, tic), file=output) 

452 byteswap = False 

453 elif endian == '>': 

454 print("%sbig%s" % (tic, tic), file=output) 

455 byteswap = sys.byteorder != "big" 

456 else: 

457 print("%slittle%s" % (tic, tic), file=output) 

458 byteswap = sys.byteorder != "little" 

459 print("byteswap: ", bp(byteswap), file=output) 

460 print("type: %s" % obj.dtype, file=output) 

461 

462 

463@set_module('numpy') 

464def info(object=None, maxwidth=76, output=sys.stdout, toplevel='numpy'): 

465 """ 

466 Get help information for a function, class, or module. 

467 

468 Parameters 

469 ---------- 

470 object : object or str, optional 

471 Input object or name to get information about. If `object` is a 

472 numpy object, its docstring is given. If it is a string, available 

473 modules are searched for matching objects. If None, information 

474 about `info` itself is returned. 

475 maxwidth : int, optional 

476 Printing width. 

477 output : file like object, optional 

478 File like object that the output is written to, default is 

479 ``stdout``. The object has to be opened in 'w' or 'a' mode. 

480 toplevel : str, optional 

481 Start search at this level. 

482 

483 See Also 

484 -------- 

485 source, lookfor 

486 

487 Notes 

488 ----- 

489 When used interactively with an object, ``np.info(obj)`` is equivalent 

490 to ``help(obj)`` on the Python prompt or ``obj?`` on the IPython 

491 prompt. 

492 

493 Examples 

494 -------- 

495 >>> np.info(np.polyval) # doctest: +SKIP 

496 polyval(p, x) 

497 Evaluate the polynomial p at x. 

498 ... 

499 

500 When using a string for `object` it is possible to get multiple results. 

501 

502 >>> np.info('fft') # doctest: +SKIP 

503 *** Found in numpy *** 

504 Core FFT routines 

505 ... 

506 *** Found in numpy.fft *** 

507 fft(a, n=None, axis=-1) 

508 ... 

509 *** Repeat reference found in numpy.fft.fftpack *** 

510 *** Total of 3 references found. *** 

511 

512 """ 

513 global _namedict, _dictlist 

514 # Local import to speed up numpy's import time. 

515 import pydoc 

516 import inspect 

517 

518 if (hasattr(object, '_ppimport_importer') or 

519 hasattr(object, '_ppimport_module')): 

520 object = object._ppimport_module 

521 elif hasattr(object, '_ppimport_attr'): 

522 object = object._ppimport_attr 

523 

524 if object is None: 

525 info(info) 

526 elif isinstance(object, ndarray): 

527 _info(object, output=output) 

528 elif isinstance(object, str): 

529 if _namedict is None: 

530 _namedict, _dictlist = _makenamedict(toplevel) 

531 numfound = 0 

532 objlist = [] 

533 for namestr in _dictlist: 

534 try: 

535 obj = _namedict[namestr][object] 

536 if id(obj) in objlist: 

537 print("\n " 

538 "*** Repeat reference found in %s *** " % namestr, 

539 file=output 

540 ) 

541 else: 

542 objlist.append(id(obj)) 

543 print(" *** Found in %s ***" % namestr, file=output) 

544 info(obj) 

545 print("-"*maxwidth, file=output) 

546 numfound += 1 

547 except KeyError: 

548 pass 

549 if numfound == 0: 

550 print("Help for %s not found." % object, file=output) 

551 else: 

552 print("\n " 

553 "*** Total of %d references found. ***" % numfound, 

554 file=output 

555 ) 

556 

557 elif inspect.isfunction(object): 

558 name = object.__name__ 

559 arguments = formatargspec(*getargspec(object)) 

560 

561 if len(name+arguments) > maxwidth: 

562 argstr = _split_line(name, arguments, maxwidth) 

563 else: 

564 argstr = name + arguments 

565 

566 print(" " + argstr + "\n", file=output) 

567 print(inspect.getdoc(object), file=output) 

568 

569 elif inspect.isclass(object): 

570 name = object.__name__ 

571 arguments = "()" 

572 try: 

573 if hasattr(object, '__init__'): 

574 arguments = formatargspec( 

575 *getargspec(object.__init__.__func__) 

576 ) 

577 arglist = arguments.split(', ') 

578 if len(arglist) > 1: 

579 arglist[1] = "("+arglist[1] 

580 arguments = ", ".join(arglist[1:]) 

581 except Exception: 

582 pass 

583 

584 if len(name+arguments) > maxwidth: 

585 argstr = _split_line(name, arguments, maxwidth) 

586 else: 

587 argstr = name + arguments 

588 

589 print(" " + argstr + "\n", file=output) 

590 doc1 = inspect.getdoc(object) 

591 if doc1 is None: 

592 if hasattr(object, '__init__'): 

593 print(inspect.getdoc(object.__init__), file=output) 

594 else: 

595 print(inspect.getdoc(object), file=output) 

596 

597 methods = pydoc.allmethods(object) 

598 if methods != []: 

599 print("\n\nMethods:\n", file=output) 

600 for meth in methods: 

601 if meth[0] == '_': 

602 continue 

603 thisobj = getattr(object, meth, None) 

604 if thisobj is not None: 

605 methstr, other = pydoc.splitdoc( 

606 inspect.getdoc(thisobj) or "None" 

607 ) 

608 print(" %s -- %s" % (meth, methstr), file=output) 

609 

610 elif inspect.ismethod(object): 

611 name = object.__name__ 

612 arguments = formatargspec( 

613 *getargspec(object.__func__) 

614 ) 

615 arglist = arguments.split(', ') 

616 if len(arglist) > 1: 

617 arglist[1] = "("+arglist[1] 

618 arguments = ", ".join(arglist[1:]) 

619 else: 

620 arguments = "()" 

621 

622 if len(name+arguments) > maxwidth: 

623 argstr = _split_line(name, arguments, maxwidth) 

624 else: 

625 argstr = name + arguments 

626 

627 print(" " + argstr + "\n", file=output) 

628 print(inspect.getdoc(object), file=output) 

629 

630 elif hasattr(object, '__doc__'): 

631 print(inspect.getdoc(object), file=output) 

632 

633 

634@set_module('numpy') 

635def source(object, output=sys.stdout): 

636 """ 

637 Print or write to a file the source code for a NumPy object. 

638 

639 The source code is only returned for objects written in Python. Many 

640 functions and classes are defined in C and will therefore not return 

641 useful information. 

642 

643 Parameters 

644 ---------- 

645 object : numpy object 

646 Input object. This can be any object (function, class, module, 

647 ...). 

648 output : file object, optional 

649 If `output` not supplied then source code is printed to screen 

650 (sys.stdout). File object must be created with either write 'w' or 

651 append 'a' modes. 

652 

653 See Also 

654 -------- 

655 lookfor, info 

656 

657 Examples 

658 -------- 

659 >>> np.source(np.interp) #doctest: +SKIP 

660 In file: /usr/lib/python2.6/dist-packages/numpy/lib/function_base.py 

661 def interp(x, xp, fp, left=None, right=None): 

662 \"\"\".... (full docstring printed)\"\"\" 

663 if isinstance(x, (float, int, number)): 

664 return compiled_interp([x], xp, fp, left, right).item() 

665 else: 

666 return compiled_interp(x, xp, fp, left, right) 

667 

668 The source code is only returned for objects written in Python. 

669 

670 >>> np.source(np.array) #doctest: +SKIP 

671 Not available for this object. 

672 

673 """ 

674 # Local import to speed up numpy's import time. 

675 import inspect 

676 try: 

677 print("In file: %s\n" % inspect.getsourcefile(object), file=output) 

678 print(inspect.getsource(object), file=output) 

679 except Exception: 

680 print("Not available for this object.", file=output) 

681 

682 

683# Cache for lookfor: {id(module): {name: (docstring, kind, index), ...}...} 

684# where kind: "func", "class", "module", "object" 

685# and index: index in breadth-first namespace traversal 

686_lookfor_caches = {} 

687 

688# regexp whose match indicates that the string may contain a function 

689# signature 

690_function_signature_re = re.compile(r"[a-z0-9_]+\(.*[,=].*\)", re.I) 

691 

692 

693@set_module('numpy') 

694def lookfor(what, module=None, import_modules=True, regenerate=False, 

695 output=None): 

696 """ 

697 Do a keyword search on docstrings. 

698 

699 A list of objects that matched the search is displayed, 

700 sorted by relevance. All given keywords need to be found in the 

701 docstring for it to be returned as a result, but the order does 

702 not matter. 

703 

704 Parameters 

705 ---------- 

706 what : str 

707 String containing words to look for. 

708 module : str or list, optional 

709 Name of module(s) whose docstrings to go through. 

710 import_modules : bool, optional 

711 Whether to import sub-modules in packages. Default is True. 

712 regenerate : bool, optional 

713 Whether to re-generate the docstring cache. Default is False. 

714 output : file-like, optional 

715 File-like object to write the output to. If omitted, use a pager. 

716 

717 See Also 

718 -------- 

719 source, info 

720 

721 Notes 

722 ----- 

723 Relevance is determined only roughly, by checking if the keywords occur 

724 in the function name, at the start of a docstring, etc. 

725 

726 Examples 

727 -------- 

728 >>> np.lookfor('binary representation') # doctest: +SKIP 

729 Search results for 'binary representation' 

730 ------------------------------------------ 

731 numpy.binary_repr 

732 Return the binary representation of the input number as a string. 

733 numpy.core.setup_common.long_double_representation 

734 Given a binary dump as given by GNU od -b, look for long double 

735 numpy.base_repr 

736 Return a string representation of a number in the given base system. 

737 ... 

738 

739 """ 

740 import pydoc 

741 

742 # Cache 

743 cache = _lookfor_generate_cache(module, import_modules, regenerate) 

744 

745 # Search 

746 # XXX: maybe using a real stemming search engine would be better? 

747 found = [] 

748 whats = str(what).lower().split() 

749 if not whats: 

750 return 

751 

752 for name, (docstring, kind, index) in cache.items(): 

753 if kind in ('module', 'object'): 

754 # don't show modules or objects 

755 continue 

756 doc = docstring.lower() 

757 if all(w in doc for w in whats): 

758 found.append(name) 

759 

760 # Relevance sort 

761 # XXX: this is full Harrison-Stetson heuristics now, 

762 # XXX: it probably could be improved 

763 

764 kind_relevance = {'func': 1000, 'class': 1000, 

765 'module': -1000, 'object': -1000} 

766 

767 def relevance(name, docstr, kind, index): 

768 r = 0 

769 # do the keywords occur within the start of the docstring? 

770 first_doc = "\n".join(docstr.lower().strip().split("\n")[:3]) 

771 r += sum([200 for w in whats if w in first_doc]) 

772 # do the keywords occur in the function name? 

773 r += sum([30 for w in whats if w in name]) 

774 # is the full name long? 

775 r += -len(name) * 5 

776 # is the object of bad type? 

777 r += kind_relevance.get(kind, -1000) 

778 # is the object deep in namespace hierarchy? 

779 r += -name.count('.') * 10 

780 r += max(-index / 100, -100) 

781 return r 

782 

783 def relevance_value(a): 

784 return relevance(a, *cache[a]) 

785 found.sort(key=relevance_value) 

786 

787 # Pretty-print 

788 s = "Search results for '%s'" % (' '.join(whats)) 

789 help_text = [s, "-"*len(s)] 

790 for name in found[::-1]: 

791 doc, kind, ix = cache[name] 

792 

793 doclines = [line.strip() for line in doc.strip().split("\n") 

794 if line.strip()] 

795 

796 # find a suitable short description 

797 try: 

798 first_doc = doclines[0].strip() 

799 if _function_signature_re.search(first_doc): 

800 first_doc = doclines[1].strip() 

801 except IndexError: 

802 first_doc = "" 

803 help_text.append("%s\n %s" % (name, first_doc)) 

804 

805 if not found: 

806 help_text.append("Nothing found.") 

807 

808 # Output 

809 if output is not None: 

810 output.write("\n".join(help_text)) 

811 elif len(help_text) > 10: 

812 pager = pydoc.getpager() 

813 pager("\n".join(help_text)) 

814 else: 

815 print("\n".join(help_text)) 

816 

817def _lookfor_generate_cache(module, import_modules, regenerate): 

818 """ 

819 Generate docstring cache for given module. 

820 

821 Parameters 

822 ---------- 

823 module : str, None, module 

824 Module for which to generate docstring cache 

825 import_modules : bool 

826 Whether to import sub-modules in packages. 

827 regenerate : bool 

828 Re-generate the docstring cache 

829 

830 Returns 

831 ------- 

832 cache : dict {obj_full_name: (docstring, kind, index), ...} 

833 Docstring cache for the module, either cached one (regenerate=False) 

834 or newly generated. 

835 

836 """ 

837 # Local import to speed up numpy's import time. 

838 import inspect 

839 

840 from io import StringIO 

841 

842 if module is None: 

843 module = "numpy" 

844 

845 if isinstance(module, str): 

846 try: 

847 __import__(module) 

848 except ImportError: 

849 return {} 

850 module = sys.modules[module] 

851 elif isinstance(module, list) or isinstance(module, tuple): 

852 cache = {} 

853 for mod in module: 

854 cache.update(_lookfor_generate_cache(mod, import_modules, 

855 regenerate)) 

856 return cache 

857 

858 if id(module) in _lookfor_caches and not regenerate: 

859 return _lookfor_caches[id(module)] 

860 

861 # walk items and collect docstrings 

862 cache = {} 

863 _lookfor_caches[id(module)] = cache 

864 seen = {} 

865 index = 0 

866 stack = [(module.__name__, module)] 

867 while stack: 

868 name, item = stack.pop(0) 

869 if id(item) in seen: 

870 continue 

871 seen[id(item)] = True 

872 

873 index += 1 

874 kind = "object" 

875 

876 if inspect.ismodule(item): 

877 kind = "module" 

878 try: 

879 _all = item.__all__ 

880 except AttributeError: 

881 _all = None 

882 

883 # import sub-packages 

884 if import_modules and hasattr(item, '__path__'): 

885 for pth in item.__path__: 

886 for mod_path in os.listdir(pth): 

887 this_py = os.path.join(pth, mod_path) 

888 init_py = os.path.join(pth, mod_path, '__init__.py') 

889 if (os.path.isfile(this_py) and 

890 mod_path.endswith('.py')): 

891 to_import = mod_path[:-3] 

892 elif os.path.isfile(init_py): 

893 to_import = mod_path 

894 else: 

895 continue 

896 if to_import == '__init__': 

897 continue 

898 

899 try: 

900 old_stdout = sys.stdout 

901 old_stderr = sys.stderr 

902 try: 

903 sys.stdout = StringIO() 

904 sys.stderr = StringIO() 

905 __import__("%s.%s" % (name, to_import)) 

906 finally: 

907 sys.stdout = old_stdout 

908 sys.stderr = old_stderr 

909 # Catch SystemExit, too 

910 except BaseException: 

911 continue 

912 

913 for n, v in _getmembers(item): 

914 try: 

915 item_name = getattr(v, '__name__', "%s.%s" % (name, n)) 

916 mod_name = getattr(v, '__module__', None) 

917 except NameError: 

918 # ref. SWIG's global cvars 

919 # NameError: Unknown C global variable 

920 item_name = "%s.%s" % (name, n) 

921 mod_name = None 

922 if '.' not in item_name and mod_name: 

923 item_name = "%s.%s" % (mod_name, item_name) 

924 

925 if not item_name.startswith(name + '.'): 

926 # don't crawl "foreign" objects 

927 if isinstance(v, ufunc): 

928 # ... unless they are ufuncs 

929 pass 

930 else: 

931 continue 

932 elif not (inspect.ismodule(v) or _all is None or n in _all): 

933 continue 

934 stack.append(("%s.%s" % (name, n), v)) 

935 elif inspect.isclass(item): 

936 kind = "class" 

937 for n, v in _getmembers(item): 

938 stack.append(("%s.%s" % (name, n), v)) 

939 elif hasattr(item, "__call__"): 

940 kind = "func" 

941 

942 try: 

943 doc = inspect.getdoc(item) 

944 except NameError: 

945 # ref SWIG's NameError: Unknown C global variable 

946 doc = None 

947 if doc is not None: 

948 cache[name] = (doc, kind, index) 

949 

950 return cache 

951 

952def _getmembers(item): 

953 import inspect 

954 try: 

955 members = inspect.getmembers(item) 

956 except Exception: 

957 members = [(x, getattr(item, x)) for x in dir(item) 

958 if hasattr(item, x)] 

959 return members 

960 

961 

962def safe_eval(source): 

963 """ 

964 Protected string evaluation. 

965 

966 Evaluate a string containing a Python literal expression without 

967 allowing the execution of arbitrary non-literal code. 

968 

969 Parameters 

970 ---------- 

971 source : str 

972 The string to evaluate. 

973 

974 Returns 

975 ------- 

976 obj : object 

977 The result of evaluating `source`. 

978 

979 Raises 

980 ------ 

981 SyntaxError 

982 If the code has invalid Python syntax, or if it contains 

983 non-literal code. 

984 

985 Examples 

986 -------- 

987 >>> np.safe_eval('1') 

988 1 

989 >>> np.safe_eval('[1, 2, 3]') 

990 [1, 2, 3] 

991 >>> np.safe_eval('{"foo": ("bar", 10.0)}') 

992 {'foo': ('bar', 10.0)} 

993 

994 >>> np.safe_eval('import os') 

995 Traceback (most recent call last): 

996 ... 

997 SyntaxError: invalid syntax 

998 

999 >>> np.safe_eval('open("/home/user/.ssh/id_dsa").read()') 

1000 Traceback (most recent call last): 

1001 ... 

1002 ValueError: malformed node or string: <_ast.Call object at 0x...> 

1003 

1004 """ 

1005 # Local import to speed up numpy's import time. 

1006 import ast 

1007 return ast.literal_eval(source) 

1008 

1009 

1010def _median_nancheck(data, result, axis, out): 

1011 """ 

1012 Utility function to check median result from data for NaN values at the end 

1013 and return NaN in that case. Input result can also be a MaskedArray. 

1014 

1015 Parameters 

1016 ---------- 

1017 data : array 

1018 Input data to median function 

1019 result : Array or MaskedArray 

1020 Result of median function 

1021 axis : {int, sequence of int, None}, optional 

1022 Axis or axes along which the median was computed. 

1023 out : ndarray, optional 

1024 Output array in which to place the result. 

1025 Returns 

1026 ------- 

1027 median : scalar or ndarray 

1028 Median or NaN in axes which contained NaN in the input. 

1029 """ 

1030 if data.size == 0: 

1031 return result 

1032 data = np.moveaxis(data, axis, -1) 

1033 n = np.isnan(data[..., -1]) 

1034 # masked NaN values are ok 

1035 if np.ma.isMaskedArray(n): 

1036 n = n.filled(False) 

1037 if result.ndim == 0: 

1038 if n == True: 

1039 if out is not None: 

1040 out[...] = data.dtype.type(np.nan) 

1041 result = out 

1042 else: 

1043 result = data.dtype.type(np.nan) 

1044 elif np.count_nonzero(n.ravel()) > 0: 

1045 result[n] = np.nan 

1046 return result 

1047 

1048#-----------------------------------------------------------------------------