Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/IPython/core/oinspect.py: 5%

Shortcuts on this page

r m x   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

538 statements  

1# -*- coding: utf-8 -*- 

2"""Tools for inspecting Python objects. 

3 

4Uses syntax highlighting for presenting the various information elements. 

5 

6Similar in spirit to the inspect module, but all calls take a name argument to 

7reference the name under which an object is being read. 

8""" 

9 

10# Copyright (c) IPython Development Team. 

11# Distributed under the terms of the Modified BSD License. 

12 

13__all__ = ['Inspector','InspectColors'] 

14 

15# stdlib modules 

16from dataclasses import dataclass 

17from inspect import signature 

18from textwrap import dedent 

19import ast 

20import html 

21import inspect 

22import io as stdlib_io 

23import linecache 

24import os 

25import sys 

26import types 

27import warnings 

28 

29from typing import Any, Optional, Dict, Union, List, Tuple 

30 

31if sys.version_info <= (3, 10): 

32 from typing_extensions import TypeAlias 

33else: 

34 from typing import TypeAlias 

35 

36# IPython's own 

37from IPython.core import page 

38from IPython.lib.pretty import pretty 

39from IPython.testing.skipdoctest import skip_doctest 

40from IPython.utils import PyColorize 

41from IPython.utils import openpy 

42from IPython.utils.dir2 import safe_hasattr 

43from IPython.utils.path import compress_user 

44from IPython.utils.text import indent 

45from IPython.utils.wildcard import list_namespace 

46from IPython.utils.wildcard import typestr2type 

47from IPython.utils.coloransi import TermColors, ColorScheme, ColorSchemeTable 

48from IPython.utils.py3compat import cast_unicode 

49from IPython.utils.colorable import Colorable 

50from IPython.utils.decorators import undoc 

51 

52from pygments import highlight 

53from pygments.lexers import PythonLexer 

54from pygments.formatters import HtmlFormatter 

55 

56HOOK_NAME = "__custom_documentations__" 

57 

58 

59UnformattedBundle: TypeAlias = Dict[str, List[Tuple[str, str]]] # List of (title, body) 

60Bundle: TypeAlias = Dict[str, str] 

61 

62 

63@dataclass 

64class OInfo: 

65 ismagic: bool 

66 isalias: bool 

67 found: bool 

68 namespace: Optional[str] 

69 parent: Any 

70 obj: Any 

71 

72 def get(self, field): 

73 """Get a field from the object for backward compatibility with before 8.12 

74 

75 see https://github.com/h5py/h5py/issues/2253 

76 """ 

77 # We need to deprecate this at some point, but the warning will show in completion. 

78 # Let's comment this for now and uncomment end of 2023 ish 

79 # warnings.warn( 

80 # f"OInfo dataclass with fields access since IPython 8.12 please use OInfo.{field} instead." 

81 # "OInfo used to be a dict but a dataclass provide static fields verification with mypy." 

82 # "This warning and backward compatibility `get()` method were added in 8.13.", 

83 # DeprecationWarning, 

84 # stacklevel=2, 

85 # ) 

86 return getattr(self, field) 

87 

88 

89def pylight(code): 

90 return highlight(code, PythonLexer(), HtmlFormatter(noclasses=True)) 

91 

92# builtin docstrings to ignore 

93_func_call_docstring = types.FunctionType.__call__.__doc__ 

94_object_init_docstring = object.__init__.__doc__ 

95_builtin_type_docstrings = { 

96 inspect.getdoc(t) for t in (types.ModuleType, types.MethodType, 

97 types.FunctionType, property) 

98} 

99 

100_builtin_func_type = type(all) 

101_builtin_meth_type = type(str.upper) # Bound methods have the same type as builtin functions 

102#**************************************************************************** 

103# Builtin color schemes 

104 

105Colors = TermColors # just a shorthand 

106 

107InspectColors = PyColorize.ANSICodeColors 

108 

109#**************************************************************************** 

110# Auxiliary functions and objects 

111 

112# See the messaging spec for the definition of all these fields. This list 

113# effectively defines the order of display 

114info_fields = ['type_name', 'base_class', 'string_form', 'namespace', 

115 'length', 'file', 'definition', 'docstring', 'source', 

116 'init_definition', 'class_docstring', 'init_docstring', 

117 'call_def', 'call_docstring', 

118 # These won't be printed but will be used to determine how to 

119 # format the object 

120 'ismagic', 'isalias', 'isclass', 'found', 'name' 

121 ] 

122 

123 

124def object_info(**kw): 

125 """Make an object info dict with all fields present.""" 

126 infodict = {k:None for k in info_fields} 

127 infodict.update(kw) 

128 return infodict 

129 

130 

131def get_encoding(obj): 

132 """Get encoding for python source file defining obj 

133 

134 Returns None if obj is not defined in a sourcefile. 

135 """ 

136 ofile = find_file(obj) 

137 # run contents of file through pager starting at line where the object 

138 # is defined, as long as the file isn't binary and is actually on the 

139 # filesystem. 

140 if ofile is None: 

141 return None 

