##// END OF EJS Templates
Allow to dispatch getting documentation on objects...
Matthias Bussonnier -
Show More
@@ -1,3898 +1,3907
1 1 # -*- coding: utf-8 -*-
2 2 """Main IPython class."""
3 3
4 4 #-----------------------------------------------------------------------------
5 5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 7 # Copyright (C) 2008-2011 The IPython Development Team
8 8 #
9 9 # Distributed under the terms of the BSD License. The full license is in
10 10 # the file COPYING, distributed as part of this software.
11 11 #-----------------------------------------------------------------------------
12 12
13 13
14 14 import abc
15 15 import ast
16 16 import atexit
17 17 import bdb
18 18 import builtins as builtin_mod
19 19 import functools
20 20 import inspect
21 21 import os
22 22 import re
23 23 import runpy
24 24 import subprocess
25 25 import sys
26 26 import tempfile
27 27 import traceback
28 28 import types
29 29 import warnings
30 30 from ast import stmt
31 31 from io import open as io_open
32 32 from logging import error
33 33 from pathlib import Path
34 34 from typing import Callable
35 35 from typing import List as ListType, Dict as DictType, Any as AnyType
36 36 from typing import Optional, Sequence, Tuple
37 37 from warnings import warn
38 38
39 39 from pickleshare import PickleShareDB
40 40 from tempfile import TemporaryDirectory
41 41 from traitlets import (
42 42 Any,
43 43 Bool,
44 44 CaselessStrEnum,
45 45 Dict,
46 46 Enum,
47 47 Instance,
48 48 Integer,
49 49 List,
50 50 Type,
51 51 Unicode,
52 52 default,
53 53 observe,
54 54 validate,
55 55 )
56 56 from traitlets.config.configurable import SingletonConfigurable
57 57 from traitlets.utils.importstring import import_item
58 58
59 59 import IPython.core.hooks
60 60 from IPython.core import magic, oinspect, page, prefilter, ultratb
61 61 from IPython.core.alias import Alias, AliasManager
62 62 from IPython.core.autocall import ExitAutocall
63 63 from IPython.core.builtin_trap import BuiltinTrap
64 64 from IPython.core.compilerop import CachingCompiler
65 65 from IPython.core.debugger import InterruptiblePdb
66 66 from IPython.core.display_trap import DisplayTrap
67 67 from IPython.core.displayhook import DisplayHook
68 68 from IPython.core.displaypub import DisplayPublisher
69 69 from IPython.core.error import InputRejected, UsageError
70 70 from IPython.core.events import EventManager, available_events
71 71 from IPython.core.extensions import ExtensionManager
72 72 from IPython.core.formatters import DisplayFormatter
73 73 from IPython.core.history import HistoryManager
74 74 from IPython.core.inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
75 75 from IPython.core.logger import Logger
76 76 from IPython.core.macro import Macro
77 77 from IPython.core.payload import PayloadManager
78 78 from IPython.core.prefilter import PrefilterManager
79 79 from IPython.core.profiledir import ProfileDir
80 80 from IPython.core.usage import default_banner
81 81 from IPython.display import display
82 82 from IPython.paths import get_ipython_dir
83 83 from IPython.testing.skipdoctest import skip_doctest
84 84 from IPython.utils import PyColorize, io, openpy, py3compat
85 85 from IPython.utils.decorators import undoc
86 86 from IPython.utils.io import ask_yes_no
87 87 from IPython.utils.ipstruct import Struct
88 88 from IPython.utils.path import ensure_dir_exists, get_home_dir, get_py_filename
89 89 from IPython.utils.process import getoutput, system
90 90 from IPython.utils.strdispatch import StrDispatch
91 91 from IPython.utils.syspathcontext import prepended_to_syspath
92 92 from IPython.utils.text import DollarFormatter, LSString, SList, format_screen
93 93 from IPython.core.oinspect import OInfo
94 94
95 95
96 96 sphinxify: Optional[Callable]
97 97
98 98 try:
99 99 import docrepr.sphinxify as sphx
100 100
101 101 def sphinxify(oinfo):
102 102 wrapped_docstring = sphx.wrap_main_docstring(oinfo)
103 103
104 104 def sphinxify_docstring(docstring):
105 105 with TemporaryDirectory() as dirname:
106 106 return {
107 107 "text/html": sphx.sphinxify(wrapped_docstring, dirname),
108 108 "text/plain": docstring,
109 109 }
110 110
111 111 return sphinxify_docstring
112 112 except ImportError:
113 113 sphinxify = None
114 114
115 115
116 116 class ProvisionalWarning(DeprecationWarning):
117 117 """
118 118 Warning class for unstable features
119 119 """
120 120 pass
121 121
122 122 from ast import Module
123 123
124 124 _assign_nodes = (ast.AugAssign, ast.AnnAssign, ast.Assign)
125 125 _single_targets_nodes = (ast.AugAssign, ast.AnnAssign)
126 126
127 127 #-----------------------------------------------------------------------------
128 128 # Await Helpers
129 129 #-----------------------------------------------------------------------------
130 130
131 131 # we still need to run things using the asyncio eventloop, but there is no
132 132 # async integration
133 133 from .async_helpers import (
134 134 _asyncio_runner,
135 135 _curio_runner,
136 136 _pseudo_sync_runner,
137 137 _should_be_async,
138 138 _trio_runner,
139 139 )
140 140
141 141 #-----------------------------------------------------------------------------
142 142 # Globals
143 143 #-----------------------------------------------------------------------------
144 144
145 145 # compiled regexps for autoindent management
146 146 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
147 147
148 148 #-----------------------------------------------------------------------------
149 149 # Utilities
150 150 #-----------------------------------------------------------------------------
151 151
152 152
153 153 def is_integer_string(s: str):
154 154 """
155 155 Variant of "str.isnumeric()" that allow negative values and other ints.
156 156 """
157 157 try:
158 158 int(s)
159 159 return True
160 160 except ValueError:
161 161 return False
162 162 raise ValueError("Unexpected error")
163 163
164 164
165 165 @undoc
166 166 def softspace(file, newvalue):
167 167 """Copied from code.py, to remove the dependency"""
168 168
169 169 oldvalue = 0
170 170 try:
171 171 oldvalue = file.softspace
172 172 except AttributeError:
173 173 pass
174 174 try:
175 175 file.softspace = newvalue
176 176 except (AttributeError, TypeError):
177 177 # "attribute-less object" or "read-only attributes"
178 178 pass
179 179 return oldvalue
180 180
181 181 @undoc
182 182 def no_op(*a, **kw):
183 183 pass
184 184
185 185
186 186 class SpaceInInput(Exception): pass
187 187
188 188
189 189 class SeparateUnicode(Unicode):
190 190 r"""A Unicode subclass to validate separate_in, separate_out, etc.
191 191
192 192 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.
193 193 """
194 194
195 195 def validate(self, obj, value):
196 196 if value == '0': value = ''
197 197 value = value.replace('\\n','\n')
198 198 return super(SeparateUnicode, self).validate(obj, value)
199 199
200 200
201 201 @undoc
202 202 class DummyMod(object):
203 203 """A dummy module used for IPython's interactive module when
204 204 a namespace must be assigned to the module's __dict__."""
205 205 __spec__ = None
206 206
207 207
208 208 class ExecutionInfo(object):
209 209 """The arguments used for a call to :meth:`InteractiveShell.run_cell`
210 210
211 211 Stores information about what is going to happen.
212 212 """
213 213 raw_cell = None
214 214 store_history = False
215 215 silent = False
216 216 shell_futures = True
217 217 cell_id = None
218 218
219 219 def __init__(self, raw_cell, store_history, silent, shell_futures, cell_id):
220 220 self.raw_cell = raw_cell
221 221 self.store_history = store_history
222 222 self.silent = silent
223 223 self.shell_futures = shell_futures
224 224 self.cell_id = cell_id
225 225
226 226 def __repr__(self):
227 227 name = self.__class__.__qualname__
228 228 raw_cell = (
229 229 (self.raw_cell[:50] + "..") if len(self.raw_cell) > 50 else self.raw_cell
230 230 )
231 231 return (
232 232 '<%s object at %x, raw_cell="%s" store_history=%s silent=%s shell_futures=%s cell_id=%s>'
233 233 % (
234 234 name,
235 235 id(self),
236 236 raw_cell,
237 237 self.store_history,
238 238 self.silent,
239 239 self.shell_futures,
240 240 self.cell_id,
241 241 )
242 242 )
243 243
244 244
245 245 class ExecutionResult(object):
246 246 """The result of a call to :meth:`InteractiveShell.run_cell`
247 247
248 248 Stores information about what took place.
249 249 """
250 250 execution_count = None
251 251 error_before_exec = None
252 252 error_in_exec: Optional[BaseException] = None
253 253 info = None
254 254 result = None
255 255
256 256 def __init__(self, info):
257 257 self.info = info
258 258
259 259 @property
260 260 def success(self):
261 261 return (self.error_before_exec is None) and (self.error_in_exec is None)
262 262
263 263 def raise_error(self):
264 264 """Reraises error if `success` is `False`, otherwise does nothing"""
265 265 if self.error_before_exec is not None:
266 266 raise self.error_before_exec
267 267 if self.error_in_exec is not None:
268 268 raise self.error_in_exec
269 269
270 270 def __repr__(self):
271 271 name = self.__class__.__qualname__
272 272 return '<%s object at %x, execution_count=%s error_before_exec=%s error_in_exec=%s info=%s result=%s>' %\
273 273 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))
274 274
275 275 @functools.wraps(io_open)
276 276 def _modified_open(file, *args, **kwargs):
277 277 if file in {0, 1, 2}:
278 278 raise ValueError(
279 279 f"IPython won't let you open fd={file} by default "
280 280 "as it is likely to crash IPython. If you know what you are doing, "
281 281 "you can use builtins' open."
282 282 )
283 283
284 284 return io_open(file, *args, **kwargs)
285 285
286 286 class InteractiveShell(SingletonConfigurable):
287 287 """An enhanced, interactive shell for Python."""
288 288
289 289 _instance = None
290 290
291 291 ast_transformers = List([], help=
292 292 """
293 293 A list of ast.NodeTransformer subclass instances, which will be applied
294 294 to user input before code is run.
295 295 """
296 296 ).tag(config=True)
297 297
298 298 autocall = Enum((0,1,2), default_value=0, help=
299 299 """
300 300 Make IPython automatically call any callable object even if you didn't
301 301 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
302 302 automatically. The value can be '0' to disable the feature, '1' for
303 303 'smart' autocall, where it is not applied if there are no more
304 304 arguments on the line, and '2' for 'full' autocall, where all callable
305 305 objects are automatically called (even if no arguments are present).
306 306 """
307 307 ).tag(config=True)
308 308
309 309 autoindent = Bool(True, help=
310 310 """
311 311 Autoindent IPython code entered interactively.
312 312 """
313 313 ).tag(config=True)
314 314
315 315 autoawait = Bool(True, help=
316 316 """
317 317 Automatically run await statement in the top level repl.
318 318 """
319 319 ).tag(config=True)
320 320
321 321 loop_runner_map ={
322 322 'asyncio':(_asyncio_runner, True),
323 323 'curio':(_curio_runner, True),
324 324 'trio':(_trio_runner, True),
325 325 'sync': (_pseudo_sync_runner, False)
326 326 }
327 327
328 328 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",
329 329 allow_none=True,
330 330 help="""Select the loop runner that will be used to execute top-level asynchronous code"""
331 331 ).tag(config=True)
332 332
333 333 @default('loop_runner')
334 334 def _default_loop_runner(self):
335 335 return import_item("IPython.core.interactiveshell._asyncio_runner")
336 336
337 337 @validate('loop_runner')
338 338 def _import_runner(self, proposal):
339 339 if isinstance(proposal.value, str):
340 340 if proposal.value in self.loop_runner_map:
341 341 runner, autoawait = self.loop_runner_map[proposal.value]
342 342 self.autoawait = autoawait
343 343 return runner
344 344 runner = import_item(proposal.value)
345 345 if not callable(runner):
346 346 raise ValueError('loop_runner must be callable')
347 347 return runner
348 348 if not callable(proposal.value):
349 349 raise ValueError('loop_runner must be callable')
350 350 return proposal.value
351 351
352 352 automagic = Bool(True, help=
353 353 """
354 354 Enable magic commands to be called without the leading %.
355 355 """
356 356 ).tag(config=True)
357 357
358 358 banner1 = Unicode(default_banner,
359 359 help="""The part of the banner to be printed before the profile"""
360 360 ).tag(config=True)
361 361 banner2 = Unicode('',
362 362 help="""The part of the banner to be printed after the profile"""
363 363 ).tag(config=True)
364 364
365 365 cache_size = Integer(1000, help=
366 366 """
367 367 Set the size of the output cache. The default is 1000, you can
368 368 change it permanently in your config file. Setting it to 0 completely
369 369 disables the caching system, and the minimum value accepted is 3 (if
370 370 you provide a value less than 3, it is reset to 0 and a warning is
371 371 issued). This limit is defined because otherwise you'll spend more
372 372 time re-flushing a too small cache than working
373 373 """
374 374 ).tag(config=True)
375 375 color_info = Bool(True, help=
376 376 """
377 377 Use colors for displaying information about objects. Because this
378 378 information is passed through a pager (like 'less'), and some pagers
379 379 get confused with color codes, this capability can be turned off.
380 380 """
381 381 ).tag(config=True)
382 382 colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'),
383 383 default_value='Neutral',
384 384 help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)."
385 385 ).tag(config=True)
386 386 debug = Bool(False).tag(config=True)
387 387 disable_failing_post_execute = Bool(False,
388 388 help="Don't call post-execute functions that have failed in the past."
389 389 ).tag(config=True)
390 390 display_formatter = Instance(DisplayFormatter, allow_none=True)
391 391 displayhook_class = Type(DisplayHook)
392 392 display_pub_class = Type(DisplayPublisher)
393 393 compiler_class = Type(CachingCompiler)
394 394 inspector_class = Type(
395 395 oinspect.Inspector, help="Class to use to instantiate the shell inspector"
396 396 ).tag(config=True)
397 397
398 398 sphinxify_docstring = Bool(False, help=
399 399 """
400 400 Enables rich html representation of docstrings. (This requires the
401 401 docrepr module).
402 402 """).tag(config=True)
403 403
404 404 @observe("sphinxify_docstring")
405 405 def _sphinxify_docstring_changed(self, change):
406 406 if change['new']:
407 407 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)
408 408
409 409 enable_html_pager = Bool(False, help=
410 410 """
411 411 (Provisional API) enables html representation in mime bundles sent
412 412 to pagers.
413 413 """).tag(config=True)
414 414
415 415 @observe("enable_html_pager")
416 416 def _enable_html_pager_changed(self, change):
417 417 if change['new']:
418 418 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)
419 419
420 420 data_pub_class = None
421 421
422 422 exit_now = Bool(False)
423 423 exiter = Instance(ExitAutocall)
424 424 @default('exiter')
425 425 def _exiter_default(self):
426 426 return ExitAutocall(self)
427 427 # Monotonically increasing execution counter
428 428 execution_count = Integer(1)
429 429 filename = Unicode("<ipython console>")
430 430 ipython_dir= Unicode('').tag(config=True) # Set to get_ipython_dir() in __init__
431 431
432 432 # Used to transform cells before running them, and check whether code is complete
433 433 input_transformer_manager = Instance('IPython.core.inputtransformer2.TransformerManager',
434 434 ())
435 435
436 436 @property
437 437 def input_transformers_cleanup(self):
438 438 return self.input_transformer_manager.cleanup_transforms
439 439
440 440 input_transformers_post = List([],
441 441 help="A list of string input transformers, to be applied after IPython's "
442 442 "own input transformations."
443 443 )
444 444
445 445 @property
446 446 def input_splitter(self):
447 447 """Make this available for backward compatibility (pre-7.0 release) with existing code.
448 448
449 449 For example, ipykernel ipykernel currently uses
450 450 `shell.input_splitter.check_complete`
451 451 """
452 452 from warnings import warn
453 453 warn("`input_splitter` is deprecated since IPython 7.0, prefer `input_transformer_manager`.",
454 454 DeprecationWarning, stacklevel=2
455 455 )
456 456 return self.input_transformer_manager
457 457
458 458 logstart = Bool(False, help=
459 459 """
460 460 Start logging to the default log file in overwrite mode.
461 461 Use `logappend` to specify a log file to **append** logs to.
462 462 """
463 463 ).tag(config=True)
464 464 logfile = Unicode('', help=
465 465 """
466 466 The name of the logfile to use.
467 467 """
468 468 ).tag(config=True)
469 469 logappend = Unicode('', help=
470 470 """
471 471 Start logging to the given file in append mode.
472 472 Use `logfile` to specify a log file to **overwrite** logs to.
473 473 """
474 474 ).tag(config=True)
475 475 object_info_string_level = Enum((0,1,2), default_value=0,
476 476 ).tag(config=True)
477 477 pdb = Bool(False, help=
478 478 """
479 479 Automatically call the pdb debugger after every exception.
480 480 """
481 481 ).tag(config=True)
482 482 display_page = Bool(False,
483 483 help="""If True, anything that would be passed to the pager
484 484 will be displayed as regular output instead."""
485 485 ).tag(config=True)
486 486
487 487
488 488 show_rewritten_input = Bool(True,
489 489 help="Show rewritten input, e.g. for autocall."
490 490 ).tag(config=True)
491 491
492 492 quiet = Bool(False).tag(config=True)
493 493
494 494 history_length = Integer(10000,
495 495 help='Total length of command history'
496 496 ).tag(config=True)
497 497
498 498 history_load_length = Integer(1000, help=
499 499 """
500 500 The number of saved history entries to be loaded
501 501 into the history buffer at startup.
502 502 """
503 503 ).tag(config=True)
504 504
505 505 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],
506 506 default_value='last_expr',
507 507 help="""
508 508 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying
509 509 which nodes should be run interactively (displaying output from expressions).
510 510 """
511 511 ).tag(config=True)
512 512
513 513 warn_venv = Bool(
514 514 True,
515 515 help="Warn if running in a virtual environment with no IPython installed (so IPython from the global environment is used).",
516 516 ).tag(config=True)
517 517
518 518 # TODO: this part of prompt management should be moved to the frontends.
519 519 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
520 520 separate_in = SeparateUnicode('\n').tag(config=True)
521 521 separate_out = SeparateUnicode('').tag(config=True)
522 522 separate_out2 = SeparateUnicode('').tag(config=True)
523 523 wildcards_case_sensitive = Bool(True).tag(config=True)
524 524 xmode = CaselessStrEnum(('Context', 'Plain', 'Verbose', 'Minimal'),
525 525 default_value='Context',
526 526 help="Switch modes for the IPython exception handlers."
527 527 ).tag(config=True)
528 528
529 529 # Subcomponents of InteractiveShell
530 530 alias_manager = Instance('IPython.core.alias.AliasManager', allow_none=True)
531 531 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager', allow_none=True)
532 532 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap', allow_none=True)
533 533 display_trap = Instance('IPython.core.display_trap.DisplayTrap', allow_none=True)
534 534 extension_manager = Instance('IPython.core.extensions.ExtensionManager', allow_none=True)
535 535 payload_manager = Instance('IPython.core.payload.PayloadManager', allow_none=True)
536 536 history_manager = Instance('IPython.core.history.HistoryAccessorBase', allow_none=True)
537 537 magics_manager = Instance('IPython.core.magic.MagicsManager', allow_none=True)
538 538
539 539 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)
540 540 @property
541 541 def profile(self):
542 542 if self.profile_dir is not None:
543 543 name = os.path.basename(self.profile_dir.location)
544 544 return name.replace('profile_','')
545 545
546 546
547 547 # Private interface
548 548 _post_execute = Dict()
549 549
550 550 # Tracks any GUI loop loaded for pylab
551 551 pylab_gui_select = None
552 552
553 553 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')
554 554
555 555 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)
556 556
557 557 def __init__(self, ipython_dir=None, profile_dir=None,
558 558 user_module=None, user_ns=None,
559 559 custom_exceptions=((), None), **kwargs):
560 560 # This is where traits with a config_key argument are updated
561 561 # from the values on config.
562 562 super(InteractiveShell, self).__init__(**kwargs)
563 563 if 'PromptManager' in self.config:
564 564 warn('As of IPython 5.0 `PromptManager` config will have no effect'
565 565 ' and has been replaced by TerminalInteractiveShell.prompts_class')
566 566 self.configurables = [self]
567 567
568 568 # These are relatively independent and stateless
569 569 self.init_ipython_dir(ipython_dir)
570 570 self.init_profile_dir(profile_dir)
571 571 self.init_instance_attrs()
572 572 self.init_environment()
573 573
574 574 # Check if we're in a virtualenv, and set up sys.path.
575 575 self.init_virtualenv()
576 576
577 577 # Create namespaces (user_ns, user_global_ns, etc.)
578 578 self.init_create_namespaces(user_module, user_ns)
579 579 # This has to be done after init_create_namespaces because it uses
580 580 # something in self.user_ns, but before init_sys_modules, which
581 581 # is the first thing to modify sys.
582 582 # TODO: When we override sys.stdout and sys.stderr before this class
583 583 # is created, we are saving the overridden ones here. Not sure if this
584 584 # is what we want to do.
585 585 self.save_sys_module_state()
586 586 self.init_sys_modules()
587 587
588 588 # While we're trying to have each part of the code directly access what
589 589 # it needs without keeping redundant references to objects, we have too
590 590 # much legacy code that expects ip.db to exist.
591 591 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
592 592
593 593 self.init_history()
594 594 self.init_encoding()
595 595 self.init_prefilter()
596 596
597 597 self.init_syntax_highlighting()
598 598 self.init_hooks()
599 599 self.init_events()
600 600 self.init_pushd_popd_magic()
601 601 self.init_user_ns()
602 602 self.init_logger()
603 603 self.init_builtins()
604 604
605 605 # The following was in post_config_initialization
606 606 self.init_inspector()
607 607 self.raw_input_original = input
608 608 self.init_completer()
609 609 # TODO: init_io() needs to happen before init_traceback handlers
610 610 # because the traceback handlers hardcode the stdout/stderr streams.
611 611 # This logic in in debugger.Pdb and should eventually be changed.
612 612 self.init_io()
613 613 self.init_traceback_handlers(custom_exceptions)
614 614 self.init_prompts()
615 615 self.init_display_formatter()
616 616 self.init_display_pub()
617 617 self.init_data_pub()
618 618 self.init_displayhook()
619 619 self.init_magics()
620 620 self.init_alias()
621 621 self.init_logstart()
622 622 self.init_pdb()
623 623 self.init_extension_manager()
624 624 self.init_payload()
625 625 self.events.trigger('shell_initialized', self)
626 626 atexit.register(self.atexit_operations)
627 627
628 628 # The trio runner is used for running Trio in the foreground thread. It
629 629 # is different from `_trio_runner(async_fn)` in `async_helpers.py`
630 630 # which calls `trio.run()` for every cell. This runner runs all cells
631 631 # inside a single Trio event loop. If used, it is set from
632 632 # `ipykernel.kernelapp`.
633 633 self.trio_runner = None
634 634
635 635 def get_ipython(self):
636 636 """Return the currently running IPython instance."""
637 637 return self
638 638
639 639 #-------------------------------------------------------------------------
640 640 # Trait changed handlers
641 641 #-------------------------------------------------------------------------
642 642 @observe('ipython_dir')
643 643 def _ipython_dir_changed(self, change):
644 644 ensure_dir_exists(change['new'])
645 645
646 646 def set_autoindent(self,value=None):
647 647 """Set the autoindent flag.
648 648
649 649 If called with no arguments, it acts as a toggle."""
650 650 if value is None:
651 651 self.autoindent = not self.autoindent
652 652 else:
653 653 self.autoindent = value
654 654
655 655 def set_trio_runner(self, tr):
656 656 self.trio_runner = tr
657 657
658 658 #-------------------------------------------------------------------------
659 659 # init_* methods called by __init__
660 660 #-------------------------------------------------------------------------
661 661
662 662 def init_ipython_dir(self, ipython_dir):
663 663 if ipython_dir is not None:
664 664 self.ipython_dir = ipython_dir
665 665 return
666 666
667 667 self.ipython_dir = get_ipython_dir()
668 668
669 669 def init_profile_dir(self, profile_dir):
670 670 if profile_dir is not None:
671 671 self.profile_dir = profile_dir
672 672 return
673 673 self.profile_dir = ProfileDir.create_profile_dir_by_name(
674 674 self.ipython_dir, "default"
675 675 )
676 676
677 677 def init_instance_attrs(self):
678 678 self.more = False
679 679
680 680 # command compiler
681 681 self.compile = self.compiler_class()
682 682
683 683 # Make an empty namespace, which extension writers can rely on both
684 684 # existing and NEVER being used by ipython itself. This gives them a
685 685 # convenient location for storing additional information and state
686 686 # their extensions may require, without fear of collisions with other
687 687 # ipython names that may develop later.
688 688 self.meta = Struct()
689 689
690 690 # Temporary files used for various purposes. Deleted at exit.
691 691 # The files here are stored with Path from Pathlib
692 692 self.tempfiles = []
693 693 self.tempdirs = []
694 694
695 695 # keep track of where we started running (mainly for crash post-mortem)
696 696 # This is not being used anywhere currently.
697 697 self.starting_dir = os.getcwd()
698 698
699 699 # Indentation management
700 700 self.indent_current_nsp = 0
701 701
702 702 # Dict to track post-execution functions that have been registered
703 703 self._post_execute = {}
704 704
705 705 def init_environment(self):
706 706 """Any changes we need to make to the user's environment."""
707 707 pass
708 708
709 709 def init_encoding(self):
710 710 # Get system encoding at startup time. Certain terminals (like Emacs
711 711 # under Win32 have it set to None, and we need to have a known valid
712 712 # encoding to use in the raw_input() method
713 713 try:
714 714 self.stdin_encoding = sys.stdin.encoding or 'ascii'
715 715 except AttributeError:
716 716 self.stdin_encoding = 'ascii'
717 717
718 718
719 719 @observe('colors')
720 720 def init_syntax_highlighting(self, changes=None):
721 721 # Python source parser/formatter for syntax highlighting
722 722 pyformat = PyColorize.Parser(style=self.colors, parent=self).format
723 723 self.pycolorize = lambda src: pyformat(src,'str')
724 724
725 725 def refresh_style(self):
726 726 # No-op here, used in subclass
727 727 pass
728 728
729 729 def init_pushd_popd_magic(self):
730 730 # for pushd/popd management
731 731 self.home_dir = get_home_dir()
732 732
733 733 self.dir_stack = []
734 734
735 735 def init_logger(self):
736 736 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
737 737 logmode='rotate')
738 738
739 739 def init_logstart(self):
740 740 """Initialize logging in case it was requested at the command line.
741 741 """
742 742 if self.logappend:
743 743 self.magic('logstart %s append' % self.logappend)
744 744 elif self.logfile:
745 745 self.magic('logstart %s' % self.logfile)
746 746 elif self.logstart:
747 747 self.magic('logstart')
748 748
749 749
750 750 def init_builtins(self):
751 751 # A single, static flag that we set to True. Its presence indicates
752 752 # that an IPython shell has been created, and we make no attempts at
753 753 # removing on exit or representing the existence of more than one
754 754 # IPython at a time.
755 755 builtin_mod.__dict__['__IPYTHON__'] = True
756 756 builtin_mod.__dict__['display'] = display
757 757
758 758 self.builtin_trap = BuiltinTrap(shell=self)
759 759
760 760 @observe('colors')
761 761 def init_inspector(self, changes=None):
762 762 # Object inspector
763 763 self.inspector = self.inspector_class(
764 764 oinspect.InspectColors,
765 765 PyColorize.ANSICodeColors,
766 766 self.colors,
767 767 self.object_info_string_level,
768 768 )
769 769
770 770 def init_io(self):
771 771 # implemented in subclasses, TerminalInteractiveShell does call
772 772 # colorama.init().
773 773 pass
774 774
775 775 def init_prompts(self):
776 776 # Set system prompts, so that scripts can decide if they are running
777 777 # interactively.
778 778 sys.ps1 = 'In : '
779 779 sys.ps2 = '...: '
780 780 sys.ps3 = 'Out: '
781 781
782 782 def init_display_formatter(self):
783 783 self.display_formatter = DisplayFormatter(parent=self)
784 784 self.configurables.append(self.display_formatter)
785 785
786 786 def init_display_pub(self):
787 787 self.display_pub = self.display_pub_class(parent=self, shell=self)
788 788 self.configurables.append(self.display_pub)
789 789
790 790 def init_data_pub(self):
791 791 if not self.data_pub_class:
792 792 self.data_pub = None
793 793 return
794 794 self.data_pub = self.data_pub_class(parent=self)
795 795 self.configurables.append(self.data_pub)
796 796
797 797 def init_displayhook(self):
798 798 # Initialize displayhook, set in/out prompts and printing system
799 799 self.displayhook = self.displayhook_class(
800 800 parent=self,
801 801 shell=self,
802 802 cache_size=self.cache_size,
803 803 )
804 804 self.configurables.append(self.displayhook)
805 805 # This is a context manager that installs/revmoes the displayhook at
806 806 # the appropriate time.
807 807 self.display_trap = DisplayTrap(hook=self.displayhook)
808 808
809 809 @staticmethod
810 810 def get_path_links(p: Path):
811 811 """Gets path links including all symlinks
812 812
813 813 Examples
814 814 --------
815 815 In [1]: from IPython.core.interactiveshell import InteractiveShell
816 816
817 817 In [2]: import sys, pathlib
818 818
819 819 In [3]: paths = InteractiveShell.get_path_links(pathlib.Path(sys.executable))
820 820
821 821 In [4]: len(paths) == len(set(paths))
822 822 Out[4]: True
823 823
824 824 In [5]: bool(paths)
825 825 Out[5]: True
826 826 """
827 827 paths = [p]
828 828 while p.is_symlink():
829 829 new_path = Path(os.readlink(p))
830 830 if not new_path.is_absolute():
831 831 new_path = p.parent / new_path
832 832 p = new_path
833 833 paths.append(p)
834 834 return paths
835 835
836 836 def init_virtualenv(self):
837 837 """Add the current virtualenv to sys.path so the user can import modules from it.
838 838 This isn't perfect: it doesn't use the Python interpreter with which the
839 839 virtualenv was built, and it ignores the --no-site-packages option. A
840 840 warning will appear suggesting the user installs IPython in the
841 841 virtualenv, but for many cases, it probably works well enough.
842 842
843 843 Adapted from code snippets online.
844 844
845 845 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
846 846 """
847 847 if 'VIRTUAL_ENV' not in os.environ:
848 848 # Not in a virtualenv
849 849 return
850 850 elif os.environ["VIRTUAL_ENV"] == "":
851 851 warn("Virtual env path set to '', please check if this is intended.")
852 852 return
853 853
854 854 p = Path(sys.executable)
855 855 p_venv = Path(os.environ["VIRTUAL_ENV"])
856 856
857 857 # fallback venv detection:
858 858 # stdlib venv may symlink sys.executable, so we can't use realpath.
859 859 # but others can symlink *to* the venv Python, so we can't just use sys.executable.
860 860 # So we just check every item in the symlink tree (generally <= 3)
861 861 paths = self.get_path_links(p)
862 862
863 863 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible
864 864 if p_venv.parts[1] == "cygdrive":
865 865 drive_name = p_venv.parts[2]
866 866 p_venv = (drive_name + ":/") / Path(*p_venv.parts[3:])
867 867
868 868 if any(p_venv == p.parents[1] for p in paths):
869 869 # Our exe is inside or has access to the virtualenv, don't need to do anything.
870 870 return
871 871
872 872 if sys.platform == "win32":
873 873 virtual_env = str(Path(os.environ["VIRTUAL_ENV"], "Lib", "site-packages"))
874 874 else:
875 875 virtual_env_path = Path(
876 876 os.environ["VIRTUAL_ENV"], "lib", "python{}.{}", "site-packages"
877 877 )
878 878 p_ver = sys.version_info[:2]
879 879
880 880 # Predict version from py[thon]-x.x in the $VIRTUAL_ENV
881 881 re_m = re.search(r"\bpy(?:thon)?([23])\.(\d+)\b", os.environ["VIRTUAL_ENV"])
882 882 if re_m:
883 883 predicted_path = Path(str(virtual_env_path).format(*re_m.groups()))
884 884 if predicted_path.exists():
885 885 p_ver = re_m.groups()
886 886
887 887 virtual_env = str(virtual_env_path).format(*p_ver)
888 888 if self.warn_venv:
889 889 warn(
890 890 "Attempting to work in a virtualenv. If you encounter problems, "
891 891 "please install IPython inside the virtualenv."
892 892 )
893 893 import site
894 894 sys.path.insert(0, virtual_env)
895 895 site.addsitedir(virtual_env)
896 896
897 897 #-------------------------------------------------------------------------
898 898 # Things related to injections into the sys module
899 899 #-------------------------------------------------------------------------
900 900
901 901 def save_sys_module_state(self):
902 902 """Save the state of hooks in the sys module.
903 903
904 904 This has to be called after self.user_module is created.
905 905 """
906 906 self._orig_sys_module_state = {'stdin': sys.stdin,
907 907 'stdout': sys.stdout,
908 908 'stderr': sys.stderr,
909 909 'excepthook': sys.excepthook}
910 910 self._orig_sys_modules_main_name = self.user_module.__name__
911 911 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
912 912
913 913 def restore_sys_module_state(self):
914 914 """Restore the state of the sys module."""
915 915 try:
916 916 for k, v in self._orig_sys_module_state.items():
917 917 setattr(sys, k, v)
918 918 except AttributeError:
919 919 pass
920 920 # Reset what what done in self.init_sys_modules
921 921 if self._orig_sys_modules_main_mod is not None:
922 922 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
923 923
924 924 #-------------------------------------------------------------------------
925 925 # Things related to the banner
926 926 #-------------------------------------------------------------------------
927 927
928 928 @property
929 929 def banner(self):
930 930 banner = self.banner1
931 931 if self.profile and self.profile != 'default':
932 932 banner += '\nIPython profile: %s\n' % self.profile
933 933 if self.banner2:
934 934 banner += '\n' + self.banner2
935 935 return banner
936 936
937 937 def show_banner(self, banner=None):
938 938 if banner is None:
939 939 banner = self.banner
940 940 sys.stdout.write(banner)
941 941
942 942 #-------------------------------------------------------------------------
943 943 # Things related to hooks
944 944 #-------------------------------------------------------------------------
945 945
946 946 def init_hooks(self):
947 947 # hooks holds pointers used for user-side customizations
948 948 self.hooks = Struct()
949 949
950 950 self.strdispatchers = {}
951 951
952 952 # Set all default hooks, defined in the IPython.hooks module.
953 953 hooks = IPython.core.hooks
954 954 for hook_name in hooks.__all__:
955 955 # default hooks have priority 100, i.e. low; user hooks should have
956 956 # 0-100 priority
957 957 self.set_hook(hook_name, getattr(hooks, hook_name), 100)
958 958
959 959 if self.display_page:
960 960 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)
961 961
962 962 def set_hook(self, name, hook, priority=50, str_key=None, re_key=None):
963 963 """set_hook(name,hook) -> sets an internal IPython hook.
964 964
965 965 IPython exposes some of its internal API as user-modifiable hooks. By
966 966 adding your function to one of these hooks, you can modify IPython's
967 967 behavior to call at runtime your own routines."""
968 968
969 969 # At some point in the future, this should validate the hook before it
970 970 # accepts it. Probably at least check that the hook takes the number
971 971 # of args it's supposed to.
972 972
973 973 f = types.MethodType(hook,self)
974 974
975 975 # check if the hook is for strdispatcher first
976 976 if str_key is not None:
977 977 sdp = self.strdispatchers.get(name, StrDispatch())
978 978 sdp.add_s(str_key, f, priority )
979 979 self.strdispatchers[name] = sdp
980 980 return
981 981 if re_key is not None:
982 982 sdp = self.strdispatchers.get(name, StrDispatch())
983 983 sdp.add_re(re.compile(re_key), f, priority )
984 984 self.strdispatchers[name] = sdp
985 985 return
986 986
987 987 dp = getattr(self.hooks, name, None)
988 988 if name not in IPython.core.hooks.__all__:
989 989 print("Warning! Hook '%s' is not one of %s" % \
990 990 (name, IPython.core.hooks.__all__ ))
991 991
992 992 if name in IPython.core.hooks.deprecated:
993 993 alternative = IPython.core.hooks.deprecated[name]
994 994 raise ValueError(
995 995 "Hook {} has been deprecated since IPython 5.0. Use {} instead.".format(
996 996 name, alternative
997 997 )
998 998 )
999 999
1000 1000 if not dp:
1001 1001 dp = IPython.core.hooks.CommandChainDispatcher()
1002 1002
1003 1003 try:
1004 1004 dp.add(f,priority)
1005 1005 except AttributeError:
1006 1006 # it was not commandchain, plain old func - replace
1007 1007 dp = f
1008 1008
1009 1009 setattr(self.hooks,name, dp)
1010 1010
1011 1011 #-------------------------------------------------------------------------
1012 1012 # Things related to events
1013 1013 #-------------------------------------------------------------------------
1014 1014
1015 1015 def init_events(self):
1016 1016 self.events = EventManager(self, available_events)
1017 1017
1018 1018 self.events.register("pre_execute", self._clear_warning_registry)
1019 1019
1020 1020 def register_post_execute(self, func):
1021 1021 """DEPRECATED: Use ip.events.register('post_run_cell', func)
1022 1022
1023 1023 Register a function for calling after code execution.
1024 1024 """
1025 1025 raise ValueError(
1026 1026 "ip.register_post_execute is deprecated since IPython 1.0, use "
1027 1027 "ip.events.register('post_run_cell', func) instead."
1028 1028 )
1029 1029
1030 1030 def _clear_warning_registry(self):
1031 1031 # clear the warning registry, so that different code blocks with
1032 1032 # overlapping line number ranges don't cause spurious suppression of
1033 1033 # warnings (see gh-6611 for details)
1034 1034 if "__warningregistry__" in self.user_global_ns:
1035 1035 del self.user_global_ns["__warningregistry__"]
1036 1036
1037 1037 #-------------------------------------------------------------------------
1038 1038 # Things related to the "main" module
1039 1039 #-------------------------------------------------------------------------
1040 1040
1041 1041 def new_main_mod(self, filename, modname):
1042 1042 """Return a new 'main' module object for user code execution.
1043 1043
1044 1044 ``filename`` should be the path of the script which will be run in the
1045 1045 module. Requests with the same filename will get the same module, with
1046 1046 its namespace cleared.
1047 1047
1048 1048 ``modname`` should be the module name - normally either '__main__' or
1049 1049 the basename of the file without the extension.
1050 1050
1051 1051 When scripts are executed via %run, we must keep a reference to their
1052 1052 __main__ module around so that Python doesn't
1053 1053 clear it, rendering references to module globals useless.
1054 1054
1055 1055 This method keeps said reference in a private dict, keyed by the
1056 1056 absolute path of the script. This way, for multiple executions of the
1057 1057 same script we only keep one copy of the namespace (the last one),
1058 1058 thus preventing memory leaks from old references while allowing the
1059 1059 objects from the last execution to be accessible.
1060 1060 """
1061 1061 filename = os.path.abspath(filename)
1062 1062 try:
1063 1063 main_mod = self._main_mod_cache[filename]
1064 1064 except KeyError:
1065 1065 main_mod = self._main_mod_cache[filename] = types.ModuleType(
1066 1066 modname,
1067 1067 doc="Module created for script run in IPython")
1068 1068 else:
1069 1069 main_mod.__dict__.clear()
1070 1070 main_mod.__name__ = modname
1071 1071
1072 1072 main_mod.__file__ = filename
1073 1073 # It seems pydoc (and perhaps others) needs any module instance to
1074 1074 # implement a __nonzero__ method
1075 1075 main_mod.__nonzero__ = lambda : True
1076 1076
1077 1077 return main_mod
1078 1078
1079 1079 def clear_main_mod_cache(self):
1080 1080 """Clear the cache of main modules.
1081 1081
1082 1082 Mainly for use by utilities like %reset.
1083 1083
1084 1084 Examples
1085 1085 --------
1086 1086 In [15]: import IPython
1087 1087
1088 1088 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')
1089 1089
1090 1090 In [17]: len(_ip._main_mod_cache) > 0
1091 1091 Out[17]: True
1092 1092
1093 1093 In [18]: _ip.clear_main_mod_cache()
1094 1094
1095 1095 In [19]: len(_ip._main_mod_cache) == 0
1096 1096 Out[19]: True
1097 1097 """
1098 1098 self._main_mod_cache.clear()
1099 1099
1100 1100 #-------------------------------------------------------------------------
1101 1101 # Things related to debugging
1102 1102 #-------------------------------------------------------------------------
1103 1103
1104 1104 def init_pdb(self):
1105 1105 # Set calling of pdb on exceptions
1106 1106 # self.call_pdb is a property
1107 1107 self.call_pdb = self.pdb
1108 1108
1109 1109 def _get_call_pdb(self):
1110 1110 return self._call_pdb
1111 1111
1112 1112 def _set_call_pdb(self,val):
1113 1113
1114 1114 if val not in (0,1,False,True):
1115 1115 raise ValueError('new call_pdb value must be boolean')
1116 1116
1117 1117 # store value in instance
1118 1118 self._call_pdb = val
1119 1119
1120 1120 # notify the actual exception handlers
1121 1121 self.InteractiveTB.call_pdb = val
1122 1122
1123 1123 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1124 1124 'Control auto-activation of pdb at exceptions')
1125 1125
1126 1126 def debugger(self,force=False):
1127 1127 """Call the pdb debugger.
1128 1128
1129 1129 Keywords:
1130 1130
1131 1131 - force(False): by default, this routine checks the instance call_pdb
1132 1132 flag and does not actually invoke the debugger if the flag is false.
1133 1133 The 'force' option forces the debugger to activate even if the flag
1134 1134 is false.
1135 1135 """
1136 1136
1137 1137 if not (force or self.call_pdb):
1138 1138 return
1139 1139
1140 1140 if not hasattr(sys,'last_traceback'):
1141 1141 error('No traceback has been produced, nothing to debug.')
1142 1142 return
1143 1143
1144 1144 self.InteractiveTB.debugger(force=True)
1145 1145
1146 1146 #-------------------------------------------------------------------------
1147 1147 # Things related to IPython's various namespaces
1148 1148 #-------------------------------------------------------------------------
1149 1149 default_user_namespaces = True
1150 1150
1151 1151 def init_create_namespaces(self, user_module=None, user_ns=None):
1152 1152 # Create the namespace where the user will operate. user_ns is
1153 1153 # normally the only one used, and it is passed to the exec calls as
1154 1154 # the locals argument. But we do carry a user_global_ns namespace
1155 1155 # given as the exec 'globals' argument, This is useful in embedding
1156 1156 # situations where the ipython shell opens in a context where the
1157 1157 # distinction between locals and globals is meaningful. For
1158 1158 # non-embedded contexts, it is just the same object as the user_ns dict.
1159 1159
1160 1160 # FIXME. For some strange reason, __builtins__ is showing up at user
1161 1161 # level as a dict instead of a module. This is a manual fix, but I
1162 1162 # should really track down where the problem is coming from. Alex
1163 1163 # Schmolck reported this problem first.
1164 1164
1165 1165 # A useful post by Alex Martelli on this topic:
1166 1166 # Re: inconsistent value from __builtins__
1167 1167 # Von: Alex Martelli <aleaxit@yahoo.com>
1168 1168 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
1169 1169 # Gruppen: comp.lang.python
1170 1170
1171 1171 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
1172 1172 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
1173 1173 # > <type 'dict'>
1174 1174 # > >>> print type(__builtins__)
1175 1175 # > <type 'module'>
1176 1176 # > Is this difference in return value intentional?
1177 1177
1178 1178 # Well, it's documented that '__builtins__' can be either a dictionary
1179 1179 # or a module, and it's been that way for a long time. Whether it's
1180 1180 # intentional (or sensible), I don't know. In any case, the idea is
1181 1181 # that if you need to access the built-in namespace directly, you
1182 1182 # should start with "import __builtin__" (note, no 's') which will
1183 1183 # definitely give you a module. Yeah, it's somewhat confusing:-(.
1184 1184
1185 1185 # These routines return a properly built module and dict as needed by
1186 1186 # the rest of the code, and can also be used by extension writers to
1187 1187 # generate properly initialized namespaces.
1188 1188 if (user_ns is not None) or (user_module is not None):
1189 1189 self.default_user_namespaces = False
1190 1190 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
1191 1191
1192 1192 # A record of hidden variables we have added to the user namespace, so
1193 1193 # we can list later only variables defined in actual interactive use.
1194 1194 self.user_ns_hidden = {}
1195 1195
1196 1196 # Now that FakeModule produces a real module, we've run into a nasty
1197 1197 # problem: after script execution (via %run), the module where the user
1198 1198 # code ran is deleted. Now that this object is a true module (needed
1199 1199 # so doctest and other tools work correctly), the Python module
1200 1200 # teardown mechanism runs over it, and sets to None every variable
1201 1201 # present in that module. Top-level references to objects from the
1202 1202 # script survive, because the user_ns is updated with them. However,
1203 1203 # calling functions defined in the script that use other things from
1204 1204 # the script will fail, because the function's closure had references
1205 1205 # to the original objects, which are now all None. So we must protect
1206 1206 # these modules from deletion by keeping a cache.
1207 1207 #
1208 1208 # To avoid keeping stale modules around (we only need the one from the
1209 1209 # last run), we use a dict keyed with the full path to the script, so
1210 1210 # only the last version of the module is held in the cache. Note,
1211 1211 # however, that we must cache the module *namespace contents* (their
1212 1212 # __dict__). Because if we try to cache the actual modules, old ones
1213 1213 # (uncached) could be destroyed while still holding references (such as
1214 1214 # those held by GUI objects that tend to be long-lived)>
1215 1215 #
1216 1216 # The %reset command will flush this cache. See the cache_main_mod()
1217 1217 # and clear_main_mod_cache() methods for details on use.
1218 1218
1219 1219 # This is the cache used for 'main' namespaces
1220 1220 self._main_mod_cache = {}
1221 1221
1222 1222 # A table holding all the namespaces IPython deals with, so that
1223 1223 # introspection facilities can search easily.
1224 1224 self.ns_table = {'user_global':self.user_module.__dict__,
1225 1225 'user_local':self.user_ns,
1226 1226 'builtin':builtin_mod.__dict__
1227 1227 }
1228 1228
1229 1229 @property
1230 1230 def user_global_ns(self):
1231 1231 return self.user_module.__dict__
1232 1232
1233 1233 def prepare_user_module(self, user_module=None, user_ns=None):
1234 1234 """Prepare the module and namespace in which user code will be run.
1235 1235
1236 1236 When IPython is started normally, both parameters are None: a new module
1237 1237 is created automatically, and its __dict__ used as the namespace.
1238 1238
1239 1239 If only user_module is provided, its __dict__ is used as the namespace.
1240 1240 If only user_ns is provided, a dummy module is created, and user_ns
1241 1241 becomes the global namespace. If both are provided (as they may be
1242 1242 when embedding), user_ns is the local namespace, and user_module
1243 1243 provides the global namespace.
1244 1244
1245 1245 Parameters
1246 1246 ----------
1247 1247 user_module : module, optional
1248 1248 The current user module in which IPython is being run. If None,
1249 1249 a clean module will be created.
1250 1250 user_ns : dict, optional
1251 1251 A namespace in which to run interactive commands.
1252 1252
1253 1253 Returns
1254 1254 -------
1255 1255 A tuple of user_module and user_ns, each properly initialised.
1256 1256 """
1257 1257 if user_module is None and user_ns is not None:
1258 1258 user_ns.setdefault("__name__", "__main__")
1259 1259 user_module = DummyMod()
1260 1260 user_module.__dict__ = user_ns
1261 1261
1262 1262 if user_module is None:
1263 1263 user_module = types.ModuleType("__main__",
1264 1264 doc="Automatically created module for IPython interactive environment")
1265 1265
1266 1266 # We must ensure that __builtin__ (without the final 's') is always
1267 1267 # available and pointing to the __builtin__ *module*. For more details:
1268 1268 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1269 1269 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1270 1270 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1271 1271
1272 1272 if user_ns is None:
1273 1273 user_ns = user_module.__dict__
1274 1274
1275 1275 return user_module, user_ns
1276 1276
1277 1277 def init_sys_modules(self):
1278 1278 # We need to insert into sys.modules something that looks like a
1279 1279 # module but which accesses the IPython namespace, for shelve and
1280 1280 # pickle to work interactively. Normally they rely on getting
1281 1281 # everything out of __main__, but for embedding purposes each IPython
1282 1282 # instance has its own private namespace, so we can't go shoving
1283 1283 # everything into __main__.
1284 1284
1285 1285 # note, however, that we should only do this for non-embedded
1286 1286 # ipythons, which really mimic the __main__.__dict__ with their own
1287 1287 # namespace. Embedded instances, on the other hand, should not do
1288 1288 # this because they need to manage the user local/global namespaces
1289 1289 # only, but they live within a 'normal' __main__ (meaning, they
1290 1290 # shouldn't overtake the execution environment of the script they're
1291 1291 # embedded in).
1292 1292
1293 1293 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1294 1294 main_name = self.user_module.__name__
1295 1295 sys.modules[main_name] = self.user_module
1296 1296
1297 1297 def init_user_ns(self):
1298 1298 """Initialize all user-visible namespaces to their minimum defaults.
1299 1299
1300 1300 Certain history lists are also initialized here, as they effectively
1301 1301 act as user namespaces.
1302 1302
1303 1303 Notes
1304 1304 -----
1305 1305 All data structures here are only filled in, they are NOT reset by this
1306 1306 method. If they were not empty before, data will simply be added to
1307 1307 them.
1308 1308 """
1309 1309 # This function works in two parts: first we put a few things in
1310 1310 # user_ns, and we sync that contents into user_ns_hidden so that these
1311 1311 # initial variables aren't shown by %who. After the sync, we add the
1312 1312 # rest of what we *do* want the user to see with %who even on a new
1313 1313 # session (probably nothing, so they really only see their own stuff)
1314 1314
1315 1315 # The user dict must *always* have a __builtin__ reference to the
1316 1316 # Python standard __builtin__ namespace, which must be imported.
1317 1317 # This is so that certain operations in prompt evaluation can be
1318 1318 # reliably executed with builtins. Note that we can NOT use
1319 1319 # __builtins__ (note the 's'), because that can either be a dict or a
1320 1320 # module, and can even mutate at runtime, depending on the context
1321 1321 # (Python makes no guarantees on it). In contrast, __builtin__ is
1322 1322 # always a module object, though it must be explicitly imported.
1323 1323
1324 1324 # For more details:
1325 1325 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1326 1326 ns = {}
1327 1327
1328 1328 # make global variables for user access to the histories
1329 1329 ns['_ih'] = self.history_manager.input_hist_parsed
1330 1330 ns['_oh'] = self.history_manager.output_hist
1331 1331 ns['_dh'] = self.history_manager.dir_hist
1332 1332
1333 1333 # user aliases to input and output histories. These shouldn't show up
1334 1334 # in %who, as they can have very large reprs.
1335 1335 ns['In'] = self.history_manager.input_hist_parsed
1336 1336 ns['Out'] = self.history_manager.output_hist
1337 1337
1338 1338 # Store myself as the public api!!!
1339 1339 ns['get_ipython'] = self.get_ipython
1340 1340
1341 1341 ns['exit'] = self.exiter
1342 1342 ns['quit'] = self.exiter
1343 1343 ns["open"] = _modified_open
1344 1344
1345 1345 # Sync what we've added so far to user_ns_hidden so these aren't seen
1346 1346 # by %who
1347 1347 self.user_ns_hidden.update(ns)
1348 1348
1349 1349 # Anything put into ns now would show up in %who. Think twice before
1350 1350 # putting anything here, as we really want %who to show the user their
1351 1351 # stuff, not our variables.
1352 1352
1353 1353 # Finally, update the real user's namespace
1354 1354 self.user_ns.update(ns)
1355 1355
1356 1356 @property
1357 1357 def all_ns_refs(self):
1358 1358 """Get a list of references to all the namespace dictionaries in which
1359 1359 IPython might store a user-created object.
1360 1360
1361 1361 Note that this does not include the displayhook, which also caches
1362 1362 objects from the output."""
1363 1363 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \
1364 1364 [m.__dict__ for m in self._main_mod_cache.values()]
1365 1365
1366 1366 def reset(self, new_session=True, aggressive=False):
1367 1367 """Clear all internal namespaces, and attempt to release references to
1368 1368 user objects.
1369 1369
1370 1370 If new_session is True, a new history session will be opened.
1371 1371 """
1372 1372 # Clear histories
1373 1373 self.history_manager.reset(new_session)
1374 1374 # Reset counter used to index all histories
1375 1375 if new_session:
1376 1376 self.execution_count = 1
1377 1377
1378 1378 # Reset last execution result
1379 1379 self.last_execution_succeeded = True
1380 1380 self.last_execution_result = None
1381 1381
1382 1382 # Flush cached output items
1383 1383 if self.displayhook.do_full_cache:
1384 1384 self.displayhook.flush()
1385 1385
1386 1386 # The main execution namespaces must be cleared very carefully,
1387 1387 # skipping the deletion of the builtin-related keys, because doing so
1388 1388 # would cause errors in many object's __del__ methods.
1389 1389 if self.user_ns is not self.user_global_ns:
1390 1390 self.user_ns.clear()
1391 1391 ns = self.user_global_ns
1392 1392 drop_keys = set(ns.keys())
1393 1393 drop_keys.discard('__builtin__')
1394 1394 drop_keys.discard('__builtins__')
1395 1395 drop_keys.discard('__name__')
1396 1396 for k in drop_keys:
1397 1397 del ns[k]
1398 1398
1399 1399 self.user_ns_hidden.clear()
1400 1400
1401 1401 # Restore the user namespaces to minimal usability
1402 1402 self.init_user_ns()
1403 1403 if aggressive and not hasattr(self, "_sys_modules_keys"):
1404 1404 print("Cannot restore sys.module, no snapshot")
1405 1405 elif aggressive:
1406 1406 print("culling sys module...")
1407 1407 current_keys = set(sys.modules.keys())
1408 1408 for k in current_keys - self._sys_modules_keys:
1409 1409 if k.startswith("multiprocessing"):
1410 1410 continue
1411 1411 del sys.modules[k]
1412 1412
1413 1413 # Restore the default and user aliases
1414 1414 self.alias_manager.clear_aliases()
1415 1415 self.alias_manager.init_aliases()
1416 1416
1417 1417 # Now define aliases that only make sense on the terminal, because they
1418 1418 # need direct access to the console in a way that we can't emulate in
1419 1419 # GUI or web frontend
1420 1420 if os.name == 'posix':
1421 1421 for cmd in ('clear', 'more', 'less', 'man'):
1422 1422 if cmd not in self.magics_manager.magics['line']:
1423 1423 self.alias_manager.soft_define_alias(cmd, cmd)
1424 1424
1425 1425 # Flush the private list of module references kept for script
1426 1426 # execution protection
1427 1427 self.clear_main_mod_cache()
1428 1428
1429 1429 def del_var(self, varname, by_name=False):
1430 1430 """Delete a variable from the various namespaces, so that, as
1431 1431 far as possible, we're not keeping any hidden references to it.
1432 1432
1433 1433 Parameters
1434 1434 ----------
1435 1435 varname : str
1436 1436 The name of the variable to delete.
1437 1437 by_name : bool
1438 1438 If True, delete variables with the given name in each
1439 1439 namespace. If False (default), find the variable in the user
1440 1440 namespace, and delete references to it.
1441 1441 """
1442 1442 if varname in ('__builtin__', '__builtins__'):
1443 1443 raise ValueError("Refusing to delete %s" % varname)
1444 1444
1445 1445 ns_refs = self.all_ns_refs
1446 1446
1447 1447 if by_name: # Delete by name
1448 1448 for ns in ns_refs:
1449 1449 try:
1450 1450 del ns[varname]
1451 1451 except KeyError:
1452 1452 pass
1453 1453 else: # Delete by object
1454 1454 try:
1455 1455 obj = self.user_ns[varname]
1456 1456 except KeyError as e:
1457 1457 raise NameError("name '%s' is not defined" % varname) from e
1458 1458 # Also check in output history
1459 1459 ns_refs.append(self.history_manager.output_hist)
1460 1460 for ns in ns_refs:
1461 1461 to_delete = [n for n, o in ns.items() if o is obj]
1462 1462 for name in to_delete:
1463 1463 del ns[name]
1464 1464
1465 1465 # Ensure it is removed from the last execution result
1466 1466 if self.last_execution_result.result is obj:
1467 1467 self.last_execution_result = None
1468 1468
1469 1469 # displayhook keeps extra references, but not in a dictionary
1470 1470 for name in ('_', '__', '___'):
1471 1471 if getattr(self.displayhook, name) is obj:
1472 1472 setattr(self.displayhook, name, None)
1473 1473
1474 1474 def reset_selective(self, regex=None):
1475 1475 """Clear selective variables from internal namespaces based on a
1476 1476 specified regular expression.
1477 1477
1478 1478 Parameters
1479 1479 ----------
1480 1480 regex : string or compiled pattern, optional
1481 1481 A regular expression pattern that will be used in searching
1482 1482 variable names in the users namespaces.
1483 1483 """
1484 1484 if regex is not None:
1485 1485 try:
1486 1486 m = re.compile(regex)
1487 1487 except TypeError as e:
1488 1488 raise TypeError('regex must be a string or compiled pattern') from e
1489 1489 # Search for keys in each namespace that match the given regex
1490 1490 # If a match is found, delete the key/value pair.
1491 1491 for ns in self.all_ns_refs:
1492 1492 for var in ns:
1493 1493 if m.search(var):
1494 1494 del ns[var]
1495 1495
1496 1496 def push(self, variables, interactive=True):
1497 1497 """Inject a group of variables into the IPython user namespace.
1498 1498
1499 1499 Parameters
1500 1500 ----------
1501 1501 variables : dict, str or list/tuple of str
1502 1502 The variables to inject into the user's namespace. If a dict, a
1503 1503 simple update is done. If a str, the string is assumed to have
1504 1504 variable names separated by spaces. A list/tuple of str can also
1505 1505 be used to give the variable names. If just the variable names are
1506 1506 give (list/tuple/str) then the variable values looked up in the
1507 1507 callers frame.
1508 1508 interactive : bool
1509 1509 If True (default), the variables will be listed with the ``who``
1510 1510 magic.
1511 1511 """
1512 1512 vdict = None
1513 1513
1514 1514 # We need a dict of name/value pairs to do namespace updates.
1515 1515 if isinstance(variables, dict):
1516 1516 vdict = variables
1517 1517 elif isinstance(variables, (str, list, tuple)):
1518 1518 if isinstance(variables, str):
1519 1519 vlist = variables.split()
1520 1520 else:
1521 1521 vlist = variables
1522 1522 vdict = {}
1523 1523 cf = sys._getframe(1)
1524 1524 for name in vlist:
1525 1525 try:
1526 1526 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1527 1527 except:
1528 1528 print('Could not get variable %s from %s' %
1529 1529 (name,cf.f_code.co_name))
1530 1530 else:
1531 1531 raise ValueError('variables must be a dict/str/list/tuple')
1532 1532
1533 1533 # Propagate variables to user namespace
1534 1534 self.user_ns.update(vdict)
1535 1535
1536 1536 # And configure interactive visibility
1537 1537 user_ns_hidden = self.user_ns_hidden
1538 1538 if interactive:
1539 1539 for name in vdict:
1540 1540 user_ns_hidden.pop(name, None)
1541 1541 else:
1542 1542 user_ns_hidden.update(vdict)
1543 1543
1544 1544 def drop_by_id(self, variables):
1545 1545 """Remove a dict of variables from the user namespace, if they are the
1546 1546 same as the values in the dictionary.
1547 1547
1548 1548 This is intended for use by extensions: variables that they've added can
1549 1549 be taken back out if they are unloaded, without removing any that the
1550 1550 user has overwritten.
1551 1551
1552 1552 Parameters
1553 1553 ----------
1554 1554 variables : dict
1555 1555 A dictionary mapping object names (as strings) to the objects.
1556 1556 """
1557 1557 for name, obj in variables.items():
1558 1558 if name in self.user_ns and self.user_ns[name] is obj:
1559 1559 del self.user_ns[name]
1560 1560 self.user_ns_hidden.pop(name, None)
1561 1561
1562 1562 #-------------------------------------------------------------------------
1563 1563 # Things related to object introspection
1564 1564 #-------------------------------------------------------------------------
1565 1565 @staticmethod
1566 1566 def _find_parts(oname: str) -> Tuple[bool, ListType[str]]:
1567 1567 """
1568 1568 Given an object name, return a list of parts of this object name.
1569 1569
1570 1570 Basically split on docs when using attribute access,
1571 1571 and extract the value when using square bracket.
1572 1572
1573 1573
1574 1574 For example foo.bar[3].baz[x] -> foo, bar, 3, baz, x
1575 1575
1576 1576
1577 1577 Returns
1578 1578 -------
1579 1579 parts_ok: bool
1580 1580 wether we were properly able to parse parts.
1581 1581 parts: list of str
1582 1582 extracted parts
1583 1583
1584 1584
1585 1585
1586 1586 """
1587 1587 raw_parts = oname.split(".")
1588 1588 parts = []
1589 1589 parts_ok = True
1590 1590 for p in raw_parts:
1591 1591 if p.endswith("]"):
1592 1592 var, *indices = p.split("[")
1593 1593 if not var.isidentifier():
1594 1594 parts_ok = False
1595 1595 break
1596 1596 parts.append(var)
1597 1597 for ind in indices:
1598 1598 if ind[-1] != "]" and not is_integer_string(ind[:-1]):
1599 1599 parts_ok = False
1600 1600 break
1601 1601 parts.append(ind[:-1])
1602 1602 continue
1603 1603
1604 1604 if not p.isidentifier():
1605 1605 parts_ok = False
1606 1606 parts.append(p)
1607 1607
1608 1608 return parts_ok, parts
1609 1609
1610 1610 def _ofind(
1611 1611 self, oname: str, namespaces: Optional[Sequence[Tuple[str, AnyType]]] = None
1612 ):
1612 ) -> OInfo:
1613 1613 """Find an object in the available namespaces.
1614 1614
1615 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1615
1616 Returns
1617 -------
1618 OInfo with fields:
1619 - ismagic
1620 - isalias
1621 - found
1622 - obj
1623 - namespac
1624 - parent
1616 1625
1617 1626 Has special code to detect magic functions.
1618 1627 """
1619 1628 oname = oname.strip()
1620 1629 parts_ok, parts = self._find_parts(oname)
1621 1630
1622 1631 if (
1623 1632 not oname.startswith(ESC_MAGIC)
1624 1633 and not oname.startswith(ESC_MAGIC2)
1625 1634 and not parts_ok
1626 1635 ):
1627 1636 return OInfo(
1628 1637 ismagic=False,
1629 1638 isalias=False,
1630 1639 found=False,
1631 1640 obj=None,
1632 1641 namespace=None,
1633 1642 parent=None,
1634 1643 )
1635 1644
1636 1645 if namespaces is None:
1637 1646 # Namespaces to search in:
1638 1647 # Put them in a list. The order is important so that we
1639 1648 # find things in the same order that Python finds them.
1640 1649 namespaces = [ ('Interactive', self.user_ns),
1641 1650 ('Interactive (global)', self.user_global_ns),
1642 1651 ('Python builtin', builtin_mod.__dict__),
1643 1652 ]
1644 1653
1645 1654 ismagic = False
1646 1655 isalias = False
1647 1656 found = False
1648 1657 ospace = None
1649 1658 parent = None
1650 1659 obj = None
1651 1660
1652 1661
1653 1662 # Look for the given name by splitting it in parts. If the head is
1654 1663 # found, then we look for all the remaining parts as members, and only
1655 1664 # declare success if we can find them all.
1656 1665 oname_parts = parts
1657 1666 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1658 1667 for nsname,ns in namespaces:
1659 1668 try:
1660 1669 obj = ns[oname_head]
1661 1670 except KeyError:
1662 1671 continue
1663 1672 else:
1664 1673 for idx, part in enumerate(oname_rest):
1665 1674 try:
1666 1675 parent = obj
1667 1676 # The last part is looked up in a special way to avoid
1668 1677 # descriptor invocation as it may raise or have side
1669 1678 # effects.
1670 1679 if idx == len(oname_rest) - 1:
1671 1680 obj = self._getattr_property(obj, part)
1672 1681 else:
1673 1682 if is_integer_string(part):
1674 1683 obj = obj[int(part)]
1675 1684 else:
1676 1685 obj = getattr(obj, part)
1677 1686 except:
1678 1687 # Blanket except b/c some badly implemented objects
1679 1688 # allow __getattr__ to raise exceptions other than
1680 1689 # AttributeError, which then crashes IPython.
1681 1690 break
1682 1691 else:
1683 1692 # If we finish the for loop (no break), we got all members
1684 1693 found = True
1685 1694 ospace = nsname
1686 1695 break # namespace loop
1687 1696
1688 1697 # Try to see if it's magic
1689 1698 if not found:
1690 1699 obj = None
1691 1700 if oname.startswith(ESC_MAGIC2):
1692 1701 oname = oname.lstrip(ESC_MAGIC2)
1693 1702 obj = self.find_cell_magic(oname)
1694 1703 elif oname.startswith(ESC_MAGIC):
1695 1704 oname = oname.lstrip(ESC_MAGIC)
1696 1705 obj = self.find_line_magic(oname)
1697 1706 else:
1698 1707 # search without prefix, so run? will find %run?
1699 1708 obj = self.find_line_magic(oname)
1700 1709 if obj is None:
1701 1710 obj = self.find_cell_magic(oname)
1702 1711 if obj is not None:
1703 1712 found = True
1704 1713 ospace = 'IPython internal'
1705 1714 ismagic = True
1706 1715 isalias = isinstance(obj, Alias)
1707 1716
1708 1717 # Last try: special-case some literals like '', [], {}, etc:
1709 1718 if not found and oname_head in ["''",'""','[]','{}','()']:
1710 1719 obj = eval(oname_head)
1711 1720 found = True
1712 1721 ospace = 'Interactive'
1713 1722
1714 1723 return OInfo(
1715 1724 obj=obj,
1716 1725 found=found,
1717 1726 parent=parent,
1718 1727 ismagic=ismagic,
1719 1728 isalias=isalias,
1720 1729 namespace=ospace,
1721 1730 )
1722 1731
1723 1732 @staticmethod
1724 1733 def _getattr_property(obj, attrname):
1725 1734 """Property-aware getattr to use in object finding.
1726 1735
1727 1736 If attrname represents a property, return it unevaluated (in case it has
1728 1737 side effects or raises an error.
1729 1738
1730 1739 """
1731 1740 if not isinstance(obj, type):
1732 1741 try:
1733 1742 # `getattr(type(obj), attrname)` is not guaranteed to return
1734 1743 # `obj`, but does so for property:
1735 1744 #
1736 1745 # property.__get__(self, None, cls) -> self
1737 1746 #
1738 1747 # The universal alternative is to traverse the mro manually
1739 1748 # searching for attrname in class dicts.
1740 1749 if is_integer_string(attrname):
1741 1750 return obj[int(attrname)]
1742 1751 else:
1743 1752 attr = getattr(type(obj), attrname)
1744 1753 except AttributeError:
1745 1754 pass
1746 1755 else:
1747 1756 # This relies on the fact that data descriptors (with both
1748 1757 # __get__ & __set__ magic methods) take precedence over
1749 1758 # instance-level attributes:
1750 1759 #
1751 1760 # class A(object):
1752 1761 # @property
1753 1762 # def foobar(self): return 123
1754 1763 # a = A()
1755 1764 # a.__dict__['foobar'] = 345
1756 1765 # a.foobar # == 123
1757 1766 #
1758 1767 # So, a property may be returned right away.
1759 1768 if isinstance(attr, property):
1760 1769 return attr
1761 1770
1762 1771 # Nothing helped, fall back.
1763 1772 return getattr(obj, attrname)
1764 1773
1765 1774 def _object_find(self, oname, namespaces=None) -> OInfo:
1766 1775 """Find an object and return a struct with info about it."""
1767 1776 return self._ofind(oname, namespaces)
1768 1777
1769 1778 def _inspect(self, meth, oname, namespaces=None, **kw):
1770 1779 """Generic interface to the inspector system.
1771 1780
1772 1781 This function is meant to be called by pdef, pdoc & friends.
1773 1782 """
1774 info = self._object_find(oname, namespaces)
1783 info: OInfo = self._object_find(oname, namespaces)
1775 1784 docformat = (
1776 1785 sphinxify(self.object_inspect(oname)) if self.sphinxify_docstring else None
1777 1786 )
1778 if info.found:
1787 if info.found or hasattr(info.parent, oinspect.HOOK_NAME):
1779 1788 pmethod = getattr(self.inspector, meth)
1780 1789 # TODO: only apply format_screen to the plain/text repr of the mime
1781 1790 # bundle.
1782 1791 formatter = format_screen if info.ismagic else docformat
1783 1792 if meth == 'pdoc':
1784 1793 pmethod(info.obj, oname, formatter)
1785 1794 elif meth == 'pinfo':
1786 1795 pmethod(
1787 1796 info.obj,
1788 1797 oname,
1789 1798 formatter,
1790 1799 info,
1791 1800 enable_html_pager=self.enable_html_pager,
1792 1801 **kw,
1793 1802 )
1794 1803 else:
1795 1804 pmethod(info.obj, oname)
1796 1805 else:
1797 1806 print('Object `%s` not found.' % oname)
1798 1807 return 'not found' # so callers can take other action
1799 1808
1800 1809 def object_inspect(self, oname, detail_level=0):
1801 1810 """Get object info about oname"""
1802 1811 with self.builtin_trap:
1803 1812 info = self._object_find(oname)
1804 1813 if info.found:
1805 1814 return self.inspector.info(info.obj, oname, info=info,
1806 1815 detail_level=detail_level
1807 1816 )
1808 1817 else:
1809 1818 return oinspect.object_info(name=oname, found=False)
1810 1819
1811 1820 def object_inspect_text(self, oname, detail_level=0):
1812 1821 """Get object info as formatted text"""
1813 1822 return self.object_inspect_mime(oname, detail_level)['text/plain']
1814 1823
1815 1824 def object_inspect_mime(self, oname, detail_level=0, omit_sections=()):
1816 1825 """Get object info as a mimebundle of formatted representations.
1817 1826
1818 1827 A mimebundle is a dictionary, keyed by mime-type.
1819 1828 It must always have the key `'text/plain'`.
1820 1829 """
1821 1830 with self.builtin_trap:
1822 1831 info = self._object_find(oname)
1823 1832 if info.found:
1824 1833 docformat = (
1825 1834 sphinxify(self.object_inspect(oname))
1826 1835 if self.sphinxify_docstring
1827 1836 else None
1828 1837 )
1829 1838 return self.inspector._get_info(
1830 1839 info.obj,
1831 1840 oname,
1832 1841 info=info,
1833 1842 detail_level=detail_level,
1834 1843 formatter=docformat,
1835 1844 omit_sections=omit_sections,
1836 1845 )
1837 1846 else:
1838 1847 raise KeyError(oname)
1839 1848
1840 1849 #-------------------------------------------------------------------------
1841 1850 # Things related to history management
1842 1851 #-------------------------------------------------------------------------
1843 1852
1844 1853 def init_history(self):
1845 1854 """Sets up the command history, and starts regular autosaves."""
1846 1855 self.history_manager = HistoryManager(shell=self, parent=self)
1847 1856 self.configurables.append(self.history_manager)
1848 1857
1849 1858 #-------------------------------------------------------------------------
1850 1859 # Things related to exception handling and tracebacks (not debugging)
1851 1860 #-------------------------------------------------------------------------
1852 1861
1853 1862 debugger_cls = InterruptiblePdb
1854 1863
1855 1864 def init_traceback_handlers(self, custom_exceptions):
1856 1865 # Syntax error handler.
1857 1866 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor', parent=self)
1858 1867
1859 1868 # The interactive one is initialized with an offset, meaning we always
1860 1869 # want to remove the topmost item in the traceback, which is our own
1861 1870 # internal code. Valid modes: ['Plain','Context','Verbose','Minimal']
1862 1871 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1863 1872 color_scheme='NoColor',
1864 1873 tb_offset = 1,
1865 1874 debugger_cls=self.debugger_cls, parent=self)
1866 1875
1867 1876 # The instance will store a pointer to the system-wide exception hook,
1868 1877 # so that runtime code (such as magics) can access it. This is because
1869 1878 # during the read-eval loop, it may get temporarily overwritten.
1870 1879 self.sys_excepthook = sys.excepthook
1871 1880
1872 1881 # and add any custom exception handlers the user may have specified
1873 1882 self.set_custom_exc(*custom_exceptions)
1874 1883
1875 1884 # Set the exception mode
1876 1885 self.InteractiveTB.set_mode(mode=self.xmode)
1877 1886
1878 1887 def set_custom_exc(self, exc_tuple, handler):
1879 1888 """set_custom_exc(exc_tuple, handler)
1880 1889
1881 1890 Set a custom exception handler, which will be called if any of the
1882 1891 exceptions in exc_tuple occur in the mainloop (specifically, in the
1883 1892 run_code() method).
1884 1893
1885 1894 Parameters
1886 1895 ----------
1887 1896 exc_tuple : tuple of exception classes
1888 1897 A *tuple* of exception classes, for which to call the defined
1889 1898 handler. It is very important that you use a tuple, and NOT A
1890 1899 LIST here, because of the way Python's except statement works. If
1891 1900 you only want to trap a single exception, use a singleton tuple::
1892 1901
1893 1902 exc_tuple == (MyCustomException,)
1894 1903
1895 1904 handler : callable
1896 1905 handler must have the following signature::
1897 1906
1898 1907 def my_handler(self, etype, value, tb, tb_offset=None):
1899 1908 ...
1900 1909 return structured_traceback
1901 1910
1902 1911 Your handler must return a structured traceback (a list of strings),
1903 1912 or None.
1904 1913
1905 1914 This will be made into an instance method (via types.MethodType)
1906 1915 of IPython itself, and it will be called if any of the exceptions
1907 1916 listed in the exc_tuple are caught. If the handler is None, an
1908 1917 internal basic one is used, which just prints basic info.
1909 1918
1910 1919 To protect IPython from crashes, if your handler ever raises an
1911 1920 exception or returns an invalid result, it will be immediately
1912 1921 disabled.
1913 1922
1914 1923 Notes
1915 1924 -----
1916 1925 WARNING: by putting in your own exception handler into IPython's main
1917 1926 execution loop, you run a very good chance of nasty crashes. This
1918 1927 facility should only be used if you really know what you are doing.
1919 1928 """
1920 1929
1921 1930 if not isinstance(exc_tuple, tuple):
1922 1931 raise TypeError("The custom exceptions must be given as a tuple.")
1923 1932
1924 1933 def dummy_handler(self, etype, value, tb, tb_offset=None):
1925 1934 print('*** Simple custom exception handler ***')
1926 1935 print('Exception type :', etype)
1927 1936 print('Exception value:', value)
1928 1937 print('Traceback :', tb)
1929 1938
1930 1939 def validate_stb(stb):
1931 1940 """validate structured traceback return type
1932 1941
1933 1942 return type of CustomTB *should* be a list of strings, but allow
1934 1943 single strings or None, which are harmless.
1935 1944
1936 1945 This function will *always* return a list of strings,
1937 1946 and will raise a TypeError if stb is inappropriate.
1938 1947 """
1939 1948 msg = "CustomTB must return list of strings, not %r" % stb
1940 1949 if stb is None:
1941 1950 return []
1942 1951 elif isinstance(stb, str):
1943 1952 return [stb]
1944 1953 elif not isinstance(stb, list):
1945 1954 raise TypeError(msg)
1946 1955 # it's a list
1947 1956 for line in stb:
1948 1957 # check every element
1949 1958 if not isinstance(line, str):
1950 1959 raise TypeError(msg)
1951 1960 return stb
1952 1961
1953 1962 if handler is None:
1954 1963 wrapped = dummy_handler
1955 1964 else:
1956 1965 def wrapped(self,etype,value,tb,tb_offset=None):
1957 1966 """wrap CustomTB handler, to protect IPython from user code
1958 1967
1959 1968 This makes it harder (but not impossible) for custom exception
1960 1969 handlers to crash IPython.
1961 1970 """
1962 1971 try:
1963 1972 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1964 1973 return validate_stb(stb)
1965 1974 except:
1966 1975 # clear custom handler immediately
1967 1976 self.set_custom_exc((), None)
1968 1977 print("Custom TB Handler failed, unregistering", file=sys.stderr)
1969 1978 # show the exception in handler first
1970 1979 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1971 1980 print(self.InteractiveTB.stb2text(stb))
1972 1981 print("The original exception:")
1973 1982 stb = self.InteractiveTB.structured_traceback(
1974 1983 (etype,value,tb), tb_offset=tb_offset
1975 1984 )
1976 1985 return stb
1977 1986
1978 1987 self.CustomTB = types.MethodType(wrapped,self)
1979 1988 self.custom_exceptions = exc_tuple
1980 1989
1981 1990 def excepthook(self, etype, value, tb):
1982 1991 """One more defense for GUI apps that call sys.excepthook.
1983 1992
1984 1993 GUI frameworks like wxPython trap exceptions and call
1985 1994 sys.excepthook themselves. I guess this is a feature that
1986 1995 enables them to keep running after exceptions that would
1987 1996 otherwise kill their mainloop. This is a bother for IPython
1988 1997 which expects to catch all of the program exceptions with a try:
1989 1998 except: statement.
1990 1999
1991 2000 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1992 2001 any app directly invokes sys.excepthook, it will look to the user like
1993 2002 IPython crashed. In order to work around this, we can disable the
1994 2003 CrashHandler and replace it with this excepthook instead, which prints a
1995 2004 regular traceback using our InteractiveTB. In this fashion, apps which
1996 2005 call sys.excepthook will generate a regular-looking exception from
1997 2006 IPython, and the CrashHandler will only be triggered by real IPython
1998 2007 crashes.
1999 2008
2000 2009 This hook should be used sparingly, only in places which are not likely
2001 2010 to be true IPython errors.
2002 2011 """
2003 2012 self.showtraceback((etype, value, tb), tb_offset=0)
2004 2013
2005 2014 def _get_exc_info(self, exc_tuple=None):
2006 2015 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
2007 2016
2008 2017 Ensures sys.last_type,value,traceback hold the exc_info we found,
2009 2018 from whichever source.
2010 2019
2011 2020 raises ValueError if none of these contain any information
2012 2021 """
2013 2022 if exc_tuple is None:
2014 2023 etype, value, tb = sys.exc_info()
2015 2024 else:
2016 2025 etype, value, tb = exc_tuple
2017 2026
2018 2027 if etype is None:
2019 2028 if hasattr(sys, 'last_type'):
2020 2029 etype, value, tb = sys.last_type, sys.last_value, \
2021 2030 sys.last_traceback
2022 2031
2023 2032 if etype is None:
2024 2033 raise ValueError("No exception to find")
2025 2034
2026 2035 # Now store the exception info in sys.last_type etc.
2027 2036 # WARNING: these variables are somewhat deprecated and not
2028 2037 # necessarily safe to use in a threaded environment, but tools
2029 2038 # like pdb depend on their existence, so let's set them. If we
2030 2039 # find problems in the field, we'll need to revisit their use.
2031 2040 sys.last_type = etype
2032 2041 sys.last_value = value
2033 2042 sys.last_traceback = tb
2034 2043
2035 2044 return etype, value, tb
2036 2045
2037 2046 def show_usage_error(self, exc):
2038 2047 """Show a short message for UsageErrors
2039 2048
2040 2049 These are special exceptions that shouldn't show a traceback.
2041 2050 """
2042 2051 print("UsageError: %s" % exc, file=sys.stderr)
2043 2052
2044 2053 def get_exception_only(self, exc_tuple=None):
2045 2054 """
2046 2055 Return as a string (ending with a newline) the exception that
2047 2056 just occurred, without any traceback.
2048 2057 """
2049 2058 etype, value, tb = self._get_exc_info(exc_tuple)
2050 2059 msg = traceback.format_exception_only(etype, value)
2051 2060 return ''.join(msg)
2052 2061
2053 2062 def showtraceback(self, exc_tuple=None, filename=None, tb_offset=None,
2054 2063 exception_only=False, running_compiled_code=False):
2055 2064 """Display the exception that just occurred.
2056 2065
2057 2066 If nothing is known about the exception, this is the method which
2058 2067 should be used throughout the code for presenting user tracebacks,
2059 2068 rather than directly invoking the InteractiveTB object.
2060 2069
2061 2070 A specific showsyntaxerror() also exists, but this method can take
2062 2071 care of calling it if needed, so unless you are explicitly catching a
2063 2072 SyntaxError exception, don't try to analyze the stack manually and
2064 2073 simply call this method."""
2065 2074
2066 2075 try:
2067 2076 try:
2068 2077 etype, value, tb = self._get_exc_info(exc_tuple)
2069 2078 except ValueError:
2070 2079 print('No traceback available to show.', file=sys.stderr)
2071 2080 return
2072 2081
2073 2082 if issubclass(etype, SyntaxError):
2074 2083 # Though this won't be called by syntax errors in the input
2075 2084 # line, there may be SyntaxError cases with imported code.
2076 2085 self.showsyntaxerror(filename, running_compiled_code)
2077 2086 elif etype is UsageError:
2078 2087 self.show_usage_error(value)
2079 2088 else:
2080 2089 if exception_only:
2081 2090 stb = ['An exception has occurred, use %tb to see '
2082 2091 'the full traceback.\n']
2083 2092 stb.extend(self.InteractiveTB.get_exception_only(etype,
2084 2093 value))
2085 2094 else:
2086 2095 try:
2087 2096 # Exception classes can customise their traceback - we
2088 2097 # use this in IPython.parallel for exceptions occurring
2089 2098 # in the engines. This should return a list of strings.
2090 2099 if hasattr(value, "_render_traceback_"):
2091 2100 stb = value._render_traceback_()
2092 2101 else:
2093 2102 stb = self.InteractiveTB.structured_traceback(
2094 2103 etype, value, tb, tb_offset=tb_offset
2095 2104 )
2096 2105
2097 2106 except Exception:
2098 2107 print(
2099 2108 "Unexpected exception formatting exception. Falling back to standard exception"
2100 2109 )
2101 2110 traceback.print_exc()
2102 2111 return None
2103 2112
2104 2113 self._showtraceback(etype, value, stb)
2105 2114 if self.call_pdb:
2106 2115 # drop into debugger
2107 2116 self.debugger(force=True)
2108 2117 return
2109 2118
2110 2119 # Actually show the traceback
2111 2120 self._showtraceback(etype, value, stb)
2112 2121
2113 2122 except KeyboardInterrupt:
2114 2123 print('\n' + self.get_exception_only(), file=sys.stderr)
2115 2124
2116 2125 def _showtraceback(self, etype, evalue, stb: str):
2117 2126 """Actually show a traceback.
2118 2127
2119 2128 Subclasses may override this method to put the traceback on a different
2120 2129 place, like a side channel.
2121 2130 """
2122 2131 val = self.InteractiveTB.stb2text(stb)
2123 2132 try:
2124 2133 print(val)
2125 2134 except UnicodeEncodeError:
2126 2135 print(val.encode("utf-8", "backslashreplace").decode())
2127 2136
2128 2137 def showsyntaxerror(self, filename=None, running_compiled_code=False):
2129 2138 """Display the syntax error that just occurred.
2130 2139
2131 2140 This doesn't display a stack trace because there isn't one.
2132 2141
2133 2142 If a filename is given, it is stuffed in the exception instead
2134 2143 of what was there before (because Python's parser always uses
2135 2144 "<string>" when reading from a string).
2136 2145
2137 2146 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),
2138 2147 longer stack trace will be displayed.
2139 2148 """
2140 2149 etype, value, last_traceback = self._get_exc_info()
2141 2150
2142 2151 if filename and issubclass(etype, SyntaxError):
2143 2152 try:
2144 2153 value.filename = filename
2145 2154 except:
2146 2155 # Not the format we expect; leave it alone
2147 2156 pass
2148 2157
2149 2158 # If the error occurred when executing compiled code, we should provide full stacktrace.
2150 2159 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []
2151 2160 stb = self.SyntaxTB.structured_traceback(etype, value, elist)
2152 2161 self._showtraceback(etype, value, stb)
2153 2162
2154 2163 # This is overridden in TerminalInteractiveShell to show a message about
2155 2164 # the %paste magic.
2156 2165 def showindentationerror(self):
2157 2166 """Called by _run_cell when there's an IndentationError in code entered
2158 2167 at the prompt.
2159 2168
2160 2169 This is overridden in TerminalInteractiveShell to show a message about
2161 2170 the %paste magic."""
2162 2171 self.showsyntaxerror()
2163 2172
2164 2173 @skip_doctest
2165 2174 def set_next_input(self, s, replace=False):
2166 2175 """ Sets the 'default' input string for the next command line.
2167 2176
2168 2177 Example::
2169 2178
2170 2179 In [1]: _ip.set_next_input("Hello Word")
2171 2180 In [2]: Hello Word_ # cursor is here
2172 2181 """
2173 2182 self.rl_next_input = s
2174 2183
2175 2184 def _indent_current_str(self):
2176 2185 """return the current level of indentation as a string"""
2177 2186 return self.input_splitter.get_indent_spaces() * ' '
2178 2187
2179 2188 #-------------------------------------------------------------------------
2180 2189 # Things related to text completion
2181 2190 #-------------------------------------------------------------------------
2182 2191
2183 2192 def init_completer(self):
2184 2193 """Initialize the completion machinery.
2185 2194
2186 2195 This creates completion machinery that can be used by client code,
2187 2196 either interactively in-process (typically triggered by the readline
2188 2197 library), programmatically (such as in test suites) or out-of-process
2189 2198 (typically over the network by remote frontends).
2190 2199 """
2191 2200 from IPython.core.completer import IPCompleter
2192 2201 from IPython.core.completerlib import (
2193 2202 cd_completer,
2194 2203 magic_run_completer,
2195 2204 module_completer,
2196 2205 reset_completer,
2197 2206 )
2198 2207
2199 2208 self.Completer = IPCompleter(shell=self,
2200 2209 namespace=self.user_ns,
2201 2210 global_namespace=self.user_global_ns,
2202 2211 parent=self,
2203 2212 )
2204 2213 self.configurables.append(self.Completer)
2205 2214
2206 2215 # Add custom completers to the basic ones built into IPCompleter
2207 2216 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
2208 2217 self.strdispatchers['complete_command'] = sdisp
2209 2218 self.Completer.custom_completers = sdisp
2210 2219
2211 2220 self.set_hook('complete_command', module_completer, str_key = 'import')
2212 2221 self.set_hook('complete_command', module_completer, str_key = 'from')
2213 2222 self.set_hook('complete_command', module_completer, str_key = '%aimport')
2214 2223 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
2215 2224 self.set_hook('complete_command', cd_completer, str_key = '%cd')
2216 2225 self.set_hook('complete_command', reset_completer, str_key = '%reset')
2217 2226
2218 2227 @skip_doctest
2219 2228 def complete(self, text, line=None, cursor_pos=None):
2220 2229 """Return the completed text and a list of completions.
2221 2230
2222 2231 Parameters
2223 2232 ----------
2224 2233 text : string
2225 2234 A string of text to be completed on. It can be given as empty and
2226 2235 instead a line/position pair are given. In this case, the
2227 2236 completer itself will split the line like readline does.
2228 2237 line : string, optional
2229 2238 The complete line that text is part of.
2230 2239 cursor_pos : int, optional
2231 2240 The position of the cursor on the input line.
2232 2241
2233 2242 Returns
2234 2243 -------
2235 2244 text : string
2236 2245 The actual text that was completed.
2237 2246 matches : list
2238 2247 A sorted list with all possible completions.
2239 2248
2240 2249 Notes
2241 2250 -----
2242 2251 The optional arguments allow the completion to take more context into
2243 2252 account, and are part of the low-level completion API.
2244 2253
2245 2254 This is a wrapper around the completion mechanism, similar to what
2246 2255 readline does at the command line when the TAB key is hit. By
2247 2256 exposing it as a method, it can be used by other non-readline
2248 2257 environments (such as GUIs) for text completion.
2249 2258
2250 2259 Examples
2251 2260 --------
2252 2261 In [1]: x = 'hello'
2253 2262
2254 2263 In [2]: _ip.complete('x.l')
2255 2264 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2256 2265 """
2257 2266
2258 2267 # Inject names into __builtin__ so we can complete on the added names.
2259 2268 with self.builtin_trap:
2260 2269 return self.Completer.complete(text, line, cursor_pos)
2261 2270
2262 2271 def set_custom_completer(self, completer, pos=0) -> None:
2263 2272 """Adds a new custom completer function.
2264 2273
2265 2274 The position argument (defaults to 0) is the index in the completers
2266 2275 list where you want the completer to be inserted.
2267 2276
2268 2277 `completer` should have the following signature::
2269 2278
2270 2279 def completion(self: Completer, text: string) -> List[str]:
2271 2280 raise NotImplementedError
2272 2281
2273 2282 It will be bound to the current Completer instance and pass some text
2274 2283 and return a list with current completions to suggest to the user.
2275 2284 """
2276 2285
2277 2286 newcomp = types.MethodType(completer, self.Completer)
2278 2287 self.Completer.custom_matchers.insert(pos,newcomp)
2279 2288
2280 2289 def set_completer_frame(self, frame=None):
2281 2290 """Set the frame of the completer."""
2282 2291 if frame:
2283 2292 self.Completer.namespace = frame.f_locals
2284 2293 self.Completer.global_namespace = frame.f_globals
2285 2294 else:
2286 2295 self.Completer.namespace = self.user_ns
2287 2296 self.Completer.global_namespace = self.user_global_ns
2288 2297
2289 2298 #-------------------------------------------------------------------------
2290 2299 # Things related to magics
2291 2300 #-------------------------------------------------------------------------
2292 2301
2293 2302 def init_magics(self):
2294 2303 from IPython.core import magics as m
2295 2304 self.magics_manager = magic.MagicsManager(shell=self,
2296 2305 parent=self,
2297 2306 user_magics=m.UserMagics(self))
2298 2307 self.configurables.append(self.magics_manager)
2299 2308
2300 2309 # Expose as public API from the magics manager
2301 2310 self.register_magics = self.magics_manager.register
2302 2311
2303 2312 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2304 2313 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,
2305 2314 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2306 2315 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,
2307 2316 m.PylabMagics, m.ScriptMagics,
2308 2317 )
2309 2318 self.register_magics(m.AsyncMagics)
2310 2319
2311 2320 # Register Magic Aliases
2312 2321 mman = self.magics_manager
2313 2322 # FIXME: magic aliases should be defined by the Magics classes
2314 2323 # or in MagicsManager, not here
2315 2324 mman.register_alias('ed', 'edit')
2316 2325 mman.register_alias('hist', 'history')
2317 2326 mman.register_alias('rep', 'recall')
2318 2327 mman.register_alias('SVG', 'svg', 'cell')
2319 2328 mman.register_alias('HTML', 'html', 'cell')
2320 2329 mman.register_alias('file', 'writefile', 'cell')
2321 2330
2322 2331 # FIXME: Move the color initialization to the DisplayHook, which
2323 2332 # should be split into a prompt manager and displayhook. We probably
2324 2333 # even need a centralize colors management object.
2325 2334 self.run_line_magic('colors', self.colors)
2326 2335
2327 2336 # Defined here so that it's included in the documentation
2328 2337 @functools.wraps(magic.MagicsManager.register_function)
2329 2338 def register_magic_function(self, func, magic_kind='line', magic_name=None):
2330 2339 self.magics_manager.register_function(
2331 2340 func, magic_kind=magic_kind, magic_name=magic_name
2332 2341 )
2333 2342
2334 2343 def _find_with_lazy_load(self, /, type_, magic_name: str):
2335 2344 """
2336 2345 Try to find a magic potentially lazy-loading it.
2337 2346
2338 2347 Parameters
2339 2348 ----------
2340 2349
2341 2350 type_: "line"|"cell"
2342 2351 the type of magics we are trying to find/lazy load.
2343 2352 magic_name: str
2344 2353 The name of the magic we are trying to find/lazy load
2345 2354
2346 2355
2347 2356 Note that this may have any side effects
2348 2357 """
2349 2358 finder = {"line": self.find_line_magic, "cell": self.find_cell_magic}[type_]
2350 2359 fn = finder(magic_name)
2351 2360 if fn is not None:
2352 2361 return fn
2353 2362 lazy = self.magics_manager.lazy_magics.get(magic_name)
2354 2363 if lazy is None:
2355 2364 return None
2356 2365
2357 2366 self.run_line_magic("load_ext", lazy)
2358 2367 res = finder(magic_name)
2359 2368 return res
2360 2369
2361 2370 def run_line_magic(self, magic_name: str, line, _stack_depth=1):
2362 2371 """Execute the given line magic.
2363 2372
2364 2373 Parameters
2365 2374 ----------
2366 2375 magic_name : str
2367 2376 Name of the desired magic function, without '%' prefix.
2368 2377 line : str
2369 2378 The rest of the input line as a single string.
2370 2379 _stack_depth : int
2371 2380 If run_line_magic() is called from magic() then _stack_depth=2.
2372 2381 This is added to ensure backward compatibility for use of 'get_ipython().magic()'
2373 2382 """
2374 2383 fn = self._find_with_lazy_load("line", magic_name)
2375 2384 if fn is None:
2376 2385 lazy = self.magics_manager.lazy_magics.get(magic_name)
2377 2386 if lazy:
2378 2387 self.run_line_magic("load_ext", lazy)
2379 2388 fn = self.find_line_magic(magic_name)
2380 2389 if fn is None:
2381 2390 cm = self.find_cell_magic(magic_name)
2382 2391 etpl = "Line magic function `%%%s` not found%s."
2383 2392 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2384 2393 'did you mean that instead?)' % magic_name )
2385 2394 raise UsageError(etpl % (magic_name, extra))
2386 2395 else:
2387 2396 # Note: this is the distance in the stack to the user's frame.
2388 2397 # This will need to be updated if the internal calling logic gets
2389 2398 # refactored, or else we'll be expanding the wrong variables.
2390 2399
2391 2400 # Determine stack_depth depending on where run_line_magic() has been called
2392 2401 stack_depth = _stack_depth
2393 2402 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2394 2403 # magic has opted out of var_expand
2395 2404 magic_arg_s = line
2396 2405 else:
2397 2406 magic_arg_s = self.var_expand(line, stack_depth)
2398 2407 # Put magic args in a list so we can call with f(*a) syntax
2399 2408 args = [magic_arg_s]
2400 2409 kwargs = {}
2401 2410 # Grab local namespace if we need it:
2402 2411 if getattr(fn, "needs_local_scope", False):
2403 2412 kwargs['local_ns'] = self.get_local_scope(stack_depth)
2404 2413 with self.builtin_trap:
2405 2414 result = fn(*args, **kwargs)
2406 2415
2407 2416 # The code below prevents the output from being displayed
2408 2417 # when using magics with decodator @output_can_be_silenced
2409 2418 # when the last Python token in the expression is a ';'.
2410 2419 if getattr(fn, magic.MAGIC_OUTPUT_CAN_BE_SILENCED, False):
2411 2420 if DisplayHook.semicolon_at_end_of_expression(magic_arg_s):
2412 2421 return None
2413 2422
2414 2423 return result
2415 2424
2416 2425 def get_local_scope(self, stack_depth):
2417 2426 """Get local scope at given stack depth.
2418 2427
2419 2428 Parameters
2420 2429 ----------
2421 2430 stack_depth : int
2422 2431 Depth relative to calling frame
2423 2432 """
2424 2433 return sys._getframe(stack_depth + 1).f_locals
2425 2434
2426 2435 def run_cell_magic(self, magic_name, line, cell):
2427 2436 """Execute the given cell magic.
2428 2437
2429 2438 Parameters
2430 2439 ----------
2431 2440 magic_name : str
2432 2441 Name of the desired magic function, without '%' prefix.
2433 2442 line : str
2434 2443 The rest of the first input line as a single string.
2435 2444 cell : str
2436 2445 The body of the cell as a (possibly multiline) string.
2437 2446 """
2438 2447 fn = self._find_with_lazy_load("cell", magic_name)
2439 2448 if fn is None:
2440 2449 lm = self.find_line_magic(magic_name)
2441 2450 etpl = "Cell magic `%%{0}` not found{1}."
2442 2451 extra = '' if lm is None else (' (But line magic `%{0}` exists, '
2443 2452 'did you mean that instead?)'.format(magic_name))
2444 2453 raise UsageError(etpl.format(magic_name, extra))
2445 2454 elif cell == '':
2446 2455 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)
2447 2456 if self.find_line_magic(magic_name) is not None:
2448 2457 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)
2449 2458 raise UsageError(message)
2450 2459 else:
2451 2460 # Note: this is the distance in the stack to the user's frame.
2452 2461 # This will need to be updated if the internal calling logic gets
2453 2462 # refactored, or else we'll be expanding the wrong variables.
2454 2463 stack_depth = 2
2455 2464 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):
2456 2465 # magic has opted out of var_expand
2457 2466 magic_arg_s = line
2458 2467 else:
2459 2468 magic_arg_s = self.var_expand(line, stack_depth)
2460 2469 kwargs = {}
2461 2470 if getattr(fn, "needs_local_scope", False):
2462 2471 kwargs['local_ns'] = self.user_ns
2463 2472
2464 2473 with self.builtin_trap:
2465 2474 args = (magic_arg_s, cell)
2466 2475 result = fn(*args, **kwargs)
2467 2476
2468 2477 # The code below prevents the output from being displayed
2469 2478 # when using magics with decodator @output_can_be_silenced
2470 2479 # when the last Python token in the expression is a ';'.
2471 2480 if getattr(fn, magic.MAGIC_OUTPUT_CAN_BE_SILENCED, False):
2472 2481 if DisplayHook.semicolon_at_end_of_expression(cell):
2473 2482 return None
2474 2483
2475 2484 return result
2476 2485
2477 2486 def find_line_magic(self, magic_name):
2478 2487 """Find and return a line magic by name.
2479 2488
2480 2489 Returns None if the magic isn't found."""
2481 2490 return self.magics_manager.magics['line'].get(magic_name)
2482 2491
2483 2492 def find_cell_magic(self, magic_name):
2484 2493 """Find and return a cell magic by name.
2485 2494
2486 2495 Returns None if the magic isn't found."""
2487 2496 return self.magics_manager.magics['cell'].get(magic_name)
2488 2497
2489 2498 def find_magic(self, magic_name, magic_kind='line'):
2490 2499 """Find and return a magic of the given type by name.
2491 2500
2492 2501 Returns None if the magic isn't found."""
2493 2502 return self.magics_manager.magics[magic_kind].get(magic_name)
2494 2503
2495 2504 def magic(self, arg_s):
2496 2505 """
2497 2506 DEPRECATED
2498 2507
2499 2508 Deprecated since IPython 0.13 (warning added in
2500 2509 8.1), use run_line_magic(magic_name, parameter_s).
2501 2510
2502 2511 Call a magic function by name.
2503 2512
2504 2513 Input: a string containing the name of the magic function to call and
2505 2514 any additional arguments to be passed to the magic.
2506 2515
2507 2516 magic('name -opt foo bar') is equivalent to typing at the ipython
2508 2517 prompt:
2509 2518
2510 2519 In[1]: %name -opt foo bar
2511 2520
2512 2521 To call a magic without arguments, simply use magic('name').
2513 2522
2514 2523 This provides a proper Python function to call IPython's magics in any
2515 2524 valid Python code you can type at the interpreter, including loops and
2516 2525 compound statements.
2517 2526 """
2518 2527 warnings.warn(
2519 2528 "`magic(...)` is deprecated since IPython 0.13 (warning added in "
2520 2529 "8.1), use run_line_magic(magic_name, parameter_s).",
2521 2530 DeprecationWarning,
2522 2531 stacklevel=2,
2523 2532 )
2524 2533 # TODO: should we issue a loud deprecation warning here?
2525 2534 magic_name, _, magic_arg_s = arg_s.partition(' ')
2526 2535 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2527 2536 return self.run_line_magic(magic_name, magic_arg_s, _stack_depth=2)
2528 2537
2529 2538 #-------------------------------------------------------------------------
2530 2539 # Things related to macros
2531 2540 #-------------------------------------------------------------------------
2532 2541
2533 2542 def define_macro(self, name, themacro):
2534 2543 """Define a new macro
2535 2544
2536 2545 Parameters
2537 2546 ----------
2538 2547 name : str
2539 2548 The name of the macro.
2540 2549 themacro : str or Macro
2541 2550 The action to do upon invoking the macro. If a string, a new
2542 2551 Macro object is created by passing the string to it.
2543 2552 """
2544 2553
2545 2554 from IPython.core import macro
2546 2555
2547 2556 if isinstance(themacro, str):
2548 2557 themacro = macro.Macro(themacro)
2549 2558 if not isinstance(themacro, macro.Macro):
2550 2559 raise ValueError('A macro must be a string or a Macro instance.')
2551 2560 self.user_ns[name] = themacro
2552 2561
2553 2562 #-------------------------------------------------------------------------
2554 2563 # Things related to the running of system commands
2555 2564 #-------------------------------------------------------------------------
2556 2565
2557 2566 def system_piped(self, cmd):
2558 2567 """Call the given cmd in a subprocess, piping stdout/err
2559 2568
2560 2569 Parameters
2561 2570 ----------
2562 2571 cmd : str
2563 2572 Command to execute (can not end in '&', as background processes are
2564 2573 not supported. Should not be a command that expects input
2565 2574 other than simple text.
2566 2575 """
2567 2576 if cmd.rstrip().endswith('&'):
2568 2577 # this is *far* from a rigorous test
2569 2578 # We do not support backgrounding processes because we either use
2570 2579 # pexpect or pipes to read from. Users can always just call
2571 2580 # os.system() or use ip.system=ip.system_raw
2572 2581 # if they really want a background process.
2573 2582 raise OSError("Background processes not supported.")
2574 2583
2575 2584 # we explicitly do NOT return the subprocess status code, because
2576 2585 # a non-None value would trigger :func:`sys.displayhook` calls.
2577 2586 # Instead, we store the exit_code in user_ns.
2578 2587 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2579 2588
2580 2589 def system_raw(self, cmd):
2581 2590 """Call the given cmd in a subprocess using os.system on Windows or
2582 2591 subprocess.call using the system shell on other platforms.
2583 2592
2584 2593 Parameters
2585 2594 ----------
2586 2595 cmd : str
2587 2596 Command to execute.
2588 2597 """
2589 2598 cmd = self.var_expand(cmd, depth=1)
2590 2599 # warn if there is an IPython magic alternative.
2591 2600 main_cmd = cmd.split()[0]
2592 2601 has_magic_alternatives = ("pip", "conda", "cd")
2593 2602
2594 2603 if main_cmd in has_magic_alternatives:
2595 2604 warnings.warn(
2596 2605 (
2597 2606 "You executed the system command !{0} which may not work "
2598 2607 "as expected. Try the IPython magic %{0} instead."
2599 2608 ).format(main_cmd)
2600 2609 )
2601 2610
2602 2611 # protect os.system from UNC paths on Windows, which it can't handle:
2603 2612 if sys.platform == 'win32':
2604 2613 from IPython.utils._process_win32 import AvoidUNCPath
2605 2614 with AvoidUNCPath() as path:
2606 2615 if path is not None:
2607 2616 cmd = '"pushd %s &&"%s' % (path, cmd)
2608 2617 try:
2609 2618 ec = os.system(cmd)
2610 2619 except KeyboardInterrupt:
2611 2620 print('\n' + self.get_exception_only(), file=sys.stderr)
2612 2621 ec = -2
2613 2622 else:
2614 2623 # For posix the result of the subprocess.call() below is an exit
2615 2624 # code, which by convention is zero for success, positive for
2616 2625 # program failure. Exit codes above 128 are reserved for signals,
2617 2626 # and the formula for converting a signal to an exit code is usually
2618 2627 # signal_number+128. To more easily differentiate between exit
2619 2628 # codes and signals, ipython uses negative numbers. For instance
2620 2629 # since control-c is signal 2 but exit code 130, ipython's
2621 2630 # _exit_code variable will read -2. Note that some shells like
2622 2631 # csh and fish don't follow sh/bash conventions for exit codes.
2623 2632 executable = os.environ.get('SHELL', None)
2624 2633 try:
2625 2634 # Use env shell instead of default /bin/sh
2626 2635 ec = subprocess.call(cmd, shell=True, executable=executable)
2627 2636 except KeyboardInterrupt:
2628 2637 # intercept control-C; a long traceback is not useful here
2629 2638 print('\n' + self.get_exception_only(), file=sys.stderr)
2630 2639 ec = 130
2631 2640 if ec > 128:
2632 2641 ec = -(ec - 128)
2633 2642
2634 2643 # We explicitly do NOT return the subprocess status code, because
2635 2644 # a non-None value would trigger :func:`sys.displayhook` calls.
2636 2645 # Instead, we store the exit_code in user_ns. Note the semantics
2637 2646 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,
2638 2647 # but raising SystemExit(_exit_code) will give status 254!
2639 2648 self.user_ns['_exit_code'] = ec
2640 2649
2641 2650 # use piped system by default, because it is better behaved
2642 2651 system = system_piped
2643 2652
2644 2653 def getoutput(self, cmd, split=True, depth=0):
2645 2654 """Get output (possibly including stderr) from a subprocess.
2646 2655
2647 2656 Parameters
2648 2657 ----------
2649 2658 cmd : str
2650 2659 Command to execute (can not end in '&', as background processes are
2651 2660 not supported.
2652 2661 split : bool, optional
2653 2662 If True, split the output into an IPython SList. Otherwise, an
2654 2663 IPython LSString is returned. These are objects similar to normal
2655 2664 lists and strings, with a few convenience attributes for easier
2656 2665 manipulation of line-based output. You can use '?' on them for
2657 2666 details.
2658 2667 depth : int, optional
2659 2668 How many frames above the caller are the local variables which should
2660 2669 be expanded in the command string? The default (0) assumes that the
2661 2670 expansion variables are in the stack frame calling this function.
2662 2671 """
2663 2672 if cmd.rstrip().endswith('&'):
2664 2673 # this is *far* from a rigorous test
2665 2674 raise OSError("Background processes not supported.")
2666 2675 out = getoutput(self.var_expand(cmd, depth=depth+1))
2667 2676 if split:
2668 2677 out = SList(out.splitlines())
2669 2678 else:
2670 2679 out = LSString(out)
2671 2680 return out
2672 2681
2673 2682 #-------------------------------------------------------------------------
2674 2683 # Things related to aliases
2675 2684 #-------------------------------------------------------------------------
2676 2685
2677 2686 def init_alias(self):
2678 2687 self.alias_manager = AliasManager(shell=self, parent=self)
2679 2688 self.configurables.append(self.alias_manager)
2680 2689
2681 2690 #-------------------------------------------------------------------------
2682 2691 # Things related to extensions
2683 2692 #-------------------------------------------------------------------------
2684 2693
2685 2694 def init_extension_manager(self):
2686 2695 self.extension_manager = ExtensionManager(shell=self, parent=self)
2687 2696 self.configurables.append(self.extension_manager)
2688 2697
2689 2698 #-------------------------------------------------------------------------
2690 2699 # Things related to payloads
2691 2700 #-------------------------------------------------------------------------
2692 2701
2693 2702 def init_payload(self):
2694 2703 self.payload_manager = PayloadManager(parent=self)
2695 2704 self.configurables.append(self.payload_manager)
2696 2705
2697 2706 #-------------------------------------------------------------------------
2698 2707 # Things related to the prefilter
2699 2708 #-------------------------------------------------------------------------
2700 2709
2701 2710 def init_prefilter(self):
2702 2711 self.prefilter_manager = PrefilterManager(shell=self, parent=self)
2703 2712 self.configurables.append(self.prefilter_manager)
2704 2713 # Ultimately this will be refactored in the new interpreter code, but
2705 2714 # for now, we should expose the main prefilter method (there's legacy
2706 2715 # code out there that may rely on this).
2707 2716 self.prefilter = self.prefilter_manager.prefilter_lines
2708 2717
2709 2718 def auto_rewrite_input(self, cmd):
2710 2719 """Print to the screen the rewritten form of the user's command.
2711 2720
2712 2721 This shows visual feedback by rewriting input lines that cause
2713 2722 automatic calling to kick in, like::
2714 2723
2715 2724 /f x
2716 2725
2717 2726 into::
2718 2727
2719 2728 ------> f(x)
2720 2729
2721 2730 after the user's input prompt. This helps the user understand that the
2722 2731 input line was transformed automatically by IPython.
2723 2732 """
2724 2733 if not self.show_rewritten_input:
2725 2734 return
2726 2735
2727 2736 # This is overridden in TerminalInteractiveShell to use fancy prompts
2728 2737 print("------> " + cmd)
2729 2738
2730 2739 #-------------------------------------------------------------------------
2731 2740 # Things related to extracting values/expressions from kernel and user_ns
2732 2741 #-------------------------------------------------------------------------
2733 2742
2734 2743 def _user_obj_error(self):
2735 2744 """return simple exception dict
2736 2745
2737 2746 for use in user_expressions
2738 2747 """
2739 2748
2740 2749 etype, evalue, tb = self._get_exc_info()
2741 2750 stb = self.InteractiveTB.get_exception_only(etype, evalue)
2742 2751
2743 2752 exc_info = {
2744 2753 "status": "error",
2745 2754 "traceback": stb,
2746 2755 "ename": etype.__name__,
2747 2756 "evalue": py3compat.safe_unicode(evalue),
2748 2757 }
2749 2758
2750 2759 return exc_info
2751 2760
2752 2761 def _format_user_obj(self, obj):
2753 2762 """format a user object to display dict
2754 2763
2755 2764 for use in user_expressions
2756 2765 """
2757 2766
2758 2767 data, md = self.display_formatter.format(obj)
2759 2768 value = {
2760 2769 'status' : 'ok',
2761 2770 'data' : data,
2762 2771 'metadata' : md,
2763 2772 }
2764 2773 return value
2765 2774
2766 2775 def user_expressions(self, expressions):
2767 2776 """Evaluate a dict of expressions in the user's namespace.
2768 2777
2769 2778 Parameters
2770 2779 ----------
2771 2780 expressions : dict
2772 2781 A dict with string keys and string values. The expression values
2773 2782 should be valid Python expressions, each of which will be evaluated
2774 2783 in the user namespace.
2775 2784
2776 2785 Returns
2777 2786 -------
2778 2787 A dict, keyed like the input expressions dict, with the rich mime-typed
2779 2788 display_data of each value.
2780 2789 """
2781 2790 out = {}
2782 2791 user_ns = self.user_ns
2783 2792 global_ns = self.user_global_ns
2784 2793
2785 2794 for key, expr in expressions.items():
2786 2795 try:
2787 2796 value = self._format_user_obj(eval(expr, global_ns, user_ns))
2788 2797 except:
2789 2798 value = self._user_obj_error()
2790 2799 out[key] = value
2791 2800 return out
2792 2801
2793 2802 #-------------------------------------------------------------------------
2794 2803 # Things related to the running of code
2795 2804 #-------------------------------------------------------------------------
2796 2805
2797 2806 def ex(self, cmd):
2798 2807 """Execute a normal python statement in user namespace."""
2799 2808 with self.builtin_trap:
2800 2809 exec(cmd, self.user_global_ns, self.user_ns)
2801 2810
2802 2811 def ev(self, expr):
2803 2812 """Evaluate python expression expr in user namespace.
2804 2813
2805 2814 Returns the result of evaluation
2806 2815 """
2807 2816 with self.builtin_trap:
2808 2817 return eval(expr, self.user_global_ns, self.user_ns)
2809 2818
2810 2819 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):
2811 2820 """A safe version of the builtin execfile().
2812 2821
2813 2822 This version will never throw an exception, but instead print
2814 2823 helpful error messages to the screen. This only works on pure
2815 2824 Python files with the .py extension.
2816 2825
2817 2826 Parameters
2818 2827 ----------
2819 2828 fname : string
2820 2829 The name of the file to be executed.
2821 2830 *where : tuple
2822 2831 One or two namespaces, passed to execfile() as (globals,locals).
2823 2832 If only one is given, it is passed as both.
2824 2833 exit_ignore : bool (False)
2825 2834 If True, then silence SystemExit for non-zero status (it is always
2826 2835 silenced for zero status, as it is so common).
2827 2836 raise_exceptions : bool (False)
2828 2837 If True raise exceptions everywhere. Meant for testing.
2829 2838 shell_futures : bool (False)
2830 2839 If True, the code will share future statements with the interactive
2831 2840 shell. It will both be affected by previous __future__ imports, and
2832 2841 any __future__ imports in the code will affect the shell. If False,
2833 2842 __future__ imports are not shared in either direction.
2834 2843
2835 2844 """
2836 2845 fname = Path(fname).expanduser().resolve()
2837 2846
2838 2847 # Make sure we can open the file
2839 2848 try:
2840 2849 with fname.open("rb"):
2841 2850 pass
2842 2851 except:
2843 2852 warn('Could not open file <%s> for safe execution.' % fname)
2844 2853 return
2845 2854
2846 2855 # Find things also in current directory. This is needed to mimic the
2847 2856 # behavior of running a script from the system command line, where
2848 2857 # Python inserts the script's directory into sys.path
2849 2858 dname = str(fname.parent)
2850 2859
2851 2860 with prepended_to_syspath(dname), self.builtin_trap:
2852 2861 try:
2853 2862 glob, loc = (where + (None, ))[:2]
2854 2863 py3compat.execfile(
2855 2864 fname, glob, loc,
2856 2865 self.compile if shell_futures else None)
2857 2866 except SystemExit as status:
2858 2867 # If the call was made with 0 or None exit status (sys.exit(0)
2859 2868 # or sys.exit() ), don't bother showing a traceback, as both of
2860 2869 # these are considered normal by the OS:
2861 2870 # > python -c'import sys;sys.exit(0)'; echo $?
2862 2871 # 0
2863 2872 # > python -c'import sys;sys.exit()'; echo $?
2864 2873 # 0
2865 2874 # For other exit status, we show the exception unless
2866 2875 # explicitly silenced, but only in short form.
2867 2876 if status.code:
2868 2877 if raise_exceptions:
2869 2878 raise
2870 2879 if not exit_ignore:
2871 2880 self.showtraceback(exception_only=True)
2872 2881 except:
2873 2882 if raise_exceptions:
2874 2883 raise
2875 2884 # tb offset is 2 because we wrap execfile
2876 2885 self.showtraceback(tb_offset=2)
2877 2886
2878 2887 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):
2879 2888 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.
2880 2889
2881 2890 Parameters
2882 2891 ----------
2883 2892 fname : str
2884 2893 The name of the file to execute. The filename must have a
2885 2894 .ipy or .ipynb extension.
2886 2895 shell_futures : bool (False)
2887 2896 If True, the code will share future statements with the interactive
2888 2897 shell. It will both be affected by previous __future__ imports, and
2889 2898 any __future__ imports in the code will affect the shell. If False,
2890 2899 __future__ imports are not shared in either direction.
2891 2900 raise_exceptions : bool (False)
2892 2901 If True raise exceptions everywhere. Meant for testing.
2893 2902 """
2894 2903 fname = Path(fname).expanduser().resolve()
2895 2904
2896 2905 # Make sure we can open the file
2897 2906 try:
2898 2907 with fname.open("rb"):
2899 2908 pass
2900 2909 except:
2901 2910 warn('Could not open file <%s> for safe execution.' % fname)
2902 2911 return
2903 2912
2904 2913 # Find things also in current directory. This is needed to mimic the
2905 2914 # behavior of running a script from the system command line, where
2906 2915 # Python inserts the script's directory into sys.path
2907 2916 dname = str(fname.parent)
2908 2917
2909 2918 def get_cells():
2910 2919 """generator for sequence of code blocks to run"""
2911 2920 if fname.suffix == ".ipynb":
2912 2921 from nbformat import read
2913 2922 nb = read(fname, as_version=4)
2914 2923 if not nb.cells:
2915 2924 return
2916 2925 for cell in nb.cells:
2917 2926 if cell.cell_type == 'code':
2918 2927 yield cell.source
2919 2928 else:
2920 2929 yield fname.read_text(encoding="utf-8")
2921 2930
2922 2931 with prepended_to_syspath(dname):
2923 2932 try:
2924 2933 for cell in get_cells():
2925 2934 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)
2926 2935 if raise_exceptions:
2927 2936 result.raise_error()
2928 2937 elif not result.success:
2929 2938 break
2930 2939 except:
2931 2940 if raise_exceptions:
2932 2941 raise
2933 2942 self.showtraceback()
2934 2943 warn('Unknown failure executing file: <%s>' % fname)
2935 2944
2936 2945 def safe_run_module(self, mod_name, where):
2937 2946 """A safe version of runpy.run_module().
2938 2947
2939 2948 This version will never throw an exception, but instead print
2940 2949 helpful error messages to the screen.
2941 2950
2942 2951 `SystemExit` exceptions with status code 0 or None are ignored.
2943 2952
2944 2953 Parameters
2945 2954 ----------
2946 2955 mod_name : string
2947 2956 The name of the module to be executed.
2948 2957 where : dict
2949 2958 The globals namespace.
2950 2959 """
2951 2960 try:
2952 2961 try:
2953 2962 where.update(
2954 2963 runpy.run_module(str(mod_name), run_name="__main__",
2955 2964 alter_sys=True)
2956 2965 )
2957 2966 except SystemExit as status:
2958 2967 if status.code:
2959 2968 raise
2960 2969 except:
2961 2970 self.showtraceback()
2962 2971 warn('Unknown failure executing module: <%s>' % mod_name)
2963 2972
2964 2973 def run_cell(
2965 2974 self,
2966 2975 raw_cell,
2967 2976 store_history=False,
2968 2977 silent=False,
2969 2978 shell_futures=True,
2970 2979 cell_id=None,
2971 2980 ):
2972 2981 """Run a complete IPython cell.
2973 2982
2974 2983 Parameters
2975 2984 ----------
2976 2985 raw_cell : str
2977 2986 The code (including IPython code such as %magic functions) to run.
2978 2987 store_history : bool
2979 2988 If True, the raw and translated cell will be stored in IPython's
2980 2989 history. For user code calling back into IPython's machinery, this
2981 2990 should be set to False.
2982 2991 silent : bool
2983 2992 If True, avoid side-effects, such as implicit displayhooks and
2984 2993 and logging. silent=True forces store_history=False.
2985 2994 shell_futures : bool
2986 2995 If True, the code will share future statements with the interactive
2987 2996 shell. It will both be affected by previous __future__ imports, and
2988 2997 any __future__ imports in the code will affect the shell. If False,
2989 2998 __future__ imports are not shared in either direction.
2990 2999
2991 3000 Returns
2992 3001 -------
2993 3002 result : :class:`ExecutionResult`
2994 3003 """
2995 3004 result = None
2996 3005 try:
2997 3006 result = self._run_cell(
2998 3007 raw_cell, store_history, silent, shell_futures, cell_id
2999 3008 )
3000 3009 finally:
3001 3010 self.events.trigger('post_execute')
3002 3011 if not silent:
3003 3012 self.events.trigger('post_run_cell', result)
3004 3013 return result
3005 3014
3006 3015 def _run_cell(
3007 3016 self,
3008 3017 raw_cell: str,
3009 3018 store_history: bool,
3010 3019 silent: bool,
3011 3020 shell_futures: bool,
3012 3021 cell_id: str,
3013 3022 ) -> ExecutionResult:
3014 3023 """Internal method to run a complete IPython cell."""
3015 3024
3016 3025 # we need to avoid calling self.transform_cell multiple time on the same thing
3017 3026 # so we need to store some results:
3018 3027 preprocessing_exc_tuple = None
3019 3028 try:
3020 3029 transformed_cell = self.transform_cell(raw_cell)
3021 3030 except Exception:
3022 3031 transformed_cell = raw_cell
3023 3032 preprocessing_exc_tuple = sys.exc_info()
3024 3033
3025 3034 assert transformed_cell is not None
3026 3035 coro = self.run_cell_async(
3027 3036 raw_cell,
3028 3037 store_history=store_history,
3029 3038 silent=silent,
3030 3039 shell_futures=shell_futures,
3031 3040 transformed_cell=transformed_cell,
3032 3041 preprocessing_exc_tuple=preprocessing_exc_tuple,
3033 3042 cell_id=cell_id,
3034 3043 )
3035 3044
3036 3045 # run_cell_async is async, but may not actually need an eventloop.
3037 3046 # when this is the case, we want to run it using the pseudo_sync_runner
3038 3047 # so that code can invoke eventloops (for example via the %run , and
3039 3048 # `%paste` magic.
3040 3049 if self.trio_runner:
3041 3050 runner = self.trio_runner
3042 3051 elif self.should_run_async(
3043 3052 raw_cell,
3044 3053 transformed_cell=transformed_cell,
3045 3054 preprocessing_exc_tuple=preprocessing_exc_tuple,
3046 3055 ):
3047 3056 runner = self.loop_runner
3048 3057 else:
3049 3058 runner = _pseudo_sync_runner
3050 3059
3051 3060 try:
3052 3061 result = runner(coro)
3053 3062 except BaseException as e:
3054 3063 info = ExecutionInfo(
3055 3064 raw_cell, store_history, silent, shell_futures, cell_id
3056 3065 )
3057 3066 result = ExecutionResult(info)
3058 3067 result.error_in_exec = e
3059 3068 self.showtraceback(running_compiled_code=True)
3060 3069 finally:
3061 3070 return result
3062 3071
3063 3072 def should_run_async(
3064 3073 self, raw_cell: str, *, transformed_cell=None, preprocessing_exc_tuple=None
3065 3074 ) -> bool:
3066 3075 """Return whether a cell should be run asynchronously via a coroutine runner
3067 3076
3068 3077 Parameters
3069 3078 ----------
3070 3079 raw_cell : str
3071 3080 The code to be executed
3072 3081
3073 3082 Returns
3074 3083 -------
3075 3084 result: bool
3076 3085 Whether the code needs to be run with a coroutine runner or not
3077 3086 .. versionadded:: 7.0
3078 3087 """
3079 3088 if not self.autoawait:
3080 3089 return False
3081 3090 if preprocessing_exc_tuple is not None:
3082 3091 return False
3083 3092 assert preprocessing_exc_tuple is None
3084 3093 if transformed_cell is None:
3085 3094 warnings.warn(
3086 3095 "`should_run_async` will not call `transform_cell`"
3087 3096 " automatically in the future. Please pass the result to"
3088 3097 " `transformed_cell` argument and any exception that happen"
3089 3098 " during the"
3090 3099 "transform in `preprocessing_exc_tuple` in"
3091 3100 " IPython 7.17 and above.",
3092 3101 DeprecationWarning,
3093 3102 stacklevel=2,
3094 3103 )
3095 3104 try:
3096 3105 cell = self.transform_cell(raw_cell)
3097 3106 except Exception:
3098 3107 # any exception during transform will be raised
3099 3108 # prior to execution
3100 3109 return False
3101 3110 else:
3102 3111 cell = transformed_cell
3103 3112 return _should_be_async(cell)
3104 3113
3105 3114 async def run_cell_async(
3106 3115 self,
3107 3116 raw_cell: str,
3108 3117 store_history=False,
3109 3118 silent=False,
3110 3119 shell_futures=True,
3111 3120 *,
3112 3121 transformed_cell: Optional[str] = None,
3113 3122 preprocessing_exc_tuple: Optional[AnyType] = None,
3114 3123 cell_id=None,
3115 3124 ) -> ExecutionResult:
3116 3125 """Run a complete IPython cell asynchronously.
3117 3126
3118 3127 Parameters
3119 3128 ----------
3120 3129 raw_cell : str
3121 3130 The code (including IPython code such as %magic functions) to run.
3122 3131 store_history : bool
3123 3132 If True, the raw and translated cell will be stored in IPython's
3124 3133 history. For user code calling back into IPython's machinery, this
3125 3134 should be set to False.
3126 3135 silent : bool
3127 3136 If True, avoid side-effects, such as implicit displayhooks and
3128 3137 and logging. silent=True forces store_history=False.
3129 3138 shell_futures : bool
3130 3139 If True, the code will share future statements with the interactive
3131 3140 shell. It will both be affected by previous __future__ imports, and
3132 3141 any __future__ imports in the code will affect the shell. If False,
3133 3142 __future__ imports are not shared in either direction.
3134 3143 transformed_cell: str
3135 3144 cell that was passed through transformers
3136 3145 preprocessing_exc_tuple:
3137 3146 trace if the transformation failed.
3138 3147
3139 3148 Returns
3140 3149 -------
3141 3150 result : :class:`ExecutionResult`
3142 3151
3143 3152 .. versionadded:: 7.0
3144 3153 """
3145 3154 info = ExecutionInfo(raw_cell, store_history, silent, shell_futures, cell_id)
3146 3155 result = ExecutionResult(info)
3147 3156
3148 3157 if (not raw_cell) or raw_cell.isspace():
3149 3158 self.last_execution_succeeded = True
3150 3159 self.last_execution_result = result
3151 3160 return result
3152 3161
3153 3162 if silent:
3154 3163 store_history = False
3155 3164
3156 3165 if store_history:
3157 3166 result.execution_count = self.execution_count
3158 3167
3159 3168 def error_before_exec(value):
3160 3169 if store_history:
3161 3170 self.execution_count += 1
3162 3171 result.error_before_exec = value
3163 3172 self.last_execution_succeeded = False
3164 3173 self.last_execution_result = result
3165 3174 return result
3166 3175
3167 3176 self.events.trigger('pre_execute')
3168 3177 if not silent:
3169 3178 self.events.trigger('pre_run_cell', info)
3170 3179
3171 3180 if transformed_cell is None:
3172 3181 warnings.warn(
3173 3182 "`run_cell_async` will not call `transform_cell`"
3174 3183 " automatically in the future. Please pass the result to"
3175 3184 " `transformed_cell` argument and any exception that happen"
3176 3185 " during the"
3177 3186 "transform in `preprocessing_exc_tuple` in"
3178 3187 " IPython 7.17 and above.",
3179 3188 DeprecationWarning,
3180 3189 stacklevel=2,
3181 3190 )
3182 3191 # If any of our input transformation (input_transformer_manager or
3183 3192 # prefilter_manager) raises an exception, we store it in this variable
3184 3193 # so that we can display the error after logging the input and storing
3185 3194 # it in the history.
3186 3195 try:
3187 3196 cell = self.transform_cell(raw_cell)
3188 3197 except Exception:
3189 3198 preprocessing_exc_tuple = sys.exc_info()
3190 3199 cell = raw_cell # cell has to exist so it can be stored/logged
3191 3200 else:
3192 3201 preprocessing_exc_tuple = None
3193 3202 else:
3194 3203 if preprocessing_exc_tuple is None:
3195 3204 cell = transformed_cell
3196 3205 else:
3197 3206 cell = raw_cell
3198 3207
3199 3208 # Do NOT store paste/cpaste magic history
3200 3209 if "get_ipython().run_line_magic(" in cell and "paste" in cell:
3201 3210 store_history = False
3202 3211
3203 3212 # Store raw and processed history
3204 3213 if store_history:
3205 3214 self.history_manager.store_inputs(self.execution_count, cell, raw_cell)
3206 3215 if not silent:
3207 3216 self.logger.log(cell, raw_cell)
3208 3217
3209 3218 # Display the exception if input processing failed.
3210 3219 if preprocessing_exc_tuple is not None:
3211 3220 self.showtraceback(preprocessing_exc_tuple)
3212 3221 if store_history:
3213 3222 self.execution_count += 1
3214 3223 return error_before_exec(preprocessing_exc_tuple[1])
3215 3224
3216 3225 # Our own compiler remembers the __future__ environment. If we want to
3217 3226 # run code with a separate __future__ environment, use the default
3218 3227 # compiler
3219 3228 compiler = self.compile if shell_futures else self.compiler_class()
3220 3229
3221 3230 _run_async = False
3222 3231
3223 3232 with self.builtin_trap:
3224 3233 cell_name = compiler.cache(cell, self.execution_count, raw_code=raw_cell)
3225 3234
3226 3235 with self.display_trap:
3227 3236 # Compile to bytecode
3228 3237 try:
3229 3238 code_ast = compiler.ast_parse(cell, filename=cell_name)
3230 3239 except self.custom_exceptions as e:
3231 3240 etype, value, tb = sys.exc_info()
3232 3241 self.CustomTB(etype, value, tb)
3233 3242 return error_before_exec(e)
3234 3243 except IndentationError as e:
3235 3244 self.showindentationerror()
3236 3245 return error_before_exec(e)
3237 3246 except (OverflowError, SyntaxError, ValueError, TypeError,
3238 3247 MemoryError) as e:
3239 3248 self.showsyntaxerror()
3240 3249 return error_before_exec(e)
3241 3250
3242 3251 # Apply AST transformations
3243 3252 try:
3244 3253 code_ast = self.transform_ast(code_ast)
3245 3254 except InputRejected as e:
3246 3255 self.showtraceback()
3247 3256 return error_before_exec(e)
3248 3257
3249 3258 # Give the displayhook a reference to our ExecutionResult so it
3250 3259 # can fill in the output value.
3251 3260 self.displayhook.exec_result = result
3252 3261
3253 3262 # Execute the user code
3254 3263 interactivity = "none" if silent else self.ast_node_interactivity
3255 3264
3256 3265
3257 3266 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,
3258 3267 interactivity=interactivity, compiler=compiler, result=result)
3259 3268
3260 3269 self.last_execution_succeeded = not has_raised
3261 3270 self.last_execution_result = result
3262 3271
3263 3272 # Reset this so later displayed values do not modify the
3264 3273 # ExecutionResult
3265 3274 self.displayhook.exec_result = None
3266 3275
3267 3276 if store_history:
3268 3277 # Write output to the database. Does nothing unless
3269 3278 # history output logging is enabled.
3270 3279 self.history_manager.store_output(self.execution_count)
3271 3280 # Each cell is a *single* input, regardless of how many lines it has
3272 3281 self.execution_count += 1
3273 3282
3274 3283 return result
3275 3284
3276 3285 def transform_cell(self, raw_cell):
3277 3286 """Transform an input cell before parsing it.
3278 3287
3279 3288 Static transformations, implemented in IPython.core.inputtransformer2,
3280 3289 deal with things like ``%magic`` and ``!system`` commands.
3281 3290 These run on all input.
3282 3291 Dynamic transformations, for things like unescaped magics and the exit
3283 3292 autocall, depend on the state of the interpreter.
3284 3293 These only apply to single line inputs.
3285 3294
3286 3295 These string-based transformations are followed by AST transformations;
3287 3296 see :meth:`transform_ast`.
3288 3297 """
3289 3298 # Static input transformations
3290 3299 cell = self.input_transformer_manager.transform_cell(raw_cell)
3291 3300
3292 3301 if len(cell.splitlines()) == 1:
3293 3302 # Dynamic transformations - only applied for single line commands
3294 3303 with self.builtin_trap:
3295 3304 # use prefilter_lines to handle trailing newlines
3296 3305 # restore trailing newline for ast.parse
3297 3306 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
3298 3307
3299 3308 lines = cell.splitlines(keepends=True)
3300 3309 for transform in self.input_transformers_post:
3301 3310 lines = transform(lines)
3302 3311 cell = ''.join(lines)
3303 3312
3304 3313 return cell
3305 3314
3306 3315 def transform_ast(self, node):
3307 3316 """Apply the AST transformations from self.ast_transformers
3308 3317
3309 3318 Parameters
3310 3319 ----------
3311 3320 node : ast.Node
3312 3321 The root node to be transformed. Typically called with the ast.Module
3313 3322 produced by parsing user input.
3314 3323
3315 3324 Returns
3316 3325 -------
3317 3326 An ast.Node corresponding to the node it was called with. Note that it
3318 3327 may also modify the passed object, so don't rely on references to the
3319 3328 original AST.
3320 3329 """
3321 3330 for transformer in self.ast_transformers:
3322 3331 try:
3323 3332 node = transformer.visit(node)
3324 3333 except InputRejected:
3325 3334 # User-supplied AST transformers can reject an input by raising
3326 3335 # an InputRejected. Short-circuit in this case so that we
3327 3336 # don't unregister the transform.
3328 3337 raise
3329 3338 except Exception:
3330 3339 warn("AST transformer %r threw an error. It will be unregistered." % transformer)
3331 3340 self.ast_transformers.remove(transformer)
3332 3341
3333 3342 if self.ast_transformers:
3334 3343 ast.fix_missing_locations(node)
3335 3344 return node
3336 3345
3337 3346 async def run_ast_nodes(
3338 3347 self,
3339 3348 nodelist: ListType[stmt],
3340 3349 cell_name: str,
3341 3350 interactivity="last_expr",
3342 3351 compiler=compile,
3343 3352 result=None,
3344 3353 ):
3345 3354 """Run a sequence of AST nodes. The execution mode depends on the
3346 3355 interactivity parameter.
3347 3356
3348 3357 Parameters
3349 3358 ----------
3350 3359 nodelist : list
3351 3360 A sequence of AST nodes to run.
3352 3361 cell_name : str
3353 3362 Will be passed to the compiler as the filename of the cell. Typically
3354 3363 the value returned by ip.compile.cache(cell).
3355 3364 interactivity : str
3356 3365 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',
3357 3366 specifying which nodes should be run interactively (displaying output
3358 3367 from expressions). 'last_expr' will run the last node interactively
3359 3368 only if it is an expression (i.e. expressions in loops or other blocks
3360 3369 are not displayed) 'last_expr_or_assign' will run the last expression
3361 3370 or the last assignment. Other values for this parameter will raise a
3362 3371 ValueError.
3363 3372
3364 3373 compiler : callable
3365 3374 A function with the same interface as the built-in compile(), to turn
3366 3375 the AST nodes into code objects. Default is the built-in compile().
3367 3376 result : ExecutionResult, optional
3368 3377 An object to store exceptions that occur during execution.
3369 3378
3370 3379 Returns
3371 3380 -------
3372 3381 True if an exception occurred while running code, False if it finished
3373 3382 running.
3374 3383 """
3375 3384 if not nodelist:
3376 3385 return
3377 3386
3378 3387
3379 3388 if interactivity == 'last_expr_or_assign':
3380 3389 if isinstance(nodelist[-1], _assign_nodes):
3381 3390 asg = nodelist[-1]
3382 3391 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:
3383 3392 target = asg.targets[0]
3384 3393 elif isinstance(asg, _single_targets_nodes):
3385 3394 target = asg.target
3386 3395 else:
3387 3396 target = None
3388 3397 if isinstance(target, ast.Name):
3389 3398 nnode = ast.Expr(ast.Name(target.id, ast.Load()))
3390 3399 ast.fix_missing_locations(nnode)
3391 3400 nodelist.append(nnode)
3392 3401 interactivity = 'last_expr'
3393 3402
3394 3403 _async = False
3395 3404 if interactivity == 'last_expr':
3396 3405 if isinstance(nodelist[-1], ast.Expr):
3397 3406 interactivity = "last"
3398 3407 else:
3399 3408 interactivity = "none"
3400 3409
3401 3410 if interactivity == 'none':
3402 3411 to_run_exec, to_run_interactive = nodelist, []
3403 3412 elif interactivity == 'last':
3404 3413 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
3405 3414 elif interactivity == 'all':
3406 3415 to_run_exec, to_run_interactive = [], nodelist
3407 3416 else:
3408 3417 raise ValueError("Interactivity was %r" % interactivity)
3409 3418
3410 3419 try:
3411 3420
3412 3421 def compare(code):
3413 3422 is_async = inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE
3414 3423 return is_async
3415 3424
3416 3425 # refactor that to just change the mod constructor.
3417 3426 to_run = []
3418 3427 for node in to_run_exec:
3419 3428 to_run.append((node, "exec"))
3420 3429
3421 3430 for node in to_run_interactive:
3422 3431 to_run.append((node, "single"))
3423 3432
3424 3433 for node, mode in to_run:
3425 3434 if mode == "exec":
3426 3435 mod = Module([node], [])
3427 3436 elif mode == "single":
3428 3437 mod = ast.Interactive([node]) # type: ignore
3429 3438 with compiler.extra_flags(
3430 3439 getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x0)
3431 3440 if self.autoawait
3432 3441 else 0x0
3433 3442 ):
3434 3443 code = compiler(mod, cell_name, mode)
3435 3444 asy = compare(code)
3436 3445 if await self.run_code(code, result, async_=asy):
3437 3446 return True
3438 3447
3439 3448 # Flush softspace
3440 3449 if softspace(sys.stdout, 0):
3441 3450 print()
3442 3451
3443 3452 except:
3444 3453 # It's possible to have exceptions raised here, typically by
3445 3454 # compilation of odd code (such as a naked 'return' outside a
3446 3455 # function) that did parse but isn't valid. Typically the exception
3447 3456 # is a SyntaxError, but it's safest just to catch anything and show
3448 3457 # the user a traceback.
3449 3458
3450 3459 # We do only one try/except outside the loop to minimize the impact
3451 3460 # on runtime, and also because if any node in the node list is
3452 3461 # broken, we should stop execution completely.
3453 3462 if result:
3454 3463 result.error_before_exec = sys.exc_info()[1]
3455 3464 self.showtraceback()
3456 3465 return True
3457 3466
3458 3467 return False
3459 3468
3460 3469 async def run_code(self, code_obj, result=None, *, async_=False):
3461 3470 """Execute a code object.
3462 3471
3463 3472 When an exception occurs, self.showtraceback() is called to display a
3464 3473 traceback.
3465 3474
3466 3475 Parameters
3467 3476 ----------
3468 3477 code_obj : code object
3469 3478 A compiled code object, to be executed
3470 3479 result : ExecutionResult, optional
3471 3480 An object to store exceptions that occur during execution.
3472 3481 async_ : Bool (Experimental)
3473 3482 Attempt to run top-level asynchronous code in a default loop.
3474 3483
3475 3484 Returns
3476 3485 -------
3477 3486 False : successful execution.
3478 3487 True : an error occurred.
3479 3488 """
3480 3489 # special value to say that anything above is IPython and should be
3481 3490 # hidden.
3482 3491 __tracebackhide__ = "__ipython_bottom__"
3483 3492 # Set our own excepthook in case the user code tries to call it
3484 3493 # directly, so that the IPython crash handler doesn't get triggered
3485 3494 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook
3486 3495
3487 3496 # we save the original sys.excepthook in the instance, in case config
3488 3497 # code (such as magics) needs access to it.
3489 3498 self.sys_excepthook = old_excepthook
3490 3499 outflag = True # happens in more places, so it's easier as default
3491 3500 try:
3492 3501 try:
3493 3502 if async_:
3494 3503 await eval(code_obj, self.user_global_ns, self.user_ns)
3495 3504 else:
3496 3505 exec(code_obj, self.user_global_ns, self.user_ns)
3497 3506 finally:
3498 3507 # Reset our crash handler in place
3499 3508 sys.excepthook = old_excepthook
3500 3509 except SystemExit as e:
3501 3510 if result is not None:
3502 3511 result.error_in_exec = e
3503 3512 self.showtraceback(exception_only=True)
3504 3513 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)
3505 3514 except bdb.BdbQuit:
3506 3515 etype, value, tb = sys.exc_info()
3507 3516 if result is not None:
3508 3517 result.error_in_exec = value
3509 3518 # the BdbQuit stops here
3510 3519 except self.custom_exceptions:
3511 3520 etype, value, tb = sys.exc_info()
3512 3521 if result is not None:
3513 3522 result.error_in_exec = value
3514 3523 self.CustomTB(etype, value, tb)
3515 3524 except:
3516 3525 if result is not None:
3517 3526 result.error_in_exec = sys.exc_info()[1]
3518 3527 self.showtraceback(running_compiled_code=True)
3519 3528 else:
3520 3529 outflag = False
3521 3530 return outflag
3522 3531
3523 3532 # For backwards compatibility
3524 3533 runcode = run_code
3525 3534
3526 3535 def check_complete(self, code: str) -> Tuple[str, str]:
3527 3536 """Return whether a block of code is ready to execute, or should be continued
3528 3537
3529 3538 Parameters
3530 3539 ----------
3531 3540 code : string
3532 3541 Python input code, which can be multiline.
3533 3542
3534 3543 Returns
3535 3544 -------
3536 3545 status : str
3537 3546 One of 'complete', 'incomplete', or 'invalid' if source is not a
3538 3547 prefix of valid code.
3539 3548 indent : str
3540 3549 When status is 'incomplete', this is some whitespace to insert on
3541 3550 the next line of the prompt.
3542 3551 """
3543 3552 status, nspaces = self.input_transformer_manager.check_complete(code)
3544 3553 return status, ' ' * (nspaces or 0)
3545 3554
3546 3555 #-------------------------------------------------------------------------
3547 3556 # Things related to GUI support and pylab
3548 3557 #-------------------------------------------------------------------------
3549 3558
3550 3559 active_eventloop = None
3551 3560
3552 3561 def enable_gui(self, gui=None):
3553 3562 raise NotImplementedError('Implement enable_gui in a subclass')
3554 3563
3555 3564 def enable_matplotlib(self, gui=None):
3556 3565 """Enable interactive matplotlib and inline figure support.
3557 3566
3558 3567 This takes the following steps:
3559 3568
3560 3569 1. select the appropriate eventloop and matplotlib backend
3561 3570 2. set up matplotlib for interactive use with that backend
3562 3571 3. configure formatters for inline figure display
3563 3572 4. enable the selected gui eventloop
3564 3573
3565 3574 Parameters
3566 3575 ----------
3567 3576 gui : optional, string
3568 3577 If given, dictates the choice of matplotlib GUI backend to use
3569 3578 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3570 3579 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3571 3580 matplotlib (as dictated by the matplotlib build-time options plus the
3572 3581 user's matplotlibrc configuration file). Note that not all backends
3573 3582 make sense in all contexts, for example a terminal ipython can't
3574 3583 display figures inline.
3575 3584 """
3576 3585 from matplotlib_inline.backend_inline import configure_inline_support
3577 3586
3578 3587 from IPython.core import pylabtools as pt
3579 3588 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)
3580 3589
3581 3590 if gui != 'inline':
3582 3591 # If we have our first gui selection, store it
3583 3592 if self.pylab_gui_select is None:
3584 3593 self.pylab_gui_select = gui
3585 3594 # Otherwise if they are different
3586 3595 elif gui != self.pylab_gui_select:
3587 3596 print('Warning: Cannot change to a different GUI toolkit: %s.'
3588 3597 ' Using %s instead.' % (gui, self.pylab_gui_select))
3589 3598 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)
3590 3599
3591 3600 pt.activate_matplotlib(backend)
3592 3601 configure_inline_support(self, backend)
3593 3602
3594 3603 # Now we must activate the gui pylab wants to use, and fix %run to take
3595 3604 # plot updates into account
3596 3605 self.enable_gui(gui)
3597 3606 self.magics_manager.registry['ExecutionMagics'].default_runner = \
3598 3607 pt.mpl_runner(self.safe_execfile)
3599 3608
3600 3609 return gui, backend
3601 3610
3602 3611 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
3603 3612 """Activate pylab support at runtime.
3604 3613
3605 3614 This turns on support for matplotlib, preloads into the interactive
3606 3615 namespace all of numpy and pylab, and configures IPython to correctly
3607 3616 interact with the GUI event loop. The GUI backend to be used can be
3608 3617 optionally selected with the optional ``gui`` argument.
3609 3618
3610 3619 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.
3611 3620
3612 3621 Parameters
3613 3622 ----------
3614 3623 gui : optional, string
3615 3624 If given, dictates the choice of matplotlib GUI backend to use
3616 3625 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
3617 3626 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
3618 3627 matplotlib (as dictated by the matplotlib build-time options plus the
3619 3628 user's matplotlibrc configuration file). Note that not all backends
3620 3629 make sense in all contexts, for example a terminal ipython can't
3621 3630 display figures inline.
3622 3631 import_all : optional, bool, default: True
3623 3632 Whether to do `from numpy import *` and `from pylab import *`
3624 3633 in addition to module imports.
3625 3634 welcome_message : deprecated
3626 3635 This argument is ignored, no welcome message will be displayed.
3627 3636 """
3628 3637 from IPython.core.pylabtools import import_pylab
3629 3638
3630 3639 gui, backend = self.enable_matplotlib(gui)
3631 3640
3632 3641 # We want to prevent the loading of pylab to pollute the user's
3633 3642 # namespace as shown by the %who* magics, so we execute the activation
3634 3643 # code in an empty namespace, and we update *both* user_ns and
3635 3644 # user_ns_hidden with this information.
3636 3645 ns = {}
3637 3646 import_pylab(ns, import_all)
3638 3647 # warn about clobbered names
3639 3648 ignored = {"__builtins__"}
3640 3649 both = set(ns).intersection(self.user_ns).difference(ignored)
3641 3650 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]
3642 3651 self.user_ns.update(ns)
3643 3652 self.user_ns_hidden.update(ns)
3644 3653 return gui, backend, clobbered
3645 3654
3646 3655 #-------------------------------------------------------------------------
3647 3656 # Utilities
3648 3657 #-------------------------------------------------------------------------
3649 3658
3650 3659 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
3651 3660 """Expand python variables in a string.
3652 3661
3653 3662 The depth argument indicates how many frames above the caller should
3654 3663 be walked to look for the local namespace where to expand variables.
3655 3664
3656 3665 The global namespace for expansion is always the user's interactive
3657 3666 namespace.
3658 3667 """
3659 3668 ns = self.user_ns.copy()
3660 3669 try:
3661 3670 frame = sys._getframe(depth+1)
3662 3671 except ValueError:
3663 3672 # This is thrown if there aren't that many frames on the stack,
3664 3673 # e.g. if a script called run_line_magic() directly.
3665 3674 pass
3666 3675 else:
3667 3676 ns.update(frame.f_locals)
3668 3677
3669 3678 try:
3670 3679 # We have to use .vformat() here, because 'self' is a valid and common
3671 3680 # name, and expanding **ns for .format() would make it collide with
3672 3681 # the 'self' argument of the method.
3673 3682 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
3674 3683 except Exception:
3675 3684 # if formatter couldn't format, just let it go untransformed
3676 3685 pass
3677 3686 return cmd
3678 3687
3679 3688 def mktempfile(self, data=None, prefix='ipython_edit_'):
3680 3689 """Make a new tempfile and return its filename.
3681 3690
3682 3691 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),
3683 3692 but it registers the created filename internally so ipython cleans it up
3684 3693 at exit time.
3685 3694
3686 3695 Optional inputs:
3687 3696
3688 3697 - data(None): if data is given, it gets written out to the temp file
3689 3698 immediately, and the file is closed again."""
3690 3699
3691 3700 dir_path = Path(tempfile.mkdtemp(prefix=prefix))
3692 3701 self.tempdirs.append(dir_path)
3693 3702
3694 3703 handle, filename = tempfile.mkstemp(".py", prefix, dir=str(dir_path))
3695 3704 os.close(handle) # On Windows, there can only be one open handle on a file
3696 3705
3697 3706 file_path = Path(filename)
3698 3707 self.tempfiles.append(file_path)
3699 3708
3700 3709 if data:
3701 3710 file_path.write_text(data, encoding="utf-8")
3702 3711 return filename
3703 3712
3704 3713 def ask_yes_no(self, prompt, default=None, interrupt=None):
3705 3714 if self.quiet:
3706 3715 return True
3707 3716 return ask_yes_no(prompt,default,interrupt)
3708 3717
3709 3718 def show_usage(self):
3710 3719 """Show a usage message"""
3711 3720 page.page(IPython.core.usage.interactive_usage)
3712 3721
3713 3722 def extract_input_lines(self, range_str, raw=False):
3714 3723 """Return as a string a set of input history slices.
3715 3724
3716 3725 Parameters
3717 3726 ----------
3718 3727 range_str : str
3719 3728 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
3720 3729 since this function is for use by magic functions which get their
3721 3730 arguments as strings. The number before the / is the session
3722 3731 number: ~n goes n back from the current session.
3723 3732
3724 3733 If empty string is given, returns history of current session
3725 3734 without the last input.
3726 3735
3727 3736 raw : bool, optional
3728 3737 By default, the processed input is used. If this is true, the raw
3729 3738 input history is used instead.
3730 3739
3731 3740 Notes
3732 3741 -----
3733 3742 Slices can be described with two notations:
3734 3743
3735 3744 * ``N:M`` -> standard python form, means including items N...(M-1).
3736 3745 * ``N-M`` -> include items N..M (closed endpoint).
3737 3746 """
3738 3747 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3739 3748 text = "\n".join(x for _, _, x in lines)
3740 3749
3741 3750 # Skip the last line, as it's probably the magic that called this
3742 3751 if not range_str:
3743 3752 if "\n" not in text:
3744 3753 text = ""
3745 3754 else:
3746 3755 text = text[: text.rfind("\n")]
3747 3756
3748 3757 return text
3749 3758
3750 3759 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):
3751 3760 """Get a code string from history, file, url, or a string or macro.
3752 3761
3753 3762 This is mainly used by magic functions.
3754 3763
3755 3764 Parameters
3756 3765 ----------
3757 3766 target : str
3758 3767 A string specifying code to retrieve. This will be tried respectively
3759 3768 as: ranges of input history (see %history for syntax), url,
3760 3769 corresponding .py file, filename, or an expression evaluating to a
3761 3770 string or Macro in the user namespace.
3762 3771
3763 3772 If empty string is given, returns complete history of current
3764 3773 session, without the last line.
3765 3774
3766 3775 raw : bool
3767 3776 If true (default), retrieve raw history. Has no effect on the other
3768 3777 retrieval mechanisms.
3769 3778
3770 3779 py_only : bool (default False)
3771 3780 Only try to fetch python code, do not try alternative methods to decode file
3772 3781 if unicode fails.
3773 3782
3774 3783 Returns
3775 3784 -------
3776 3785 A string of code.
3777 3786 ValueError is raised if nothing is found, and TypeError if it evaluates
3778 3787 to an object of another type. In each case, .args[0] is a printable
3779 3788 message.
3780 3789 """
3781 3790 code = self.extract_input_lines(target, raw=raw) # Grab history
3782 3791 if code:
3783 3792 return code
3784 3793 try:
3785 3794 if target.startswith(('http://', 'https://')):
3786 3795 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)
3787 3796 except UnicodeDecodeError as e:
3788 3797 if not py_only :
3789 3798 # Deferred import
3790 3799 from urllib.request import urlopen
3791 3800 response = urlopen(target)
3792 3801 return response.read().decode('latin1')
3793 3802 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3794 3803
3795 3804 potential_target = [target]
3796 3805 try :
3797 3806 potential_target.insert(0,get_py_filename(target))
3798 3807 except IOError:
3799 3808 pass
3800 3809
3801 3810 for tgt in potential_target :
3802 3811 if os.path.isfile(tgt): # Read file
3803 3812 try :
3804 3813 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)
3805 3814 except UnicodeDecodeError as e:
3806 3815 if not py_only :
3807 3816 with io_open(tgt,'r', encoding='latin1') as f :
3808 3817 return f.read()
3809 3818 raise ValueError(("'%s' seem to be unreadable.") % target) from e
3810 3819 elif os.path.isdir(os.path.expanduser(tgt)):
3811 3820 raise ValueError("'%s' is a directory, not a regular file." % target)
3812 3821
3813 3822 if search_ns:
3814 3823 # Inspect namespace to load object source
3815 3824 object_info = self.object_inspect(target, detail_level=1)
3816 3825 if object_info['found'] and object_info['source']:
3817 3826 return object_info['source']
3818 3827
3819 3828 try: # User namespace
3820 3829 codeobj = eval(target, self.user_ns)
3821 3830 except Exception as e:
3822 3831 raise ValueError(("'%s' was not found in history, as a file, url, "
3823 3832 "nor in the user namespace.") % target) from e
3824 3833
3825 3834 if isinstance(codeobj, str):
3826 3835 return codeobj
3827 3836 elif isinstance(codeobj, Macro):
3828 3837 return codeobj.value
3829 3838
3830 3839 raise TypeError("%s is neither a string nor a macro." % target,
3831 3840 codeobj)
3832 3841
3833 3842 def _atexit_once(self):
3834 3843 """
3835 3844 At exist operation that need to be called at most once.
3836 3845 Second call to this function per instance will do nothing.
3837 3846 """
3838 3847
3839 3848 if not getattr(self, "_atexit_once_called", False):
3840 3849 self._atexit_once_called = True
3841 3850 # Clear all user namespaces to release all references cleanly.
3842 3851 self.reset(new_session=False)
3843 3852 # Close the history session (this stores the end time and line count)
3844 3853 # this must be *before* the tempfile cleanup, in case of temporary
3845 3854 # history db
3846 3855 self.history_manager.end_session()
3847 3856 self.history_manager = None
3848 3857
3849 3858 #-------------------------------------------------------------------------
3850 3859 # Things related to IPython exiting
3851 3860 #-------------------------------------------------------------------------
3852 3861 def atexit_operations(self):
3853 3862 """This will be executed at the time of exit.
3854 3863
3855 3864 Cleanup operations and saving of persistent data that is done
3856 3865 unconditionally by IPython should be performed here.
3857 3866
3858 3867 For things that may depend on startup flags or platform specifics (such
3859 3868 as having readline or not), register a separate atexit function in the
3860 3869 code that has the appropriate information, rather than trying to
3861 3870 clutter
3862 3871 """
3863 3872 self._atexit_once()
3864 3873
3865 3874 # Cleanup all tempfiles and folders left around
3866 3875 for tfile in self.tempfiles:
3867 3876 try:
3868 3877 tfile.unlink()
3869 3878 self.tempfiles.remove(tfile)
3870 3879 except FileNotFoundError:
3871 3880 pass
3872 3881 del self.tempfiles
3873 3882 for tdir in self.tempdirs:
3874 3883 try:
3875 3884 tdir.rmdir()
3876 3885 self.tempdirs.remove(tdir)
3877 3886 except FileNotFoundError:
3878 3887 pass
3879 3888 del self.tempdirs
3880 3889
3881 3890 # Restore user's cursor
3882 3891 if hasattr(self, "editing_mode") and self.editing_mode == "vi":
3883 3892 sys.stdout.write("\x1b[0 q")
3884 3893 sys.stdout.flush()
3885 3894
3886 3895 def cleanup(self):
3887 3896 self.restore_sys_module_state()
3888 3897
3889 3898
3890 3899 # Overridden in terminal subclass to change prompts
3891 3900 def switch_doctest_mode(self, mode):
3892 3901 pass
3893 3902
3894 3903
3895 3904 class InteractiveShellABC(metaclass=abc.ABCMeta):
3896 3905 """An abstract base class for InteractiveShell."""
3897 3906
3898 3907 InteractiveShellABC.register(InteractiveShell)
@@ -1,1098 +1,1154
1 1 # -*- coding: utf-8 -*-
2 2 """Tools for inspecting Python objects.
3 3
4 4 Uses syntax highlighting for presenting the various information elements.
5 5
6 6 Similar in spirit to the inspect module, but all calls take a name argument to
7 7 reference the name under which an object is being read.
8 8 """
9 9
10 10 # Copyright (c) IPython Development Team.
11 11 # Distributed under the terms of the Modified BSD License.
12 12
13 13 __all__ = ['Inspector','InspectColors']
14 14
15 15 # stdlib modules
16 import ast
17 import inspect
16 from dataclasses import dataclass
18 17 from inspect import signature
18 from textwrap import dedent
19 import ast
19 20 import html
21 import inspect
22 import io as stdlib_io
20 23 import linecache
21 import warnings
22 24 import os
23 from textwrap import dedent
25 import sys
24 26 import types
25 import io as stdlib_io
27 import warnings
26 28
27 from typing import Union
29 from typing import Any, Optional, Dict, Union, List, Tuple
30
31 if sys.version_info <= (3, 10):
32 from typing_extensions import TypeAlias
33 else:
34 from typing import TypeAlias
28 35
29 36 # IPython's own
30 37 from IPython.core import page
31 38 from IPython.lib.pretty import pretty
32 39 from IPython.testing.skipdoctest import skip_doctest
33 40 from IPython.utils import PyColorize
34 41 from IPython.utils import openpy
35 42 from IPython.utils.dir2 import safe_hasattr
36 43 from IPython.utils.path import compress_user
37 44 from IPython.utils.text import indent
38 45 from IPython.utils.wildcard import list_namespace
39 46 from IPython.utils.wildcard import typestr2type
40 47 from IPython.utils.coloransi import TermColors, ColorScheme, ColorSchemeTable
41 48 from IPython.utils.py3compat import cast_unicode
42 49 from IPython.utils.colorable import Colorable
43 50 from IPython.utils.decorators import undoc
44 51
45 52 from pygments import highlight
46 53 from pygments.lexers import PythonLexer
47 54 from pygments.formatters import HtmlFormatter
48 55
49 from typing import Any, Optional
50 from dataclasses import dataclass
56 HOOK_NAME = "__custom_documentations__"
57
58
59 UnformattedBundle: TypeAlias = Dict[str, List[Tuple[str, str]]] # List of (title, body)
60 Bundle: TypeAlias = Dict[str, str]
51 61
52 62
53 63 @dataclass
54 64 class OInfo:
55 65 ismagic: bool
56 66 isalias: bool
57 67 found: bool
58 68 namespace: Optional[str]
59 69 parent: Any
60 70 obj: Any
61 71
62 72 def pylight(code):
63 73 return highlight(code, PythonLexer(), HtmlFormatter(noclasses=True))
64 74
65 75 # builtin docstrings to ignore
66 76 _func_call_docstring = types.FunctionType.__call__.__doc__
67 77 _object_init_docstring = object.__init__.__doc__
68 78 _builtin_type_docstrings = {
69 79 inspect.getdoc(t) for t in (types.ModuleType, types.MethodType,
70 80 types.FunctionType, property)
71 81 }
72 82
73 83 _builtin_func_type = type(all)
74 84 _builtin_meth_type = type(str.upper) # Bound methods have the same type as builtin functions
75 85 #****************************************************************************
76 86 # Builtin color schemes
77 87
78 88 Colors = TermColors # just a shorthand
79 89
80 90 InspectColors = PyColorize.ANSICodeColors
81 91
82 92 #****************************************************************************
83 93 # Auxiliary functions and objects
84 94
85 95 # See the messaging spec for the definition of all these fields. This list
86 96 # effectively defines the order of display
87 97 info_fields = ['type_name', 'base_class', 'string_form', 'namespace',
88 98 'length', 'file', 'definition', 'docstring', 'source',
89 99 'init_definition', 'class_docstring', 'init_docstring',
90 100 'call_def', 'call_docstring',
91 101 # These won't be printed but will be used to determine how to
92 102 # format the object
93 103 'ismagic', 'isalias', 'isclass', 'found', 'name'
94 104 ]
95 105
96 106
97 107 def object_info(**kw):
98 108 """Make an object info dict with all fields present."""
99 109 infodict = {k:None for k in info_fields}
100 110 infodict.update(kw)
101 111 return infodict
102 112
103 113
104 114 def get_encoding(obj):
105 115 """Get encoding for python source file defining obj
106 116
107 117 Returns None if obj is not defined in a sourcefile.
108 118 """
109 119 ofile = find_file(obj)
110 120 # run contents of file through pager starting at line where the object
111 121 # is defined, as long as the file isn't binary and is actually on the
112 122 # filesystem.
113 123 if ofile is None:
114 124 return None
115 125 elif ofile.endswith(('.so', '.dll', '.pyd')):
116 126 return None
117 127 elif not os.path.isfile(ofile):
118 128 return None
119 129 else:
120 130 # Print only text files, not extension binaries. Note that
121 131 # getsourcelines returns lineno with 1-offset and page() uses
122 132 # 0-offset, so we must adjust.
123 133 with stdlib_io.open(ofile, 'rb') as buffer: # Tweaked to use io.open for Python 2
124 134 encoding, lines = openpy.detect_encoding(buffer.readline)
125 135 return encoding
126 136
127 137 def getdoc(obj) -> Union[str,None]:
128 138 """Stable wrapper around inspect.getdoc.
129 139
130 140 This can't crash because of attribute problems.
131 141
132 142 It also attempts to call a getdoc() method on the given object. This
133 143 allows objects which provide their docstrings via non-standard mechanisms
134 144 (like Pyro proxies) to still be inspected by ipython's ? system.
135 145 """
136 146 # Allow objects to offer customized documentation via a getdoc method:
137 147 try:
138 148 ds = obj.getdoc()
139 149 except Exception:
140 150 pass
141 151 else:
142 152 if isinstance(ds, str):
143 153 return inspect.cleandoc(ds)
144 154 docstr = inspect.getdoc(obj)
145 155 return docstr
146 156
147 157
148 158 def getsource(obj, oname='') -> Union[str,None]:
149 159 """Wrapper around inspect.getsource.
150 160
151 161 This can be modified by other projects to provide customized source
152 162 extraction.
153 163
154 164 Parameters
155 165 ----------
156 166 obj : object
157 167 an object whose source code we will attempt to extract
158 168 oname : str
159 169 (optional) a name under which the object is known
160 170
161 171 Returns
162 172 -------
163 173 src : unicode or None
164 174
165 175 """
166 176
167 177 if isinstance(obj, property):
168 178 sources = []
169 179 for attrname in ['fget', 'fset', 'fdel']:
170 180 fn = getattr(obj, attrname)
171 181 if fn is not None:
172 182 encoding = get_encoding(fn)
173 183 oname_prefix = ('%s.' % oname) if oname else ''
174 184 sources.append(''.join(('# ', oname_prefix, attrname)))
175 185 if inspect.isfunction(fn):
176 186 _src = getsource(fn)
177 187 if _src:
178 188 # assert _src is not None, "please mypy"
179 189 sources.append(dedent(_src))
180 190 else:
181 191 # Default str/repr only prints function name,
182 192 # pretty.pretty prints module name too.
183 193 sources.append(
184 194 '%s%s = %s\n' % (oname_prefix, attrname, pretty(fn))
185 195 )
186 196 if sources:
187 197 return '\n'.join(sources)
188 198 else:
189 199 return None
190 200
191 201 else:
192 202 # Get source for non-property objects.
193 203
194 204 obj = _get_wrapped(obj)
195 205
196 206 try:
197 207 src = inspect.getsource(obj)
198 208 except TypeError:
199 209 # The object itself provided no meaningful source, try looking for
200 210 # its class definition instead.
201 211 try:
202 212 src = inspect.getsource(obj.__class__)
203 213 except (OSError, TypeError):
204 214 return None
205 215 except OSError:
206 216 return None
207 217
208 218 return src
209 219
210 220
211 221 def is_simple_callable(obj):
212 222 """True if obj is a function ()"""
213 223 return (inspect.isfunction(obj) or inspect.ismethod(obj) or \
214 224 isinstance(obj, _builtin_func_type) or isinstance(obj, _builtin_meth_type))
215 225
216 226 @undoc
217 227 def getargspec(obj):
218 228 """Wrapper around :func:`inspect.getfullargspec`
219 229
220 230 In addition to functions and methods, this can also handle objects with a
221 231 ``__call__`` attribute.
222 232
223 233 DEPRECATED: Deprecated since 7.10. Do not use, will be removed.
224 234 """
225 235
226 236 warnings.warn('`getargspec` function is deprecated as of IPython 7.10'
227 237 'and will be removed in future versions.', DeprecationWarning, stacklevel=2)
228 238
229 239 if safe_hasattr(obj, '__call__') and not is_simple_callable(obj):
230 240 obj = obj.__call__
231 241
232 242 return inspect.getfullargspec(obj)
233 243
234 244 @undoc
235 245 def format_argspec(argspec):
236 246 """Format argspect, convenience wrapper around inspect's.
237 247
238 248 This takes a dict instead of ordered arguments and calls
239 249 inspect.format_argspec with the arguments in the necessary order.
240 250
241 251 DEPRECATED (since 7.10): Do not use; will be removed in future versions.
242 252 """
243 253
244 254 warnings.warn('`format_argspec` function is deprecated as of IPython 7.10'
245 255 'and will be removed in future versions.', DeprecationWarning, stacklevel=2)
246 256
247 257
248 258 return inspect.formatargspec(argspec['args'], argspec['varargs'],
249 259 argspec['varkw'], argspec['defaults'])
250 260
251 261 @undoc
252 262 def call_tip(oinfo, format_call=True):
253 263 """DEPRECATED since 6.0. Extract call tip data from an oinfo dict."""
254 264 warnings.warn(
255 265 "`call_tip` function is deprecated as of IPython 6.0"
256 266 "and will be removed in future versions.",
257 267 DeprecationWarning,
258 268 stacklevel=2,
259 269 )
260 270 # Get call definition
261 271 argspec = oinfo.get('argspec')
262 272 if argspec is None:
263 273 call_line = None
264 274 else:
265 275 # Callable objects will have 'self' as their first argument, prune
266 276 # it out if it's there for clarity (since users do *not* pass an
267 277 # extra first argument explicitly).
268 278 try:
269 279 has_self = argspec['args'][0] == 'self'
270 280 except (KeyError, IndexError):
271 281 pass
272 282 else:
273 283 if has_self:
274 284 argspec['args'] = argspec['args'][1:]
275 285
276 286 call_line = oinfo['name']+format_argspec(argspec)
277 287
278 288 # Now get docstring.
279 289 # The priority is: call docstring, constructor docstring, main one.
280 290 doc = oinfo.get('call_docstring')
281 291 if doc is None:
282 292 doc = oinfo.get('init_docstring')
283 293 if doc is None:
284 294 doc = oinfo.get('docstring','')
285 295
286 296 return call_line, doc
287 297
288 298
289 299 def _get_wrapped(obj):
290 300 """Get the original object if wrapped in one or more @decorators
291 301
292 302 Some objects automatically construct similar objects on any unrecognised
293 303 attribute access (e.g. unittest.mock.call). To protect against infinite loops,
294 304 this will arbitrarily cut off after 100 levels of obj.__wrapped__
295 305 attribute access. --TK, Jan 2016
296 306 """
297 307 orig_obj = obj
298 308 i = 0
299 309 while safe_hasattr(obj, '__wrapped__'):
300 310 obj = obj.__wrapped__
301 311 i += 1
302 312 if i > 100:
303 313 # __wrapped__ is probably a lie, so return the thing we started with
304 314 return orig_obj
305 315 return obj
306 316
307 317 def find_file(obj) -> str:
308 318 """Find the absolute path to the file where an object was defined.
309 319
310 320 This is essentially a robust wrapper around `inspect.getabsfile`.
311 321
312 322 Returns None if no file can be found.
313 323
314 324 Parameters
315 325 ----------
316 326 obj : any Python object
317 327
318 328 Returns
319 329 -------
320 330 fname : str
321 331 The absolute path to the file where the object was defined.
322 332 """
323 333 obj = _get_wrapped(obj)
324 334
325 335 fname = None
326 336 try:
327 337 fname = inspect.getabsfile(obj)
328 338 except TypeError:
329 339 # For an instance, the file that matters is where its class was
330 340 # declared.
331 341 try:
332 342 fname = inspect.getabsfile(obj.__class__)
333 343 except (OSError, TypeError):
334 344 # Can happen for builtins
335 345 pass
336 346 except OSError:
337 347 pass
338 348
339 349 return cast_unicode(fname)
340 350
341 351
342 352 def find_source_lines(obj):
343 353 """Find the line number in a file where an object was defined.
344 354
345 355 This is essentially a robust wrapper around `inspect.getsourcelines`.
346 356
347 357 Returns None if no file can be found.
348 358
349 359 Parameters
350 360 ----------
351 361 obj : any Python object
352 362
353 363 Returns
354 364 -------
355 365 lineno : int
356 366 The line number where the object definition starts.
357 367 """
358 368 obj = _get_wrapped(obj)
359 369
360 370 try:
361 371 lineno = inspect.getsourcelines(obj)[1]
362 372 except TypeError:
363 373 # For instances, try the class object like getsource() does
364 374 try:
365 375 lineno = inspect.getsourcelines(obj.__class__)[1]
366 376 except (OSError, TypeError):
367 377 return None
368 378 except OSError:
369 379 return None
370 380
371 381 return lineno
372 382
373 383 class Inspector(Colorable):
374 384
375 385 def __init__(self, color_table=InspectColors,
376 386 code_color_table=PyColorize.ANSICodeColors,
377 387 scheme=None,
378 388 str_detail_level=0,
379 389 parent=None, config=None):
380 390 super(Inspector, self).__init__(parent=parent, config=config)
381 391 self.color_table = color_table
382 392 self.parser = PyColorize.Parser(out='str', parent=self, style=scheme)
383 393 self.format = self.parser.format
384 394 self.str_detail_level = str_detail_level
385 395 self.set_active_scheme(scheme)
386 396
387 397 def _getdef(self,obj,oname='') -> Union[str,None]:
388 398 """Return the call signature for any callable object.
389 399
390 400 If any exception is generated, None is returned instead and the
391 401 exception is suppressed."""
392 402 try:
393 403 return _render_signature(signature(obj), oname)
394 404 except:
395 405 return None
396 406
397 407 def __head(self,h) -> str:
398 408 """Return a header string with proper colors."""
399 409 return '%s%s%s' % (self.color_table.active_colors.header,h,
400 410 self.color_table.active_colors.normal)
401 411
402 412 def set_active_scheme(self, scheme):
403 413 if scheme is not None:
404 414 self.color_table.set_active_scheme(scheme)
405 415 self.parser.color_table.set_active_scheme(scheme)
406 416
407 417 def noinfo(self, msg, oname):
408 418 """Generic message when no information is found."""
409 419 print('No %s found' % msg, end=' ')
410 420 if oname:
411 421 print('for %s' % oname)
412 422 else:
413 423 print()
414 424
415 425 def pdef(self, obj, oname=''):
416 426 """Print the call signature for any callable object.
417 427
418 428 If the object is a class, print the constructor information."""
419 429
420 430 if not callable(obj):
421 431 print('Object is not callable.')
422 432 return
423 433
424 434 header = ''
425 435
426 436 if inspect.isclass(obj):
427 437 header = self.__head('Class constructor information:\n')
428 438
429 439
430 440 output = self._getdef(obj,oname)
431 441 if output is None:
432 442 self.noinfo('definition header',oname)
433 443 else:
434 444 print(header,self.format(output), end=' ')
435 445
436 446 # In Python 3, all classes are new-style, so they all have __init__.
437 447 @skip_doctest
438 448 def pdoc(self, obj, oname='', formatter=None):
439 449 """Print the docstring for any object.
440 450
441 451 Optional:
442 452 -formatter: a function to run the docstring through for specially
443 453 formatted docstrings.
444 454
445 455 Examples
446 456 --------
447 457 In [1]: class NoInit:
448 458 ...: pass
449 459
450 460 In [2]: class NoDoc:
451 461 ...: def __init__(self):
452 462 ...: pass
453 463
454 464 In [3]: %pdoc NoDoc
455 465 No documentation found for NoDoc
456 466
457 467 In [4]: %pdoc NoInit
458 468 No documentation found for NoInit
459 469
460 470 In [5]: obj = NoInit()
461 471
462 472 In [6]: %pdoc obj
463 473 No documentation found for obj
464 474
465 475 In [5]: obj2 = NoDoc()
466 476
467 477 In [6]: %pdoc obj2
468 478 No documentation found for obj2
469 479 """
470 480
471 481 head = self.__head # For convenience
472 482 lines = []
473 483 ds = getdoc(obj)
474 484 if formatter:
475 485 ds = formatter(ds).get('plain/text', ds)
476 486 if ds:
477 487 lines.append(head("Class docstring:"))
478 488 lines.append(indent(ds))
479 489 if inspect.isclass(obj) and hasattr(obj, '__init__'):
480 490 init_ds = getdoc(obj.__init__)
481 491 if init_ds is not None:
482 492 lines.append(head("Init docstring:"))
483 493 lines.append(indent(init_ds))
484 494 elif hasattr(obj,'__call__'):
485 495 call_ds = getdoc(obj.__call__)
486 496 if call_ds:
487 497 lines.append(head("Call docstring:"))
488 498 lines.append(indent(call_ds))
489 499
490 500 if not lines:
491 501 self.noinfo('documentation',oname)
492 502 else:
493 503 page.page('\n'.join(lines))
494 504
495 505 def psource(self, obj, oname=''):
496 506 """Print the source code for an object."""
497 507
498 508 # Flush the source cache because inspect can return out-of-date source
499 509 linecache.checkcache()
500 510 try:
501 511 src = getsource(obj, oname=oname)
502 512 except Exception:
503 513 src = None
504 514
505 515 if src is None:
506 516 self.noinfo('source', oname)
507 517 else:
508 518 page.page(self.format(src))
509 519
510 520 def pfile(self, obj, oname=''):
511 521 """Show the whole file where an object was defined."""
512 522
513 523 lineno = find_source_lines(obj)
514 524 if lineno is None:
515 525 self.noinfo('file', oname)
516 526 return
517 527
518 528 ofile = find_file(obj)
519 529 # run contents of file through pager starting at line where the object
520 530 # is defined, as long as the file isn't binary and is actually on the
521 531 # filesystem.
522 532 if ofile.endswith(('.so', '.dll', '.pyd')):
523 533 print('File %r is binary, not printing.' % ofile)
524 534 elif not os.path.isfile(ofile):
525 535 print('File %r does not exist, not printing.' % ofile)
526 536 else:
527 537 # Print only text files, not extension binaries. Note that
528 538 # getsourcelines returns lineno with 1-offset and page() uses
529 539 # 0-offset, so we must adjust.
530 540 page.page(self.format(openpy.read_py_file(ofile, skip_encoding_cookie=False)), lineno - 1)
531 541
532 542
533 543 def _mime_format(self, text:str, formatter=None) -> dict:
534 544 """Return a mime bundle representation of the input text.
535 545
536 546 - if `formatter` is None, the returned mime bundle has
537 547 a ``text/plain`` field, with the input text.
538 548 a ``text/html`` field with a ``<pre>`` tag containing the input text.
539 549
540 550 - if ``formatter`` is not None, it must be a callable transforming the
541 551 input text into a mime bundle. Default values for ``text/plain`` and
542 552 ``text/html`` representations are the ones described above.
543 553
544 554 Note:
545 555
546 556 Formatters returning strings are supported but this behavior is deprecated.
547 557
548 558 """
549 559 defaults = {
550 560 "text/plain": text,
551 561 "text/html": f"<pre>{html.escape(text)}</pre>",
552 562 }
553 563
554 564 if formatter is None:
555 565 return defaults
556 566 else:
557 567 formatted = formatter(text)
558 568
559 569 if not isinstance(formatted, dict):
560 570 # Handle the deprecated behavior of a formatter returning
561 571 # a string instead of a mime bundle.
562 572 return {"text/plain": formatted, "text/html": f"<pre>{formatted}</pre>"}
563 573
564 574 else:
565 575 return dict(defaults, **formatted)
566 576
567
568 def format_mime(self, bundle):
577 def format_mime(self, bundle: UnformattedBundle) -> Bundle:
569 578 """Format a mimebundle being created by _make_info_unformatted into a real mimebundle"""
570 579 # Format text/plain mimetype
571 if isinstance(bundle["text/plain"], (list, tuple)):
572 # bundle['text/plain'] is a list of (head, formatted body) pairs
573 lines = []
574 _len = max(len(h) for h, _ in bundle["text/plain"])
575
576 for head, body in bundle["text/plain"]:
577 body = body.strip("\n")
578 delim = "\n" if "\n" in body else " "
579 lines.append(
580 f"{self.__head(head+':')}{(_len - len(head))*' '}{delim}{body}"
581 )
580 assert isinstance(bundle["text/plain"], list)
581 for item in bundle["text/plain"]:
582 assert isinstance(item, tuple)
582 583
583 bundle["text/plain"] = "\n".join(lines)
584 new_b: Bundle = {}
585 lines = []
586 _len = max(len(h) for h, _ in bundle["text/plain"])
584 587
585 # Format the text/html mimetype
586 if isinstance(bundle["text/html"], (list, tuple)):
587 # bundle['text/html'] is a list of (head, formatted body) pairs
588 bundle["text/html"] = "\n".join(
589 (f"<h1>{head}</h1>\n{body}" for (head, body) in bundle["text/html"])
588 for head, body in bundle["text/plain"]:
589 body = body.strip("\n")
590 delim = "\n" if "\n" in body else " "
591 lines.append(
592 f"{self.__head(head+':')}{(_len - len(head))*' '}{delim}{body}"
590 593 )
591 return bundle
594
595 new_b["text/plain"] = "\n".join(lines)
596
597 if "text/html" in bundle:
598 assert isinstance(bundle["text/html"], list)
599 for item in bundle["text/html"]:
600 assert isinstance(item, tuple)
601 # Format the text/html mimetype
602 if isinstance(bundle["text/html"], (list, tuple)):
603 # bundle['text/html'] is a list of (head, formatted body) pairs
604 new_b["text/html"] = "\n".join(
605 (f"<h1>{head}</h1>\n{body}" for (head, body) in bundle["text/html"])
606 )
607
608 for k in bundle.keys():
609 if k in ("text/html", "text/plain"):
610 continue
611 else:
612 new_b = bundle[k] # type:ignore
613 return new_b
592 614
593 615 def _append_info_field(
594 self, bundle, title: str, key: str, info, omit_sections, formatter
616 self,
617 bundle: UnformattedBundle,
618 title: str,
619 key: str,
620 info,
621 omit_sections,
622 formatter,
595 623 ):
596 624 """Append an info value to the unformatted mimebundle being constructed by _make_info_unformatted"""
597 625 if title in omit_sections or key in omit_sections:
598 626 return
599 627 field = info[key]
600 628 if field is not None:
601 629 formatted_field = self._mime_format(field, formatter)
602 630 bundle["text/plain"].append((title, formatted_field["text/plain"]))
603 631 bundle["text/html"].append((title, formatted_field["text/html"]))
604 632
605 def _make_info_unformatted(self, obj, info, formatter, detail_level, omit_sections):
633 def _make_info_unformatted(
634 self, obj, info, formatter, detail_level, omit_sections
635 ) -> UnformattedBundle:
606 636 """Assemble the mimebundle as unformatted lists of information"""
607 bundle = {
637 bundle: UnformattedBundle = {
608 638 "text/plain": [],
609 639 "text/html": [],
610 640 }
611 641
612 642 # A convenience function to simplify calls below
613 def append_field(bundle, title: str, key: str, formatter=None):
643 def append_field(
644 bundle: UnformattedBundle, title: str, key: str, formatter=None
645 ):
614 646 self._append_info_field(
615 647 bundle,
616 648 title=title,
617 649 key=key,
618 650 info=info,
619 651 omit_sections=omit_sections,
620 652 formatter=formatter,
621 653 )
622 654
623 def code_formatter(text):
655 def code_formatter(text) -> Bundle:
624 656 return {
625 657 'text/plain': self.format(text),
626 658 'text/html': pylight(text)
627 659 }
628 660
629 661 if info["isalias"]:
630 662 append_field(bundle, "Repr", "string_form")
631 663
632 664 elif info['ismagic']:
633 665 if detail_level > 0:
634 666 append_field(bundle, "Source", "source", code_formatter)
635 667 else:
636 668 append_field(bundle, "Docstring", "docstring", formatter)
637 669 append_field(bundle, "File", "file")
638 670
639 671 elif info['isclass'] or is_simple_callable(obj):
640 672 # Functions, methods, classes
641 673 append_field(bundle, "Signature", "definition", code_formatter)
642 674 append_field(bundle, "Init signature", "init_definition", code_formatter)
643 675 append_field(bundle, "Docstring", "docstring", formatter)
644 676 if detail_level > 0 and info["source"]:
645 677 append_field(bundle, "Source", "source", code_formatter)
646 678 else:
647 679 append_field(bundle, "Init docstring", "init_docstring", formatter)
648 680
649 681 append_field(bundle, "File", "file")
650 682 append_field(bundle, "Type", "type_name")
651 683 append_field(bundle, "Subclasses", "subclasses")
652 684
653 685 else:
654 686 # General Python objects
655 687 append_field(bundle, "Signature", "definition", code_formatter)
656 688 append_field(bundle, "Call signature", "call_def", code_formatter)
657 689 append_field(bundle, "Type", "type_name")
658 690 append_field(bundle, "String form", "string_form")
659 691
660 692 # Namespace
661 693 if info["namespace"] != "Interactive":
662 694 append_field(bundle, "Namespace", "namespace")
663 695
664 696 append_field(bundle, "Length", "length")
665 697 append_field(bundle, "File", "file")
666 698
667 699 # Source or docstring, depending on detail level and whether
668 700 # source found.
669 701 if detail_level > 0 and info["source"]:
670 702 append_field(bundle, "Source", "source", code_formatter)
671 703 else:
672 704 append_field(bundle, "Docstring", "docstring", formatter)
673 705
674 706 append_field(bundle, "Class docstring", "class_docstring", formatter)
675 707 append_field(bundle, "Init docstring", "init_docstring", formatter)
676 708 append_field(bundle, "Call docstring", "call_docstring", formatter)
677 709 return bundle
678 710
679 711
680 712 def _get_info(
681 self, obj, oname="", formatter=None, info=None, detail_level=0, omit_sections=()
682 ):
713 self,
714 obj: Any,
715 oname: str = "",
716 formatter=None,
717 info: Optional[OInfo] = None,
718 detail_level=0,
719 omit_sections=(),
720 ) -> Bundle:
683 721 """Retrieve an info dict and format it.
684 722
685 723 Parameters
686 724 ----------
687 725 obj : any
688 726 Object to inspect and return info from
689 727 oname : str (default: ''):
690 728 Name of the variable pointing to `obj`.
691 729 formatter : callable
692 730 info
693 731 already computed information
694 732 detail_level : integer
695 733 Granularity of detail level, if set to 1, give more information.
696 734 omit_sections : container[str]
697 735 Titles or keys to omit from output (can be set, tuple, etc., anything supporting `in`)
698 736 """
699 737
700 info = self.info(obj, oname=oname, info=info, detail_level=detail_level)
738 info_dict = self.info(obj, oname=oname, info=info, detail_level=detail_level)
701 739 bundle = self._make_info_unformatted(
702 obj, info, formatter, detail_level=detail_level, omit_sections=omit_sections
740 obj,
741 info_dict,
742 formatter,
743 detail_level=detail_level,
744 omit_sections=omit_sections,
703 745 )
704 746 return self.format_mime(bundle)
705 747
706 748 def pinfo(
707 749 self,
708 750 obj,
709 751 oname="",
710 752 formatter=None,
711 info=None,
753 info: Optional[OInfo] = None,
712 754 detail_level=0,
713 755 enable_html_pager=True,
714 756 omit_sections=(),
715 757 ):
716 758 """Show detailed information about an object.
717 759
718 760 Optional arguments:
719 761
720 762 - oname: name of the variable pointing to the object.
721 763
722 764 - formatter: callable (optional)
723 765 A special formatter for docstrings.
724 766
725 767 The formatter is a callable that takes a string as an input
726 768 and returns either a formatted string or a mime type bundle
727 769 in the form of a dictionary.
728 770
729 771 Although the support of custom formatter returning a string
730 772 instead of a mime type bundle is deprecated.
731 773
732 774 - info: a structure with some information fields which may have been
733 775 precomputed already.
734 776
735 777 - detail_level: if set to 1, more information is given.
736 778
737 779 - omit_sections: set of section keys and titles to omit
738 780 """
739 info = self._get_info(
781 assert info is not None
782 info_b: Bundle = self._get_info(
740 783 obj, oname, formatter, info, detail_level, omit_sections=omit_sections
741 784 )
742 785 if not enable_html_pager:
743 del info['text/html']
744 page.page(info)
786 del info_b["text/html"]
787 page.page(info_b)
745 788
746 789 def _info(self, obj, oname="", info=None, detail_level=0):
747 790 """
748 791 Inspector.info() was likely improperly marked as deprecated
749 792 while only a parameter was deprecated. We "un-deprecate" it.
750 793 """
751 794
752 795 warnings.warn(
753 796 "The `Inspector.info()` method has been un-deprecated as of 8.0 "
754 797 "and the `formatter=` keyword removed. `Inspector._info` is now "
755 798 "an alias, and you can just call `.info()` directly.",
756 799 DeprecationWarning,
757 800 stacklevel=2,
758 801 )
759 802 return self.info(obj, oname=oname, info=info, detail_level=detail_level)
760 803
761 def info(self, obj, oname="", info=None, detail_level=0) -> dict:
804 def info(self, obj, oname="", info=None, detail_level=0) -> Dict[str, Any]:
762 805 """Compute a dict with detailed information about an object.
763 806
764 807 Parameters
765 808 ----------
766 809 obj : any
767 810 An object to find information about
768 811 oname : str (default: '')
769 812 Name of the variable pointing to `obj`.
770 813 info : (default: None)
771 814 A struct (dict like with attr access) with some information fields
772 815 which may have been precomputed already.
773 816 detail_level : int (default:0)
774 817 If set to 1, more information is given.
775 818
776 819 Returns
777 820 -------
778 821 An object info dict with known fields from `info_fields`. Keys are
779 822 strings, values are string or None.
780 823 """
781 824
782 825 if info is None:
783 826 ismagic = False
784 827 isalias = False
785 828 ospace = ''
786 829 else:
787 830 ismagic = info.ismagic
788 831 isalias = info.isalias
789 832 ospace = info.namespace
790 833
791 834 # Get docstring, special-casing aliases:
792 if isalias:
835 att_name = oname.split(".")[-1]
836 parents_docs = None
837 prelude = ""
838 if info and info.parent and hasattr(info.parent, HOOK_NAME):
839 parents_docs_dict = getattr(info.parent, HOOK_NAME)
840 parents_docs = parents_docs_dict.get(att_name, None)
841 out = dict(
842 name=oname, found=True, isalias=isalias, ismagic=ismagic, subclasses=None
843 )
844
845 if parents_docs:
846 ds = parents_docs
847 elif isalias:
793 848 if not callable(obj):
794 849 try:
795 850 ds = "Alias to the system command:\n %s" % obj[1]
796 851 except:
797 852 ds = "Alias: " + str(obj)
798 853 else:
799 854 ds = "Alias to " + str(obj)
800 855 if obj.__doc__:
801 856 ds += "\nDocstring:\n" + obj.__doc__
802 857 else:
803 858 ds_or_None = getdoc(obj)
804 859 if ds_or_None is None:
805 860 ds = '<no docstring>'
806 861 else:
807 862 ds = ds_or_None
808 863
864 ds = prelude + ds
865
809 866 # store output in a dict, we initialize it here and fill it as we go
810 out = dict(name=oname, found=True, isalias=isalias, ismagic=ismagic, subclasses=None)
811 867
812 868 string_max = 200 # max size of strings to show (snipped if longer)
813 869 shalf = int((string_max - 5) / 2)
814 870
815 871 if ismagic:
816 872 out['type_name'] = 'Magic function'
817 873 elif isalias:
818 874 out['type_name'] = 'System alias'
819 875 else:
820 876 out['type_name'] = type(obj).__name__
821 877
822 878 try:
823 879 bclass = obj.__class__
824 880 out['base_class'] = str(bclass)
825 881 except:
826 882 pass
827 883
828 884 # String form, but snip if too long in ? form (full in ??)
829 885 if detail_level >= self.str_detail_level:
830 886 try:
831 887 ostr = str(obj)
832 888 str_head = 'string_form'
833 889 if not detail_level and len(ostr)>string_max:
834 890 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
835 891 ostr = ("\n" + " " * len(str_head.expandtabs())).\
836 892 join(q.strip() for q in ostr.split("\n"))
837 893 out[str_head] = ostr
838 894 except:
839 895 pass
840 896
841 897 if ospace:
842 898 out['namespace'] = ospace
843 899
844 900 # Length (for strings and lists)
845 901 try:
846 902 out['length'] = str(len(obj))
847 903 except Exception:
848 904 pass
849 905
850 906 # Filename where object was defined
851 907 binary_file = False
852 908 fname = find_file(obj)
853 909 if fname is None:
854 910 # if anything goes wrong, we don't want to show source, so it's as
855 911 # if the file was binary
856 912 binary_file = True
857 913 else:
858 914 if fname.endswith(('.so', '.dll', '.pyd')):
859 915 binary_file = True
860 916 elif fname.endswith('<string>'):
861 917 fname = 'Dynamically generated function. No source code available.'
862 918 out['file'] = compress_user(fname)
863 919
864 920 # Original source code for a callable, class or property.
865 921 if detail_level:
866 922 # Flush the source cache because inspect can return out-of-date
867 923 # source
868 924 linecache.checkcache()
869 925 try:
870 926 if isinstance(obj, property) or not binary_file:
871 927 src = getsource(obj, oname)
872 928 if src is not None:
873 929 src = src.rstrip()
874 930 out['source'] = src
875 931
876 932 except Exception:
877 933 pass
878 934
879 935 # Add docstring only if no source is to be shown (avoid repetitions).
880 936 if ds and not self._source_contains_docstring(out.get('source'), ds):
881 937 out['docstring'] = ds
882 938
883 939 # Constructor docstring for classes
884 940 if inspect.isclass(obj):
885 941 out['isclass'] = True
886 942
887 943 # get the init signature:
888 944 try:
889 945 init_def = self._getdef(obj, oname)
890 946 except AttributeError:
891 947 init_def = None
892 948
893 949 # get the __init__ docstring
894 950 try:
895 951 obj_init = obj.__init__
896 952 except AttributeError:
897 953 init_ds = None
898 954 else:
899 955 if init_def is None:
900 956 # Get signature from init if top-level sig failed.
901 957 # Can happen for built-in types (list, etc.).
902 958 try:
903 959 init_def = self._getdef(obj_init, oname)
904 960 except AttributeError:
905 961 pass
906 962 init_ds = getdoc(obj_init)
907 963 # Skip Python's auto-generated docstrings
908 964 if init_ds == _object_init_docstring:
909 965 init_ds = None
910 966
911 967 if init_def:
912 968 out['init_definition'] = init_def
913 969
914 970 if init_ds:
915 971 out['init_docstring'] = init_ds
916 972
917 973 names = [sub.__name__ for sub in type.__subclasses__(obj)]
918 974 if len(names) < 10:
919 975 all_names = ', '.join(names)
920 976 else:
921 977 all_names = ', '.join(names[:10]+['...'])
922 978 out['subclasses'] = all_names
923 979 # and class docstring for instances:
924 980 else:
925 981 # reconstruct the function definition and print it:
926 982 defln = self._getdef(obj, oname)
927 983 if defln:
928 984 out['definition'] = defln
929 985
930 986 # First, check whether the instance docstring is identical to the
931 987 # class one, and print it separately if they don't coincide. In
932 988 # most cases they will, but it's nice to print all the info for
933 989 # objects which use instance-customized docstrings.
934 990 if ds:
935 991 try:
936 992 cls = getattr(obj,'__class__')
937 993 except:
938 994 class_ds = None
939 995 else:
940 996 class_ds = getdoc(cls)
941 997 # Skip Python's auto-generated docstrings
942 998 if class_ds in _builtin_type_docstrings:
943 999 class_ds = None
944 1000 if class_ds and ds != class_ds:
945 1001 out['class_docstring'] = class_ds
946 1002
947 1003 # Next, try to show constructor docstrings
948 1004 try:
949 1005 init_ds = getdoc(obj.__init__)
950 1006 # Skip Python's auto-generated docstrings
951 1007 if init_ds == _object_init_docstring:
952 1008 init_ds = None
953 1009 except AttributeError:
954 1010 init_ds = None
955 1011 if init_ds:
956 1012 out['init_docstring'] = init_ds
957 1013
958 1014 # Call form docstring for callable instances
959 1015 if safe_hasattr(obj, '__call__') and not is_simple_callable(obj):
960 1016 call_def = self._getdef(obj.__call__, oname)
961 1017 if call_def and (call_def != out.get('definition')):
962 1018 # it may never be the case that call def and definition differ,
963 1019 # but don't include the same signature twice
964 1020 out['call_def'] = call_def
965 1021 call_ds = getdoc(obj.__call__)
966 1022 # Skip Python's auto-generated docstrings
967 1023 if call_ds == _func_call_docstring:
968 1024 call_ds = None
969 1025 if call_ds:
970 1026 out['call_docstring'] = call_ds
971 1027
972 1028 return object_info(**out)
973 1029
974 1030 @staticmethod
975 1031 def _source_contains_docstring(src, doc):
976 1032 """
977 1033 Check whether the source *src* contains the docstring *doc*.
978 1034
979 1035 This is is helper function to skip displaying the docstring if the
980 1036 source already contains it, avoiding repetition of information.
981 1037 """
982 1038 try:
983 def_node, = ast.parse(dedent(src)).body
984 return ast.get_docstring(def_node) == doc
1039 (def_node,) = ast.parse(dedent(src)).body
1040 return ast.get_docstring(def_node) == doc # type: ignore[arg-type]
985 1041 except Exception:
986 1042 # The source can become invalid or even non-existent (because it
987 1043 # is re-fetched from the source file) so the above code fail in
988 1044 # arbitrary ways.
989 1045 return False
990 1046
991 1047 def psearch(self,pattern,ns_table,ns_search=[],
992 1048 ignore_case=False,show_all=False, *, list_types=False):
993 1049 """Search namespaces with wildcards for objects.
994 1050
995 1051 Arguments:
996 1052
997 1053 - pattern: string containing shell-like wildcards to use in namespace
998 1054 searches and optionally a type specification to narrow the search to
999 1055 objects of that type.
1000 1056
1001 1057 - ns_table: dict of name->namespaces for search.
1002 1058
1003 1059 Optional arguments:
1004 1060
1005 1061 - ns_search: list of namespace names to include in search.
1006 1062
1007 1063 - ignore_case(False): make the search case-insensitive.
1008 1064
1009 1065 - show_all(False): show all names, including those starting with
1010 1066 underscores.
1011 1067
1012 1068 - list_types(False): list all available object types for object matching.
1013 1069 """
1014 1070 #print 'ps pattern:<%r>' % pattern # dbg
1015 1071
1016 1072 # defaults
1017 1073 type_pattern = 'all'
1018 1074 filter = ''
1019 1075
1020 1076 # list all object types
1021 1077 if list_types:
1022 1078 page.page('\n'.join(sorted(typestr2type)))
1023 1079 return
1024 1080
1025 1081 cmds = pattern.split()
1026 1082 len_cmds = len(cmds)
1027 1083 if len_cmds == 1:
1028 1084 # Only filter pattern given
1029 1085 filter = cmds[0]
1030 1086 elif len_cmds == 2:
1031 1087 # Both filter and type specified
1032 1088 filter,type_pattern = cmds
1033 1089 else:
1034 1090 raise ValueError('invalid argument string for psearch: <%s>' %
1035 1091 pattern)
1036 1092
1037 1093 # filter search namespaces
1038 1094 for name in ns_search:
1039 1095 if name not in ns_table:
1040 1096 raise ValueError('invalid namespace <%s>. Valid names: %s' %
1041 1097 (name,ns_table.keys()))
1042 1098
1043 1099 #print 'type_pattern:',type_pattern # dbg
1044 1100 search_result, namespaces_seen = set(), set()
1045 1101 for ns_name in ns_search:
1046 1102 ns = ns_table[ns_name]
1047 1103 # Normally, locals and globals are the same, so we just check one.
1048 1104 if id(ns) in namespaces_seen:
1049 1105 continue
1050 1106 namespaces_seen.add(id(ns))
1051 1107 tmp_res = list_namespace(ns, type_pattern, filter,
1052 1108 ignore_case=ignore_case, show_all=show_all)
1053 1109 search_result.update(tmp_res)
1054 1110
1055 1111 page.page('\n'.join(sorted(search_result)))
1056 1112
1057 1113
1058 1114 def _render_signature(obj_signature, obj_name) -> str:
1059 1115 """
1060 1116 This was mostly taken from inspect.Signature.__str__.
1061 1117 Look there for the comments.
1062 1118 The only change is to add linebreaks when this gets too long.
1063 1119 """
1064 1120 result = []
1065 1121 pos_only = False
1066 1122 kw_only = True
1067 1123 for param in obj_signature.parameters.values():
1068 1124 if param.kind == inspect.Parameter.POSITIONAL_ONLY:
1069 1125 pos_only = True
1070 1126 elif pos_only:
1071 1127 result.append('/')
1072 1128 pos_only = False
1073 1129
1074 1130 if param.kind == inspect.Parameter.VAR_POSITIONAL:
1075 1131 kw_only = False
1076 1132 elif param.kind == inspect.Parameter.KEYWORD_ONLY and kw_only:
1077 1133 result.append('*')
1078 1134 kw_only = False
1079 1135
1080 1136 result.append(str(param))
1081 1137
1082 1138 if pos_only:
1083 1139 result.append('/')
1084 1140
1085 1141 # add up name, parameters, braces (2), and commas
1086 1142 if len(obj_name) + sum(len(r) + 2 for r in result) > 75:
1087 1143 # This doesn’t fit behind β€œSignature: ” in an inspect window.
1088 1144 rendered = '{}(\n{})'.format(obj_name, ''.join(
1089 1145 ' {},\n'.format(r) for r in result)
1090 1146 )
1091 1147 else:
1092 1148 rendered = '{}({})'.format(obj_name, ', '.join(result))
1093 1149
1094 1150 if obj_signature.return_annotation is not inspect._empty:
1095 1151 anno = inspect.formatannotation(obj_signature.return_annotation)
1096 1152 rendered += ' -> {}'.format(anno)
1097 1153
1098 1154 return rendered
@@ -1,541 +1,578
1 1 """Tests for the object inspection functionality.
2 2 """
3 3
4 4 # Copyright (c) IPython Development Team.
5 5 # Distributed under the terms of the Modified BSD License.
6 6
7 7
8 8 from contextlib import contextmanager
9 9 from inspect import signature, Signature, Parameter
10 10 import inspect
11 11 import os
12 12 import pytest
13 13 import re
14 14 import sys
15 15
16 16 from .. import oinspect
17 17
18 18 from decorator import decorator
19 19
20 20 from IPython.testing.tools import AssertPrints, AssertNotPrints
21 21 from IPython.utils.path import compress_user
22 22
23 23
24 24 #-----------------------------------------------------------------------------
25 25 # Globals and constants
26 26 #-----------------------------------------------------------------------------
27 27
28 28 inspector = None
29 29
30 30 def setup_module():
31 31 global inspector
32 32 inspector = oinspect.Inspector()
33 33
34 34
35 35 class SourceModuleMainTest:
36 36 __module__ = "__main__"
37 37
38 38
39 39 #-----------------------------------------------------------------------------
40 40 # Local utilities
41 41 #-----------------------------------------------------------------------------
42 42
43 43 # WARNING: since this test checks the line number where a function is
44 44 # defined, if any code is inserted above, the following line will need to be
45 45 # updated. Do NOT insert any whitespace between the next line and the function
46 46 # definition below.
47 47 THIS_LINE_NUMBER = 47 # Put here the actual number of this line
48 48
49 49
50 50 def test_find_source_lines():
51 51 assert oinspect.find_source_lines(test_find_source_lines) == THIS_LINE_NUMBER + 3
52 52 assert oinspect.find_source_lines(type) is None
53 53 assert oinspect.find_source_lines(SourceModuleMainTest) is None
54 54 assert oinspect.find_source_lines(SourceModuleMainTest()) is None
55 55
56 56
57 57 def test_getsource():
58 58 assert oinspect.getsource(type) is None
59 59 assert oinspect.getsource(SourceModuleMainTest) is None
60 60 assert oinspect.getsource(SourceModuleMainTest()) is None
61 61
62 62
63 63 def test_inspect_getfile_raises_exception():
64 64 """Check oinspect.find_file/getsource/find_source_lines expectations"""
65 65 with pytest.raises(TypeError):
66 66 inspect.getfile(type)
67 67 with pytest.raises(OSError if sys.version_info >= (3, 10) else TypeError):
68 68 inspect.getfile(SourceModuleMainTest)
69 69
70 70
71 71 # A couple of utilities to ensure these tests work the same from a source or a
72 72 # binary install
73 73 def pyfile(fname):
74 74 return os.path.normcase(re.sub('.py[co]$', '.py', fname))
75 75
76 76
77 77 def match_pyfiles(f1, f2):
78 78 assert pyfile(f1) == pyfile(f2)
79 79
80 80
81 81 def test_find_file():
82 82 match_pyfiles(oinspect.find_file(test_find_file), os.path.abspath(__file__))
83 83 assert oinspect.find_file(type) is None
84 84 assert oinspect.find_file(SourceModuleMainTest) is None
85 85 assert oinspect.find_file(SourceModuleMainTest()) is None
86 86
87 87
88 88 def test_find_file_decorated1():
89 89
90 90 @decorator
91 91 def noop1(f):
92 92 def wrapper(*a, **kw):
93 93 return f(*a, **kw)
94 94 return wrapper
95 95
96 96 @noop1
97 97 def f(x):
98 98 "My docstring"
99 99
100 100 match_pyfiles(oinspect.find_file(f), os.path.abspath(__file__))
101 101 assert f.__doc__ == "My docstring"
102 102
103 103
104 104 def test_find_file_decorated2():
105 105
106 106 @decorator
107 107 def noop2(f, *a, **kw):
108 108 return f(*a, **kw)
109 109
110 110 @noop2
111 111 @noop2
112 112 @noop2
113 113 def f(x):
114 114 "My docstring 2"
115 115
116 116 match_pyfiles(oinspect.find_file(f), os.path.abspath(__file__))
117 117 assert f.__doc__ == "My docstring 2"
118 118
119 119
120 120 def test_find_file_magic():
121 121 run = ip.find_line_magic('run')
122 122 assert oinspect.find_file(run) is not None
123 123
124 124
125 125 # A few generic objects we can then inspect in the tests below
126 126
127 127 class Call(object):
128 128 """This is the class docstring."""
129 129
130 130 def __init__(self, x, y=1):
131 131 """This is the constructor docstring."""
132 132
133 133 def __call__(self, *a, **kw):
134 134 """This is the call docstring."""
135 135
136 136 def method(self, x, z=2):
137 137 """Some method's docstring"""
138 138
139 139 class HasSignature(object):
140 140 """This is the class docstring."""
141 141 __signature__ = Signature([Parameter('test', Parameter.POSITIONAL_OR_KEYWORD)])
142 142
143 143 def __init__(self, *args):
144 144 """This is the init docstring"""
145 145
146 146
147 147 class SimpleClass(object):
148 148 def method(self, x, z=2):
149 149 """Some method's docstring"""
150 150
151 151
152 152 class Awkward(object):
153 153 def __getattr__(self, name):
154 154 raise Exception(name)
155 155
156 156 class NoBoolCall:
157 157 """
158 158 callable with `__bool__` raising should still be inspect-able.
159 159 """
160 160
161 161 def __call__(self):
162 162 """does nothing"""
163 163 pass
164 164
165 165 def __bool__(self):
166 166 """just raise NotImplemented"""
167 167 raise NotImplementedError('Must be implemented')
168 168
169 169
170 170 class SerialLiar(object):
171 171 """Attribute accesses always get another copy of the same class.
172 172
173 173 unittest.mock.call does something similar, but it's not ideal for testing
174 174 as the failure mode is to eat all your RAM. This gives up after 10k levels.
175 175 """
176 176 def __init__(self, max_fibbing_twig, lies_told=0):
177 177 if lies_told > 10000:
178 178 raise RuntimeError('Nose too long, honesty is the best policy')
179 179 self.max_fibbing_twig = max_fibbing_twig
180 180 self.lies_told = lies_told
181 181 max_fibbing_twig[0] = max(max_fibbing_twig[0], lies_told)
182 182
183 183 def __getattr__(self, item):
184 184 return SerialLiar(self.max_fibbing_twig, self.lies_told + 1)
185 185
186 186 #-----------------------------------------------------------------------------
187 187 # Tests
188 188 #-----------------------------------------------------------------------------
189 189
190 190 def test_info():
191 191 "Check that Inspector.info fills out various fields as expected."
192 192 i = inspector.info(Call, oname="Call")
193 193 assert i["type_name"] == "type"
194 194 expected_class = str(type(type)) # <class 'type'> (Python 3) or <type 'type'>
195 195 assert i["base_class"] == expected_class
196 196 assert re.search(
197 197 "<class 'IPython.core.tests.test_oinspect.Call'( at 0x[0-9a-f]{1,9})?>",
198 198 i["string_form"],
199 199 )
200 200 fname = __file__
201 201 if fname.endswith(".pyc"):
202 202 fname = fname[:-1]
203 203 # case-insensitive comparison needed on some filesystems
204 204 # e.g. Windows:
205 205 assert i["file"].lower() == compress_user(fname).lower()
206 206 assert i["definition"] == None
207 207 assert i["docstring"] == Call.__doc__
208 208 assert i["source"] == None
209 209 assert i["isclass"] is True
210 210 assert i["init_definition"] == "Call(x, y=1)"
211 211 assert i["init_docstring"] == Call.__init__.__doc__
212 212
213 213 i = inspector.info(Call, detail_level=1)
214 214 assert i["source"] is not None
215 215 assert i["docstring"] == None
216 216
217 217 c = Call(1)
218 218 c.__doc__ = "Modified instance docstring"
219 219 i = inspector.info(c)
220 220 assert i["type_name"] == "Call"
221 221 assert i["docstring"] == "Modified instance docstring"
222 222 assert i["class_docstring"] == Call.__doc__
223 223 assert i["init_docstring"] == Call.__init__.__doc__
224 224 assert i["call_docstring"] == Call.__call__.__doc__
225 225
226 226
227 227 def test_class_signature():
228 228 info = inspector.info(HasSignature, "HasSignature")
229 229 assert info["init_definition"] == "HasSignature(test)"
230 230 assert info["init_docstring"] == HasSignature.__init__.__doc__
231 231
232 232
233 233 def test_info_awkward():
234 234 # Just test that this doesn't throw an error.
235 235 inspector.info(Awkward())
236 236
237 237 def test_bool_raise():
238 238 inspector.info(NoBoolCall())
239 239
240 240 def test_info_serialliar():
241 241 fib_tracker = [0]
242 242 inspector.info(SerialLiar(fib_tracker))
243 243
244 244 # Nested attribute access should be cut off at 100 levels deep to avoid
245 245 # infinite loops: https://github.com/ipython/ipython/issues/9122
246 246 assert fib_tracker[0] < 9000
247 247
248 248 def support_function_one(x, y=2, *a, **kw):
249 249 """A simple function."""
250 250
251 251 def test_calldef_none():
252 252 # We should ignore __call__ for all of these.
253 253 for obj in [support_function_one, SimpleClass().method, any, str.upper]:
254 254 i = inspector.info(obj)
255 255 assert i["call_def"] is None
256 256
257 257
258 258 def f_kwarg(pos, *, kwonly):
259 259 pass
260 260
261 261 def test_definition_kwonlyargs():
262 262 i = inspector.info(f_kwarg, oname="f_kwarg") # analysis:ignore
263 263 assert i["definition"] == "f_kwarg(pos, *, kwonly)"
264 264
265 265
266 266 def test_getdoc():
267 267 class A(object):
268 268 """standard docstring"""
269 269 pass
270 270
271 271 class B(object):
272 272 """standard docstring"""
273 273 def getdoc(self):
274 274 return "custom docstring"
275 275
276 276 class C(object):
277 277 """standard docstring"""
278 278 def getdoc(self):
279 279 return None
280 280
281 281 a = A()
282 282 b = B()
283 283 c = C()
284 284
285 285 assert oinspect.getdoc(a) == "standard docstring"
286 286 assert oinspect.getdoc(b) == "custom docstring"
287 287 assert oinspect.getdoc(c) == "standard docstring"
288 288
289 289
290 290 def test_empty_property_has_no_source():
291 291 i = inspector.info(property(), detail_level=1)
292 292 assert i["source"] is None
293 293
294 294
295 295 def test_property_sources():
296 296 # A simple adder whose source and signature stays
297 297 # the same across Python distributions
298 298 def simple_add(a, b):
299 299 "Adds two numbers"
300 300 return a + b
301 301
302 302 class A(object):
303 303 @property
304 304 def foo(self):
305 305 return 'bar'
306 306
307 307 foo = foo.setter(lambda self, v: setattr(self, 'bar', v))
308 308
309 309 dname = property(oinspect.getdoc)
310 310 adder = property(simple_add)
311 311
312 312 i = inspector.info(A.foo, detail_level=1)
313 313 assert "def foo(self):" in i["source"]
314 314 assert "lambda self, v:" in i["source"]
315 315
316 316 i = inspector.info(A.dname, detail_level=1)
317 317 assert "def getdoc(obj)" in i["source"]
318 318
319 319 i = inspector.info(A.adder, detail_level=1)
320 320 assert "def simple_add(a, b)" in i["source"]
321 321
322 322
323 323 def test_property_docstring_is_in_info_for_detail_level_0():
324 324 class A(object):
325 325 @property
326 326 def foobar(self):
327 327 """This is `foobar` property."""
328 328 pass
329 329
330 330 ip.user_ns["a_obj"] = A()
331 331 assert (
332 332 "This is `foobar` property."
333 333 == ip.object_inspect("a_obj.foobar", detail_level=0)["docstring"]
334 334 )
335 335
336 336 ip.user_ns["a_cls"] = A
337 337 assert (
338 338 "This is `foobar` property."
339 339 == ip.object_inspect("a_cls.foobar", detail_level=0)["docstring"]
340 340 )
341 341
342 342
343 343 def test_pdef():
344 344 # See gh-1914
345 345 def foo(): pass
346 346 inspector.pdef(foo, 'foo')
347 347
348 348
349 349 @contextmanager
350 350 def cleanup_user_ns(**kwargs):
351 351 """
352 352 On exit delete all the keys that were not in user_ns before entering.
353 353
354 354 It does not restore old values !
355 355
356 356 Parameters
357 357 ----------
358 358
359 359 **kwargs
360 360 used to update ip.user_ns
361 361
362 362 """
363 363 try:
364 364 known = set(ip.user_ns.keys())
365 365 ip.user_ns.update(kwargs)
366 366 yield
367 367 finally:
368 368 added = set(ip.user_ns.keys()) - known
369 369 for k in added:
370 370 del ip.user_ns[k]
371 371
372 372
373 373 def test_pinfo_getindex():
374 374 def dummy():
375 375 """
376 376 MARKER
377 377 """
378 378
379 379 container = [dummy]
380 380 with cleanup_user_ns(container=container):
381 381 with AssertPrints("MARKER"):
382 382 ip._inspect("pinfo", "container[0]", detail_level=0)
383 383 assert "container" not in ip.user_ns.keys()
384 384
385 385
386 386 def test_qmark_getindex():
387 387 def dummy():
388 388 """
389 389 MARKER 2
390 390 """
391 391
392 392 container = [dummy]
393 393 with cleanup_user_ns(container=container):
394 394 with AssertPrints("MARKER 2"):
395 395 ip.run_cell("container[0]?")
396 396 assert "container" not in ip.user_ns.keys()
397 397
398 398
399 399 def test_qmark_getindex_negatif():
400 400 def dummy():
401 401 """
402 402 MARKER 3
403 403 """
404 404
405 405 container = [dummy]
406 406 with cleanup_user_ns(container=container):
407 407 with AssertPrints("MARKER 3"):
408 408 ip.run_cell("container[-1]?")
409 409 assert "container" not in ip.user_ns.keys()
410 410
411 411
412 412
413 413 def test_pinfo_nonascii():
414 414 # See gh-1177
415 415 from . import nonascii2
416 416 ip.user_ns['nonascii2'] = nonascii2
417 417 ip._inspect('pinfo', 'nonascii2', detail_level=1)
418 418
419 419 def test_pinfo_type():
420 420 """
421 421 type can fail in various edge case, for example `type.__subclass__()`
422 422 """
423 423 ip._inspect('pinfo', 'type')
424 424
425 425
426 426 def test_pinfo_docstring_no_source():
427 427 """Docstring should be included with detail_level=1 if there is no source"""
428 428 with AssertPrints('Docstring:'):
429 429 ip._inspect('pinfo', 'str.format', detail_level=0)
430 430 with AssertPrints('Docstring:'):
431 431 ip._inspect('pinfo', 'str.format', detail_level=1)
432 432
433 433
434 434 def test_pinfo_no_docstring_if_source():
435 435 """Docstring should not be included with detail_level=1 if source is found"""
436 436 def foo():
437 437 """foo has a docstring"""
438 438
439 439 ip.user_ns['foo'] = foo
440 440
441 441 with AssertPrints('Docstring:'):
442 442 ip._inspect('pinfo', 'foo', detail_level=0)
443 443 with AssertPrints('Source:'):
444 444 ip._inspect('pinfo', 'foo', detail_level=1)
445 445 with AssertNotPrints('Docstring:'):
446 446 ip._inspect('pinfo', 'foo', detail_level=1)
447 447
448 448
449 449 def test_pinfo_docstring_if_detail_and_no_source():
450 450 """ Docstring should be displayed if source info not available """
451 451 obj_def = '''class Foo(object):
452 452 """ This is a docstring for Foo """
453 453 def bar(self):
454 454 """ This is a docstring for Foo.bar """
455 455 pass
456 456 '''
457 457
458 458 ip.run_cell(obj_def)
459 459 ip.run_cell('foo = Foo()')
460 460
461 461 with AssertNotPrints("Source:"):
462 462 with AssertPrints('Docstring:'):
463 463 ip._inspect('pinfo', 'foo', detail_level=0)
464 464 with AssertPrints('Docstring:'):
465 465 ip._inspect('pinfo', 'foo', detail_level=1)
466 466 with AssertPrints('Docstring:'):
467 467 ip._inspect('pinfo', 'foo.bar', detail_level=0)
468 468
469 469 with AssertNotPrints('Docstring:'):
470 470 with AssertPrints('Source:'):
471 471 ip._inspect('pinfo', 'foo.bar', detail_level=1)
472 472
473 473
474 def test_pinfo_docstring_dynamic():
475 obj_def = """class Bar:
476 __custom_documentations__ = {
477 "prop" : "cdoc for prop",
478 "non_exist" : "cdoc for non_exist",
479 }
480 @property
481 def prop(self):
482 '''
483 Docstring for prop
484 '''
485 return self._prop
486
487 @prop.setter
488 def prop(self, v):
489 self._prop = v
490 """
491 ip.run_cell(obj_def)
492
493 ip.run_cell("b = Bar()")
494
495 with AssertPrints("Docstring: cdoc for prop"):
496 ip.run_line_magic("pinfo", "b.prop")
497
498 with AssertPrints("Docstring: cdoc for non_exist"):
499 ip.run_line_magic("pinfo", "b.non_exist")
500
501 with AssertPrints("Docstring: cdoc for prop"):
502 ip.run_cell("b.prop?")
503
504 with AssertPrints("Docstring: cdoc for non_exist"):
505 ip.run_cell("b.non_exist?")
506
507 with AssertPrints("Docstring: <no docstring>"):
508 ip.run_cell("b.undefined?")
509
510
474 511 def test_pinfo_magic():
475 with AssertPrints('Docstring:'):
476 ip._inspect('pinfo', 'lsmagic', detail_level=0)
512 with AssertPrints("Docstring:"):
513 ip._inspect("pinfo", "lsmagic", detail_level=0)
477 514
478 with AssertPrints('Source:'):
479 ip._inspect('pinfo', 'lsmagic', detail_level=1)
515 with AssertPrints("Source:"):
516 ip._inspect("pinfo", "lsmagic", detail_level=1)
480 517
481 518
482 519 def test_init_colors():
483 520 # ensure colors are not present in signature info
484 521 info = inspector.info(HasSignature)
485 522 init_def = info["init_definition"]
486 523 assert "[0m" not in init_def
487 524
488 525
489 526 def test_builtin_init():
490 527 info = inspector.info(list)
491 528 init_def = info['init_definition']
492 529 assert init_def is not None
493 530
494 531
495 532 def test_render_signature_short():
496 533 def short_fun(a=1): pass
497 534 sig = oinspect._render_signature(
498 535 signature(short_fun),
499 536 short_fun.__name__,
500 537 )
501 538 assert sig == "short_fun(a=1)"
502 539
503 540
504 541 def test_render_signature_long():
505 542 from typing import Optional
506 543
507 544 def long_function(
508 545 a_really_long_parameter: int,
509 546 and_another_long_one: bool = False,
510 547 let_us_make_sure_this_is_looong: Optional[str] = None,
511 548 ) -> bool: pass
512 549
513 550 sig = oinspect._render_signature(
514 551 signature(long_function),
515 552 long_function.__name__,
516 553 )
517 554 assert sig in [
518 555 # Python >=3.9
519 556 '''\
520 557 long_function(
521 558 a_really_long_parameter: int,
522 559 and_another_long_one: bool = False,
523 560 let_us_make_sure_this_is_looong: Optional[str] = None,
524 561 ) -> bool\
525 562 ''',
526 563 # Python >=3.7
527 564 '''\
528 565 long_function(
529 566 a_really_long_parameter: int,
530 567 and_another_long_one: bool = False,
531 568 let_us_make_sure_this_is_looong: Union[str, NoneType] = None,
532 569 ) -> bool\
533 570 ''', # Python <=3.6
534 571 '''\
535 572 long_function(
536 573 a_really_long_parameter:int,
537 574 and_another_long_one:bool=False,
538 575 let_us_make_sure_this_is_looong:Union[str, NoneType]=None,
539 576 ) -> bool\
540 577 ''',
541 578 ]
@@ -1,1499 +1,1574
1 1 ============
2 2 8.x Series
3 3 ============
4 4
5 .. _version 8.12.0:
6
7
8 Dynamic documentation dispatch
9 ------------------------------
10
11
12 We are experimenting with dynamic documentation dispatch for object attribute.
13 See :ghissue:`13860`. The goal is to allow object to define documentation for
14 their attributes, properties, even when those are dynamically defined with
15 `__getattr__`.
16
17 In particular when those objects are base types it can be useful to show the
18 documentation
19
20
21 .. code::
22
23 In [1]: class User:
24 ...:
25 ...: __custom_documentations__ = {
26 ...: "first": "The first name of the user.",
27 ...: "last": "The last name of the user.",
28 ...: }
29 ...:
30 ...: first:str
31 ...: last:str
32 ...:
33 ...: def __init__(self, first, last):
34 ...: self.first = first
35 ...: self.last = last
36 ...:
37 ...: @property
38 ...: def full(self):
39 ...: """`self.first` and `self.last` joined by a space."""
40 ...: return self.first + " " + self.last
41 ...:
42 ...:
43 ...: user = Person('Jane', 'Doe')
44
45 In [2]: user.first?
46 Type: str
47 String form: Jane
48 Length: 4
49 Docstring: the first name of a the person object, a str
50 Class docstring:
51 ....
52
53 In [3]: user.last?
54 Type: str
55 String form: Doe
56 Length: 3
57 Docstring: the last name, also a str
58 ...
59
60
61 We can see here the symmetry with IPython looking for the docstring on the
62 properties::
63
64
65 In [4]: user.full?
66 HERE
67 Type: property
68 String form: <property object at 0x102bb15d0>
69 Docstring: first and last join by a space
70
71
72 Note that while in the above example we use a static dictionary, libraries may
73 decide to use a custom object that define ``__getitem__``, we caution against
74 using objects that would trigger computation to show documentation, but it is
75 sometime preferable for highly dynamic code that for example export ans API as
76 object.
77
78
79
5 80 .. _version 8.11.0:
6 81
7 82 IPython 8.11
8 83 ------------
9 84
10 85 Back on almost regular monthly schedule for IPython with end-of-month
11 86 really-late-Friday release to make sure some bugs are properly fixed.
12 87 Small addition of with a few new features, bugfix and UX improvements.
13 88
14 89 This is a non-exhaustive list, but among other you will find:
15 90
16 91 Faster Traceback Highlighting
17 92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 93
19 94 Resurrection of pre-IPython-8 traceback highlighting code.
20 95
21 96 Really long and complicated files were slow to highlight in traceback with
22 97 IPython 8 despite upstream improvement that make many case better. Therefore
23 98 starting with IPython 8.11 when one of the highlighted file is more than 10 000
24 99 line long by default, we'll fallback to a faster path that does not have all the
25 100 features of highlighting failing AST nodes.
26 101
27 102 This can be configures by setting the value of
28 103 ``IPython.code.ultratb.FAST_THRESHOLD`` to an arbitrary low or large value.
29 104
30 105
31 106 Autoreload verbosity
32 107 ~~~~~~~~~~~~~~~~~~~~
33 108
34 109 We introduce more descriptive names for the ``%autoreload`` parameter:
35 110
36 111 - ``%autoreload now`` (also ``%autoreload``) - perform autoreload immediately.
37 112 - ``%autoreload off`` (also ``%autoreload 0``) - turn off autoreload.
38 113 - ``%autoreload explicit`` (also ``%autoreload 1``) - turn on autoreload only for modules
39 114 whitelisted by ``%aimport`` statements.
40 115 - ``%autoreload all`` (also ``%autoreload 2``) - turn on autoreload for all modules except those
41 116 blacklisted by ``%aimport`` statements.
42 117 - ``%autoreload complete`` (also ``%autoreload 3``) - all the fatures of ``all`` but also adding new
43 118 objects from the imported modules (see
44 119 IPython/extensions/tests/test_autoreload.py::test_autoload_newly_added_objects).
45 120
46 121 The original designations (e.g. "2") still work, and these new ones are case-insensitive.
47 122
48 123 Additionally, the option ``--print`` or ``-p`` can be added to the line to print the names of
49 124 modules being reloaded. Similarly, ``--log`` or ``-l`` will output the names to the logger at INFO
50 125 level. Both can be used simultaneously.
51 126
52 127 The parsing logic for ``%aimport`` is now improved such that modules can be whitelisted and
53 128 blacklisted in the same line, e.g. it's now possible to call ``%aimport os, -math`` to include
54 129 ``os`` for ``%autoreload explicit`` and exclude ``math`` for modes ``all`` and ``complete``.
55 130
56 131 Terminal shortcuts customization
57 132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58 133
59 134 Previously modifying shortcuts was only possible by hooking into startup files
60 135 and practically limited to adding new shortcuts or removing all shortcuts bound
61 136 to a specific key. This release enables users to override existing terminal
62 137 shortcuts, disable them or add new keybindings.
63 138
64 139 For example, to set the :kbd:`right` to accept a single character of auto-suggestion
65 140 you could use::
66 141
67 142 my_shortcuts = [
68 143 {
69 144 "command": "IPython:auto_suggest.accept_character",
70 145 "new_keys": ["right"]
71 146 }
72 147 ]
73 148 %config TerminalInteractiveShell.shortcuts = my_shortcuts
74 149
75 150 You can learn more in :std:configtrait:`TerminalInteractiveShell.shortcuts`
76 151 configuration reference.
77 152
78 153 Miscellaneous
79 154 ~~~~~~~~~~~~~
80 155
81 156 - ``%gui`` should now support PySide6. :ghpull:`13864`
82 157 - Cli shortcuts can now be configured :ghpull:`13928`, see above.
83 158 (note that there might be an issue with prompt_toolkit 3.0.37 and shortcut configuration).
84 159
85 160 - Capture output should now respect ``;`` semicolon to suppress output.
86 161 :ghpull:`13940`
87 162 - Base64 encoded images (in jupyter frontend), will not have trailing newlines.
88 163 :ghpull:`13941`
89 164
90 165 As usual you can find the full list of PRs on GitHub under `the 8.11 milestone
91 166 <https://github.com/ipython/ipython/milestone/113?closed=1>`__.
92 167
93 168 Thanks to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
94 169 work on IPython and related libraries.
95 170
96 171 .. _version 8.10.0:
97
172
98 173 IPython 8.10
99 174 ------------
100 175
101 176 Out of schedule release of IPython with minor fixes to patch a potential CVE-2023-24816.
102 177 This is a really low severity CVE that you most likely are not affected by unless:
103 178
104 179 - You are on windows.
105 180 - You have a custom build of Python without ``_ctypes``
106 181 - You cd or start IPython or Jupyter in untrusted directory which names may be
107 182 valid shell commands.
108 183
109 184 You can read more on `the advisory
110 <https://github.com/ipython/ipython/security/advisories/GHSA-29gw-9793-fvw7>`__.
185 <https://github.com/ipython/ipython/security/advisories/GHSA-29gw-9793-fvw7>`__.
111 186
112 187 In addition to fixing this CVE we also fix a couple of outstanding bugs and issues.
113 188
114 189 As usual you can find the full list of PRs on GitHub under `the 8.10 milestone
115 190 <https://github.com/ipython/ipython/milestone/112?closed=1>`__.
116 191
117 192 In Particular:
118 193
119 194 - bump minimum numpy to `>=1.21` version following NEP29. :ghpull:`13930`
120 195 - fix for compatibility with MyPy 1.0. :ghpull:`13933`
121 196 - fix nbgrader stalling when IPython's ``showtraceback`` function is
122 197 monkeypatched. :ghpull:`13934`
123 198
124 199
125 200
126 201 As this release also contains those minimal changes in addition to fixing the
127 202 CVE I decided to bump the minor version anyway.
128 203
129 204 This will not affect the normal release schedule, so IPython 8.11 is due in
130 205 about 2 weeks.
131 206
132 207 .. _version 8.9.0:
133 208
134 209 IPython 8.9.0
135 210 -------------
136 211
137 212 Second release of IPython in 2023, last Friday of the month, we are back on
138 213 track. This is a small release with a few bug-fixes, and improvements, mostly
139 214 with respect to terminal shortcuts.
140 215
141 216
142 217 The biggest improvement for 8.9 is a drastic amelioration of the
143 218 auto-suggestions sponsored by D.E. Shaw and implemented by the more and more
144 219 active contributor `@krassowski <https://github.com/krassowski>`.
145 220
146 221 - ``right`` accepts a single character from suggestion
147 222 - ``ctrl+right`` accepts a semantic token (macos default shortcuts take
148 223 precedence and need to be disabled to make this work)
149 224 - ``backspace`` deletes a character and resumes hinting autosuggestions
150 225 - ``ctrl-left`` accepts suggestion and moves cursor left one character.
151 226 - ``backspace`` deletes a character and resumes hinting autosuggestions
152 227 - ``down`` moves to suggestion to later in history when no lines are present below the cursors.
153 228 - ``up`` moves to suggestion from earlier in history when no lines are present above the cursor.
154 229
155 230 This is best described by the Gif posted by `@krassowski
156 231 <https://github.com/krassowski>`, and in the PR itself :ghpull:`13888`.
157 232
158 233 .. image:: ../_images/autosuggest.gif
159 234
160 235 Please report any feedback in order for us to improve the user experience.
161 236 In particular we are also working on making the shortcuts configurable.
162 237
163 238 If you are interested in better terminal shortcuts, I also invite you to
164 239 participate in issue `13879
165 240 <https://github.com/ipython/ipython/issues/13879>`__.
166 241
167 242
168 243 As we follow `NEP29
169 244 <https://numpy.org/neps/nep-0029-deprecation_policy.html>`__, next version of
170 245 IPython will officially stop supporting numpy 1.20, and will stop supporting
171 246 Python 3.8 after April release.
172 247
173 248 As usual you can find the full list of PRs on GitHub under `the 8.9 milestone
174 249 <https://github.com/ipython/ipython/milestone/111?closed=1>`__.
175 250
176 251
177 252 Thanks to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
178 253 work on IPython and related libraries.
179 254
180 255 .. _version 8.8.0:
181 256
182 257 IPython 8.8.0
183 258 -------------
184 259
185 260 First release of IPython in 2023 as there was no release at the end of
186 261 December.
187 262
188 263 This is an unusually big release (relatively speaking) with more than 15 Pull
189 264 Requests merged.
190 265
191 266 Of particular interest are:
192 267
193 268 - :ghpull:`13852` that replaces the greedy completer and improves
194 269 completion, in particular for dictionary keys.
195 270 - :ghpull:`13858` that adds ``py.typed`` to ``setup.cfg`` to make sure it is
196 271 bundled in wheels.
197 272 - :ghpull:`13869` that implements tab completions for IPython options in the
198 273 shell when using `argcomplete <https://github.com/kislyuk/argcomplete>`. I
199 274 believe this also needs a recent version of Traitlets.
200 275 - :ghpull:`13865` makes the ``inspector`` class of `InteractiveShell`
201 276 configurable.
202 277 - :ghpull:`13880` that removes minor-version entrypoints as the minor version
203 278 entry points that would be included in the wheel would be the one of the
204 279 Python version that was used to build the ``whl`` file.
205 280
206 281 In no particular order, the rest of the changes update the test suite to be
207 282 compatible with Pygments 2.14, various docfixes, testing on more recent python
208 283 versions and various updates.
209 284
210 285 As usual you can find the full list of PRs on GitHub under `the 8.8 milestone
211 286 <https://github.com/ipython/ipython/milestone/110>`__.
212 287
213 288 Many thanks to @krassowski for the many PRs and @jasongrout for reviewing and
214 289 merging contributions.
215 290
216 291 Thanks to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
217 292 work on IPython and related libraries.
218 293
219 294 .. _version 8.7.0:
220 295
221 296 IPython 8.7.0
222 297 -------------
223 298
224 299
225 300 Small release of IPython with a couple of bug fixes and new features for this
226 301 month. Next month is the end of year, it is unclear if there will be a release
227 302 close to the new year's eve, or if the next release will be at the end of January.
228 303
229 304 Here are a few of the relevant fixes,
230 305 as usual you can find the full list of PRs on GitHub under `the 8.7 milestone
231 306 <https://github.com/ipython/ipython/pulls?q=milestone%3A8.7>`__.
232 307
233 308
234 309 - :ghpull:`13834` bump the minimum prompt toolkit to 3.0.11.
235 310 - IPython shipped with the ``py.typed`` marker now, and we are progressively
236 311 adding more types. :ghpull:`13831`
237 312 - :ghpull:`13817` add configuration of code blacks formatting.
238 313
239 314
240 315 Thanks to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
241 316 work on IPython and related libraries.
242 317
243 318
244 319 .. _version 8.6.0:
245 320
246 321 IPython 8.6.0
247 322 -------------
248 323
249 324 Back to a more regular release schedule (at least I try), as Friday is
250 325 already over by more than 24h hours. This is a slightly bigger release with a
251 326 few new features that contain no less than 25 PRs.
252 327
253 328 We'll notably found a couple of non negligible changes:
254 329
255 330 The ``install_ext`` and related functions have been removed after being
256 331 deprecated for years. You can use pip to install extensions. ``pip`` did not
257 332 exist when ``install_ext`` was introduced. You can still load local extensions
258 333 without installing them. Just set your ``sys.path`` for example. :ghpull:`13744`
259 334
260 335 IPython now has extra entry points that use the major *and minor* version of
261 336 python. For some of you this means that you can do a quick ``ipython3.10`` to
262 337 launch IPython from the Python 3.10 interpreter, while still using Python 3.11
263 338 as your main Python. :ghpull:`13743`
264 339
265 340 The completer matcher API has been improved. See :ghpull:`13745`. This should
266 341 improve the type inference and improve dict keys completions in many use case.
267 342 Thanks ``@krassowski`` for all the work, and the D.E. Shaw group for sponsoring
268 343 it.
269 344
270 345 The color of error nodes in tracebacks can now be customized. See
271 346 :ghpull:`13756`. This is a private attribute until someone finds the time to
272 347 properly add a configuration option. Note that with Python 3.11 that also shows
273 348 the relevant nodes in traceback, it would be good to leverage this information
274 349 (plus the "did you mean" info added on attribute errors). But that's likely work
275 350 I won't have time to do before long, so contributions welcome.
276 351
277 352 As we follow NEP 29, we removed support for numpy 1.19 :ghpull:`13760`.
278 353
279 354
280 355 The ``open()`` function present in the user namespace by default will now refuse
281 356 to open the file descriptors 0,1,2 (stdin, out, err), to avoid crashing IPython.
282 357 This mostly occurs in teaching context when incorrect values get passed around.
283 358
284 359
285 360 The ``?``, ``??``, and corresponding ``pinfo``, ``pinfo2`` magics can now find
286 361 objects inside arrays. That is to say, the following now works::
287 362
288 363
289 364 >>> def my_func(*arg, **kwargs):pass
290 365 >>> container = [my_func]
291 366 >>> container[0]?
292 367
293 368
294 369 If ``container`` define a custom ``getitem``, this __will__ trigger the custom
295 370 method. So don't put side effects in your ``getitems``. Thanks to the D.E. Shaw
296 371 group for the request and sponsoring the work.
297 372
298 373
299 374 As usual you can find the full list of PRs on GitHub under `the 8.6 milestone
300 375 <https://github.com/ipython/ipython/pulls?q=milestone%3A8.6>`__.
301 376
302 377 Thanks to all hacktoberfest contributors, please contribute to
303 378 `closember.org <https://closember.org/>`__.
304 379
305 380 Thanks to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
306 381 work on IPython and related libraries.
307 382
308 383 .. _version 8.5.0:
309 384
310 385 IPython 8.5.0
311 386 -------------
312 387
313 388 First release since a couple of month due to various reasons and timing preventing
314 389 me for sticking to the usual monthly release the last Friday of each month. This
315 390 is of non negligible size as it has more than two dozen PRs with various fixes
316 391 an bug fixes.
317 392
318 393 Many thanks to everybody who contributed PRs for your patience in review and
319 394 merges.
320 395
321 396 Here is a non-exhaustive list of changes that have been implemented for IPython
322 397 8.5.0. As usual you can find the full list of issues and PRs tagged with `the
323 398 8.5 milestone
324 399 <https://github.com/ipython/ipython/pulls?q=is%3Aclosed+milestone%3A8.5+>`__.
325 400
326 401 - Added a shortcut for accepting auto suggestion. The End key shortcut for
327 402 accepting auto-suggestion This binding works in Vi mode too, provided
328 403 ``TerminalInteractiveShell.emacs_bindings_in_vi_insert_mode`` is set to be
329 404 ``True`` :ghpull:`13566`.
330 405
331 406 - No popup in window for latex generation when generating latex (e.g. via
332 407 `_latex_repr_`) no popup window is shows under Windows. :ghpull:`13679`
333 408
334 409 - Fixed error raised when attempting to tab-complete an input string with
335 410 consecutive periods or forward slashes (such as "file:///var/log/...").
336 411 :ghpull:`13675`
337 412
338 413 - Relative filenames in Latex rendering :
339 414 The `latex_to_png_dvipng` command internally generates input and output file
340 415 arguments to `latex` and `dvipis`. These arguments are now generated as
341 416 relative files to the current working directory instead of absolute file
342 417 paths. This solves a problem where the current working directory contains
343 418 characters that are not handled properly by `latex` and `dvips`. There are
344 419 no changes to the user API. :ghpull:`13680`
345 420
346 421 - Stripping decorators bug: Fixed bug which meant that ipython code blocks in
347 422 restructured text documents executed with the ipython-sphinx extension
348 423 skipped any lines of code containing python decorators. :ghpull:`13612`
349 424
350 425 - Allow some modules with frozen dataclasses to be reloaded. :ghpull:`13732`
351 426 - Fix paste magic on wayland. :ghpull:`13671`
352 427 - show maxlen in deque's repr. :ghpull:`13648`
353 428
354 429 Restore line numbers for Input
355 430 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
356 431
357 432 Line number information in tracebacks from input are restored.
358 433 Line numbers from input were removed during the transition to v8 enhanced traceback reporting.
359 434
360 435 So, instead of::
361 436
362 437 ---------------------------------------------------------------------------
363 438 ZeroDivisionError Traceback (most recent call last)
364 439 Input In [3], in <cell line: 1>()
365 440 ----> 1 myfunc(2)
366 441
367 442 Input In [2], in myfunc(z)
368 443 1 def myfunc(z):
369 444 ----> 2 foo.boo(z-1)
370 445
371 446 File ~/code/python/ipython/foo.py:3, in boo(x)
372 447 2 def boo(x):
373 448 ----> 3 return 1/(1-x)
374 449
375 450 ZeroDivisionError: division by zero
376 451
377 452 The error traceback now looks like::
378 453
379 454 ---------------------------------------------------------------------------
380 455 ZeroDivisionError Traceback (most recent call last)
381 456 Cell In [3], line 1
382 457 ----> 1 myfunc(2)
383 458
384 459 Cell In [2], line 2, in myfunc(z)
385 460 1 def myfunc(z):
386 461 ----> 2 foo.boo(z-1)
387 462
388 463 File ~/code/python/ipython/foo.py:3, in boo(x)
389 464 2 def boo(x):
390 465 ----> 3 return 1/(1-x)
391 466
392 467 ZeroDivisionError: division by zero
393 468
394 469 or, with xmode=Plain::
395 470
396 471 Traceback (most recent call last):
397 472 Cell In [12], line 1
398 473 myfunc(2)
399 474 Cell In [6], line 2 in myfunc
400 475 foo.boo(z-1)
401 476 File ~/code/python/ipython/foo.py:3 in boo
402 477 return 1/(1-x)
403 478 ZeroDivisionError: division by zero
404 479
405 480 :ghpull:`13560`
406 481
407 482 New setting to silence warning if working inside a virtual environment
408 483 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
409 484
410 485 Previously, when starting IPython in a virtual environment without IPython installed (so IPython from the global environment is used), the following warning was printed:
411 486
412 487 Attempting to work in a virtualenv. If you encounter problems, please install IPython inside the virtualenv.
413 488
414 489 This warning can be permanently silenced by setting ``c.InteractiveShell.warn_venv`` to ``False`` (the default is ``True``).
415 490
416 491 :ghpull:`13706`
417 492
418 493 -------
419 494
420 495 Thanks to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
421 496 work on IPython and related libraries.
422 497
423 498
424 499 .. _version 8.4.0:
425 500
426 501 IPython 8.4.0
427 502 -------------
428 503
429 504 As for 7.34, this version contains a single fix: fix uncaught BdbQuit exceptions on ipdb
430 505 exit :ghpull:`13668`, and a single typo fix in documentation: :ghpull:`13682`
431 506
432 507 Thanks to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
433 508 work on IPython and related libraries.
434 509
435 510
436 511 .. _version 8.3.0:
437 512
438 513 IPython 8.3.0
439 514 -------------
440 515
441 516 - :ghpull:`13625`, using ``?``, ``??``, ``*?`` will not call
442 517 ``set_next_input`` as most frontend allow proper multiline editing and it was
443 518 causing issues for many users of multi-cell frontends. This has been backported to 7.33
444 519
445 520
446 521 - :ghpull:`13600`, ``pre_run_*``-hooks will now have a ``cell_id`` attribute on
447 522 the info object when frontend provides it. This has been backported to 7.33
448 523
449 524 - :ghpull:`13624`, fixed :kbd:`End` key being broken after accepting an
450 525 auto-suggestion.
451 526
452 527 - :ghpull:`13657` fixed an issue where history from different sessions would be mixed.
453 528
454 529 .. _version 8.2.0:
455 530
456 531 IPython 8.2.0
457 532 -------------
458 533
459 534 IPython 8.2 mostly bring bugfixes to IPython.
460 535
461 536 - Auto-suggestion can now be elected with the ``end`` key. :ghpull:`13566`
462 537 - Some traceback issues with ``assert etb is not None`` have been fixed. :ghpull:`13588`
463 538 - History is now pulled from the sqitel database and not from in-memory.
464 539 In particular when using the ``%paste`` magic, the content of the pasted text will
465 540 be part of the history and not the verbatim text ``%paste`` anymore. :ghpull:`13592`
466 541 - Fix ``Ctrl-\\`` exit cleanup :ghpull:`13603`
467 542 - Fixes to ``ultratb`` ipdb support when used outside of IPython. :ghpull:`13498`
468 543
469 544
470 545 I am still trying to fix and investigate :ghissue:`13598`, which seems to be
471 546 random, and would appreciate help if you find a reproducible minimal case. I've
472 547 tried to make various changes to the codebase to mitigate it, but a proper fix
473 548 will be difficult without understanding the cause.
474 549
475 550
476 551 All the issues on pull-requests for this release can be found in the `8.2
477 552 milestone. <https://github.com/ipython/ipython/milestone/100>`__ . And some
478 553 documentation only PR can be found as part of the `7.33 milestone
479 554 <https://github.com/ipython/ipython/milestone/101>`__ (currently not released).
480 555
481 556 Thanks to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
482 557 work on IPython and related libraries.
483 558
484 559 .. _version 8.1.1:
485 560
486 561 IPython 8.1.1
487 562 -------------
488 563
489 564 Fix an issue with virtualenv and Python 3.8 introduced in 8.1
490 565
491 566 Revert :ghpull:`13537` (fix an issue with symlinks in virtualenv) that raises an
492 567 error in Python 3.8, and fixed in a different way in :ghpull:`13559`.
493 568
494 569 .. _version 8.1:
495 570
496 571 IPython 8.1.0
497 572 -------------
498 573
499 574 IPython 8.1 is the first minor release after 8.0 and fixes a number of bugs and
500 575 updates a few behaviors that were problematic with the 8.0 as with many new major
501 576 release.
502 577
503 578 Note that beyond the changes listed here, IPython 8.1.0 also contains all the
504 579 features listed in :ref:`version 7.32`.
505 580
506 581 - Misc and multiple fixes around quotation auto-closing. It is now disabled by
507 582 default. Run with ``TerminalInteractiveShell.auto_match=True`` to re-enabled
508 583 - Require pygments>=2.4.0 :ghpull:`13459`, this was implicit in the code, but
509 584 is now explicit in ``setup.cfg``/``setup.py``
510 585 - Docs improvement of ``core.magic_arguments`` examples. :ghpull:`13433`
511 586 - Multi-line edit executes too early with await. :ghpull:`13424`
512 587
513 588 - ``black`` is back as an optional dependency, and autoformatting disabled by
514 589 default until some fixes are implemented (black improperly reformat magics).
515 590 :ghpull:`13471` Additionally the ability to use ``yapf`` as a code
516 591 reformatter has been added :ghpull:`13528` . You can use
517 592 ``TerminalInteractiveShell.autoformatter="black"``,
518 593 ``TerminalInteractiveShell.autoformatter="yapf"`` to re-enable auto formating
519 594 with black, or switch to yapf.
520 595
521 596 - Fix and issue where ``display`` was not defined.
522 597
523 598 - Auto suggestions are now configurable. Currently only
524 599 ``AutoSuggestFromHistory`` (default) and ``None``. new provider contribution
525 600 welcomed. :ghpull:`13475`
526 601
527 602 - multiple packaging/testing improvement to simplify downstream packaging
528 603 (xfail with reasons, try to not access network...).
529 604
530 605 - Update deprecation. ``InteractiveShell.magic`` internal method has been
531 606 deprecated for many years but did not emit a warning until now.
532 607
533 608 - internal ``appended_to_syspath`` context manager has been deprecated.
534 609
535 610 - fix an issue with symlinks in virtualenv :ghpull:`13537` (Reverted in 8.1.1)
536 611
537 612 - Fix an issue with vim mode, where cursor would not be reset on exit :ghpull:`13472`
538 613
539 614 - ipython directive now remove only known pseudo-decorators :ghpull:`13532`
540 615
541 616 - ``IPython/lib/security`` which used to be used for jupyter notebook has been
542 617 removed.
543 618
544 619 - Fix an issue where ``async with`` would execute on new lines. :ghpull:`13436`
545 620
546 621
547 622 We want to remind users that IPython is part of the Jupyter organisations, and
548 623 thus governed by a Code of Conduct. Some of the behavior we have seen on GitHub is not acceptable.
549 624 Abuse and non-respectful comments on discussion will not be tolerated.
550 625
551 626 Many thanks to all the contributors to this release, many of the above fixed issues and
552 627 new features were done by first time contributors, showing there is still
553 628 plenty of easy contribution possible in IPython
554 629 . You can find all individual contributions
555 630 to this milestone `on github <https://github.com/ipython/ipython/milestone/91>`__.
556 631
557 632 Thanks as well to the `D. E. Shaw group <https://deshaw.com/>`__ for sponsoring
558 633 work on IPython and related libraries. In particular the Lazy autoloading of
559 634 magics that you will find described in the 7.32 release notes.
560 635
561 636
562 637 .. _version 8.0.1:
563 638
564 639 IPython 8.0.1 (CVE-2022-21699)
565 640 ------------------------------
566 641
567 642 IPython 8.0.1, 7.31.1 and 5.11 are security releases that change some default
568 643 values in order to prevent potential Execution with Unnecessary Privileges.
569 644
570 645 Almost all version of IPython looks for configuration and profiles in current
571 646 working directory. Since IPython was developed before pip and environments
572 647 existed it was used a convenient way to load code/packages in a project
573 648 dependant way.
574 649
575 650 In 2022, it is not necessary anymore, and can lead to confusing behavior where
576 651 for example cloning a repository and starting IPython or loading a notebook from
577 652 any Jupyter-Compatible interface that has ipython set as a kernel can lead to
578 653 code execution.
579 654
580 655
581 656 I did not find any standard way for packaged to advertise CVEs they fix, I'm
582 657 thus trying to add a ``__patched_cves__`` attribute to the IPython module that
583 658 list the CVEs that should have been fixed. This attribute is informational only
584 659 as if a executable has a flaw, this value can always be changed by an attacker.
585 660
586 661 .. code::
587 662
588 663 In [1]: import IPython
589 664
590 665 In [2]: IPython.__patched_cves__
591 666 Out[2]: {'CVE-2022-21699'}
592 667
593 668 In [3]: 'CVE-2022-21699' in IPython.__patched_cves__
594 669 Out[3]: True
595 670
596 671 Thus starting with this version:
597 672
598 673 - The current working directory is not searched anymore for profiles or
599 674 configurations files.
600 675 - Added a ``__patched_cves__`` attribute (set of strings) to IPython module that contain
601 676 the list of fixed CVE. This is informational only.
602 677
603 678 Further details can be read on the `GitHub Advisory <https://github.com/ipython/ipython/security/advisories/GHSA-pq7m-3gw7-gq5x>`__
604 679
605 680
606 681 .. _version 8.0:
607 682
608 683 IPython 8.0
609 684 -----------
610 685
611 686 IPython 8.0 is bringing a large number of new features and improvements to both the
612 687 user of the terminal and of the kernel via Jupyter. The removal of compatibility
613 688 with an older version of Python is also the opportunity to do a couple of
614 689 performance improvements in particular with respect to startup time.
615 690 The 8.x branch started diverging from its predecessor around IPython 7.12
616 691 (January 2020).
617 692
618 693 This release contains 250+ pull requests, in addition to many of the features
619 694 and backports that have made it to the 7.x branch. Please see the
620 695 `8.0 milestone <https://github.com/ipython/ipython/milestone/73?closed=1>`__ for the full list of pull requests.
621 696
622 697 Please feel free to send pull requests to update those notes after release,
623 698 I have likely forgotten a few things reviewing 250+ PRs.
624 699
625 700 Dependencies changes/downstream packaging
626 701 -----------------------------------------
627 702
628 703 Most of our building steps have been changed to be (mostly) declarative
629 704 and follow PEP 517. We are trying to completely remove ``setup.py`` (:ghpull:`13238`) and are
630 705 looking for help to do so.
631 706
632 707 - minimum supported ``traitlets`` version is now 5+
633 708 - we now require ``stack_data``
634 709 - minimal Python is now 3.8
635 710 - ``nose`` is not a testing requirement anymore
636 711 - ``pytest`` replaces nose.
637 712 - ``iptest``/``iptest3`` cli entrypoints do not exist anymore.
638 713 - the minimum officially ​supported ``numpy`` version has been bumped, but this should
639 714 not have much effect on packaging.
640 715
641 716
642 717 Deprecation and removal
643 718 -----------------------
644 719
645 720 We removed almost all features, arguments, functions, and modules that were
646 721 marked as deprecated between IPython 1.0 and 5.0. As a reminder, 5.0 was released
647 722 in 2016, and 1.0 in 2013. Last release of the 5 branch was 5.10.0, in May 2020.
648 723 The few remaining deprecated features we left have better deprecation warnings
649 724 or have been turned into explicit errors for better error messages.
650 725
651 726 I will use this occasion to add the following requests to anyone emitting a
652 727 deprecation warning:
653 728
654 729 - Please add at least ``stacklevel=2`` so that the warning is emitted into the
655 730 caller context, and not the callee one.
656 731 - Please add **since which version** something is deprecated.
657 732
658 733 As a side note, it is much easier to conditionally compare version
659 734 numbers rather than using ``try/except`` when functionality changes with a version.
660 735
661 736 I won't list all the removed features here, but modules like ``IPython.kernel``,
662 737 which was just a shim module around ``ipykernel`` for the past 8 years, have been
663 738 removed, and so many other similar things that pre-date the name **Jupyter**
664 739 itself.
665 740
666 741 We no longer need to add ``IPython.extensions`` to the PYTHONPATH because that is being
667 742 handled by ``load_extension``.
668 743
669 744 We are also removing ``Cythonmagic``, ``sympyprinting`` and ``rmagic`` as they are now in
670 745 other packages and no longer need to be inside IPython.
671 746
672 747
673 748 Documentation
674 749 -------------
675 750
676 751 The majority of our docstrings have now been reformatted and automatically fixed by
677 752 the experimental `VΓ©lin <https://pypi.org/project/velin/>`_ project to conform
678 753 to numpydoc.
679 754
680 755 Type annotations
681 756 ----------------
682 757
683 758 While IPython itself is highly dynamic and can't be completely typed, many of
684 759 the functions now have type annotations, and part of the codebase is now checked
685 760 by mypy.
686 761
687 762
688 763 Featured changes
689 764 ----------------
690 765
691 766 Here is a features list of changes in IPython 8.0. This is of course non-exhaustive.
692 767 Please note as well that many features have been added in the 7.x branch as well
693 768 (and hence why you want to read the 7.x what's new notes), in particular
694 769 features contributed by QuantStack (with respect to debugger protocol and Xeus
695 770 Python), as well as many debugger features that I was pleased to implement as
696 771 part of my work at QuanSight and sponsored by DE Shaw.
697 772
698 773 Traceback improvements
699 774 ~~~~~~~~~~~~~~~~~~~~~~
700 775
701 776 Previously, error tracebacks for errors happening in code cells were showing a
702 777 hash, the one used for compiling the Python AST::
703 778
704 779 In [1]: def foo():
705 780 ...: return 3 / 0
706 781 ...:
707 782
708 783 In [2]: foo()
709 784 ---------------------------------------------------------------------------
710 785 ZeroDivisionError Traceback (most recent call last)
711 786 <ipython-input-2-c19b6d9633cf> in <module>
712 787 ----> 1 foo()
713 788
714 789 <ipython-input-1-1595a74c32d5> in foo()
715 790 1 def foo():
716 791 ----> 2 return 3 / 0
717 792 3
718 793
719 794 ZeroDivisionError: division by zero
720 795
721 796 The error traceback is now correctly formatted, showing the cell number in which the error happened::
722 797
723 798 In [1]: def foo():
724 799 ...: return 3 / 0
725 800 ...:
726 801
727 802 Input In [2]: foo()
728 803 ---------------------------------------------------------------------------
729 804 ZeroDivisionError Traceback (most recent call last)
730 805 input In [2], in <module>
731 806 ----> 1 foo()
732 807
733 808 Input In [1], in foo()
734 809 1 def foo():
735 810 ----> 2 return 3 / 0
736 811
737 812 ZeroDivisionError: division by zero
738 813
739 814 The ``stack_data`` package has been integrated, which provides smarter information in the traceback;
740 815 in particular it will highlight the AST node where an error occurs which can help to quickly narrow down errors.
741 816
742 817 For example in the following snippet::
743 818
744 819 def foo(i):
745 820 x = [[[0]]]
746 821 return x[0][i][0]
747 822
748 823
749 824 def bar():
750 825 return foo(0) + foo(
751 826 1
752 827 ) + foo(2)
753 828
754 829
755 830 calling ``bar()`` would raise an ``IndexError`` on the return line of ``foo``,
756 831 and IPython 8.0 is capable of telling you where the index error occurs::
757 832
758 833
759 834 IndexError
760 835 Input In [2], in <module>
761 836 ----> 1 bar()
762 837 ^^^^^
763 838
764 839 Input In [1], in bar()
765 840 6 def bar():
766 841 ----> 7 return foo(0) + foo(
767 842 ^^^^
768 843 8 1
769 844 ^^^^^^^^
770 845 9 ) + foo(2)
771 846 ^^^^
772 847
773 848 Input In [1], in foo(i)
774 849 1 def foo(i):
775 850 2 x = [[[0]]]
776 851 ----> 3 return x[0][i][0]
777 852 ^^^^^^^
778 853
779 854 The corresponding locations marked here with ``^`` will show up highlighted in
780 855 the terminal and notebooks.
781 856
782 857 Finally, a colon ``::`` and line number is appended after a filename in
783 858 traceback::
784 859
785 860
786 861 ZeroDivisionError Traceback (most recent call last)
787 862 File ~/error.py:4, in <module>
788 863 1 def f():
789 864 2 1/0
790 865 ----> 4 f()
791 866
792 867 File ~/error.py:2, in f()
793 868 1 def f():
794 869 ----> 2 1/0
795 870
796 871 Many terminals and editors have integrations enabling you to directly jump to the
797 872 relevant file/line when this syntax is used, so this small addition may have a high
798 873 impact on productivity.
799 874
800 875
801 876 Autosuggestions
802 877 ~~~~~~~~~~~~~~~
803 878
804 879 Autosuggestion is a very useful feature available in `fish <https://fishshell.com/>`__, `zsh <https://en.wikipedia.org/wiki/Z_shell>`__, and `prompt-toolkit <https://python-prompt-toolkit.readthedocs.io/en/master/pages/asking_for_input.html#auto-suggestion>`__.
805 880
806 881 `Ptpython <https://github.com/prompt-toolkit/ptpython#ptpython>`__ allows users to enable this feature in
807 882 `ptpython/config.py <https://github.com/prompt-toolkit/ptpython/blob/master/examples/ptpython_config/config.py#L90>`__.
808 883
809 884 This feature allows users to accept autosuggestions with ctrl e, ctrl f,
810 885 or right arrow as described below.
811 886
812 887 1. Start ipython
813 888
814 889 .. image:: ../_images/8.0/auto_suggest_1_prompt_no_text.png
815 890
816 891 2. Run ``print("hello")``
817 892
818 893 .. image:: ../_images/8.0/auto_suggest_2_print_hello_suggest.png
819 894
820 895 3. start typing ``print`` again to see the autosuggestion
821 896
822 897 .. image:: ../_images/8.0/auto_suggest_3_print_hello_suggest.png
823 898
824 899 4. Press ``ctrl-f``, or ``ctrl-e``, or ``right-arrow`` to accept the suggestion
825 900
826 901 .. image:: ../_images/8.0/auto_suggest_4_print_hello.png
827 902
828 903 You can also complete word by word:
829 904
830 905 1. Run ``def say_hello(): print("hello")``
831 906
832 907 .. image:: ../_images/8.0/auto_suggest_second_prompt.png
833 908
834 909 2. Start typing the first letter if ``def`` to see the autosuggestion
835 910
836 911 .. image:: ../_images/8.0/auto_suggest_d_phantom.png
837 912
838 913 3. Press ``alt-f`` (or ``escape`` followed by ``f``), to accept the first word of the suggestion
839 914
840 915 .. image:: ../_images/8.0/auto_suggest_def_phantom.png
841 916
842 917 Importantly, this feature does not interfere with tab completion:
843 918
844 919 1. After running ``def say_hello(): print("hello")``, press d
845 920
846 921 .. image:: ../_images/8.0/auto_suggest_d_phantom.png
847 922
848 923 2. Press Tab to start tab completion
849 924
850 925 .. image:: ../_images/8.0/auto_suggest_d_completions.png
851 926
852 927 3A. Press Tab again to select the first option
853 928
854 929 .. image:: ../_images/8.0/auto_suggest_def_completions.png
855 930
856 931 3B. Press ``alt f`` (``escape``, ``f``) to accept to accept the first word of the suggestion
857 932
858 933 .. image:: ../_images/8.0/auto_suggest_def_phantom.png
859 934
860 935 3C. Press ``ctrl-f`` or ``ctrl-e`` to accept the entire suggestion
861 936
862 937 .. image:: ../_images/8.0/auto_suggest_match_parens.png
863 938
864 939
865 940 Currently, autosuggestions are only shown in the emacs or vi insert editing modes:
866 941
867 942 - The ctrl e, ctrl f, and alt f shortcuts work by default in emacs mode.
868 943 - To use these shortcuts in vi insert mode, you will have to create `custom keybindings in your config.py <https://github.com/mskar/setup/commit/2892fcee46f9f80ef7788f0749edc99daccc52f4/>`__.
869 944
870 945
871 946 Show pinfo information in ipdb using "?" and "??"
872 947 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
873 948
874 949 In IPDB, it is now possible to show the information about an object using "?"
875 950 and "??", in much the same way that it can be done when using the IPython prompt::
876 951
877 952 ipdb> partial?
878 953 Init signature: partial(self, /, *args, **kwargs)
879 954 Docstring:
880 955 partial(func, *args, **keywords) - new function with partial application
881 956 of the given arguments and keywords.
882 957 File: ~/.pyenv/versions/3.8.6/lib/python3.8/functools.py
883 958 Type: type
884 959 Subclasses:
885 960
886 961 Previously, ``pinfo`` or ``pinfo2`` command had to be used for this purpose.
887 962
888 963
889 964 Autoreload 3 feature
890 965 ~~~~~~~~~~~~~~~~~~~~
891 966
892 967 Example: When an IPython session is run with the 'autoreload' extension loaded,
893 968 you will now have the option '3' to select, which means the following:
894 969
895 970 1. replicate all functionality from option 2
896 971 2. autoload all new funcs/classes/enums/globals from the module when they are added
897 972 3. autoload all newly imported funcs/classes/enums/globals from external modules
898 973
899 974 Try ``%autoreload 3`` in an IPython session after running ``%load_ext autoreload``.
900 975
901 976 For more information please see the following unit test : ``extensions/tests/test_autoreload.py:test_autoload_newly_added_objects``
902 977
903 978 Auto formatting with black in the CLI
904 979 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
905 980
906 981 This feature was present in 7.x, but disabled by default.
907 982
908 983 In 8.0, input was automatically reformatted with Black when black was installed.
909 984 This feature has been reverted for the time being.
910 985 You can re-enable it by setting ``TerminalInteractiveShell.autoformatter`` to ``"black"``
911 986
912 987 History Range Glob feature
913 988 ~~~~~~~~~~~~~~~~~~~~~~~~~~
914 989
915 990 Previously, when using ``%history``, users could specify either
916 991 a range of sessions and lines, for example:
917 992
918 993 .. code-block:: python
919 994
920 995 ~8/1-~6/5 # see history from the first line of 8 sessions ago,
921 996 # to the fifth line of 6 sessions ago.``
922 997
923 998 Or users could specify a glob pattern:
924 999
925 1000 .. code-block:: python
926 1001
927 1002 -g <pattern> # glob ALL history for the specified pattern.
928 1003
929 1004 However users could *not* specify both.
930 1005
931 1006 If a user *did* specify both a range and a glob pattern,
932 1007 then the glob pattern would be used (globbing *all* history) *and the range would be ignored*.
933 1008
934 1009 With this enhancement, if a user specifies both a range and a glob pattern, then the glob pattern will be applied to the specified range of history.
935 1010
936 1011 Don't start a multi-line cell with sunken parenthesis
937 1012 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
938 1013
939 1014 From now on, IPython will not ask for the next line of input when given a single
940 1015 line with more closing than opening brackets. For example, this means that if
941 1016 you (mis)type ``]]`` instead of ``[]``, a ``SyntaxError`` will show up, instead of
942 1017 the ``...:`` prompt continuation.
943 1018
944 1019 IPython shell for ipdb interact
945 1020 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
946 1021
947 1022 The ipdb ``interact`` starts an IPython shell instead of Python's built-in ``code.interact()``.
948 1023
949 1024 Automatic Vi prompt stripping
950 1025 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
951 1026
952 1027 When pasting code into IPython, it will strip the leading prompt characters if
953 1028 there are any. For example, you can paste the following code into the console -
954 1029 it will still work, even though each line is prefixed with prompts (``In``,
955 1030 ``Out``)::
956 1031
957 1032 In [1]: 2 * 2 == 4
958 1033 Out[1]: True
959 1034
960 1035 In [2]: print("This still works as pasted")
961 1036
962 1037
963 1038 Previously, this was not the case for the Vi-mode prompts::
964 1039
965 1040 In [1]: [ins] In [13]: 2 * 2 == 4
966 1041 ...: Out[13]: True
967 1042 ...:
968 1043 File "<ipython-input-1-727bb88eaf33>", line 1
969 1044 [ins] In [13]: 2 * 2 == 4
970 1045 ^
971 1046 SyntaxError: invalid syntax
972 1047
973 1048 This is now fixed, and Vi prompt prefixes - ``[ins]`` and ``[nav]`` - are
974 1049 skipped just as the normal ``In`` would be.
975 1050
976 1051 IPython shell can be started in the Vi mode using ``ipython --TerminalInteractiveShell.editing_mode=vi``,
977 1052 You should be able to change mode dynamically with ``%config TerminalInteractiveShell.editing_mode='vi'``
978 1053
979 1054 Empty History Ranges
980 1055 ~~~~~~~~~~~~~~~~~~~~
981 1056
982 1057 A number of magics that take history ranges can now be used with an empty
983 1058 range. These magics are:
984 1059
985 1060 * ``%save``
986 1061 * ``%load``
987 1062 * ``%pastebin``
988 1063 * ``%pycat``
989 1064
990 1065 Using them this way will make them take the history of the current session up
991 1066 to the point of the magic call (such that the magic itself will not be
992 1067 included).
993 1068
994 1069 Therefore it is now possible to save the whole history to a file using
995 1070 ``%save <filename>``, load and edit it using ``%load`` (makes for a nice usage
996 1071 when followed with :kbd:`F2`), send it to `dpaste.org <http://dpast.org>`_ using
997 1072 ``%pastebin``, or view the whole thing syntax-highlighted with a single
998 1073 ``%pycat``.
999 1074
1000 1075
1001 1076 Windows timing implementation: Switch to process_time
1002 1077 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1003 1078 Timing on Windows, for example with ``%%time``, was changed from being based on ``time.perf_counter``
1004 1079 (which counted time even when the process was sleeping) to being based on ``time.process_time`` instead
1005 1080 (which only counts CPU time). This brings it closer to the behavior on Linux. See :ghpull:`12984`.
1006 1081
1007 1082 Miscellaneous
1008 1083 ~~~~~~~~~~~~~
1009 1084 - Non-text formatters are not disabled in the terminal, which should simplify
1010 1085 writing extensions displaying images or other mimetypes in supporting terminals.
1011 1086 :ghpull:`12315`
1012 1087 - It is now possible to automatically insert matching brackets in Terminal IPython using the
1013 1088 ``TerminalInteractiveShell.auto_match=True`` option. :ghpull:`12586`
1014 1089 - We are thinking of deprecating the current ``%%javascript`` magic in favor of a better replacement. See :ghpull:`13376`.
1015 1090 - ``~`` is now expanded when part of a path in most magics :ghpull:`13385`
1016 1091 - ``%/%%timeit`` magic now adds a comma every thousands to make reading a long number easier :ghpull:`13379`
1017 1092 - ``"info"`` messages can now be customised to hide some fields :ghpull:`13343`
1018 1093 - ``collections.UserList`` now pretty-prints :ghpull:`13320`
1019 1094 - The debugger now has a persistent history, which should make it less
1020 1095 annoying to retype commands :ghpull:`13246`
1021 1096 - ``!pip`` ``!conda`` ``!cd`` or ``!ls`` are likely doing the wrong thing. We
1022 1097 now warn users if they use one of those commands. :ghpull:`12954`
1023 1098 - Make ``%precision`` work for ``numpy.float64`` type :ghpull:`12902`
1024 1099
1025 1100 Re-added support for XDG config directories
1026 1101 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1027 1102
1028 1103 XDG support through the years comes and goes. There is a tension between having
1029 1104 an identical location for configuration in all platforms versus having simple instructions.
1030 1105 After initial failures a couple of years ago, IPython was modified to automatically migrate XDG
1031 1106 config files back into ``~/.ipython``. That migration code has now been removed.
1032 1107 IPython now checks the XDG locations, so if you _manually_ move your config
1033 1108 files to your preferred location, IPython will not move them back.
1034 1109
1035 1110
1036 1111 Preparing for Python 3.10
1037 1112 -------------------------
1038 1113
1039 1114 To prepare for Python 3.10, we have started working on removing reliance and
1040 1115 any dependency that is not compatible with Python 3.10. This includes migrating our
1041 1116 test suite to pytest and starting to remove nose. This also means that the
1042 1117 ``iptest`` command is now gone and all testing is via pytest.
1043 1118
1044 1119 This was in large part thanks to the NumFOCUS Small Developer grant, which enabled us to
1045 1120 allocate \$4000 to hire `Nikita Kniazev (@Kojoley) <https://github.com/Kojoley>`_,
1046 1121 who did a fantastic job at updating our code base, migrating to pytest, pushing
1047 1122 our coverage, and fixing a large number of bugs. I highly recommend contacting
1048 1123 them if you need help with C++ and Python projects.
1049 1124
1050 1125 You can find all relevant issues and PRs with `the SDG 2021 tag <https://github.com/ipython/ipython/issues?q=label%3A%22Numfocus+SDG+2021%22+>`__
1051 1126
1052 1127 Removing support for older Python versions
1053 1128 ------------------------------------------
1054 1129
1055 1130
1056 1131 We are removing support for Python up through 3.7, allowing internal code to use the more
1057 1132 efficient ``pathlib`` and to make better use of type annotations.
1058 1133
1059 1134 .. image:: ../_images/8.0/pathlib_pathlib_everywhere.jpg
1060 1135 :alt: "Meme image of Toy Story with Woody and Buzz, with the text 'pathlib, pathlib everywhere'"
1061 1136
1062 1137
1063 1138 We had about 34 PRs only to update some logic to update some functions from managing strings to
1064 1139 using Pathlib.
1065 1140
1066 1141 The completer has also seen significant updates and now makes use of newer Jedi APIs,
1067 1142 offering faster and more reliable tab completion.
1068 1143
1069 1144 Misc Statistics
1070 1145 ---------------
1071 1146
1072 1147 Here are some numbers::
1073 1148
1074 1149 7.x: 296 files, 12561 blank lines, 20282 comments, 35142 line of code.
1075 1150 8.0: 252 files, 12053 blank lines, 19232 comments, 34505 line of code.
1076 1151
1077 1152 $ git diff --stat 7.x...master | tail -1
1078 1153 340 files changed, 13399 insertions(+), 12421 deletions(-)
1079 1154
1080 1155 We have commits from 162 authors, who contributed 1916 commits in 23 month, excluding merges (to not bias toward
1081 1156 maintainers pushing buttons).::
1082 1157
1083 1158 $ git shortlog -s --no-merges 7.x...master | sort -nr
1084 1159 535 Matthias Bussonnier
1085 1160 86 Nikita Kniazev
1086 1161 69 Blazej Michalik
1087 1162 49 Samuel Gaist
1088 1163 27 Itamar Turner-Trauring
1089 1164 18 Spas Kalaydzhisyki
1090 1165 17 Thomas Kluyver
1091 1166 17 Quentin Peter
1092 1167 17 James Morris
1093 1168 17 Artur Svistunov
1094 1169 15 Bart Skowron
1095 1170 14 Alex Hall
1096 1171 13 rushabh-v
1097 1172 13 Terry Davis
1098 1173 13 Benjamin Ragan-Kelley
1099 1174 8 martinRenou
1100 1175 8 farisachugthai
1101 1176 7 dswij
1102 1177 7 Gal B
1103 1178 7 Corentin Cadiou
1104 1179 6 yuji96
1105 1180 6 Martin Skarzynski
1106 1181 6 Justin Palmer
1107 1182 6 Daniel Goldfarb
1108 1183 6 Ben Greiner
1109 1184 5 Sammy Al Hashemi
1110 1185 5 Paul Ivanov
1111 1186 5 Inception95
1112 1187 5 Eyenpi
1113 1188 5 Douglas Blank
1114 1189 5 Coco Mishra
1115 1190 5 Bibo Hao
1116 1191 5 AndrΓ© A. Gomes
1117 1192 5 Ahmed Fasih
1118 1193 4 takuya fujiwara
1119 1194 4 palewire
1120 1195 4 Thomas A Caswell
1121 1196 4 Talley Lambert
1122 1197 4 Scott Sanderson
1123 1198 4 Ram Rachum
1124 1199 4 Nick Muoh
1125 1200 4 Nathan Goldbaum
1126 1201 4 Mithil Poojary
1127 1202 4 Michael T
1128 1203 4 Jakub Klus
1129 1204 4 Ian Castleden
1130 1205 4 Eli Rykoff
1131 1206 4 Ashwin Vishnu
1132 1207 3 谭九鼎
1133 1208 3 sleeping
1134 1209 3 Sylvain Corlay
1135 1210 3 Peter Corke
1136 1211 3 Paul Bissex
1137 1212 3 Matthew Feickert
1138 1213 3 Fernando Perez
1139 1214 3 Eric Wieser
1140 1215 3 Daniel Mietchen
1141 1216 3 Aditya Sathe
1142 1217 3 007vedant
1143 1218 2 rchiodo
1144 1219 2 nicolaslazo
1145 1220 2 luttik
1146 1221 2 gorogoroumaru
1147 1222 2 foobarbyte
1148 1223 2 bar-hen
1149 1224 2 Theo Ouzhinski
1150 1225 2 Strawkage
1151 1226 2 Samreen Zarroug
1152 1227 2 Pete Blois
1153 1228 2 Meysam Azad
1154 1229 2 Matthieu Ancellin
1155 1230 2 Mark Schmitz
1156 1231 2 Maor Kleinberger
1157 1232 2 MRCWirtz
1158 1233 2 Lumir Balhar
1159 1234 2 Julien Rabinow
1160 1235 2 Juan Luis Cano RodrΓ­guez
1161 1236 2 Joyce Er
1162 1237 2 Jakub
1163 1238 2 Faris A Chugthai
1164 1239 2 Ethan Madden
1165 1240 2 Dimitri Papadopoulos
1166 1241 2 Diego Fernandez
1167 1242 2 Daniel Shimon
1168 1243 2 Coco Bennett
1169 1244 2 Carlos Cordoba
1170 1245 2 Boyuan Liu
1171 1246 2 BaoGiang HoangVu
1172 1247 2 Augusto
1173 1248 2 Arthur Svistunov
1174 1249 2 Arthur Moreira
1175 1250 2 Ali Nabipour
1176 1251 2 Adam Hackbarth
1177 1252 1 richard
1178 1253 1 linar-jether
1179 1254 1 lbennett
1180 1255 1 juacrumar
1181 1256 1 gpotter2
1182 1257 1 digitalvirtuoso
1183 1258 1 dalthviz
1184 1259 1 Yonatan Goldschmidt
1185 1260 1 Tomasz KΕ‚oczko
1186 1261 1 Tobias Bengfort
1187 1262 1 Timur Kushukov
1188 1263 1 Thomas
1189 1264 1 Snir Broshi
1190 1265 1 Shao Yang Hong
1191 1266 1 Sanjana-03
1192 1267 1 Romulo Filho
1193 1268 1 Rodolfo Carvalho
1194 1269 1 Richard Shadrach
1195 1270 1 Reilly Tucker Siemens
1196 1271 1 Rakessh Roshan
1197 1272 1 Piers Titus van der Torren
1198 1273 1 PhanatosZou
1199 1274 1 Pavel Safronov
1200 1275 1 Paulo S. Costa
1201 1276 1 Paul McCarthy
1202 1277 1 NotWearingPants
1203 1278 1 Naelson Douglas
1204 1279 1 Michael Tiemann
1205 1280 1 Matt Wozniski
1206 1281 1 Markus Wageringel
1207 1282 1 Marcus Wirtz
1208 1283 1 Marcio Mazza
1209 1284 1 LumΓ­r 'Frenzy' Balhar
1210 1285 1 Lightyagami1
1211 1286 1 Leon Anavi
1212 1287 1 LeafyLi
1213 1288 1 L0uisJ0shua
1214 1289 1 Kyle Cutler
1215 1290 1 Krzysztof Cybulski
1216 1291 1 Kevin Kirsche
1217 1292 1 KIU Shueng Chuan
1218 1293 1 Jonathan Slenders
1219 1294 1 Jay Qi
1220 1295 1 Jake VanderPlas
1221 1296 1 Iwan Briquemont
1222 1297 1 Hussaina Begum Nandyala
1223 1298 1 Gordon Ball
1224 1299 1 Gabriel Simonetto
1225 1300 1 Frank Tobia
1226 1301 1 Erik
1227 1302 1 Elliott Sales de Andrade
1228 1303 1 Daniel Hahler
1229 1304 1 Dan Green-Leipciger
1230 1305 1 Dan Green
1231 1306 1 Damian Yurzola
1232 1307 1 Coon, Ethan T
1233 1308 1 Carol Willing
1234 1309 1 Brian Lee
1235 1310 1 Brendan Gerrity
1236 1311 1 Blake Griffin
1237 1312 1 Bastian Ebeling
1238 1313 1 Bartosz Telenczuk
1239 1314 1 Ankitsingh6299
1240 1315 1 Andrew Port
1241 1316 1 Andrew J. Hesford
1242 1317 1 Albert Zhang
1243 1318 1 Adam Johnson
1244 1319
1245 1320 This does not, of course, represent non-code contributions, for which we are also grateful.
1246 1321
1247 1322
1248 1323 API Changes using Frappuccino
1249 1324 -----------------------------
1250 1325
1251 1326 This is an experimental exhaustive API difference using `Frappuccino <https://pypi.org/project/frappuccino/>`_
1252 1327
1253 1328
1254 1329 The following items are new in IPython 8.0 ::
1255 1330
1256 1331 + IPython.core.async_helpers.get_asyncio_loop()
1257 1332 + IPython.core.completer.Dict
1258 1333 + IPython.core.completer.Pattern
1259 1334 + IPython.core.completer.Sequence
1260 1335 + IPython.core.completer.__skip_doctest__
1261 1336 + IPython.core.debugger.Pdb.precmd(self, line)
1262 1337 + IPython.core.debugger.__skip_doctest__
1263 1338 + IPython.core.display.__getattr__(name)
1264 1339 + IPython.core.display.warn
1265 1340 + IPython.core.display_functions
1266 1341 + IPython.core.display_functions.DisplayHandle
1267 1342 + IPython.core.display_functions.DisplayHandle.display(self, obj, **kwargs)
1268 1343 + IPython.core.display_functions.DisplayHandle.update(self, obj, **kwargs)
1269 1344 + IPython.core.display_functions.__all__
1270 1345 + IPython.core.display_functions.__builtins__
1271 1346 + IPython.core.display_functions.__cached__
1272 1347 + IPython.core.display_functions.__doc__
1273 1348 + IPython.core.display_functions.__file__
1274 1349 + IPython.core.display_functions.__loader__
1275 1350 + IPython.core.display_functions.__name__
1276 1351 + IPython.core.display_functions.__package__
1277 1352 + IPython.core.display_functions.__spec__
1278 1353 + IPython.core.display_functions.b2a_hex
1279 1354 + IPython.core.display_functions.clear_output(wait=False)
1280 1355 + IPython.core.display_functions.display(*objs, include='None', exclude='None', metadata='None', transient='None', display_id='None', raw=False, clear=False, **kwargs)
1281 1356 + IPython.core.display_functions.publish_display_data(data, metadata='None', source='<deprecated>', *, transient='None', **kwargs)
1282 1357 + IPython.core.display_functions.update_display(obj, *, display_id, **kwargs)
1283 1358 + IPython.core.extensions.BUILTINS_EXTS
1284 1359 + IPython.core.inputtransformer2.has_sunken_brackets(tokens)
1285 1360 + IPython.core.interactiveshell.Callable
1286 1361 + IPython.core.interactiveshell.__annotations__
1287 1362 + IPython.core.ultratb.List
1288 1363 + IPython.core.ultratb.Tuple
1289 1364 + IPython.lib.pretty.CallExpression
1290 1365 + IPython.lib.pretty.CallExpression.factory(name)
1291 1366 + IPython.lib.pretty.RawStringLiteral
1292 1367 + IPython.lib.pretty.RawText
1293 1368 + IPython.terminal.debugger.TerminalPdb.do_interact(self, arg)
1294 1369 + IPython.terminal.embed.Set
1295 1370
1296 1371 The following items have been removed (or moved to superclass)::
1297 1372
1298 1373 - IPython.core.application.BaseIPythonApplication.initialize_subcommand
1299 1374 - IPython.core.completer.Sentinel
1300 1375 - IPython.core.completer.skip_doctest
1301 1376 - IPython.core.debugger.Tracer
1302 1377 - IPython.core.display.DisplayHandle
1303 1378 - IPython.core.display.DisplayHandle.display
1304 1379 - IPython.core.display.DisplayHandle.update
1305 1380 - IPython.core.display.b2a_hex
1306 1381 - IPython.core.display.clear_output
1307 1382 - IPython.core.display.display
1308 1383 - IPython.core.display.publish_display_data
1309 1384 - IPython.core.display.update_display
1310 1385 - IPython.core.excolors.Deprec
1311 1386 - IPython.core.excolors.ExceptionColors
1312 1387 - IPython.core.history.warn
1313 1388 - IPython.core.hooks.late_startup_hook
1314 1389 - IPython.core.hooks.pre_run_code_hook
1315 1390 - IPython.core.hooks.shutdown_hook
1316 1391 - IPython.core.interactiveshell.InteractiveShell.init_deprecation_warnings
1317 1392 - IPython.core.interactiveshell.InteractiveShell.init_readline
1318 1393 - IPython.core.interactiveshell.InteractiveShell.write
1319 1394 - IPython.core.interactiveshell.InteractiveShell.write_err
1320 1395 - IPython.core.interactiveshell.get_default_colors
1321 1396 - IPython.core.interactiveshell.removed_co_newlocals
1322 1397 - IPython.core.magics.execution.ExecutionMagics.profile_missing_notice
1323 1398 - IPython.core.magics.script.PIPE
1324 1399 - IPython.core.prefilter.PrefilterManager.init_transformers
1325 1400 - IPython.core.release.classifiers
1326 1401 - IPython.core.release.description
1327 1402 - IPython.core.release.keywords
1328 1403 - IPython.core.release.long_description
1329 1404 - IPython.core.release.name
1330 1405 - IPython.core.release.platforms
1331 1406 - IPython.core.release.url
1332 1407 - IPython.core.ultratb.VerboseTB.format_records
1333 1408 - IPython.core.ultratb.find_recursion
1334 1409 - IPython.core.ultratb.findsource
1335 1410 - IPython.core.ultratb.fix_frame_records_filenames
1336 1411 - IPython.core.ultratb.inspect_error
1337 1412 - IPython.core.ultratb.is_recursion_error
1338 1413 - IPython.core.ultratb.with_patch_inspect
1339 1414 - IPython.external.__all__
1340 1415 - IPython.external.__builtins__
1341 1416 - IPython.external.__cached__
1342 1417 - IPython.external.__doc__
1343 1418 - IPython.external.__file__
1344 1419 - IPython.external.__loader__
1345 1420 - IPython.external.__name__
1346 1421 - IPython.external.__package__
1347 1422 - IPython.external.__path__
1348 1423 - IPython.external.__spec__
1349 1424 - IPython.kernel.KernelConnectionInfo
1350 1425 - IPython.kernel.__builtins__
1351 1426 - IPython.kernel.__cached__
1352 1427 - IPython.kernel.__warningregistry__
1353 1428 - IPython.kernel.pkg
1354 1429 - IPython.kernel.protocol_version
1355 1430 - IPython.kernel.protocol_version_info
1356 1431 - IPython.kernel.src
1357 1432 - IPython.kernel.version_info
1358 1433 - IPython.kernel.warn
1359 1434 - IPython.lib.backgroundjobs
1360 1435 - IPython.lib.backgroundjobs.BackgroundJobBase
1361 1436 - IPython.lib.backgroundjobs.BackgroundJobBase.run
1362 1437 - IPython.lib.backgroundjobs.BackgroundJobBase.traceback
1363 1438 - IPython.lib.backgroundjobs.BackgroundJobExpr
1364 1439 - IPython.lib.backgroundjobs.BackgroundJobExpr.call
1365 1440 - IPython.lib.backgroundjobs.BackgroundJobFunc
1366 1441 - IPython.lib.backgroundjobs.BackgroundJobFunc.call
1367 1442 - IPython.lib.backgroundjobs.BackgroundJobManager
1368 1443 - IPython.lib.backgroundjobs.BackgroundJobManager.flush
1369 1444 - IPython.lib.backgroundjobs.BackgroundJobManager.new
1370 1445 - IPython.lib.backgroundjobs.BackgroundJobManager.remove
1371 1446 - IPython.lib.backgroundjobs.BackgroundJobManager.result
1372 1447 - IPython.lib.backgroundjobs.BackgroundJobManager.status
1373 1448 - IPython.lib.backgroundjobs.BackgroundJobManager.traceback
1374 1449 - IPython.lib.backgroundjobs.__builtins__
1375 1450 - IPython.lib.backgroundjobs.__cached__
1376 1451 - IPython.lib.backgroundjobs.__doc__
1377 1452 - IPython.lib.backgroundjobs.__file__
1378 1453 - IPython.lib.backgroundjobs.__loader__
1379 1454 - IPython.lib.backgroundjobs.__name__
1380 1455 - IPython.lib.backgroundjobs.__package__
1381 1456 - IPython.lib.backgroundjobs.__spec__
1382 1457 - IPython.lib.kernel.__builtins__
1383 1458 - IPython.lib.kernel.__cached__
1384 1459 - IPython.lib.kernel.__doc__
1385 1460 - IPython.lib.kernel.__file__
1386 1461 - IPython.lib.kernel.__loader__
1387 1462 - IPython.lib.kernel.__name__
1388 1463 - IPython.lib.kernel.__package__
1389 1464 - IPython.lib.kernel.__spec__
1390 1465 - IPython.lib.kernel.__warningregistry__
1391 1466 - IPython.paths.fs_encoding
1392 1467 - IPython.terminal.debugger.DEFAULT_BUFFER
1393 1468 - IPython.terminal.debugger.cursor_in_leading_ws
1394 1469 - IPython.terminal.debugger.emacs_insert_mode
1395 1470 - IPython.terminal.debugger.has_selection
1396 1471 - IPython.terminal.debugger.vi_insert_mode
1397 1472 - IPython.terminal.interactiveshell.DISPLAY_BANNER_DEPRECATED
1398 1473 - IPython.terminal.ipapp.TerminalIPythonApp.parse_command_line
1399 1474 - IPython.testing.test
1400 1475 - IPython.utils.contexts.NoOpContext
1401 1476 - IPython.utils.io.IOStream
1402 1477 - IPython.utils.io.IOStream.close
1403 1478 - IPython.utils.io.IOStream.write
1404 1479 - IPython.utils.io.IOStream.writelines
1405 1480 - IPython.utils.io.__warningregistry__
1406 1481 - IPython.utils.io.atomic_writing
1407 1482 - IPython.utils.io.stderr
1408 1483 - IPython.utils.io.stdin
1409 1484 - IPython.utils.io.stdout
1410 1485 - IPython.utils.io.unicode_std_stream
1411 1486 - IPython.utils.path.get_ipython_cache_dir
1412 1487 - IPython.utils.path.get_ipython_dir
1413 1488 - IPython.utils.path.get_ipython_module_path
1414 1489 - IPython.utils.path.get_ipython_package_dir
1415 1490 - IPython.utils.path.locate_profile
1416 1491 - IPython.utils.path.unquote_filename
1417 1492 - IPython.utils.py3compat.PY2
1418 1493 - IPython.utils.py3compat.PY3
1419 1494 - IPython.utils.py3compat.buffer_to_bytes
1420 1495 - IPython.utils.py3compat.builtin_mod_name
1421 1496 - IPython.utils.py3compat.cast_bytes
1422 1497 - IPython.utils.py3compat.getcwd
1423 1498 - IPython.utils.py3compat.isidentifier
1424 1499 - IPython.utils.py3compat.u_format
1425 1500
1426 1501 The following signatures differ between 7.x and 8.0::
1427 1502
1428 1503 - IPython.core.completer.IPCompleter.unicode_name_matches(self, text)
1429 1504 + IPython.core.completer.IPCompleter.unicode_name_matches(text)
1430 1505
1431 1506 - IPython.core.completer.match_dict_keys(keys, prefix, delims)
1432 1507 + IPython.core.completer.match_dict_keys(keys, prefix, delims, extra_prefix='None')
1433 1508
1434 1509 - IPython.core.interactiveshell.InteractiveShell.object_inspect_mime(self, oname, detail_level=0)
1435 1510 + IPython.core.interactiveshell.InteractiveShell.object_inspect_mime(self, oname, detail_level=0, omit_sections='()')
1436 1511
1437 1512 - IPython.core.interactiveshell.InteractiveShell.set_hook(self, name, hook, priority=50, str_key='None', re_key='None', _warn_deprecated=True)
1438 1513 + IPython.core.interactiveshell.InteractiveShell.set_hook(self, name, hook, priority=50, str_key='None', re_key='None')
1439 1514
1440 1515 - IPython.core.oinspect.Inspector.info(self, obj, oname='', formatter='None', info='None', detail_level=0)
1441 1516 + IPython.core.oinspect.Inspector.info(self, obj, oname='', info='None', detail_level=0)
1442 1517
1443 1518 - IPython.core.oinspect.Inspector.pinfo(self, obj, oname='', formatter='None', info='None', detail_level=0, enable_html_pager=True)
1444 1519 + IPython.core.oinspect.Inspector.pinfo(self, obj, oname='', formatter='None', info='None', detail_level=0, enable_html_pager=True, omit_sections='()')
1445 1520
1446 1521 - IPython.core.profiledir.ProfileDir.copy_config_file(self, config_file, path='None', overwrite=False)
1447 1522 + IPython.core.profiledir.ProfileDir.copy_config_file(self, config_file, path, overwrite=False)
1448 1523
1449 1524 - IPython.core.ultratb.VerboseTB.format_record(self, frame, file, lnum, func, lines, index)
1450 1525 + IPython.core.ultratb.VerboseTB.format_record(self, frame_info)
1451 1526
1452 1527 - IPython.terminal.embed.InteractiveShellEmbed.mainloop(self, local_ns='None', module='None', stack_depth=0, display_banner='None', global_ns='None', compile_flags='None')
1453 1528 + IPython.terminal.embed.InteractiveShellEmbed.mainloop(self, local_ns='None', module='None', stack_depth=0, compile_flags='None')
1454 1529
1455 1530 - IPython.terminal.embed.embed(**kwargs)
1456 1531 + IPython.terminal.embed.embed(*, header='', compile_flags='None', **kwargs)
1457 1532
1458 1533 - IPython.terminal.interactiveshell.TerminalInteractiveShell.interact(self, display_banner='<object object at 0xffffff>')
1459 1534 + IPython.terminal.interactiveshell.TerminalInteractiveShell.interact(self)
1460 1535
1461 1536 - IPython.terminal.interactiveshell.TerminalInteractiveShell.mainloop(self, display_banner='<object object at 0xffffff>')
1462 1537 + IPython.terminal.interactiveshell.TerminalInteractiveShell.mainloop(self)
1463 1538
1464 1539 - IPython.utils.path.get_py_filename(name, force_win32='None')
1465 1540 + IPython.utils.path.get_py_filename(name)
1466 1541
1467 1542 The following are new attributes (that might be inherited)::
1468 1543
1469 1544 + IPython.core.completer.IPCompleter.unicode_names
1470 1545 + IPython.core.debugger.InterruptiblePdb.precmd
1471 1546 + IPython.core.debugger.Pdb.precmd
1472 1547 + IPython.core.ultratb.AutoFormattedTB.has_colors
1473 1548 + IPython.core.ultratb.ColorTB.has_colors
1474 1549 + IPython.core.ultratb.FormattedTB.has_colors
1475 1550 + IPython.core.ultratb.ListTB.has_colors
1476 1551 + IPython.core.ultratb.SyntaxTB.has_colors
1477 1552 + IPython.core.ultratb.TBTools.has_colors
1478 1553 + IPython.core.ultratb.VerboseTB.has_colors
1479 1554 + IPython.terminal.debugger.TerminalPdb.do_interact
1480 1555 + IPython.terminal.debugger.TerminalPdb.precmd
1481 1556
1482 1557 The following attribute/methods have been removed::
1483 1558
1484 1559 - IPython.core.application.BaseIPythonApplication.deprecated_subcommands
1485 1560 - IPython.core.ultratb.AutoFormattedTB.format_records
1486 1561 - IPython.core.ultratb.ColorTB.format_records
1487 1562 - IPython.core.ultratb.FormattedTB.format_records
1488 1563 - IPython.terminal.embed.InteractiveShellEmbed.init_deprecation_warnings
1489 1564 - IPython.terminal.embed.InteractiveShellEmbed.init_readline
1490 1565 - IPython.terminal.embed.InteractiveShellEmbed.write
1491 1566 - IPython.terminal.embed.InteractiveShellEmbed.write_err
1492 1567 - IPython.terminal.interactiveshell.TerminalInteractiveShell.init_deprecation_warnings
1493 1568 - IPython.terminal.interactiveshell.TerminalInteractiveShell.init_readline
1494 1569 - IPython.terminal.interactiveshell.TerminalInteractiveShell.write
1495 1570 - IPython.terminal.interactiveshell.TerminalInteractiveShell.write_err
1496 1571 - IPython.terminal.ipapp.LocateIPythonApp.deprecated_subcommands
1497 1572 - IPython.terminal.ipapp.LocateIPythonApp.initialize_subcommand
1498 1573 - IPython.terminal.ipapp.TerminalIPythonApp.deprecated_subcommands
1499 1574 - IPython.terminal.ipapp.TerminalIPythonApp.initialize_subcommand
@@ -1,115 +1,116
1 1 [metadata]
2 2 name = ipython
3 3 version = attr: IPython.core.release.__version__
4 4 url = https://ipython.org
5 5 description = IPython: Productive Interactive Computing
6 6 long_description_content_type = text/x-rst
7 7 long_description = file: long_description.rst
8 8 license_file = LICENSE
9 9 project_urls =
10 10 Documentation = https://ipython.readthedocs.io/
11 11 Funding = https://numfocus.org/
12 12 Source = https://github.com/ipython/ipython
13 13 Tracker = https://github.com/ipython/ipython/issues
14 14 keywords = Interactive, Interpreter, Shell, Embedding
15 15 platforms = Linux, Mac OSX, Windows
16 16 classifiers =
17 17 Framework :: IPython
18 18 Framework :: Jupyter
19 19 Intended Audience :: Developers
20 20 Intended Audience :: Science/Research
21 21 License :: OSI Approved :: BSD License
22 22 Programming Language :: Python
23 23 Programming Language :: Python :: 3
24 24 Programming Language :: Python :: 3 :: Only
25 25 Topic :: System :: Shells
26 26
27 27 [options]
28 28 packages = find:
29 29 python_requires = >=3.8
30 30 zip_safe = False
31 31 install_requires =
32 32 appnope; sys_platform == "darwin"
33 33 backcall
34 34 colorama; sys_platform == "win32"
35 35 decorator
36 36 jedi>=0.16
37 37 matplotlib-inline
38 38 pexpect>4.3; sys_platform != "win32"
39 39 pickleshare
40 40 prompt_toolkit>=3.0.30,<3.1.0,!=3.0.37
41 41 pygments>=2.4.0
42 42 stack_data
43 43 traitlets>=5
44 typing_extensions ; python_version<'3.10'
44 45
45 46 [options.extras_require]
46 47 black =
47 48 black
48 49 doc =
49 50 ipykernel
50 51 setuptools>=18.5
51 52 sphinx>=1.3
52 53 sphinx-rtd-theme
53 54 docrepr
54 55 matplotlib
55 56 stack_data
56 57 pytest<7
57 58 typing_extensions
58 59 %(test)s
59 60 kernel =
60 61 ipykernel
61 62 nbconvert =
62 63 nbconvert
63 64 nbformat =
64 65 nbformat
65 66 notebook =
66 67 ipywidgets
67 68 notebook
68 69 parallel =
69 70 ipyparallel
70 71 qtconsole =
71 72 qtconsole
72 73 terminal =
73 74 test =
74 75 pytest<7.1
75 76 pytest-asyncio
76 77 testpath
77 78 test_extra =
78 79 %(test)s
79 80 curio
80 81 matplotlib!=3.2.0
81 82 nbformat
82 83 numpy>=1.21
83 84 pandas
84 85 trio
85 86 all =
86 87 %(black)s
87 88 %(doc)s
88 89 %(kernel)s
89 90 %(nbconvert)s
90 91 %(nbformat)s
91 92 %(notebook)s
92 93 %(parallel)s
93 94 %(qtconsole)s
94 95 %(terminal)s
95 96 %(test_extra)s
96 97 %(test)s
97 98
98 99 [options.packages.find]
99 100 exclude =
100 101 setupext
101 102
102 103 [options.package_data]
103 104 IPython = py.typed
104 105 IPython.core = profile/README*
105 106 IPython.core.tests = *.png, *.jpg, daft_extension/*.py
106 107 IPython.lib.tests = *.wav
107 108 IPython.testing.plugin = *.txt
108 109
109 110 [velin]
110 111 ignore_patterns =
111 112 IPython/core/tests
112 113 IPython/testing
113 114
114 115 [tool.black]
115 116 exclude = 'timing\.py'
General Comments 0
You need to be logged in to leave comments. Login now