Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Implementation of namespace-related magic functions.
2"""
3#-----------------------------------------------------------------------------
4# Copyright (c) 2012 The IPython Development Team.
5#
6# Distributed under the terms of the Modified BSD License.
7#
8# The full license is in the file COPYING.txt, distributed with this software.
9#-----------------------------------------------------------------------------
11#-----------------------------------------------------------------------------
12# Imports
13#-----------------------------------------------------------------------------
15# Stdlib
16import gc
17import re
18import sys
20# Our own packages
21from IPython.core import page
22from IPython.core.error import StdinNotImplementedError, UsageError
23from IPython.core.magic import Magics, magics_class, line_magic
24from IPython.testing.skipdoctest import skip_doctest
25from IPython.utils.encoding import DEFAULT_ENCODING
26from IPython.utils.openpy import read_py_file
27from IPython.utils.path import get_py_filename
29#-----------------------------------------------------------------------------
30# Magic implementation classes
31#-----------------------------------------------------------------------------
33@magics_class
34class NamespaceMagics(Magics):
35 """Magics to manage various aspects of the user's namespace.
37 These include listing variables, introspecting into them, etc.
38 """
40 @line_magic
41 def pinfo(self, parameter_s='', namespaces=None):
42 """Provide detailed information about an object.
44 '%pinfo object' is just a synonym for object? or ?object."""
46 # print('pinfo par: <%s>' % parameter_s) # dbg
47 # detail_level: 0 -> obj? , 1 -> obj??
48 detail_level = 0
49 # We need to detect if we got called as 'pinfo pinfo foo', which can
50 # happen if the user types 'pinfo foo?' at the cmd line.
51 pinfo,qmark1,oname,qmark2 = \
52 re.match(r'(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
53 if pinfo or qmark1 or qmark2:
54 detail_level = 1
55 if "*" in oname:
56 self.psearch(oname)
57 else:
58 self.shell._inspect('pinfo', oname, detail_level=detail_level,
59 namespaces=namespaces)
61 @line_magic
62 def pinfo2(self, parameter_s='', namespaces=None):
63 """Provide extra detailed information about an object.
65 '%pinfo2 object' is just a synonym for object?? or ??object."""
66 self.shell._inspect('pinfo', parameter_s, detail_level=1,
67 namespaces=namespaces)
69 @skip_doctest
70 @line_magic
71 def pdef(self, parameter_s='', namespaces=None):
72 """Print the call signature for any callable object.
74 If the object is a class, print the constructor information.
76 Examples
77 --------
78 ::
80 In [3]: %pdef urllib.urlopen
81 urllib.urlopen(url, data=None, proxies=None)
82 """
83 self.shell._inspect('pdef',parameter_s, namespaces)
85 @line_magic
86 def pdoc(self, parameter_s='', namespaces=None):
87 """Print the docstring for an object.
89 If the given object is a class, it will print both the class and the
90 constructor docstrings."""
91 self.shell._inspect('pdoc',parameter_s, namespaces)
93 @line_magic
94 def psource(self, parameter_s='', namespaces=None):
95 """Print (or run through pager) the source code for an object."""
96 if not parameter_s:
97 raise UsageError('Missing object name.')
98 self.shell._inspect('psource',parameter_s, namespaces)
100 @line_magic
101 def pfile(self, parameter_s='', namespaces=None):
102 """Print (or run through pager) the file where an object is defined.
104 The file opens at the line where the object definition begins. IPython
105 will honor the environment variable PAGER if set, and otherwise will
106 do its best to print the file in a convenient form.
108 If the given argument is not an object currently defined, IPython will
109 try to interpret it as a filename (automatically adding a .py extension
110 if needed). You can thus use %pfile as a syntax highlighting code
111 viewer."""
113 # first interpret argument as an object name
114 out = self.shell._inspect('pfile',parameter_s, namespaces)
115 # if not, try the input as a filename
116 if out == 'not found':
117 try:
118 filename = get_py_filename(parameter_s)
119 except IOError as msg:
120 print(msg)
121 return
122 page.page(self.shell.pycolorize(read_py_file(filename, skip_encoding_cookie=False)))
124 @line_magic
125 def psearch(self, parameter_s=''):
126 """Search for object in namespaces by wildcard.
128 %psearch [options] PATTERN [OBJECT TYPE]
130 Note: ? can be used as a synonym for %psearch, at the beginning or at
131 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
132 rest of the command line must be unchanged (options come first), so
133 for example the following forms are equivalent
135 %psearch -i a* function
136 -i a* function?
137 ?-i a* function
139 Arguments:
141 PATTERN
143 where PATTERN is a string containing * as a wildcard similar to its
144 use in a shell. The pattern is matched in all namespaces on the
145 search path. By default objects starting with a single _ are not
146 matched, many IPython generated objects have a single
147 underscore. The default is case insensitive matching. Matching is
148 also done on the attributes of objects and not only on the objects
149 in a module.
151 [OBJECT TYPE]
153 Is the name of a python type from the types module. The name is
154 given in lowercase without the ending type, ex. StringType is
155 written string. By adding a type here only objects matching the
156 given type are matched. Using all here makes the pattern match all
157 types (this is the default).
159 Options:
161 -a: makes the pattern match even objects whose names start with a
162 single underscore. These names are normally omitted from the
163 search.
165 -i/-c: make the pattern case insensitive/sensitive. If neither of
166 these options are given, the default is read from your configuration
167 file, with the option ``InteractiveShell.wildcards_case_sensitive``.
168 If this option is not specified in your configuration file, IPython's
169 internal default is to do a case sensitive search.
171 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
172 specify can be searched in any of the following namespaces:
173 'builtin', 'user', 'user_global','internal', 'alias', where
174 'builtin' and 'user' are the search defaults. Note that you should
175 not use quotes when specifying namespaces.
177 -l: List all available object types for object matching. This function
178 can be used without arguments.
180 'Builtin' contains the python module builtin, 'user' contains all
181 user data, 'alias' only contain the shell aliases and no python
182 objects, 'internal' contains objects used by IPython. The
183 'user_global' namespace is only used by embedded IPython instances,
184 and it contains module-level globals. You can add namespaces to the
185 search with -s or exclude them with -e (these options can be given
186 more than once).
188 Examples
189 --------
190 ::
192 %psearch a* -> objects beginning with an a
193 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
194 %psearch a* function -> all functions beginning with an a
195 %psearch re.e* -> objects beginning with an e in module re
196 %psearch r*.e* -> objects that start with e in modules starting in r
197 %psearch r*.* string -> all strings in modules beginning with r
199 Case sensitive search::
201 %psearch -c a* list all object beginning with lower case a
203 Show objects beginning with a single _::
205 %psearch -a _* list objects beginning with a single underscore
207 List available objects::
209 %psearch -l list all available object types
210 """
211 # default namespaces to be searched
212 def_search = ['user_local', 'user_global', 'builtin']
214 # Process options/args
215 opts,args = self.parse_options(parameter_s,'cias:e:l',list_all=True)
216 opt = opts.get
217 shell = self.shell
218 psearch = shell.inspector.psearch
220 # select list object types
221 list_types = False
222 if 'l' in opts:
223 list_types = True
225 # select case options
226 if 'i' in opts:
227 ignore_case = True
228 elif 'c' in opts:
229 ignore_case = False
230 else:
231 ignore_case = not shell.wildcards_case_sensitive
233 # Build list of namespaces to search from user options
234 def_search.extend(opt('s',[]))
235 ns_exclude = ns_exclude=opt('e',[])
236 ns_search = [nm for nm in def_search if nm not in ns_exclude]
238 # Call the actual search
239 try:
240 psearch(args,shell.ns_table,ns_search,
241 show_all=opt('a'),ignore_case=ignore_case, list_types=list_types)
242 except:
243 shell.showtraceback()
245 @skip_doctest
246 @line_magic
247 def who_ls(self, parameter_s=''):
248 """Return a sorted list of all interactive variables.
250 If arguments are given, only variables of types matching these
251 arguments are returned.
253 Examples
254 --------
255 Define two variables and list them with who_ls::
257 In [1]: alpha = 123
259 In [2]: beta = 'test'
261 In [3]: %who_ls
262 Out[3]: ['alpha', 'beta']
264 In [4]: %who_ls int
265 Out[4]: ['alpha']
267 In [5]: %who_ls str
268 Out[5]: ['beta']
269 """
271 user_ns = self.shell.user_ns
272 user_ns_hidden = self.shell.user_ns_hidden
273 nonmatching = object() # This can never be in user_ns
274 out = [ i for i in user_ns
275 if not i.startswith('_') \
276 and (user_ns[i] is not user_ns_hidden.get(i, nonmatching)) ]
278 typelist = parameter_s.split()
279 if typelist:
280 typeset = set(typelist)
281 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
283 out.sort()
284 return out
286 @skip_doctest
287 @line_magic
288 def who(self, parameter_s=''):
289 """Print all interactive variables, with some minimal formatting.
291 If any arguments are given, only variables whose type matches one of
292 these are printed. For example::
294 %who function str
296 will only list functions and strings, excluding all other types of
297 variables. To find the proper type names, simply use type(var) at a
298 command line to see how python prints type names. For example:
300 ::
302 In [1]: type('hello')\\
303 Out[1]: <type 'str'>
305 indicates that the type name for strings is 'str'.
307 ``%who`` always excludes executed names loaded through your configuration
308 file and things which are internal to IPython.
310 This is deliberate, as typically you may load many modules and the
311 purpose of %who is to show you only what you've manually defined.
313 Examples
314 --------
316 Define two variables and list them with who::
318 In [1]: alpha = 123
320 In [2]: beta = 'test'
322 In [3]: %who
323 alpha beta
325 In [4]: %who int
326 alpha
328 In [5]: %who str
329 beta
330 """
332 varlist = self.who_ls(parameter_s)
333 if not varlist:
334 if parameter_s:
335 print('No variables match your requested type.')
336 else:
337 print('Interactive namespace is empty.')
338 return
340 # if we have variables, move on...
341 count = 0
342 for i in varlist:
343 print(i+'\t', end=' ')
344 count += 1
345 if count > 8:
346 count = 0
347 print()
348 print()
350 @skip_doctest
351 @line_magic
352 def whos(self, parameter_s=''):
353 """Like %who, but gives some extra information about each variable.
355 The same type filtering of %who can be applied here.
357 For all variables, the type is printed. Additionally it prints:
359 - For {},[],(): their length.
361 - For numpy arrays, a summary with shape, number of
362 elements, typecode and size in memory.
364 - For objects that have shape attribute, primarily dataframe and series like
365 objects, will print the shape.
367 - Everything else: a string representation, snipping their middle if
368 too long.
370 Examples
371 --------
372 Define two variables and list them with whos::
374 In [1]: alpha = 123
376 In [2]: beta = 'test'
378 In [3]: df = pd.DataFrame({"a": range(10), "b": range(10,20)})
380 In [4]: s = df["a"]
382 In [5]: %whos
383 Variable Type Data/Info
384 --------------------------------
385 alpha int 123
386 beta str test
387 df DataFrame Shape: (10, 2)
388 s Series Shape: (10, )
389 """
391 varnames = self.who_ls(parameter_s)
392 if not varnames:
393 if parameter_s:
394 print('No variables match your requested type.')
395 else:
396 print('Interactive namespace is empty.')
397 return
399 # if we have variables, move on...
401 # for these types, show len() instead of data:
402 seq_types = ['dict', 'list', 'tuple']
404 # for numpy arrays, display summary info
405 ndarray_type = None
406 if 'numpy' in sys.modules:
407 try:
408 from numpy import ndarray
409 except ImportError:
410 pass
411 else:
412 ndarray_type = ndarray.__name__
414 # Find all variable names and types so we can figure out column sizes
416 # some types are well known and can be shorter
417 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
418 def type_name(v):
419 tn = type(v).__name__
420 return abbrevs.get(tn,tn)
422 varlist = [self.shell.user_ns[n] for n in varnames]
424 typelist = []
425 for vv in varlist:
426 tt = type_name(vv)
428 if tt=='instance':
429 typelist.append( abbrevs.get(str(vv.__class__),
430 str(vv.__class__)))
431 else:
432 typelist.append(tt)
434 # column labels and # of spaces as separator
435 varlabel = 'Variable'
436 typelabel = 'Type'
437 datalabel = 'Data/Info'
438 colsep = 3
439 # variable format strings
440 vformat = "{0:<{varwidth}}{1:<{typewidth}}"
441 aformat = "%s: %s elems, type `%s`, %s bytes"
442 # find the size of the columns to format the output nicely
443 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
444 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
445 # table header
446 print(varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
447 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1))
448 # and the table itself
449 kb = 1024
450 Mb = 1048576 # kb**2
451 for vname,var,vtype in zip(varnames,varlist,typelist):
452 print(vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth), end=' ')
453 if vtype == ndarray_type:
454 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
455 if vtype==ndarray_type:
456 # numpy
457 vsize = var.size
458 vbytes = vsize*var.itemsize
459 vdtype = var.dtype
461 if vbytes < 100000:
462 print(aformat % (vshape, vsize, vdtype, vbytes))
463 else:
464 print(aformat % (vshape, vsize, vdtype, vbytes), end=' ')
465 if vbytes < Mb:
466 print('(%s kb)' % (vbytes/kb,))
467 else:
468 print("(%s Mb)" % (vbytes / Mb,))
469 elif hasattr(var, "shape"):
470 # Useful for DataFrames and Series
471 # Ought to work for both pandas and polars
472 print(f"Shape: {var.shape}")
473 elif hasattr(var, "__len__"):
474 ## types that can be used in len function
475 print(var if isinstance(var, str) else f"n={len(var)}")
476 else:
477 try:
478 vstr = str(var)
479 except UnicodeEncodeError:
480 vstr = var.encode(DEFAULT_ENCODING,
481 'backslashreplace')
482 except:
483 vstr = "<object with id %d (str() failed)>" % id(var)
484 vstr = vstr.replace('\n', '\\n')
485 if len(vstr) < 50:
486 print(vstr)
487 else:
488 print(vstr[:25] + "<...>" + vstr[-25:])
490 @line_magic
491 def reset(self, parameter_s=''):
492 """Resets the namespace by removing all names defined by the user, if
493 called without arguments, or by removing some types of objects, such
494 as everything currently in IPython's In[] and Out[] containers (see
495 the parameters for details).
497 Parameters
498 ----------
499 -f
500 force reset without asking for confirmation.
501 -s
502 'Soft' reset: Only clears your namespace, leaving history intact.
503 References to objects may be kept. By default (without this option),
504 we do a 'hard' reset, giving you a new session and removing all
505 references to objects from the current session.
506 --aggressive
507 Try to aggressively remove modules from sys.modules ; this
508 may allow you to reimport Python modules that have been updated and
509 pick up changes, but can have unintended consequences.
511 in
512 reset input history
513 out
514 reset output history
515 dhist
516 reset directory history
517 array
518 reset only variables that are NumPy arrays
520 See Also
521 --------
522 reset_selective : invoked as ``%reset_selective``
524 Examples
525 --------
526 ::
528 In [6]: a = 1
530 In [7]: a
531 Out[7]: 1
533 In [8]: 'a' in get_ipython().user_ns
534 Out[8]: True
536 In [9]: %reset -f
538 In [1]: 'a' in get_ipython().user_ns
539 Out[1]: False
541 In [2]: %reset -f in
542 Flushing input history
544 In [3]: %reset -f dhist in
545 Flushing directory history
546 Flushing input history
548 Notes
549 -----
550 Calling this magic from clients that do not implement standard input,
551 such as the ipython notebook interface, will reset the namespace
552 without confirmation.
553 """
554 opts, args = self.parse_options(parameter_s, "sf", "aggressive", mode="list")
555 if "f" in opts:
556 ans = True
557 else:
558 try:
559 ans = self.shell.ask_yes_no(
560 "Once deleted, variables cannot be recovered. Proceed (y/[n])?",
561 default='n')
562 except StdinNotImplementedError:
563 ans = True
564 if not ans:
565 print('Nothing done.')
566 return
568 if 's' in opts: # Soft reset
569 user_ns = self.shell.user_ns
570 for i in self.who_ls():
571 del(user_ns[i])
572 elif len(args) == 0: # Hard reset
573 self.shell.reset(new_session=False, aggressive=("aggressive" in opts))
575 # reset in/out/dhist/array: previously extensinions/clearcmd.py
576 ip = self.shell
577 user_ns = self.shell.user_ns # local lookup, heavily used
579 for target in args:
580 target = target.lower() # make matches case insensitive
581 if target == 'out':
582 print("Flushing output cache (%d entries)" % len(user_ns['_oh']))
583 self.shell.displayhook.flush()
585 elif target == 'in':
586 print("Flushing input history")
587 pc = self.shell.displayhook.prompt_count + 1
588 for n in range(1, pc):
589 key = '_i'+repr(n)
590 user_ns.pop(key,None)
591 user_ns.update(dict(_i=u'',_ii=u'',_iii=u''))
592 hm = ip.history_manager
593 # don't delete these, as %save and %macro depending on the
594 # length of these lists to be preserved
595 hm.input_hist_parsed[:] = [''] * pc
596 hm.input_hist_raw[:] = [''] * pc
597 # hm has internal machinery for _i,_ii,_iii, clear it out
598 hm._i = hm._ii = hm._iii = hm._i00 = u''
600 elif target == 'array':
601 # Support cleaning up numpy arrays
602 try:
603 from numpy import ndarray
604 # This must be done with items and not iteritems because
605 # we're going to modify the dict in-place.
606 for x,val in list(user_ns.items()):
607 if isinstance(val,ndarray):
608 del user_ns[x]
609 except ImportError:
610 print("reset array only works if Numpy is available.")
612 elif target == 'dhist':
613 print("Flushing directory history")
614 del user_ns['_dh'][:]
616 else:
617 print("Don't know how to reset ", end=' ')
618 print(target + ", please run `%reset?` for details")
620 gc.collect()
622 @line_magic
623 def reset_selective(self, parameter_s=''):
624 """Resets the namespace by removing names defined by the user.
626 Input/Output history are left around in case you need them.
628 %reset_selective [-f] regex
630 No action is taken if regex is not included
632 Options
633 -f : force reset without asking for confirmation.
635 See Also
636 --------
637 reset : invoked as ``%reset``
639 Examples
640 --------
641 We first fully reset the namespace so your output looks identical to
642 this example for pedagogical reasons; in practice you do not need a
643 full reset::
645 In [1]: %reset -f
647 Now, with a clean namespace we can make a few variables and use
648 ``%reset_selective`` to only delete names that match our regexp::
650 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
652 In [3]: who_ls
653 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
655 In [4]: %reset_selective -f b[2-3]m
657 In [5]: who_ls
658 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
660 In [6]: %reset_selective -f d
662 In [7]: who_ls
663 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
665 In [8]: %reset_selective -f c
667 In [9]: who_ls
668 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
670 In [10]: %reset_selective -f b
672 In [11]: who_ls
673 Out[11]: ['a']
675 Notes
676 -----
677 Calling this magic from clients that do not implement standard input,
678 such as the ipython notebook interface, will reset the namespace
679 without confirmation.
680 """
682 opts, regex = self.parse_options(parameter_s,'f')
684 if 'f' in opts:
685 ans = True
686 else:
687 try:
688 ans = self.shell.ask_yes_no(
689 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
690 default='n')
691 except StdinNotImplementedError:
692 ans = True
693 if not ans:
694 print('Nothing done.')
695 return
696 user_ns = self.shell.user_ns
697 if not regex:
698 print('No regex pattern specified. Nothing done.')
699 return
700 else:
701 try:
702 m = re.compile(regex)
703 except TypeError as e:
704 raise TypeError('regex must be a string or compiled pattern') from e
705 for i in self.who_ls():
706 if m.search(i):
707 del(user_ns[i])
709 @line_magic
710 def xdel(self, parameter_s=''):
711 """Delete a variable, trying to clear it from anywhere that
712 IPython's machinery has references to it. By default, this uses
713 the identity of the named object in the user namespace to remove
714 references held under other names. The object is also removed
715 from the output history.
717 Options
718 -n : Delete the specified name from all namespaces, without
719 checking their identity.
720 """
721 opts, varname = self.parse_options(parameter_s,'n')
722 try:
723 self.shell.del_var(varname, ('n' in opts))
724 except (NameError, ValueError) as e:
725 print(type(e).__name__ +": "+ str(e))