142 elif ofile.endswith(('.so', '.dll', '.pyd')): 

143 return None 

144 elif not os.path.isfile(ofile): 

145 return None 

146 else: 

147 # Print only text files, not extension binaries. Note that 

148 # getsourcelines returns lineno with 1-offset and page() uses 

149 # 0-offset, so we must adjust. 

150 with stdlib_io.open(ofile, 'rb') as buffer: # Tweaked to use io.open for Python 2 

151 encoding, lines = openpy.detect_encoding(buffer.readline) 

152 return encoding 

153 

154def getdoc(obj) -> Union[str,None]: 

155 """Stable wrapper around inspect.getdoc. 

156 

157 This can't crash because of attribute problems. 

158 

159 It also attempts to call a getdoc() method on the given object. This 

160 allows objects which provide their docstrings via non-standard mechanisms 

161 (like Pyro proxies) to still be inspected by ipython's ? system. 

162 """ 

163 # Allow objects to offer customized documentation via a getdoc method: 

164 try: 

165 ds = obj.getdoc() 

166 except Exception: 

167 pass 

168 else: 

169 if isinstance(ds, str): 

170 return inspect.cleandoc(ds) 

171 docstr = inspect.getdoc(obj) 

172 return docstr 

173 

174 

175def getsource(obj, oname='') -> Union[str,None]: 

176 """Wrapper around inspect.getsource. 

177 

178 This can be modified by other projects to provide customized source 

179 extraction. 

180 

181 Parameters 

182 ---------- 

183 obj : object 

184 an object whose source code we will attempt to extract 

185 oname : str 

186 (optional) a name under which the object is known 

187 

188 Returns 

189 ------- 

190 src : unicode or None 

191 

192 """ 

193 

194 if isinstance(obj, property): 

195 sources = [] 

196 for attrname in ['fget', 'fset', 'fdel']: 

197 fn = getattr(obj, attrname) 

198 if fn is not None: 

199 encoding = get_encoding(fn) 

200 oname_prefix = ('%s.' % oname) if oname else '' 

201 sources.append(''.join(('# ', oname_prefix, attrname))) 

202 if inspect.isfunction(fn): 

203 _src = getsource(fn) 

204 if _src: 

205 # assert _src is not None, "please mypy" 

206 sources.append(dedent(_src)) 

207 else: 

208 # Default str/repr only prints function name, 

209 # pretty.pretty prints module name too. 

210 sources.append( 

211 '%s%s = %s\n' % (oname_prefix, attrname, pretty(fn)) 

212 ) 

213 if sources: 

214 return '\n'.join(sources) 

215 else: 

216 return None 

217 

218 else: 

219 # Get source for non-property objects. 

220 

221 obj = _get_wrapped(obj) 

222 

223 try: 

224 src = inspect.getsource(obj) 

225 except TypeError: 

226 # The object itself provided no meaningful source, try looking for 

227 # its class definition instead. 

228 try: 

229 src = inspect.getsource(obj.__class__) 

230 except (OSError, TypeError): 

231 return None 

232 except OSError: 

233 return None 

234 

235 return src 

236 

237 

238def is_simple_callable(obj): 

239 """True if obj is a function ()""" 

240 return (inspect.isfunction(obj) or inspect.ismethod(obj) or \ 

241 isinstance(obj, _builtin_func_type) or isinstance(obj, _builtin_meth_type)) 

242 

243@undoc 

244def getargspec(obj): 

245 """Wrapper around :func:`inspect.getfullargspec` 

246 

247 In addition to functions and methods, this can also handle objects with a 

248 ``__call__`` attribute. 

249 

250 DEPRECATED: Deprecated since 7.10. Do not use, will be removed. 

251 """ 

252 

253 warnings.warn('`getargspec` function is deprecated as of IPython 7.10' 

254 'and will be removed in future versions.', DeprecationWarning, stacklevel=2) 

255 

256 if safe_hasattr(obj, '__call__') and not is_simple_callable(obj): 

257 obj = obj.__call__ 

258 

259 return inspect.getfullargspec(obj) 

260 

261@undoc 

262def format_argspec(argspec): 

263 """Format argspect, convenience wrapper around inspect's. 

264 

265 This takes a dict instead of ordered arguments and calls 

266 inspect.format_argspec with the arguments in the necessary order. 

267 

268 DEPRECATED (since 7.10): Do not use; will be removed in future versions. 

269 """ 

270 

271 warnings.warn('`format_argspec` function is deprecated as of IPython 7.10' 

272 'and will be removed in future versions.', DeprecationWarning, stacklevel=2) 

273 

274 

275 return inspect.formatargspec(argspec['args'], argspec['varargs'], 

276 argspec['varkw'], argspec['defaults']) 

277 

278@undoc 

279def call_tip(oinfo, format_call=True): 

280 """DEPRECATED since 6.0. Extract call tip data from an oinfo dict.""" 

281 warnings.warn( 

282 "`call_tip` function is deprecated as of IPython 6.0" 

283 "and will be removed in future versions.", 

284 DeprecationWarning, 

285 stacklevel=2, 

286 ) 

