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  #-----------------------------------------------------------------------------
  10  
  11  #-----------------------------------------------------------------------------
  12  # Imports
  13  #-----------------------------------------------------------------------------
  14  
  15  # Stdlib
  16  import gc
  17  import re
  18  import sys
  19  
  20  # Our own packages
  21  from IPython.core import page
  22  from IPython.core.error import StdinNotImplementedError, UsageError
  23  from IPython.core.magic import Magics, magics_class, line_magic
  24  from IPython.testing.skipdoctest import skip_doctest
  25  from IPython.utils.encoding import DEFAULT_ENCODING
  26  from IPython.utils.openpy import read_py_file
  27  from IPython.utils.path import get_py_filename
  28  
  29  #-----------------------------------------------------------------------------
  30  # Magic implementation classes
  31  #-----------------------------------------------------------------------------
  32  
  33  @magics_class
  34  class NamespaceMagics(Magics):
  35      """Magics to manage various aspects of the user's namespace.
  36  
  37      These include listing variables, introspecting into them, etc.
  38      """
  39  
  40      @line_magic
  41      def pinfo(self, parameter_s='', namespaces=None):
  42          """Provide detailed information about an object.
  43  
  44          '%pinfo object' is just a synonym for object? or ?object."""
  45  
  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)
  60  
  61      @line_magic
  62      def pinfo2(self, parameter_s='', namespaces=None):
  63          """Provide extra detailed information about an object.
  64  
  65          '%pinfo2 object' is just a synonym for object?? or ??object."""
  66          self.shell._inspect('pinfo', parameter_s, detail_level=1,
  67                              namespaces=namespaces)
  68  
  69      @skip_doctest
  70      @line_magic
  71      def pdef(self, parameter_s='', namespaces=None):
  72          """Print the call signature for any callable object.
  73  
  74          If the object is a class, print the constructor information.
  75  
  76          Examples
  77          --------
  78          ::
  79  
  80            In [3]: %pdef urllib.urlopen
  81            urllib.urlopen(url, data=None, proxies=None)
  82          """
  83          self.shell._inspect('pdef',parameter_s, namespaces)
  84  
  85      @line_magic
  86      def pdoc(self, parameter_s='', namespaces=None):
  87          """Print the docstring for an object.
  88  
  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)
  92  
  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)
  99  
 100      @line_magic
 101      def pfile(self, parameter_s='', namespaces=None):
 102          """Print (or run through pager) the file where an object is defined.
 103  
 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.
 107  
 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."""
 112  
 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)))
 123  
 124      @line_magic
 125      def psearch(self, parameter_s=''):
 126          """Search for object in namespaces by wildcard.
 127  
 128          %psearch [options] PATTERN [OBJECT TYPE]
 129  
 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
 134  
 135          %psearch -i a* function
 136          -i a* function?
 137          ?-i a* function
 138  
 139          Arguments:
 140  
 141            PATTERN
 142  
 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.
 150  
 151            [OBJECT TYPE]
 152  
 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).
 158  
 159          Options:
 160  
 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.
 164  
 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.
 170  
 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.
 176  
 177            -l: List all available object types for object matching. This function
 178            can be used without arguments.
 179  
 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).
 187  
 188          Examples
 189          --------
 190          ::
 191  
 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
 198  
 199          Case sensitive search::
 200  
 201            %psearch -c a*         list all object beginning with lower case a
 202  
 203          Show objects beginning with a single _::
 204  
 205            %psearch -a _*         list objects beginning with a single underscore
 206  
 207          List available objects::
 208  
 209            %psearch -l            list all available object types
 210          """
 211          # default namespaces to be searched
 212          def_search = ['user_local', 'user_global', 'builtin']
 213  
 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
 219          
 220          # select list object types
 221          list_types = False
 222          if 'l' in opts:
 223              list_types = True
 224  
 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
 232  
 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]
 237  
 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()
 244  
 245      @skip_doctest
 246      @line_magic
 247      def who_ls(self, parameter_s=''):
 248          """Return a sorted list of all interactive variables.
 249  
 250          If arguments are given, only variables of types matching these
 251          arguments are returned.
 252  
 253          Examples
 254          --------
 255          Define two variables and list them with who_ls::
 256  
 257            In [1]: alpha = 123
 258  
 259            In [2]: beta = 'test'
 260  
 261            In [3]: %who_ls
 262            Out[3]: ['alpha', 'beta']
 263  
 264            In [4]: %who_ls int
 265            Out[4]: ['alpha']
 266  
 267            In [5]: %who_ls str
 268            Out[5]: ['beta']
 269          """
 270  
 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)) ]
 277  
 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]
 282  
 283          out.sort()
 284          return out
 285  
 286      @skip_doctest
 287      @line_magic
 288      def who(self, parameter_s=''):
 289          """Print all interactive variables, with some minimal formatting.
 290  
 291          If any arguments are given, only variables whose type matches one of
 292          these are printed.  For example::
 293  
 294            %who function str
 295  
 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:
 299  
 300          ::
 301  
 302            In [1]: type('hello')\\
 303            Out[1]: <type 'str'>
 304  
 305          indicates that the type name for strings is 'str'.
 306  
 307          ``%who`` always excludes executed names loaded through your configuration
 308          file and things which are internal to IPython.
 309  
 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.
 312  
 313          Examples
 314          --------
 315  
 316          Define two variables and list them with who::
 317  
 318            In [1]: alpha = 123
 319  
 320            In [2]: beta = 'test'
 321  
 322            In [3]: %who
 323            alpha   beta
 324  
 325            In [4]: %who int
 326            alpha
 327  
 328            In [5]: %who str
 329            beta
 330          """
 331  
 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
 339  
 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()
 349  
 350      @skip_doctest
 351      @line_magic
 352      def whos(self, parameter_s=''):
 353          """Like %who, but gives some extra information about each variable.
 354  
 355          The same type filtering of %who can be applied here.
 356  
 357          For all variables, the type is printed. Additionally it prints:
 358  
 359            - For {},[],(): their length.
 360  
 361            - For numpy arrays, a summary with shape, number of
 362              elements, typecode and size in memory.
 363  
 364            - Everything else: a string representation, snipping their middle if
 365              too long.
 366  
 367          Examples
 368          --------
 369          Define two variables and list them with whos::
 370  
 371            In [1]: alpha = 123
 372  
 373            In [2]: beta = 'test'
 374  
 375            In [3]: %whos
 376            Variable   Type        Data/Info
 377            --------------------------------
 378            alpha      int         123
 379            beta       str         test
 380          """
 381  
 382          varnames = self.who_ls(parameter_s)
 383          if not varnames:
 384              if parameter_s:
 385                  print('No variables match your requested type.')
 386              else:
 387                  print('Interactive namespace is empty.')
 388              return
 389  
 390          # if we have variables, move on...
 391  
 392          # for these types, show len() instead of data:
 393          seq_types = ['dict', 'list', 'tuple']
 394  
 395          # for numpy arrays, display summary info
 396          ndarray_type = None
 397          if 'numpy' in sys.modules:
 398              try:
 399                  from numpy import ndarray
 400              except ImportError:
 401                  pass
 402              else:
 403                  ndarray_type = ndarray.__name__
 404  
 405          # Find all variable names and types so we can figure out column sizes
 406  
 407          # some types are well known and can be shorter
 408          abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
 409          def type_name(v):
 410              tn = type(v).__name__
 411              return abbrevs.get(tn,tn)
 412  
 413          varlist = [self.shell.user_ns[n] for n in varnames]
 414  
 415          typelist = []
 416          for vv in varlist:
 417              tt = type_name(vv)
 418  
 419              if tt=='instance':
 420                  typelist.append( abbrevs.get(str(vv.__class__),
 421                                               str(vv.__class__)))
 422              else:
 423                  typelist.append(tt)
 424  
 425          # column labels and # of spaces as separator
 426          varlabel = 'Variable'
 427          typelabel = 'Type'
 428          datalabel = 'Data/Info'
 429          colsep = 3
 430          # variable format strings
 431          vformat    = "{0:<{varwidth}}{1:<{typewidth}}"
 432          aformat    = "%s: %s elems, type `%s`, %s bytes"
 433          # find the size of the columns to format the output nicely
 434          varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
 435          typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
 436          # table header
 437          print(varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
 438                ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1))
 439          # and the table itself
 440          kb = 1024
 441          Mb = 1048576  # kb**2
 442          for vname,var,vtype in zip(varnames,varlist,typelist):
 443              print(vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth), end=' ')
 444              if vtype in seq_types:
 445                  print("n="+str(len(var)))
 446              elif vtype == ndarray_type:
 447                  vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
 448                  if vtype==ndarray_type:
 449                      # numpy
 450                      vsize  = var.size
 451                      vbytes = vsize*var.itemsize
 452                      vdtype = var.dtype
 453  
 454                  if vbytes < 100000:
 455                      print(aformat % (vshape, vsize, vdtype, vbytes))
 456                  else:
 457                      print(aformat % (vshape, vsize, vdtype, vbytes), end=' ')
 458                      if vbytes < Mb:
 459                          print('(%s kb)' % (vbytes/kb,))
 460                      else:
 461                          print('(%s Mb)' % (vbytes/Mb,))
 462              else:
 463                  try:
 464                      vstr = str(var)
 465                  except UnicodeEncodeError:
 466                      vstr = var.encode(DEFAULT_ENCODING,
 467                                        'backslashreplace')
 468                  except:
 469                      vstr = "<object with id %d (str() failed)>" % id(var)
 470                  vstr = vstr.replace('\n', '\\n')
 471                  if len(vstr) < 50:
 472                      print(vstr)
 473                  else:
 474                      print(vstr[:25] + "<...>" + vstr[-25:])
 475  
 476      @line_magic
 477      def reset(self, parameter_s=''):
 478          """Resets the namespace by removing all names defined by the user, if
 479          called without arguments, or by removing some types of objects, such
 480          as everything currently in IPython's In[] and Out[] containers (see
 481          the parameters for details).
 482  
 483          Parameters
 484          ----------
 485          -f
 486              force reset without asking for confirmation.
 487          -s
 488              'Soft' reset: Only clears your namespace, leaving history intact.
 489              References to objects may be kept. By default (without this option),
 490              we do a 'hard' reset, giving you a new session and removing all
 491              references to objects from the current session.
 492          --aggressive
 493              Try to aggressively remove modules from sys.modules ; this
 494              may allow you to reimport Python modules that have been updated and
 495              pick up changes, but can have unintended consequences.
 496  
 497          in
 498              reset input history
 499          out
 500              reset output history
 501          dhist
 502              reset directory history
 503          array
 504              reset only variables that are NumPy arrays
 505  
 506          See Also
 507          --------
 508          reset_selective : invoked as ``%reset_selective``
 509  
 510          Examples
 511          --------
 512          ::
 513  
 514            In [6]: a = 1
 515  
 516            In [7]: a
 517            Out[7]: 1
 518  
 519            In [8]: 'a' in get_ipython().user_ns
 520            Out[8]: True
 521  
 522            In [9]: %reset -f
 523  
 524            In [1]: 'a' in get_ipython().user_ns
 525            Out[1]: False
 526  
 527            In [2]: %reset -f in
 528            Flushing input history
 529  
 530            In [3]: %reset -f dhist in
 531            Flushing directory history
 532            Flushing input history
 533  
 534          Notes
 535          -----
 536          Calling this magic from clients that do not implement standard input,
 537          such as the ipython notebook interface, will reset the namespace
 538          without confirmation.
 539          """
 540          opts, args = self.parse_options(parameter_s, "sf", "aggressive", mode="list")
 541          if "f" in opts:
 542              ans = True
 543          else:
 544              try:
 545                  ans = self.shell.ask_yes_no(
 546                  "Once deleted, variables cannot be recovered. Proceed (y/[n])?",
 547                  default='n')
 548              except StdinNotImplementedError:
 549                  ans = True
 550          if not ans:
 551              print('Nothing done.')
 552              return
 553  
 554          if 's' in opts:                     # Soft reset
 555              user_ns = self.shell.user_ns
 556              for i in self.who_ls():
 557                  del(user_ns[i])
 558          elif len(args) == 0:                # Hard reset
 559              self.shell.reset(new_session=False, aggressive=("aggressive" in opts))
 560  
 561          # reset in/out/dhist/array: previously extensinions/clearcmd.py
 562          ip = self.shell
 563          user_ns = self.shell.user_ns  # local lookup, heavily used
 564  
 565          for target in args:
 566              target = target.lower() # make matches case insensitive
 567              if target == 'out':
 568                  print("Flushing output cache (%d entries)" % len(user_ns['_oh']))
 569                  self.shell.displayhook.flush()
 570  
 571              elif target == 'in':
 572                  print("Flushing input history")
 573                  pc = self.shell.displayhook.prompt_count + 1
 574                  for n in range(1, pc):
 575                      key = '_i'+repr(n)
 576                      user_ns.pop(key,None)
 577                  user_ns.update(dict(_i=u'',_ii=u'',_iii=u''))
 578                  hm = ip.history_manager
 579                  # don't delete these, as %save and %macro depending on the
 580                  # length of these lists to be preserved
 581                  hm.input_hist_parsed[:] = [''] * pc
 582                  hm.input_hist_raw[:] = [''] * pc
 583                  # hm has internal machinery for _i,_ii,_iii, clear it out
 584                  hm._i = hm._ii = hm._iii = hm._i00 =  u''
 585  
 586              elif target == 'array':
 587                  # Support cleaning up numpy arrays
 588                  try:
 589                      from numpy import ndarray
 590                      # This must be done with items and not iteritems because
 591                      # we're going to modify the dict in-place.
 592                      for x,val in list(user_ns.items()):
 593                          if isinstance(val,ndarray):
 594                              del user_ns[x]
 595                  except ImportError:
 596                      print("reset array only works if Numpy is available.")
 597  
 598              elif target == 'dhist':
 599                  print("Flushing directory history")
 600                  del user_ns['_dh'][:]
 601  
 602              else:
 603                  print("Don't know how to reset ", end=' ')
 604                  print(target + ", please run `%reset?` for details")
 605  
 606          gc.collect()
 607  
 608      @line_magic
 609      def reset_selective(self, parameter_s=''):
 610          """Resets the namespace by removing names defined by the user.
 611  
 612          Input/Output history are left around in case you need them.
 613  
 614          %reset_selective [-f] regex
 615  
 616          No action is taken if regex is not included
 617  
 618          Options
 619            -f : force reset without asking for confirmation.
 620  
 621          See Also
 622          --------
 623          reset : invoked as ``%reset``
 624  
 625          Examples
 626          --------
 627          We first fully reset the namespace so your output looks identical to
 628          this example for pedagogical reasons; in practice you do not need a
 629          full reset::
 630  
 631            In [1]: %reset -f
 632  
 633          Now, with a clean namespace we can make a few variables and use
 634          ``%reset_selective`` to only delete names that match our regexp::
 635  
 636            In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
 637  
 638            In [3]: who_ls
 639            Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
 640  
 641            In [4]: %reset_selective -f b[2-3]m
 642  
 643            In [5]: who_ls
 644            Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
 645  
 646            In [6]: %reset_selective -f d
 647  
 648            In [7]: who_ls
 649            Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
 650  
 651            In [8]: %reset_selective -f c
 652  
 653            In [9]: who_ls
 654            Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
 655  
 656            In [10]: %reset_selective -f b
 657  
 658            In [11]: who_ls
 659            Out[11]: ['a']
 660  
 661          Notes
 662          -----
 663          Calling this magic from clients that do not implement standard input,
 664          such as the ipython notebook interface, will reset the namespace
 665          without confirmation.
 666          """
 667  
 668          opts, regex = self.parse_options(parameter_s,'f')
 669  
 670          if 'f' in opts:
 671              ans = True
 672          else:
 673              try:
 674                  ans = self.shell.ask_yes_no(
 675                  "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
 676                  default='n')
 677              except StdinNotImplementedError:
 678                  ans = True
 679          if not ans:
 680              print('Nothing done.')
 681              return
 682          user_ns = self.shell.user_ns
 683          if not regex:
 684              print('No regex pattern specified. Nothing done.')
 685              return
 686          else:
 687              try:
 688                  m = re.compile(regex)
 689              except TypeError as e:
 690                  raise TypeError('regex must be a string or compiled pattern') from e
 691              for i in self.who_ls():
 692                  if m.search(i):
 693                      del(user_ns[i])
 694  
 695      @line_magic
 696      def xdel(self, parameter_s=''):
 697          """Delete a variable, trying to clear it from anywhere that
 698          IPython's machinery has references to it. By default, this uses
 699          the identity of the named object in the user namespace to remove
 700          references held under other names. The object is also removed
 701          from the output history.
 702  
 703          Options
 704            -n : Delete the specified name from all namespaces, without
 705            checking their identity.
 706          """
 707          opts, varname = self.parse_options(parameter_s,'n')
 708          try:
 709              self.shell.del_var(varname, ('n' in opts))
 710          except (NameError, ValueError) as e:
 711              print(type(e).__name__ +": "+ str(e))
 712