287 # Get call definition 

288 argspec = oinfo.get('argspec') 

289 if argspec is None: 

290 call_line = None 

291 else: 

292 # Callable objects will have 'self' as their first argument, prune 

293 # it out if it's there for clarity (since users do *not* pass an 

294 # extra first argument explicitly). 

295 try: 

296 has_self = argspec['args'][0] == 'self' 

297 except (KeyError, IndexError): 

298 pass 

299 else: 

300 if has_self: 

301 argspec['args'] = argspec['args'][1:] 

302 

303 call_line = oinfo['name']+format_argspec(argspec) 

304 

305 # Now get docstring. 

306 # The priority is: call docstring, constructor docstring, main one. 

307 doc = oinfo.get('call_docstring') 

308 if doc is None: 

309 doc = oinfo.get('init_docstring') 

310 if doc is None: 

311 doc = oinfo.get('docstring','') 

312 

313 return call_line, doc 

314 

315 

316def _get_wrapped(obj): 

317 """Get the original object if wrapped in one or more @decorators 

318 

319 Some objects automatically construct similar objects on any unrecognised 

320 attribute access (e.g. unittest.mock.call). To protect against infinite loops, 

321 this will arbitrarily cut off after 100 levels of obj.__wrapped__ 

322 attribute access. --TK, Jan 2016 

323 """ 

324 orig_obj = obj 

325 i = 0 

326 while safe_hasattr(obj, '__wrapped__'): 

327 obj = obj.__wrapped__ 

328 i += 1 

329 if i > 100: 

330 # __wrapped__ is probably a lie, so return the thing we started with 

331 return orig_obj 

332 return obj 

333 

334def find_file(obj) -> str: 

335 """Find the absolute path to the file where an object was defined. 

336 

337 This is essentially a robust wrapper around `inspect.getabsfile`. 

338 

339 Returns None if no file can be found. 

340 

341 Parameters 

342 ---------- 

343 obj : any Python object 

344 

345 Returns 

346 ------- 

347 fname : str 

348 The absolute path to the file where the object was defined. 

349 """ 

350 obj = _get_wrapped(obj) 

351 

352 fname = None 

353 try: 

354 fname = inspect.getabsfile(obj) 

355 except TypeError: 

356 # For an instance, the file that matters is where its class was 

357 # declared. 

358 try: 

359 fname = inspect.getabsfile(obj.__class__) 

360 except (OSError, TypeError): 

361 # Can happen for builtins 

362 pass 

363 except OSError: 

364 pass 

365 

366 return cast_unicode(fname) 

367 

368 

369def find_source_lines(obj): 

370 """Find the line number in a file where an object was defined. 

371 

372 This is essentially a robust wrapper around `inspect.getsourcelines`. 

373 

374 Returns None if no file can be found. 

375 

376 Parameters 

377 ---------- 

378 obj : any Python object 

379 

380 Returns 

381 ------- 

382 lineno : int 

383 The line number where the object definition starts. 

384 """ 

385 obj = _get_wrapped(obj) 

386 

387 try: 

388 lineno = inspect.getsourcelines(obj)[1] 

389 except TypeError: 

390 # For instances, try the class object like getsource() does 

391 try: 

392 lineno = inspect.getsourcelines(obj.__class__)[1] 

393 except (OSError, TypeError): 

394 return None 

395 except OSError: 

396 return None 

397 

398 return lineno 

399 

400class Inspector(Colorable): 

401 

402 def __init__(self, color_table=InspectColors, 

403 code_color_table=PyColorize.ANSICodeColors, 

404 scheme=None, 

405 str_detail_level=0, 

406 parent=None, config=None): 

407 super(Inspector, self).__init__(parent=parent, config=config) 

408 self.color_table = color_table 

409 self.parser = PyColorize.Parser(out='str', parent=self, style=scheme) 

410 self.format = self.parser.format 

411 self.str_detail_level = str_detail_level 

412 self.set_active_scheme(scheme) 

413 

414 def _getdef(self,obj,oname='') -> Union[str,None]: 

415 """Return the call signature for any callable object. 

416 

417 If any exception is generated, None is returned instead and the 

418 exception is suppressed.""" 

419 try: 

420 return _render_signature(signature(obj), oname) 

421 except: 

422 return None 

423 

424 def __head(self,h) -> str: 

425 """Return a header string with proper colors.""" 

426 return '%s%s%s' % (self.color_table.active_colors.header,h, 

427 self.color_table.active_colors.normal) 

428 

429 def set_active_scheme(self, scheme): 

430 if scheme is not None: 

431 self.color_table.set_active_scheme(scheme) 

432 self.parser.color_table.set_active_scheme(scheme) 

433 

434 def noinfo(self, msg, oname): 

435 """Generic message when no information is found.""" 

436 print('No %s found' % msg, end=' ') 

437 if oname: 

438 print('for %s' % oname) 

439 else: 

440 print() 

441 

442 def pdef(self, obj, oname=''): 

443 """Print the call signature for any callable object. 

444 

445 If the object is a class, print the constructor information.""" 

446 

447 if not callable(obj): 

448 print('Object is not callable.') 

449 return 

450 

451 header = '' 

452 

453 if inspect.isclass(obj): 

454 header = self.__head('Class constructor information:\n') 

455 

456 

457 output = self._getdef(obj,oname) 

458 if output is None: 

459 self.noinfo('definition header',oname) 

460 else: 

461 print(header,self.format(output), end=' ') 

462 

463 # In Python 3, all classes are new-style, so they all have __init__. 

464 @skip_doctest 

465 def pdoc(self, obj, oname='', formatter=None): 

466 """Print the docstring for any object. 

467 

468 Optional: 

469 -formatter: a function to run the docstring through for specially 

470 formatted docstrings. 

471 

472 Examples 

473 -------- 

474 In [1]: class NoInit: 

475 ...: pass 

476 

477 In [2]: class NoDoc: 

478 ...: def __init__(self): 

479 ...: pass 

480 

481 In [3]: %pdoc NoDoc 

482 No documentation found for NoDoc 

483 

484 In [4]: %pdoc NoInit 

485 No documentation found for NoInit 

486 

487 In [5]: obj = NoInit() 

488 

489 In [6]: %pdoc obj 

490 No documentation found for obj 

491 

492 In [5]: obj2 = NoDoc() 

493 

494 In [6]: %pdoc obj2 

495 No documentation found for obj2 

496 """ 

497 

498 head = self.__head # For convenience 

499 lines = [] 

500 ds = getdoc(obj) 

501 if formatter: 

502 ds = formatter(ds).get('plain/text', ds) 

503 if ds: 

504 lines.append(head("Class docstring:")) 

505 lines.append(indent(ds)) 

506 if inspect.isclass(obj) and hasattr(obj, '__init__'): 

507 init_ds = getdoc(obj.__init__) 

508 if init_ds is not None: 

509 lines.append(head("Init docstring:")) 

510 lines.append(indent(init_ds)) 

511 elif hasattr(obj,'__call__'): 

512 call_ds = getdoc(obj.__call__) 

513 if call_ds: 

514 lines.append(head("Call docstring:")) 

515 lines.append(indent(call_ds)) 

516 

517 if not lines: 

518 self.noinfo('documentation',oname) 

519 else: 

520 page.page('\n'.join(lines)) 

521 

522 def psource(self, obj, oname=''): 

523 """Print the source code for an object.""" 

524 

525 # Flush the source cache because inspect can return out-of-date source 

526 linecache.checkcache() 

527 try: 

528 src = getsource(obj, oname=oname) 

529 except Exception: 

530 src = None 

531 

532 if src is None: 

533 self.noinfo('source', oname) 

534 else: 

535 page.page(self.format(src)) 

536 

537 def pfile(self, obj, oname=''): 

538 """Show the whole file where an object was defined.""" 

539 

540 lineno = find_source_lines(obj) 

541 if lineno is None: 

542 self.noinfo('file', oname) 

543 return 

544 

545 ofile = find_file(obj) 

546 # run contents of file through pager starting at line where the object 

547 # is defined, as long as the file isn't binary and is actually on the 

548 # filesystem. 

549 if ofile.endswith(('.so', '.dll', '.pyd')): 

550 print('File %r is binary, not printing.' % ofile) 

551 elif not os.path.isfile(ofile): 

552 print('File %r does not exist, not printing.' % ofile) 

553 else: 

554 # Print only text files, not extension binaries. Note that 

555 # getsourcelines returns lineno with 1-offset and page() uses 

556 # 0-offset, so we must adjust. 

557 page.page(self.format(openpy.read_py_file(ofile, skip_encoding_cookie=False)), lineno - 1) 

558 

559 

560 def _mime_format(self, text:str, formatter=None) -> dict: 

561 """Return a mime bundle representation of the input text. 

562 

563 - if `formatter` is None, the returned mime bundle has 

564 a ``text/plain`` field, with the input text. 

565 a ``text/html`` field with a ``<pre>`` tag containing the input text. 

566 

567 - if ``formatter`` is not None, it must be a callable transforming the 

568 input text into a mime bundle. Default values for ``text/plain`` and 

569 ``text/html`` representations are the ones described above. 

570 

571 Note: 

572 

573 Formatters returning strings are supported but this behavior is deprecated. 

574 

575 """ 

576 defaults = { 

577 "text/plain": text, 

578 "text/html": f"<pre>{html.escape(text)}</pre>", 

579 } 

580 

581 if formatter is None: 

582 return defaults 

583 else: 

584 formatted = formatter(text) 

585 

586 if not isinstance(formatted, dict): 

587 # Handle the deprecated behavior of a formatter returning 

588 # a string instead of a mime bundle. 

589 return {"text/plain": formatted, "text/html": f"<pre>{formatted}</pre>"} 

590 

591 else: 

592 return dict(defaults, **formatted) 

593 

594 def format_mime(self, bundle: UnformattedBundle) -> Bundle: 

595 """Format a mimebundle being created by _make_info_unformatted into a real mimebundle""" 

596 # Format text/plain mimetype 

597 assert isinstance(bundle["text/plain"], list) 

598 for item in bundle["text/plain"]: 

599 assert isinstance(item, tuple) 

600 

601 new_b: Bundle = {} 

602 lines = [] 

603 _len = max(len(h) for h, _ in bundle["text/plain"]) 

604 

605 for head, body in bundle["text/plain"]: 

606 body = body.strip("\n") 

607 delim = "\n" if "\n" in body else " " 

608 lines.append( 

609 f"{self.__head(head+':')}{(_len - len(head))*' '}{delim}{body}" 

610 ) 

611 

612 new_b["text/plain"] = "\n".join(lines) 

613 

614 if "text/html" in bundle: 

615 assert isinstance(bundle["text/html"], list) 

616 for item in bundle["text/html"]: 

617 assert isinstance(item, tuple) 

618 # Format the text/html mimetype 

619 if isinstance(bundle["text/html"], (list, tuple)): 

620 # bundle['text/html'] is a list of (head, formatted body) pairs 

621 new_b["text/html"] = "\n".join( 

622 (f"<h1>{head}</h1>\n{body}" for (head, body) in bundle["text/html"]) 

623 ) 

624 

625 for k in bundle.keys(): 

626 if k in ("text/html", "text/plain"): 

627 continue 

628 else: 

629 new_b = bundle[k] # type:ignore 

630 return new_b 

631 

632 def _append_info_field( 

633 self, 

634 bundle: UnformattedBundle, 

635 title: str, 

636 key: str, 

637 info, 

638 omit_sections, 

639 formatter, 

640 ): 

641 """Append an info value to the unformatted mimebundle being constructed by _make_info_unformatted""" 

642 if title in omit_sections or key in omit_sections: 

643 return 

644 field = info[key] 

645 if field is not None: 

646 formatted_field = self._mime_format(field, formatter) 

647 bundle["text/plain"].append((title, formatted_field["text/plain"])) 

648 bundle["text/html"].append((title, formatted_field["text/html"])) 

649 

650 def _make_info_unformatted( 

651 self, obj, info, formatter, detail_level, omit_sections 

652 ) -> UnformattedBundle: 

653 """Assemble the mimebundle as unformatted lists of information""" 

654 bundle: UnformattedBundle = { 

655 "text/plain": [], 

656 "text/html": [], 

657 } 

658 

659 # A convenience function to simplify calls below 

660 def append_field( 

661 bundle: UnformattedBundle, title: str, key: str, formatter=None 

662 ): 

663 self._append_info_field( 

664 bundle, 

665 title=title, 

666 key=key, 

667 info=info, 

668 omit_sections=omit_sections, 

669 formatter=formatter, 

670 ) 

671 

672 def code_formatter(text) -> Bundle: 

673 return { 

674 'text/plain': self.format(text), 

675 'text/html': pylight(text) 

676 } 

677 

678 if info["isalias"]: 

679 append_field(bundle, "Repr", "string_form") 

680 

681 elif info['ismagic']: 

682 if detail_level > 0: 

683 append_field(bundle, "Source", "source", code_formatter) 

684 else: 

685 append_field(bundle, "Docstring", "docstring", formatter) 

686 append_field(bundle, "File", "file") 

687 

688 elif info['isclass'] or is_simple_callable(obj): 

689 # Functions, methods, classes 

690 append_field(bundle, "Signature", "definition", code_formatter) 

691 append_field(bundle, "Init signature", "init_definition", code_formatter) 

692 append_field(bundle, "Docstring", "docstring", formatter) 

693 if detail_level > 0 and info["source"]: 

694 append_field(bundle, "Source", "source", code_formatter) 

695 else: 

696 append_field(bundle, "Init docstring", "init_docstring", formatter) 

697 

698 append_field(bundle, "File", "file") 

699 append_field(bundle, "Type", "type_name") 

700 append_field(bundle, "Subclasses", "subclasses") 

701 

702 else: 

703 # General Python objects 

704 append_field(bundle, "Signature", "definition", code_formatter) 

705 append_field(bundle, "Call signature", "call_def", code_formatter) 

706 append_field(bundle, "Type", "type_name") 

707 append_field(bundle, "String form", "string_form") 

708 

709 # Namespace 

710 if info["namespace"] != "Interactive": 

711 append_field(bundle, "Namespace", "namespace") 

712 

713 append_field(bundle, "Length", "length") 

714 append_field(bundle, "File", "file") 

715 

716 # Source or docstring, depending on detail level and whether 

717 # source found. 

718 if detail_level > 0 and info["source"]: 

719 append_field(bundle, "Source", "source", code_formatter) 

720 else: 

721 append_field(bundle, "Docstring", "docstring", formatter) 

722 

723 append_field(bundle, "Class docstring", "class_docstring", formatter) 

724 append_field(bundle, "Init docstring", "init_docstring", formatter) 

725 append_field(bundle, "Call docstring", "call_docstring", formatter) 

726 return bundle 

727 

728 

729 def _get_info( 

730 self, 

731 obj: Any, 

732 oname: str = "", 

733 formatter=None, 

734 info: Optional[OInfo] = None, 

735 detail_level=0, 

736 omit_sections=(), 

737 ) -> Bundle: 

738 """Retrieve an info dict and format it. 

739 

740 Parameters 

741 ---------- 

742 obj : any 

743 Object to inspect and return info from 

744 oname : str (default: ''): 

745 Name of the variable pointing to `obj`. 

746 formatter : callable 

747 info 

748 already computed information 

749 detail_level : integer 

750 Granularity of detail level, if set to 1, give more information. 

751 omit_sections : container[str] 

752 Titles or keys to omit from output (can be set, tuple, etc., anything supporting `in`) 

753 """ 

754 

755 info_dict = self.info(obj, oname=oname, info=info, detail_level=detail_level) 

756 bundle = self._make_info_unformatted( 

757 obj, 

758 info_dict, 

759 formatter, 

760 detail_level=detail_level, 

761 omit_sections=omit_sections, 

762 ) 

763 return self.format_mime(bundle) 

764 

765 def pinfo( 

766 self, 

767 obj, 

768 oname="", 

769 formatter=None, 

770 info: Optional[OInfo] = None, 

771 detail_level=0, 

772 enable_html_pager=True, 

773 omit_sections=(), 

774 ): 

775 """Show detailed information about an object. 

776 

777 Optional arguments: 

778 

779 - oname: name of the variable pointing to the object. 

780 

781 - formatter: callable (optional) 

782 A special formatter for docstrings. 

783 

784 The formatter is a callable that takes a string as an input 

785 and returns either a formatted string or a mime type bundle 

786 in the form of a dictionary. 

787 

788 Although the support of custom formatter returning a string 

789 instead of a mime type bundle is deprecated. 

790 

791 - info: a structure with some information fields which may have been 

792 precomputed already. 

793 

794 - detail_level: if set to 1, more information is given. 

795 

796 - omit_sections: set of section keys and titles to omit 

797 """ 

798 assert info is not None 

799 info_b: Bundle = self._get_info( 

800 obj, oname, formatter, info, detail_level, omit_sections=omit_sections 

801 ) 

802 if not enable_html_pager: 

803 del info_b["text/html"] 

804 page.page(info_b) 

805 

806 def _info(self, obj, oname="", info=None, detail_level=0): 

807 """ 

808 Inspector.info() was likely improperly marked as deprecated 

809 while only a parameter was deprecated. We "un-deprecate" it. 

810 """ 

811 

812 warnings.warn( 

813 "The `Inspector.info()` method has been un-deprecated as of 8.0 " 

814 "and the `formatter=` keyword removed. `Inspector._info` is now " 

815 "an alias, and you can just call `.info()` directly.", 

816 DeprecationWarning, 

817 stacklevel=2, 

818 ) 

819 return self.info(obj, oname=oname, info=info, detail_level=detail_level) 

820 

821 def info(self, obj, oname="", info=None, detail_level=0) -> Dict[str, Any]: 

822 """Compute a dict with detailed information about an object. 

823 

824 Parameters 

825 ---------- 

826 obj : any 

827 An object to find information about 

828 oname : str (default: '') 

829 Name of the variable pointing to `obj`. 

830 info : (default: None) 

831 A struct (dict like with attr access) with some information fields 

832 which may have been precomputed already. 

833 detail_level : int (default:0) 

834 If set to 1, more information is given. 

835 

836 Returns 

837 ------- 

838 An object info dict with known fields from `info_fields`. Keys are 

839 strings, values are string or None. 

840 """ 

841 

842 if info is None: 

843 ismagic = False 

844 isalias = False 

845 ospace = '' 

846 else: 

847 ismagic = info.ismagic 

848 isalias = info.isalias 

849 ospace = info.namespace 

850 

851 # Get docstring, special-casing aliases: 

852 att_name = oname.split(".")[-1] 

853 parents_docs = None 

854 prelude = "" 

855 if info and info.parent is not None and hasattr(info.parent, HOOK_NAME): 

856 parents_docs_dict = getattr(info.parent, HOOK_NAME) 

857 parents_docs = parents_docs_dict.get(att_name, None) 

858 out = dict( 

859 name=oname, found=True, isalias=isalias, ismagic=ismagic, subclasses=None 

860 ) 

861 

862 if parents_docs: 

863 ds = parents_docs 

864 elif isalias: 

865 if not callable(obj): 

866 try: 

867 ds = "Alias to the system command:\n %s" % obj[1] 

868 except: 

869 ds = "Alias: " + str(obj) 

870 else: 

871 ds = "Alias to " + str(obj) 

872 if obj.__doc__: 

873 ds += "\nDocstring:\n" + obj.__doc__ 

874 else: 

875 ds_or_None = getdoc(obj) 

876 if ds_or_None is None: 

877 ds = '<no docstring>' 

878 else: 

879 ds = ds_or_None 

880 

881 ds = prelude + ds 

882 

883 # store output in a dict, we initialize it here and fill it as we go 

884 

885 string_max = 200 # max size of strings to show (snipped if longer) 

886 shalf = int((string_max - 5) / 2) 

887 

888 if ismagic: 

889 out['type_name'] = 'Magic function' 

890 elif isalias: 

891 out['type_name'] = 'System alias' 

892 else: 

893 out['type_name'] = type(obj).__name__ 

894 

895 try: 

896 bclass = obj.__class__ 

897 out['base_class'] = str(bclass) 

898 except: 

899 pass 

900 

901 # String form, but snip if too long in ? form (full in ??) 

902 if detail_level >= self.str_detail_level: 

903 try: 

904 ostr = str(obj) 

905 str_head = 'string_form' 

906 if not detail_level and len(ostr)>string_max: 

907 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:] 

908 ostr = ("\n" + " " * len(str_head.expandtabs())).\ 

909 join(q.strip() for q in ostr.split("\n")) 

910 out[str_head] = ostr 

911 except: 

912 pass 

913 

914 if ospace: 

915 out['namespace'] = ospace 

916 

917 # Length (for strings and lists) 

918 try: 

919 out['length'] = str(len(obj)) 

920 except Exception: 

921 pass 

922 

923 # Filename where object was defined 

924 binary_file = False 

925 fname = find_file(obj) 

926 if fname is None: 

927 # if anything goes wrong, we don't want to show source, so it's as 

928 # if the file was binary 

929 binary_file = True 

930 else: 

931 if fname.endswith(('.so', '.dll', '.pyd')): 

932 binary_file = True 

933 elif fname.endswith('<string>'): 

934 fname = 'Dynamically generated function. No source code available.' 

935 out['file'] = compress_user(fname) 

936 

937 # Original source code for a callable, class or property. 

938 if detail_level: 

939 # Flush the source cache because inspect can return out-of-date 

940 # source 

941 linecache.checkcache() 

942 try: 

943 if isinstance(obj, property) or not binary_file: 

944 src = getsource(obj, oname) 

945 if src is not None: 

946 src = src.rstrip() 

947 out['source'] = src 

948 

949 except Exception: 

950 pass 

951 

952 # Add docstring only if no source is to be shown (avoid repetitions). 

953 if ds and not self._source_contains_docstring(out.get('source'), ds): 

954 out['docstring'] = ds 

955 

956 # Constructor docstring for classes 

957 if inspect.isclass(obj): 

958 out['isclass'] = True 

959 

960 # get the init signature: 

961 try: 

962 init_def = self._getdef(obj, oname) 

963 except AttributeError: 

964 init_def = None 

965 

966 # get the __init__ docstring 

967 try: 

968 obj_init = obj.__init__ 

969 except AttributeError: 

970 init_ds = None 

971 else: 

972 if init_def is None: 

973 # Get signature from init if top-level sig failed. 

974 # Can happen for built-in types (list, etc.). 

975 try: 

976 init_def = self._getdef(obj_init, oname) 

977 except AttributeError: 

978 pass 

979 init_ds = getdoc(obj_init) 

980 # Skip Python's auto-generated docstrings 

981 if init_ds == _object_init_docstring: 

982 init_ds = None 

983 

984 if init_def: 

985 out['init_definition'] = init_def 

986 

987 if init_ds: 

988 out['init_docstring'] = init_ds 

989 

990 names = [sub.__name__ for sub in type.__subclasses__(obj)] 

991 if len(names) < 10: 

992 all_names = ', '.join(names) 

993 else: 

994 all_names = ', '.join(names[:10]+['...']) 

995 out['subclasses'] = all_names 

996 # and class docstring for instances: 

997 else: 

998 # reconstruct the function definition and print it: 

999 defln = self._getdef(obj, oname) 

1000 if defln: 

1001 out['definition'] = defln 

1002 

1003 # First, check whether the instance docstring is identical to the 

1004 # class one, and print it separately if they don't coincide. In 

1005 # most cases they will, but it's nice to print all the info for 

1006 # objects which use instance-customized docstrings. 

1007 if ds: 

1008 try: 

1009 cls = getattr(obj,'__class__') 

1010 except: 

1011 class_ds = None 

1012 else: 

1013 class_ds = getdoc(cls) 

1014 # Skip Python's auto-generated docstrings 

1015 if class_ds in _builtin_type_docstrings: 

1016 class_ds = None 

1017 if class_ds and ds != class_ds: 

1018 out['class_docstring'] = class_ds 

1019 

1020 # Next, try to show constructor docstrings 

1021 try: 

1022 init_ds = getdoc(obj.__init__) 

1023 # Skip Python's auto-generated docstrings 

1024 if init_ds == _object_init_docstring: 

1025 init_ds = None 

1026 except AttributeError: 

1027 init_ds = None 

1028 if init_ds: 

1029 out['init_docstring'] = init_ds 

1030 

1031 # Call form docstring for callable instances 

1032 if safe_hasattr(obj, '__call__') and not is_simple_callable(obj): 

1033 call_def = self._getdef(obj.__call__, oname) 

1034 if call_def and (call_def != out.get('definition')): 

1035 # it may never be the case that call def and definition differ, 

1036 # but don't include the same signature twice 

1037 out['call_def'] = call_def 

1038 call_ds = getdoc(obj.__call__) 

1039 # Skip Python's auto-generated docstrings 

1040 if call_ds == _func_call_docstring: 

1041 call_ds = None 

1042 if call_ds: 

1043 out['call_docstring'] = call_ds 

1044 

1045 return object_info(**out) 

1046 

1047 @staticmethod 

1048 def _source_contains_docstring(src, doc): 

1049 """ 

1050 Check whether the source *src* contains the docstring *doc*. 

1051 

1052 This is is helper function to skip displaying the docstring if the 

1053 source already contains it, avoiding repetition of information. 

1054 """ 

1055 try: 

1056 (def_node,) = ast.parse(dedent(src)).body 

1057 return ast.get_docstring(def_node) == doc # type: ignore[arg-type] 

1058 except Exception: 

1059 # The source can become invalid or even non-existent (because it 

1060 # is re-fetched from the source file) so the above code fail in 

1061 # arbitrary ways. 

1062 return False 

1063 

1064 def psearch(self,pattern,ns_table,ns_search=[], 

1065 ignore_case=False,show_all=False, *, list_types=False): 

1066 """Search namespaces with wildcards for objects. 

1067 

1068 Arguments: 

1069 

1070 - pattern: string containing shell-like wildcards to use in namespace 

1071 searches and optionally a type specification to narrow the search to 

1072 objects of that type. 

1073 

1074 - ns_table: dict of name->namespaces for search. 

1075 

1076 Optional arguments: 

1077 

1078 - ns_search: list of namespace names to include in search. 

1079 

1080 - ignore_case(False): make the search case-insensitive. 

1081 

1082 - show_all(False): show all names, including those starting with 

1083 underscores. 

1084 

1085 - list_types(False): list all available object types for object matching. 

1086 """ 

1087 #print 'ps pattern:<%r>' % pattern # dbg 

1088 

1089 # defaults 

1090 type_pattern = 'all' 

1091 filter = '' 

1092 

1093 # list all object types 

1094 if list_types: 

1095 page.page('\n'.join(sorted(typestr2type))) 

1096 return 

1097 

1098 cmds = pattern.split() 

1099 len_cmds = len(cmds) 

1100 if len_cmds == 1: 

1101 # Only filter pattern given 

1102 filter = cmds[0] 

1103 elif len_cmds == 2: 

1104 # Both filter and type specified 

1105 filter,type_pattern = cmds 

1106 else: 

1107 raise ValueError('invalid argument string for psearch: <%s>' % 

1108 pattern) 

1109 

1110 # filter search namespaces 

1111 for name in ns_search: 

1112 if name not in ns_table: 

1113 raise ValueError('invalid namespace <%s>. Valid names: %s' % 

1114 (name,ns_table.keys())) 

1115 

1116 #print 'type_pattern:',type_pattern # dbg 

1117 search_result, namespaces_seen = set(), set() 

1118 for ns_name in ns_search: 

1119 ns = ns_table[ns_name] 

1120 # Normally, locals and globals are the same, so we just check one. 

1121 if id(ns) in namespaces_seen: 

1122 continue 

1123 namespaces_seen.add(id(ns)) 

1124 tmp_res = list_namespace(ns, type_pattern, filter, 

1125 ignore_case=ignore_case, show_all=show_all) 

1126 search_result.update(tmp_res) 

1127 

1128 page.page('\n'.join(sorted(search_result))) 

1129 

1130 

1131def _render_signature(obj_signature, obj_name) -> str: 

1132 """ 

1133 This was mostly taken from inspect.Signature.__str__. 

1134 Look there for the comments. 

1135 The only change is to add linebreaks when this gets too long. 

1136 """ 

1137 result = [] 

1138 pos_only = False 

1139 kw_only = True 

1140 for param in obj_signature.parameters.values(): 

1141 if param.kind == inspect.Parameter.POSITIONAL_ONLY: 

1142 pos_only = True 

1143 elif pos_only: 

1144 result.append('/') 

1145 pos_only = False 

1146 

1147 if param.kind == inspect.Parameter.VAR_POSITIONAL: 

1148 kw_only = False 

1149 elif param.kind == inspect.Parameter.KEYWORD_ONLY and kw_only: 

1150 result.append('*') 

1151 kw_only = False 

1152 

1153 result.append(str(param)) 

1154 

1155 if pos_only: 

1156 result.append('/') 

1157 

1158 # add up name, parameters, braces (2), and commas 

1159 if len(obj_name) + sum(len(r) + 2 for r in result) > 75: 

1160 # This doesn’t fit behind “Signature: ” in an inspect window. 

1161 rendered = '{}(\n{})'.format(obj_name, ''.join( 

1162 ' {},\n'.format(r) for r in result) 

1163 ) 

1164 else: 

1165 rendered = '{}({})'.format(obj_name, ', '.join(result)) 

1166 

1167 if obj_signature.return_annotation is not inspect._empty: 

1168 anno = inspect.formatannotation(obj_signature.return_annotation) 

1169 rendered += ' -> {}'.format(anno) 

1170 

1171 return rendered