Preserve function/method identity in magic decorators

`decorator(call, func)` does `func.__doc__ = call.__doc__` and so on, where `func` is the original function and `call = lambda f, *a, **k: f(*a, **k)`. Because of that ipdoctest is not able to see the function original docstring, leading to missing tests. The resulting wrapper is simply calling the original function and thus is not needed.

IPython/core/magic.py

@@ -1,717 +1,712
 # encoding: utf-8
 """Magic functions for InteractiveShell.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2001 Janko Hauser <[e-mail]> and
 #  Copyright (C) 2001 Fernando Perez <[e-mail]>
 #  Copyright (C) 2008 The IPython Development Team
 
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 import os
 import re
 import sys
 from getopt import getopt, GetoptError
 
 from traitlets.config.configurable import Configurable
 from . import oinspect
 from .error import UsageError
 from .inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
-from decorator import decorator
 from ..utils.ipstruct import Struct
 from ..utils.process import arg_split
 from ..utils.text import dedent
 from traitlets import Bool, Dict, Instance, observe
 from logging import error
 
 #-----------------------------------------------------------------------------
 # Globals
 #-----------------------------------------------------------------------------
 
 # A dict we'll use for each class that has magics, used as temporary storage to
 # pass information between the @line/cell_magic method decorators and the
 # @magics_class class decorator, because the method decorators have no
 # access to the class when they run.  See for more details:
 # http://stackoverflow.com/questions/2366713/can-a-python-decorator-of-an-instance-method-access-the-class
 
 magics = dict(line={}, cell={})
 
 magic_kinds = ('line', 'cell')
 magic_spec = ('line', 'cell', 'line_cell')
 magic_escapes = dict(line=ESC_MAGIC, cell=ESC_MAGIC2)
 
 #-----------------------------------------------------------------------------
 # Utility classes and functions
 #-----------------------------------------------------------------------------
 
 class Bunch: pass
 
 
 def on_off(tag):
     """Return an ON/OFF string for a 1/0 input. Simple utility function."""
     return ['OFF','ON'][tag]
 
 
 def compress_dhist(dh):
     """Compress a directory history into a new one with at most 20 entries.
 
     Return a new list made from the first and last 10 elements of dhist after
     removal of duplicates.
     """
     head, tail = dh[:-10], dh[-10:]
 
     newhead = []
     done = set()
     for h in head:
         if h in done:
             continue
         newhead.append(h)
         done.add(h)
 
     return newhead + tail
 
 
 def needs_local_scope(func):
     """Decorator to mark magic functions which need to local scope to run."""
     func.needs_local_scope = True
     return func
 
 #-----------------------------------------------------------------------------
 # Class and method decorators for registering magics
 #-----------------------------------------------------------------------------
 
 def magics_class(cls):
     """Class decorator for all subclasses of the main Magics class.
 
     Any class that subclasses Magics *must* also apply this decorator, to
     ensure that all the methods that have been decorated as line/cell magics
     get correctly registered in the class instance.  This is necessary because
     when method decorators run, the class does not exist yet, so they
     temporarily store their information into a module global.  Application of
     this class decorator copies that global data to the class instance and
     clears the global.
 
     Obviously, this mechanism is not thread-safe, which means that the
     *creation* of subclasses of Magic should only be done in a single-thread
     context.  Instantiation of the classes has no restrictions.  Given that
     these classes are typically created at IPython startup time and before user
     application code becomes active, in practice this should not pose any
     problems.
     """
     cls.registered = True
     cls.magics = dict(line = magics['line'],
                       cell = magics['cell'])
     magics['line'] = {}
     magics['cell'] = {}
     return cls
 
 
 def record_magic(dct, magic_kind, magic_name, func):
     """Utility function to store a function as a magic of a specific kind.
 
     Parameters
     ----------
     dct : dict
       A dictionary with 'line' and 'cell' subdicts.
 
     magic_kind : str
       Kind of magic to be stored.
 
     magic_name : str
       Key to store the magic as.
 
     func : function
       Callable object to store.
     """
     if magic_kind == 'line_cell':
         dct['line'][magic_name] = dct['cell'][magic_name] = func
     else:
         dct[magic_kind][magic_name] = func
 
 
 def validate_type(magic_kind):
     """Ensure that the given magic_kind is valid.
 
     Check that the given magic_kind is one of the accepted spec types (stored
     in the global `magic_spec`), raise ValueError otherwise.
     """
     if magic_kind not in magic_spec:
         raise ValueError('magic_kind must be one of %s, %s given' %
                          magic_kinds, magic_kind)
 
 
 # The docstrings for the decorator below will be fairly similar for the two
 # types (method and function), so we generate them here once and reuse the
 # templates below.
 _docstring_template = \
 """Decorate the given {0} as {1} magic.
 
 The decorator can be used with or without arguments, as follows.
 
 i) without arguments: it will create a {1} magic named as the {0} being
 decorated::
 
     @deco
     def foo(...)
 
 will create a {1} magic named `foo`.
 
 ii) with one string argument: which will be used as the actual name of the
 resulting magic::
 
     @deco('bar')
     def foo(...)
 
 will create a {1} magic named `bar`.
 
 To register a class magic use ``Interactiveshell.register_magic(class or instance)``.
 """
 
 # These two are decorator factories.  While they are conceptually very similar,
 # there are enough differences in the details that it's simpler to have them
 # written as completely standalone functions rather than trying to share code
 # and make a single one with convoluted logic.
 
 def _method_magic_marker(magic_kind):
     """Decorator factory for methods in Magics subclasses.
     """
 
     validate_type(magic_kind)
 
     # This is a closure to capture the magic_kind.  We could also use a class,
     # but it's overkill for just that one bit of state.
     def magic_deco(arg):
-        call = lambda f, *a, **k: f(*a, **k)
-
         if callable(arg):
             # "Naked" decorator call (just @foo, no args)
             func = arg
             name = func.__name__
-            retval = decorator(call, func)
+            retval = arg
             record_magic(magics, magic_kind, name, name)
         elif isinstance(arg, str):
             # Decorator called with arguments (@foo('bar'))
             name = arg
             def mark(func, *a, **kw):
                 record_magic(magics, magic_kind, name, func.__name__)
-                return decorator(call, func)
+                return func
             retval = mark
         else:
             raise TypeError("Decorator can only be called with "
                             "string or function")
         return retval
 
     # Ensure the resulting decorator has a usable docstring
     magic_deco.__doc__ = _docstring_template.format('method', magic_kind)
     return magic_deco
 
 
 def _function_magic_marker(magic_kind):
     """Decorator factory for standalone functions.
     """
     validate_type(magic_kind)
     
     # This is a closure to capture the magic_kind.  We could also use a class,
     # but it's overkill for just that one bit of state.
     def magic_deco(arg):
-        call = lambda f, *a, **k: f(*a, **k)
-
         # Find get_ipython() in the caller's namespace
         caller = sys._getframe(1)
         for ns in ['f_locals', 'f_globals', 'f_builtins']:
             get_ipython = getattr(caller, ns).get('get_ipython')
             if get_ipython is not None:
                 break
         else:
             raise NameError('Decorator can only run in context where '
                             '`get_ipython` exists')
 
         ip = get_ipython()
 
         if callable(arg):
             # "Naked" decorator call (just @foo, no args)
             func = arg
             name = func.__name__
             ip.register_magic_function(func, magic_kind, name)
-            retval = decorator(call, func)
+            retval = arg
         elif isinstance(arg, str):
             # Decorator called with arguments (@foo('bar'))
             name = arg
             def mark(func, *a, **kw):
                 ip.register_magic_function(func, magic_kind, name)
-                return decorator(call, func)
+                return func
             retval = mark
         else:
             raise TypeError("Decorator can only be called with "
                              "string or function")
         return retval
 
     # Ensure the resulting decorator has a usable docstring
     ds = _docstring_template.format('function', magic_kind)
 
     ds += dedent("""
     Note: this decorator can only be used in a context where IPython is already
     active, so that the `get_ipython()` call succeeds.  You can therefore use
     it in your startup files loaded after IPython initializes, but *not* in the
     IPython configuration file itself, which is executed before IPython is
     fully up and running.  Any file located in the `startup` subdirectory of
     your configuration profile will be OK in this sense.
     """)
     
     magic_deco.__doc__ = ds
     return magic_deco
 
 
 MAGIC_NO_VAR_EXPAND_ATTR = '_ipython_magic_no_var_expand'
 
 
 def no_var_expand(magic_func):
     """Mark a magic function as not needing variable expansion
 
     By default, IPython interprets `{a}` or `$a` in the line passed to magics
     as variables that should be interpolated from the interactive namespace
     before passing the line to the magic function.
     This is not always desirable, e.g. when the magic executes Python code
     (%timeit, %time, etc.).
     Decorate magics with `@no_var_expand` to opt-out of variable expansion.
 
     .. versionadded:: 7.3
     """
     setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
     return magic_func
 
 
 # Create the actual decorators for public use
 
 # These three are used to decorate methods in class definitions
 line_magic = _method_magic_marker('line')
 cell_magic = _method_magic_marker('cell')
 line_cell_magic = _method_magic_marker('line_cell')
 
 # These three decorate standalone functions and perform the decoration
 # immediately.  They can only run where get_ipython() works
 register_line_magic = _function_magic_marker('line')
 register_cell_magic = _function_magic_marker('cell')
 register_line_cell_magic = _function_magic_marker('line_cell')
 
 #-----------------------------------------------------------------------------
 # Core Magic classes
 #-----------------------------------------------------------------------------
 
 class MagicsManager(Configurable):
     """Object that handles all magic-related functionality for IPython.
     """
     # Non-configurable class attributes
 
     # A two-level dict, first keyed by magic type, then by magic function, and
     # holding the actual callable object as value.  This is the dict used for
     # magic function dispatch
     magics = Dict()
 
     # A registry of the original objects that we've been given holding magics.
     registry = Dict()
 
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
 
     auto_magic = Bool(True, help=
         "Automatically call line magics without requiring explicit % prefix"
     ).tag(config=True)
     @observe('auto_magic')
     def _auto_magic_changed(self, change):
         self.shell.automagic = change['new']
     
     _auto_status = [
         'Automagic is OFF, % prefix IS needed for line magics.',
         'Automagic is ON, % prefix IS NOT needed for line magics.']
 
     user_magics = Instance('IPython.core.magics.UserMagics', allow_none=True)
 
     def __init__(self, shell=None, config=None, user_magics=None, **traits):
 
         super(MagicsManager, self).__init__(shell=shell, config=config,
                                            user_magics=user_magics, **traits)
         self.magics = dict(line={}, cell={})
         # Let's add the user_magics to the registry for uniformity, so *all*
         # registered magic containers can be found there.
         self.registry[user_magics.__class__.__name__] = user_magics
 
     def auto_status(self):
         """Return descriptive string with automagic status."""
         return self._auto_status[self.auto_magic]
     
     def lsmagic(self):
         """Return a dict of currently available magic functions.
 
         The return dict has the keys 'line' and 'cell', corresponding to the
         two types of magics we support.  Each value is a list of names.
         """
         return self.magics
 
     def lsmagic_docs(self, brief=False, missing=''):
         """Return dict of documentation of magic functions.
 
         The return dict has the keys 'line' and 'cell', corresponding to the
         two types of magics we support. Each value is a dict keyed by magic
         name whose value is the function docstring. If a docstring is
         unavailable, the value of `missing` is used instead.
 
         If brief is True, only the first line of each docstring will be returned.
         """
         docs = {}
         for m_type in self.magics:
             m_docs = {}
             for m_name, m_func in self.magics[m_type].items():
                 if m_func.__doc__:
                     if brief:
                         m_docs[m_name] = m_func.__doc__.split('\n', 1)[0]
                     else:
                         m_docs[m_name] = m_func.__doc__.rstrip()
                 else:
                     m_docs[m_name] = missing
             docs[m_type] = m_docs
         return docs
 
     def register(self, *magic_objects):
         """Register one or more instances of Magics.
 
         Take one or more classes or instances of classes that subclass the main 
         `core.Magic` class, and register them with IPython to use the magic
         functions they provide.  The registration process will then ensure that
         any methods that have decorated to provide line and/or cell magics will
         be recognized with the `%x`/`%%x` syntax as a line/cell magic
         respectively.
 
         If classes are given, they will be instantiated with the default
         constructor.  If your classes need a custom constructor, you should
         instanitate them first and pass the instance.
 
         The provided arguments can be an arbitrary mix of classes and instances.
 
         Parameters
         ----------
         magic_objects : one or more classes or instances
         """
         # Start by validating them to ensure they have all had their magic
         # methods registered at the instance level
         for m in magic_objects:
             if not m.registered:
                 raise ValueError("Class of magics %r was constructed without "
                                  "the @register_magics class decorator")
             if isinstance(m, type):
                 # If we're given an uninstantiated class
                 m = m(shell=self.shell)
 
             # Now that we have an instance, we can register it and update the
             # table of callables
             self.registry[m.__class__.__name__] = m
             for mtype in magic_kinds:
                 self.magics[mtype].update(m.magics[mtype])
 
     def register_function(self, func, magic_kind='line', magic_name=None):
         """Expose a standalone function as magic function for IPython.
 
         This will create an IPython magic (line, cell or both) from a
         standalone function.  The functions should have the following
         signatures: 
 
         * For line magics: `def f(line)`
         * For cell magics: `def f(line, cell)`
         * For a function that does both: `def f(line, cell=None)`
 
         In the latter case, the function will be called with `cell==None` when
         invoked as `%f`, and with cell as a string when invoked as `%%f`.
 
         Parameters
         ----------
         func : callable
           Function to be registered as a magic.
 
         magic_kind : str
           Kind of magic, one of 'line', 'cell' or 'line_cell'
 
         magic_name : optional str
           If given, the name the magic will have in the IPython namespace.  By
           default, the name of the function itself is used.
         """
 
         # Create the new method in the user_magics and register it in the
         # global table
         validate_type(magic_kind)
         magic_name = func.__name__ if magic_name is None else magic_name
         setattr(self.user_magics, magic_name, func)
         record_magic(self.magics, magic_kind, magic_name, func)
 
     def register_alias(self, alias_name, magic_name, magic_kind='line', magic_params=None):
         """Register an alias to a magic function.
 
         The alias is an instance of :class:`MagicAlias`, which holds the
         name and kind of the magic it should call. Binding is done at
         call time, so if the underlying magic function is changed the alias
         will call the new function.
 
         Parameters
         ----------
         alias_name : str
           The name of the magic to be registered.
 
         magic_name : str
           The name of an existing magic.
 
         magic_kind : str
           Kind of magic, one of 'line' or 'cell'
         """
 
         # `validate_type` is too permissive, as it allows 'line_cell'
         # which we do not handle.
         if magic_kind not in magic_kinds:
             raise ValueError('magic_kind must be one of %s, %s given' %
                              magic_kinds, magic_kind)
 
         alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
         setattr(self.user_magics, alias_name, alias)
         record_magic(self.magics, magic_kind, alias_name, alias)
 
 # Key base class that provides the central functionality for magics.
 
 
 class Magics(Configurable):
     """Base class for implementing magic functions.
 
     Shell functions which can be reached as %function_name. All magic
     functions should accept a string, which they can parse for their own
     needs. This can make some functions easier to type, eg `%cd ../`
     vs. `%cd("../")`
 
     Classes providing magic functions need to subclass this class, and they
     MUST:
 
     - Use the method decorators `@line_magic` and `@cell_magic` to decorate
       individual methods as magic functions, AND
 
     - Use the class decorator `@magics_class` to ensure that the magic
       methods are properly registered at the instance level upon instance
       initialization.
 
     See :mod:`magic_functions` for examples of actual implementation classes.
     """
     # Dict holding all command-line options for each magic.
     options_table = None
     # Dict for the mapping of magic names to methods, set by class decorator
     magics = None
     # Flag to check that the class decorator was properly applied
     registered = False
     # Instance of IPython shell
     shell = None
 
     def __init__(self, shell=None, **kwargs):
         if not(self.__class__.registered):
             raise ValueError('Magics subclass without registration - '
                              'did you forget to apply @magics_class?')
         if shell is not None:
             if hasattr(shell, 'configurables'):
                 shell.configurables.append(self)
             if hasattr(shell, 'config'):
                 kwargs.setdefault('parent', shell)
 
         self.shell = shell
         self.options_table = {}
         # The method decorators are run when the instance doesn't exist yet, so
         # they can only record the names of the methods they are supposed to
         # grab.  Only now, that the instance exists, can we create the proper
         # mapping to bound methods.  So we read the info off the original names
         # table and replace each method name by the actual bound method.
         # But we mustn't clobber the *class* mapping, in case of multiple instances.
         class_magics = self.magics
         self.magics = {}
         for mtype in magic_kinds:
             tab = self.magics[mtype] = {}
             cls_tab = class_magics[mtype]
             for magic_name, meth_name in cls_tab.items():
                 if isinstance(meth_name, str):
                     # it's a method name, grab it
                     tab[magic_name] = getattr(self, meth_name)
                 else:
                     # it's the real thing
                     tab[magic_name] = meth_name
         # Configurable **needs** to be initiated at the end or the config
         # magics get screwed up.
         super(Magics, self).__init__(**kwargs)
 
     def arg_err(self,func):
         """Print docstring if incorrect arguments were passed"""
         print('Error in arguments:')
         print(oinspect.getdoc(func))
 
     def format_latex(self, strng):
         """Format a string for latex inclusion."""
 
         # Characters that need to be escaped for latex:
         escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
         # Magic command names as headers:
         cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
                                  re.MULTILINE)
         # Magic commands
         cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
                             re.MULTILINE)
         # Paragraph continue
         par_re = re.compile(r'\\$',re.MULTILINE)
 
         # The "\n" symbol
         newline_re = re.compile(r'\\n')
 
         # Now build the string for output:
         #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
         strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
                                 strng)
         strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
         strng = par_re.sub(r'\\\\',strng)
         strng = escape_re.sub(r'\\\1',strng)
         strng = newline_re.sub(r'\\textbackslash{}n',strng)
         return strng
 
     def parse_options(self, arg_str, opt_str, *long_opts, **kw):
         """Parse options passed to an argument string.
 
         The interface is similar to that of :func:`getopt.getopt`, but it
         returns a :class:`~IPython.utils.struct.Struct` with the options as keys
         and the stripped argument string still as a string.
 
         arg_str is quoted as a true sys.argv vector by using shlex.split.
         This allows us to easily expand variables, glob files, quote
         arguments, etc.
 
         Parameters
         ----------
 
         arg_str : str
           The arguments to parse.
 
         opt_str : str
           The options specification.
 
         mode : str, default 'string'
           If given as 'list', the argument string is returned as a list (split
           on whitespace) instead of a string.
 
         list_all : bool, default False
           Put all option values in lists. Normally only options
           appearing more than once are put in a list.
 
         posix : bool, default True
           Whether to split the input line in POSIX mode or not, as per the
           conventions outlined in the :mod:`shlex` module from the standard
           library.
         """
 
         # inject default options at the beginning of the input line
         caller = sys._getframe(1).f_code.co_name
         arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
 
         mode = kw.get('mode','string')
         if mode not in ['string','list']:
             raise ValueError('incorrect mode given: %s' % mode)
         # Get options
         list_all = kw.get('list_all',0)
         posix = kw.get('posix', os.name == 'posix')
         strict = kw.get('strict', True)
 
         preserve_non_opts = kw.get("preserve_non_opts", False)
         remainder_arg_str = arg_str
 
         # Check if we have more than one argument to warrant extra processing:
         odict = {}  # Dictionary with options
         args = arg_str.split()
         if len(args) >= 1:
             # If the list of inputs only has 0 or 1 thing in it, there's no
             # need to look for options
             argv = arg_split(arg_str, posix, strict)
             # Do regular option processing
             try:
                 opts,args = getopt(argv, opt_str, long_opts)
             except GetoptError as e:
                 raise UsageError(
                     '%s ( allowed: "%s" %s)' % (e.msg, opt_str, " ".join(long_opts))
                 ) from e
             for o, a in opts:
                 if mode == "string" and preserve_non_opts:
                     # remove option-parts from the original args-string and preserve remaining-part.
                     # This relies on the arg_split(...) and getopt(...)'s impl spec, that the parsed options are
                     # returned in the original order.
                     remainder_arg_str = remainder_arg_str.replace(o, "", 1).replace(
                         a, "", 1
                     )
                 if o.startswith("--"):
                     o = o[2:]
                 else:
                     o = o[1:]
                 try:
                     odict[o].append(a)
                 except AttributeError:
                     odict[o] = [odict[o],a]
                 except KeyError:
                     if list_all:
                         odict[o] = [a]
                     else:
                         odict[o] = a
 
         # Prepare opts,args for return
         opts = Struct(odict)
         if mode == 'string':
             if preserve_non_opts:
                 args = remainder_arg_str.lstrip()
             else:
                 args = " ".join(args)
 
         return opts,args
 
     def default_option(self, fn, optstr):
         """Make an entry in the options_table for fn, with value optstr"""
 
         if fn not in self.lsmagic():
             error("%s is not a magic function" % fn)
         self.options_table[fn] = optstr
 
 
 class MagicAlias(object):
     """An alias to another magic function.
 
     An alias is determined by its magic name and magic kind. Lookup
     is done at call time, so if the underlying magic changes the alias
     will call the new function.
 
     Use the :meth:`MagicsManager.register_alias` method or the
     `%alias_magic` magic function to create and register a new alias.
     """
     def __init__(self, shell, magic_name, magic_kind, magic_params=None):
         self.shell = shell
         self.magic_name = magic_name
         self.magic_params = magic_params
         self.magic_kind = magic_kind
 
         self.pretty_target = '%s%s' % (magic_escapes[self.magic_kind], self.magic_name)
         self.__doc__ = "Alias for `%s`." % self.pretty_target
 
         self._in_call = False
 
     def __call__(self, *args, **kwargs):
         """Call the magic alias."""
         fn = self.shell.find_magic(self.magic_name, self.magic_kind)
         if fn is None:
             raise UsageError("Magic `%s` not found." % self.pretty_target)
 
         # Protect against infinite recursion.
         if self._in_call:
             raise UsageError("Infinite recursion detected; "
                              "magic aliases cannot call themselves.")
         self._in_call = True
         try:
             if self.magic_params:
                 args_list = list(args)
                 args_list[0] = self.magic_params + " " + args[0]
                 args = tuple(args_list)
             return fn(*args, **kwargs)
         finally:
             self._in_call = False

IPython/core/magics/basic.py

@@ -1,664 +1,665
 """Implementation of basic magic functions."""
 
 
 import argparse
 from logging import error
 import io
 from pprint import pformat
 import sys
 from warnings import warn
 
 from traitlets.utils.importstring import import_item
 from IPython.core import magic_arguments, page
 from IPython.core.error import UsageError
 from IPython.core.magic import Magics, magics_class, line_magic, magic_escapes
 from IPython.utils.text import format_screen, dedent, indent
 from IPython.testing.skipdoctest import skip_doctest
 from IPython.utils.ipstruct import Struct
 
 
 class MagicsDisplay(object):
     def __init__(self, magics_manager, ignore=None):
         self.ignore = ignore if ignore else []
         self.magics_manager = magics_manager
     
     def _lsmagic(self):
         """The main implementation of the %lsmagic"""
         mesc = magic_escapes['line']
         cesc = magic_escapes['cell']
         mman = self.magics_manager
         magics = mman.lsmagic()
         out = ['Available line magics:',
                mesc + ('  '+mesc).join(sorted([m for m,v in magics['line'].items() if (v not in self.ignore)])),
                '',
                'Available cell magics:',
                cesc + ('  '+cesc).join(sorted([m for m,v in magics['cell'].items() if (v not in self.ignore)])),
                '',
                mman.auto_status()]
         return '\n'.join(out)
 
     def _repr_pretty_(self, p, cycle):
         p.text(self._lsmagic())
     
     def __str__(self):
         return self._lsmagic()
     
     def _jsonable(self):
         """turn magics dict into jsonable dict of the same structure
         
         replaces object instances with their class names as strings
         """
         magic_dict = {}
         mman = self.magics_manager
         magics = mman.lsmagic()
         for key, subdict in magics.items():
             d = {}
             magic_dict[key] = d
             for name, obj in subdict.items():
                 try:
                     classname = obj.__self__.__class__.__name__
                 except AttributeError:
                     classname = 'Other'
                 
                 d[name] = classname
         return magic_dict
         
     def _repr_json_(self):
         return self._jsonable()
 
 
 @magics_class
 class BasicMagics(Magics):
     """Magics that provide central IPython functionality.
 
     These are various magics that don't fit into specific categories but that
     are all part of the base 'IPython experience'."""
 
+    @skip_doctest
     @magic_arguments.magic_arguments()
     @magic_arguments.argument(
         '-l', '--line', action='store_true',
         help="""Create a line magic alias."""
     )
     @magic_arguments.argument(
         '-c', '--cell', action='store_true',
         help="""Create a cell magic alias."""
     )
     @magic_arguments.argument(
         'name',
         help="""Name of the magic to be created."""
     )
     @magic_arguments.argument(
         'target',
         help="""Name of the existing line or cell magic."""
     )
     @magic_arguments.argument(
         '-p', '--params', default=None,
         help="""Parameters passed to the magic function."""
     )
     @line_magic
     def alias_magic(self, line=''):
         """Create an alias for an existing line or cell magic.
 
         Examples
         --------
         ::
 
           In [1]: %alias_magic t timeit
           Created `%t` as an alias for `%timeit`.
           Created `%%t` as an alias for `%%timeit`.
 
           In [2]: %t -n1 pass
           1 loops, best of 3: 954 ns per loop
 
           In [3]: %%t -n1
              ...: pass
              ...:
           1 loops, best of 3: 954 ns per loop
 
           In [4]: %alias_magic --cell whereami pwd
           UsageError: Cell magic function `%%pwd` not found.
           In [5]: %alias_magic --line whereami pwd
           Created `%whereami` as an alias for `%pwd`.
 
           In [6]: %whereami
           Out[6]: u'/home/testuser'
           
           In [7]: %alias_magic h history "-p -l 30" --line
           Created `%h` as an alias for `%history -l 30`.
         """
 
         args = magic_arguments.parse_argstring(self.alias_magic, line)
         shell = self.shell
         mman = self.shell.magics_manager
         escs = ''.join(magic_escapes.values())
 
         target = args.target.lstrip(escs)
         name = args.name.lstrip(escs)
 
         params = args.params
         if (params and
                 ((params.startswith('"') and params.endswith('"'))
                 or (params.startswith("'") and params.endswith("'")))):
             params = params[1:-1]
 
         # Find the requested magics.
         m_line = shell.find_magic(target, 'line')
         m_cell = shell.find_magic(target, 'cell')
         if args.line and m_line is None:
             raise UsageError('Line magic function `%s%s` not found.' %
                              (magic_escapes['line'], target))
         if args.cell and m_cell is None:
             raise UsageError('Cell magic function `%s%s` not found.' %
                              (magic_escapes['cell'], target))
 
         # If --line and --cell are not specified, default to the ones
         # that are available.
         if not args.line and not args.cell:
             if not m_line and not m_cell:
                 raise UsageError(
                     'No line or cell magic with name `%s` found.' % target
                 )
             args.line = bool(m_line)
             args.cell = bool(m_cell)
 
         params_str = "" if params is None else " " + params
 
         if args.line:
             mman.register_alias(name, target, 'line', params)
             print('Created `%s%s` as an alias for `%s%s%s`.' % (
                 magic_escapes['line'], name,
                 magic_escapes['line'], target, params_str))
 
         if args.cell:
             mman.register_alias(name, target, 'cell', params)
             print('Created `%s%s` as an alias for `%s%s%s`.' % (
                 magic_escapes['cell'], name,
                 magic_escapes['cell'], target, params_str))
 
     @line_magic
     def lsmagic(self, parameter_s=''):
         """List currently available magic functions."""
         return MagicsDisplay(self.shell.magics_manager, ignore=[])
 
     def _magic_docs(self, brief=False, rest=False):
         """Return docstrings from magic functions."""
         mman = self.shell.magics_manager
         docs = mman.lsmagic_docs(brief, missing='No documentation')
 
         if rest:
             format_string = '**%s%s**::\n\n%s\n\n'
         else:
             format_string = '%s%s:\n%s\n'
 
         return ''.join(
             [format_string % (magic_escapes['line'], fname,
                               indent(dedent(fndoc)))
              for fname, fndoc in sorted(docs['line'].items())]
             +
             [format_string % (magic_escapes['cell'], fname,
                               indent(dedent(fndoc)))
              for fname, fndoc in sorted(docs['cell'].items())]
         )
 
     @line_magic
     def magic(self, parameter_s=''):
         """Print information about the magic function system.
 
         Supported formats: -latex, -brief, -rest
         """
 
         mode = ''
         try:
             mode = parameter_s.split()[0][1:]
         except IndexError:
             pass
 
         brief = (mode == 'brief')
         rest = (mode == 'rest')
         magic_docs = self._magic_docs(brief, rest)
 
         if mode == 'latex':
             print(self.format_latex(magic_docs))
             return
         else:
             magic_docs = format_screen(magic_docs)
 
         out = ["""
 IPython's 'magic' functions
 ===========================
 
 The magic function system provides a series of functions which allow you to
 control the behavior of IPython itself, plus a lot of system-type
 features. There are two kinds of magics, line-oriented and cell-oriented.
 
 Line magics are prefixed with the % character and work much like OS
 command-line calls: they get as an argument the rest of the line, where
 arguments are passed without parentheses or quotes.  For example, this will
 time the given statement::
 
         %timeit range(1000)
 
 Cell magics are prefixed with a double %%, and they are functions that get as
 an argument not only the rest of the line, but also the lines below it in a
 separate argument.  These magics are called with two arguments: the rest of the
 call line and the body of the cell, consisting of the lines below the first.
 For example::
 
         %%timeit x = numpy.random.randn((100, 100))
         numpy.linalg.svd(x)
 
 will time the execution of the numpy svd routine, running the assignment of x
 as part of the setup phase, which is not timed.
 
 In a line-oriented client (the terminal or Qt console IPython), starting a new
 input with %% will automatically enter cell mode, and IPython will continue
 reading input until a blank line is given.  In the notebook, simply type the
 whole cell as one entity, but keep in mind that the %% escape can only be at
 the very start of the cell.
 
 NOTE: If you have 'automagic' enabled (via the command line option or with the
 %automagic function), you don't need to type in the % explicitly for line
 magics; cell magics always require an explicit '%%' escape.  By default,
 IPython ships with automagic on, so you should only rarely need the % escape.
 
 Example: typing '%cd mydir' (without the quotes) changes your working directory
 to 'mydir', if it exists.
 
 For a list of the available magic functions, use %lsmagic. For a description
 of any of them, type %magic_name?, e.g. '%cd?'.
 
 Currently the magic system has the following functions:""",
        magic_docs,
        "Summary of magic functions (from %slsmagic):" % magic_escapes['line'],
        str(self.lsmagic()),
        ]
         page.page('\n'.join(out))
 
 
     @line_magic
     def page(self, parameter_s=''):
         """Pretty print the object and display it through a pager.
 
         %page [options] OBJECT
 
         If no object is given, use _ (last output).
 
         Options:
 
           -r: page str(object), don't pretty-print it."""
 
         # After a function contributed by Olivier Aubert, slightly modified.
 
         # Process options/args
         opts, args = self.parse_options(parameter_s, 'r')
         raw = 'r' in opts
 
         oname = args and args or '_'
         info = self.shell._ofind(oname)
         if info['found']:
             txt = (raw and str or pformat)( info['obj'] )
             page.page(txt)
         else:
             print('Object `%s` not found' % oname)
 
     @line_magic
     def pprint(self, parameter_s=''):
         """Toggle pretty printing on/off."""
         ptformatter = self.shell.display_formatter.formatters['text/plain']
         ptformatter.pprint = bool(1 - ptformatter.pprint)
         print('Pretty printing has been turned',
               ['OFF','ON'][ptformatter.pprint])
 
     @line_magic
     def colors(self, parameter_s=''):
         """Switch color scheme for prompts, info system and exception handlers.
 
         Currently implemented schemes: NoColor, Linux, LightBG.
 
         Color scheme names are not case-sensitive.
 
         Examples
         --------
         To get a plain black and white terminal::
 
           %colors nocolor
         """
         def color_switch_err(name):
             warn('Error changing %s color schemes.\n%s' %
                  (name, sys.exc_info()[1]), stacklevel=2)
 
 
         new_scheme = parameter_s.strip()
         if not new_scheme:
             raise UsageError(
                 "%colors: you must specify a color scheme. See '%colors?'")
         # local shortcut
         shell = self.shell
 
         # Set shell colour scheme
         try:
             shell.colors = new_scheme
             shell.refresh_style()
         except:
             color_switch_err('shell')
 
         # Set exception colors
         try:
             shell.InteractiveTB.set_colors(scheme = new_scheme)
             shell.SyntaxTB.set_colors(scheme = new_scheme)
         except:
             color_switch_err('exception')
 
         # Set info (for 'object?') colors
         if shell.color_info:
             try:
                 shell.inspector.set_active_scheme(new_scheme)
             except:
                 color_switch_err('object inspector')
         else:
             shell.inspector.set_active_scheme('NoColor')
 
     @line_magic
     def xmode(self, parameter_s=''):
         """Switch modes for the exception handlers.
 
         Valid modes: Plain, Context, Verbose, and Minimal.
 
         If called without arguments, acts as a toggle.
 
         When in verbose mode the value --show (and --hide) 
         will respectively show (or hide) frames with ``__tracebackhide__ =
         True`` value set.
         """
 
         def xmode_switch_err(name):
             warn('Error changing %s exception modes.\n%s' %
                  (name,sys.exc_info()[1]))
 
         shell = self.shell
         if parameter_s.strip() == "--show":
             shell.InteractiveTB.skip_hidden = False
             return
         if parameter_s.strip() == "--hide":
             shell.InteractiveTB.skip_hidden = True
             return
 
         new_mode = parameter_s.strip().capitalize()
         try:
             shell.InteractiveTB.set_mode(mode=new_mode)
             print('Exception reporting mode:',shell.InteractiveTB.mode)
         except:
             xmode_switch_err('user')
 
     @line_magic
     def quickref(self, arg):
         """ Show a quick reference sheet """
         from IPython.core.usage import quick_reference
         qr = quick_reference + self._magic_docs(brief=True)
         page.page(qr)
 
     @line_magic
     def doctest_mode(self, parameter_s=''):
         """Toggle doctest mode on and off.
 
         This mode is intended to make IPython behave as much as possible like a
         plain Python shell, from the perspective of how its prompts, exceptions
         and output look.  This makes it easy to copy and paste parts of a
         session into doctests.  It does so by:
 
         - Changing the prompts to the classic ``>>>`` ones.
         - Changing the exception reporting mode to 'Plain'.
         - Disabling pretty-printing of output.
 
         Note that IPython also supports the pasting of code snippets that have
         leading '>>>' and '...' prompts in them.  This means that you can paste
         doctests from files or docstrings (even if they have leading
         whitespace), and the code will execute correctly.  You can then use
         '%history -t' to see the translated history; this will give you the
         input after removal of all the leading prompts and whitespace, which
         can be pasted back into an editor.
 
         With these features, you can switch into this mode easily whenever you
         need to do testing and changes to doctests, without having to leave
         your existing IPython session.
         """
 
         # Shorthands
         shell = self.shell
         meta = shell.meta
         disp_formatter = self.shell.display_formatter
         ptformatter = disp_formatter.formatters['text/plain']
         # dstore is a data store kept in the instance metadata bag to track any
         # changes we make, so we can undo them later.
         dstore = meta.setdefault('doctest_mode',Struct())
         save_dstore = dstore.setdefault
 
         # save a few values we'll need to recover later
         mode = save_dstore('mode',False)
         save_dstore('rc_pprint',ptformatter.pprint)
         save_dstore('xmode',shell.InteractiveTB.mode)
         save_dstore('rc_separate_out',shell.separate_out)
         save_dstore('rc_separate_out2',shell.separate_out2)
         save_dstore('rc_separate_in',shell.separate_in)
         save_dstore('rc_active_types',disp_formatter.active_types)
 
         if not mode:
             # turn on
 
             # Prompt separators like plain python
             shell.separate_in = ''
             shell.separate_out = ''
             shell.separate_out2 = ''
 
 
             ptformatter.pprint = False
             disp_formatter.active_types = ['text/plain']
 
             shell.magic('xmode Plain')
         else:
             # turn off
             shell.separate_in = dstore.rc_separate_in
 
             shell.separate_out = dstore.rc_separate_out
             shell.separate_out2 = dstore.rc_separate_out2
 
             ptformatter.pprint = dstore.rc_pprint
             disp_formatter.active_types = dstore.rc_active_types
 
             shell.magic('xmode ' + dstore.xmode)
 
         # mode here is the state before we switch; switch_doctest_mode takes
         # the mode we're switching to.
         shell.switch_doctest_mode(not mode)
 
         # Store new mode and inform
         dstore.mode = bool(not mode)
         mode_label = ['OFF','ON'][dstore.mode]
         print('Doctest mode is:', mode_label)
 
     @line_magic
     def gui(self, parameter_s=''):
         """Enable or disable IPython GUI event loop integration.
 
         %gui [GUINAME]
 
         This magic replaces IPython's threaded shells that were activated
         using the (pylab/wthread/etc.) command line flags.  GUI toolkits
         can now be enabled at runtime and keyboard
         interrupts should work without any problems.  The following toolkits
         are supported:  wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
 
             %gui wx      # enable wxPython event loop integration
             %gui qt4|qt  # enable PyQt4 event loop integration
             %gui qt5     # enable PyQt5 event loop integration
             %gui gtk     # enable PyGTK event loop integration
             %gui gtk3    # enable Gtk3 event loop integration
             %gui gtk4    # enable Gtk4 event loop integration
             %gui tk      # enable Tk event loop integration
             %gui osx     # enable Cocoa event loop integration
                          # (requires %matplotlib 1.1)
             %gui         # disable all event loop integration
 
         WARNING:  after any of these has been called you can simply create
         an application object, but DO NOT start the event loop yourself, as
         we have already handled that.
         """
         opts, arg = self.parse_options(parameter_s, '')
         if arg=='': arg = None
         try:
             return self.shell.enable_gui(arg)
         except Exception as e:
             # print simple error message, rather than traceback if we can't
             # hook up the GUI
             error(str(e))
 
     @skip_doctest
     @line_magic
     def precision(self, s=''):
         """Set floating point precision for pretty printing.
 
         Can set either integer precision or a format string.
 
         If numpy has been imported and precision is an int,
         numpy display precision will also be set, via ``numpy.set_printoptions``.
 
         If no argument is given, defaults will be restored.
 
         Examples
         --------
         ::
 
             In [1]: from math import pi
 
             In [2]: %precision 3
             Out[2]: u'%.3f'
 
             In [3]: pi
             Out[3]: 3.142
 
             In [4]: %precision %i
             Out[4]: u'%i'
 
             In [5]: pi
             Out[5]: 3
 
             In [6]: %precision %e
             Out[6]: u'%e'
 
             In [7]: pi**10
             Out[7]: 9.364805e+04
 
             In [8]: %precision
             Out[8]: u'%r'
 
             In [9]: pi**10
             Out[9]: 93648.047476082982
         """
         ptformatter = self.shell.display_formatter.formatters['text/plain']
         ptformatter.float_precision = s
         return ptformatter.float_format
 
     @magic_arguments.magic_arguments()
     @magic_arguments.argument(
         '-e', '--export', action='store_true', default=False,
         help=argparse.SUPPRESS
     )
     @magic_arguments.argument(
         'filename', type=str,
         help='Notebook name or filename'
     )
     @line_magic
     def notebook(self, s):
         """Export and convert IPython notebooks.
 
         This function can export the current IPython history to a notebook file.
         For example, to export the history to "foo.ipynb" do "%notebook foo.ipynb".
 
         The -e or --export flag is deprecated in IPython 5.2, and will be
         removed in the future.
         """
         args = magic_arguments.parse_argstring(self.notebook, s)
 
         from nbformat import write, v4
 
         cells = []
         hist = list(self.shell.history_manager.get_range())
         if(len(hist)<=1):
             raise ValueError('History is empty, cannot export')
         for session, execution_count, source in hist[:-1]:
             cells.append(v4.new_code_cell(
                 execution_count=execution_count,
                 source=source
             ))
         nb = v4.new_notebook(cells=cells)
         with io.open(args.filename, 'w', encoding='utf-8') as f:
             write(nb, f, version=4)
 
 @magics_class
 class AsyncMagics(BasicMagics):
 
     @line_magic
     def autoawait(self, parameter_s):
         """
         Allow to change the status of the autoawait option.
 
         This allow you to set a specific asynchronous code runner.
 
         If no value is passed, print the currently used asynchronous integration
         and whether it is activated.
 
         It can take a number of value evaluated in the following order:
 
         - False/false/off deactivate autoawait integration
         - True/true/on activate autoawait integration using configured default
           loop
         - asyncio/curio/trio activate autoawait integration and use integration
           with said library.
 
         - `sync` turn on the pseudo-sync integration (mostly used for
           `IPython.embed()` which does not run IPython with a real eventloop and
           deactivate running asynchronous code. Turning on Asynchronous code with
           the pseudo sync loop is undefined behavior and may lead IPython to crash.
 
         If the passed parameter does not match any of the above and is a python
         identifier, get said object from user namespace and set it as the
         runner, and activate autoawait. 
 
         If the object is a fully qualified object name, attempt to import it and
         set it as the runner, and activate autoawait.
         
         
         The exact behavior of autoawait is experimental and subject to change
         across version of IPython and Python.
         """
 
         param = parameter_s.strip()
         d = {True: "on", False: "off"}
 
         if not param:
             print("IPython autoawait is `{}`, and set to use `{}`".format(
                 d[self.shell.autoawait],
                 self.shell.loop_runner
             ))
             return None
 
         if param.lower() in ('false', 'off'):
             self.shell.autoawait = False
             return None
         if param.lower() in ('true', 'on'):
             self.shell.autoawait = True
             return None
 
         if param in self.shell.loop_runner_map:
             self.shell.loop_runner, self.shell.autoawait = self.shell.loop_runner_map[param]
             return None
 
         if param in self.shell.user_ns :
             self.shell.loop_runner = self.shell.user_ns[param]
             self.shell.autoawait = True
             return None
 
         runner = import_item(param)
 
         self.shell.loop_runner = runner
         self.shell.autoawait = True

IPython/core/magics/config.py

@@ -1,158 +1,187
 """Implementation of configuration-related magic functions.
 """
 #-----------------------------------------------------------------------------
 #  Copyright (c) 2012 The IPython Development Team.
 #
 #  Distributed under the terms of the Modified BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Stdlib
 import re
 
 # Our own packages
 from IPython.core.error import UsageError
 from IPython.core.magic import Magics, magics_class, line_magic
 from logging import error
 
 #-----------------------------------------------------------------------------
 # Magic implementation classes
 #-----------------------------------------------------------------------------
 
 reg = re.compile(r'^\w+\.\w+$')
 @magics_class
 class ConfigMagics(Magics):
 
     def __init__(self, shell):
         super(ConfigMagics, self).__init__(shell)
         self.configurables = []
 
     @line_magic
     def config(self, s):
         """configure IPython
 
             %config Class[.trait=value]
 
         This magic exposes most of the IPython config system. Any
         Configurable class should be able to be configured with the simple
         line::
 
             %config Class.trait=value
 
         Where `value` will be resolved in the user's namespace, if it is an
         expression or variable name.
 
         Examples
         --------
 
         To see what classes are available for config, pass no arguments::
 
             In [1]: %config
             Available objects for config:
-                TerminalInteractiveShell
-                HistoryManager
-                PrefilterManager
                 AliasManager
-                IPCompleter
                 DisplayFormatter
+                HistoryManager
+                IPCompleter
+                LoggingMagics
+                MagicsManager
+                OSMagics
+                PrefilterManager
+                ScriptMagics
+                TerminalInteractiveShell
 
         To view what is configurable on a given class, just pass the class
         name::
 
             In [2]: %config IPCompleter
-            IPCompleter options
-            -----------------
-            IPCompleter.omit__names=<Enum>
-                Current: 2
-                Choices: (0, 1, 2)
-                Instruct the completer to omit private method names
-                Specifically, when completing on ``object.<tab>``.
-                When 2 [default]: all names that start with '_' will be excluded.
-                When 1: all 'magic' names (``__foo__``) will be excluded.
-                When 0: nothing will be excluded.
-            IPCompleter.merge_completions=<CBool>
+            IPCompleter(Completer) options
+            ----------------------------
+            IPCompleter.backslash_combining_completions=<Bool>
+                Enable unicode completions, e.g. \\alpha<tab> . Includes completion of latex
+                commands, unicode names, and expanding unicode characters back to latex
+                commands.
                 Current: True
-                Whether to merge completion results into a single list
-                If False, only the completion results from the first non-empty
-                completer will be returned.
-            IPCompleter.limit_to__all__=<CBool>
+            IPCompleter.debug=<Bool>
+                Enable debug for the Completer. Mostly print extra information for
+                experimental jedi integration.
+                Current: False
+            IPCompleter.greedy=<Bool>
+                Activate greedy completion
+                        PENDING DEPRECTION. this is now mostly taken care of with Jedi.
+                        This will enable completion on elements of lists, results of function calls, etc.,
+                        but can be unsafe because the code is actually evaluated on TAB.
                 Current: False
+            IPCompleter.jedi_compute_type_timeout=<Int>
+                Experimental: restrict time (in milliseconds) during which Jedi can compute types.
+                        Set to 0 to stop computing types. Non-zero value lower than 100ms may hurt
+                        performance by preventing jedi to build its cache.
+                Current: 400
+            IPCompleter.limit_to__all__=<Bool>
+                DEPRECATED as of version 5.0.
                 Instruct the completer to use __all__ for the completion
                 Specifically, when completing on ``object.<tab>``.
                 When True: only those names in obj.__all__ will be included.
                 When False [default]: the __all__ attribute is ignored
-            IPCompleter.greedy=<CBool>
                 Current: False
-                Activate greedy completion
-                This will enable completion on elements of lists, results of
-                function calls, etc., but can be unsafe because the code is
-                actually evaluated on TAB.
+            IPCompleter.merge_completions=<Bool>
+                Whether to merge completion results into a single list
+                        If False, only the completion results from the first non-empty
+                        completer will be returned.
+                Current: True
+            IPCompleter.omit__names=<Enum>
+                Instruct the completer to omit private method names
+                        Specifically, when completing on ``object.<tab>``.
+                        When 2 [default]: all names that start with '_' will be excluded.
+                        When 1: all 'magic' names (``__foo__``) will be excluded.
+                        When 0: nothing will be excluded.
+                Choices: any of [0, 1, 2]
+                Current: 2
+            IPCompleter.profile_completions=<Bool>
+                If True, emit profiling data for completion subsystem using cProfile.
+                Current: False
+            IPCompleter.profiler_output_dir=<Unicode>
+                Template for path at which to output profile data for completions.
+                Current: '.completion_profiles'
+            IPCompleter.use_jedi=<Bool>
+                Experimental: Use Jedi to generate autocompletions. Default to True if jedi
+                is installed.
+                Current: True
 
         but the real use is in setting values::
 
             In [3]: %config IPCompleter.greedy = True
 
         and these values are read from the user_ns if they are variables::
 
             In [4]: feeling_greedy=False
 
             In [5]: %config IPCompleter.greedy = feeling_greedy
 
         """
         from traitlets.config.loader import Config
         # some IPython objects are Configurable, but do not yet have
         # any configurable traits.  Exclude them from the effects of
         # this magic, as their presence is just noise:
         configurables = sorted(set([ c for c in self.shell.configurables
                                      if c.__class__.class_traits(config=True)
                                      ]), key=lambda x: x.__class__.__name__)
         classnames = [ c.__class__.__name__ for c in configurables ]
 
         line = s.strip()
         if not line:
             # print available configurable names
             print("Available objects for config:")
             for name in classnames:
-                print("    ", name)
+                print("   ", name)
             return
         elif line in classnames:
             # `%config TerminalInteractiveShell` will print trait info for
             # TerminalInteractiveShell
             c = configurables[classnames.index(line)]
             cls = c.__class__
             help = cls.class_get_help(c)
             # strip leading '--' from cl-args:
             help = re.sub(re.compile(r'^--', re.MULTILINE), '', help)
             print(help)
             return
         elif reg.match(line):
             cls, attr = line.split('.')
             return getattr(configurables[classnames.index(cls)],attr)
         elif '=' not in line:
             msg = "Invalid config statement: %r, "\
                   "should be `Class.trait = value`."
             
             ll = line.lower()
             for classname in classnames:
                 if ll == classname.lower():
                     msg = msg + '\nDid you mean %s (note the case)?' % classname
                     break
 
             raise UsageError( msg % line)
 
         # otherwise, assume we are setting configurables.
         # leave quotes on args when splitting, because we want
         # unquoted args to eval in user_ns
         cfg = Config()
         exec("cfg."+line, self.shell.user_ns, locals())
 
         for configurable in configurables:
             try:
                 configurable.update_config(cfg)
             except Exception as e:
                 error(e)

IPython/core/magics/script.py

@@ -1,355 +1,357
 """Magic functions for running cells in various scripts."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import asyncio
 import atexit
 import errno
 import functools
 import os
 import signal
 import sys
 import time
 from contextlib import contextmanager
 from subprocess import CalledProcessError
 
 from traitlets import Dict, List, default
 
 from IPython.core import magic_arguments
 from IPython.core.magic import Magics, cell_magic, line_magic, magics_class
 from IPython.lib.backgroundjobs import BackgroundJobManager
 from IPython.utils.process import arg_split
 
 #-----------------------------------------------------------------------------
 # Magic implementation classes
 #-----------------------------------------------------------------------------
 
 def script_args(f):
     """single decorator for adding script args"""
     args = [
         magic_arguments.argument(
             '--out', type=str,
             help="""The variable in which to store stdout from the script.
             If the script is backgrounded, this will be the stdout *pipe*,
             instead of the stderr text itself and will not be auto closed.
             """
         ),
         magic_arguments.argument(
             '--err', type=str,
             help="""The variable in which to store stderr from the script.
             If the script is backgrounded, this will be the stderr *pipe*,
             instead of the stderr text itself and will not be autoclosed.
             """
         ),
         magic_arguments.argument(
             '--bg', action="store_true",
             help="""Whether to run the script in the background.
             If given, the only way to see the output of the command is
             with --out/err.
             """
         ),
         magic_arguments.argument(
             '--proc', type=str,
             help="""The variable in which to store Popen instance.
             This is used only when --bg option is given.
             """
         ),
         magic_arguments.argument(
             '--no-raise-error', action="store_false", dest='raise_error',
             help="""Whether you should raise an error message in addition to 
             a stream on stderr if you get a nonzero exit code.
             """
         )
     ]
     for arg in args:
         f = arg(f)
     return f
 
 
 @contextmanager
 def safe_watcher():
     if sys.platform == "win32":
         yield
         return
 
     from asyncio import SafeChildWatcher
 
     policy = asyncio.get_event_loop_policy()
     old_watcher = policy.get_child_watcher()
     if isinstance(old_watcher, SafeChildWatcher):
         yield
         return
 
     loop = policy.get_event_loop()
     try:
         watcher = asyncio.SafeChildWatcher()
         watcher.attach_loop(loop)
         policy.set_child_watcher(watcher)
         yield
     finally:
         watcher.close()
         policy.set_child_watcher(old_watcher)
 
 
 def dec_safe_watcher(fun):
     @functools.wraps(fun)
     def _inner(*args, **kwargs):
         with safe_watcher():
             return fun(*args, **kwargs)
 
     return _inner
 
 
 @magics_class
 class ScriptMagics(Magics):
     """Magics for talking to scripts
     
     This defines a base `%%script` cell magic for running a cell
     with a program in a subprocess, and registers a few top-level
     magics that call %%script with common interpreters.
     """
     script_magics = List(
         help="""Extra script cell magics to define
         
         This generates simple wrappers of `%%script foo` as `%%foo`.
         
         If you want to add script magics that aren't on your path,
         specify them in script_paths
         """,
     ).tag(config=True)
     @default('script_magics')
     def _script_magics_default(self):
         """default to a common list of programs"""
         
         defaults = [
             'sh',
             'bash',
             'perl',
             'ruby',
             'python',
             'python2',
             'python3',
             'pypy',
         ]
         if os.name == 'nt':
             defaults.extend([
                 'cmd',
             ])
         
         return defaults
     
     script_paths = Dict(
         help="""Dict mapping short 'ruby' names to full paths, such as '/opt/secret/bin/ruby'
         
         Only necessary for items in script_magics where the default path will not
         find the right interpreter.
         """
     ).tag(config=True)
     
     def __init__(self, shell=None):
         super(ScriptMagics, self).__init__(shell=shell)
         self._generate_script_magics()
         self.job_manager = BackgroundJobManager()
         self.bg_processes = []
         atexit.register(self.kill_bg_processes)
 
     def __del__(self):
         self.kill_bg_processes()
     
     def _generate_script_magics(self):
         cell_magics = self.magics['cell']
         for name in self.script_magics:
             cell_magics[name] = self._make_script_magic(name)
     
     def _make_script_magic(self, name):
         """make a named magic, that calls %%script with a particular program"""
         # expand to explicit path if necessary:
         script = self.script_paths.get(name, name)
         
         @magic_arguments.magic_arguments()
         @script_args
         def named_script_magic(line, cell):
             # if line, add it as cl-flags
             if line:
                 line = "%s %s" % (script, line)
             else:
                 line = script
             return self.shebang(line, cell)
         
         # write a basic docstring:
         named_script_magic.__doc__ = \
         """%%{name} script magic
         
         Run cells with {script} in a subprocess.
         
         This is a shortcut for `%%script {script}`
         """.format(**locals())
         
         return named_script_magic
     
     @magic_arguments.magic_arguments()
     @script_args
     @cell_magic("script")
     @dec_safe_watcher
     def shebang(self, line, cell):
         """Run a cell via a shell command
         
         The `%%script` line is like the #! line of script,
         specifying a program (bash, perl, ruby, etc.) with which to run.
         
         The rest of the cell is run by that program.
         
         Examples
         --------
         ::
         
             In [1]: %%script bash
                ...: for i in 1 2 3; do
                ...:   echo $i
                ...: done
             1
             2
             3
         """
 
         async def _handle_stream(stream, stream_arg, file_object):
             while True:
                 line = (await stream.readline()).decode("utf8")
                 if not line:
                     break
                 if stream_arg:
                     self.shell.user_ns[stream_arg] = line
                 else:
                     file_object.write(line)
                     file_object.flush()
 
         async def _stream_communicate(process, cell):
             process.stdin.write(cell)
             process.stdin.close()
             stdout_task = asyncio.create_task(
                 _handle_stream(process.stdout, args.out, sys.stdout)
             )
             stderr_task = asyncio.create_task(
                 _handle_stream(process.stderr, args.err, sys.stderr)
             )
             await asyncio.wait([stdout_task, stderr_task])
             await process.wait()
 
         if sys.platform.startswith("win"):
             asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
         loop = asyncio.get_event_loop_policy().get_event_loop()
         argv = arg_split(line, posix=not sys.platform.startswith("win"))
         args, cmd = self.shebang.parser.parse_known_args(argv)
         try:
             p = loop.run_until_complete(
                 asyncio.create_subprocess_exec(
                     *cmd,
                     stdout=asyncio.subprocess.PIPE,
                     stderr=asyncio.subprocess.PIPE,
                     stdin=asyncio.subprocess.PIPE,
                 )
             )
         except OSError as e:
             if e.errno == errno.ENOENT:
                 print("Couldn't find program: %r" % cmd[0])
                 return
             else:
                 raise
         
         if not cell.endswith('\n'):
             cell += '\n'
         cell = cell.encode('utf8', 'replace')
         if args.bg:
             self.bg_processes.append(p)
             self._gc_bg_processes()
             to_close = []
             if args.out:
                 self.shell.user_ns[args.out] = p.stdout
             else:
                 to_close.append(p.stdout)
             if args.err:
                 self.shell.user_ns[args.err] = p.stderr
             else:
                 to_close.append(p.stderr)
             self.job_manager.new(self._run_script, p, cell, to_close, daemon=True)
             if args.proc:
                 self.shell.user_ns[args.proc] = p
             return
         
         try:
             loop.run_until_complete(_stream_communicate(p, cell))
         except KeyboardInterrupt:
             try:
                 p.send_signal(signal.SIGINT)
                 time.sleep(0.1)
                 if p.returncode is not None:
                     print("Process is interrupted.")
                     return
                 p.terminate()
                 time.sleep(0.1)
                 if p.returncode is not None:
                     print("Process is terminated.")
                     return
                 p.kill()
                 print("Process is killed.")
             except OSError:
                 pass
             except Exception as e:
                 print("Error while terminating subprocess (pid=%i): %s" % (p.pid, e))
             return
         if args.raise_error and p.returncode!=0:
             # If we get here and p.returncode is still None, we must have
             # killed it but not yet seen its return code. We don't wait for it,
             # in case it's stuck in uninterruptible sleep. -9 = SIGKILL
             rc = p.returncode or -9
             raise CalledProcessError(rc, cell)
+
+    shebang.__skip_doctest__ = os.name != "posix"
     
     def _run_script(self, p, cell, to_close):
         """callback for running the script in the background"""
         p.stdin.write(cell)
         p.stdin.close()
         for s in to_close:
             s.close()
         p.wait()
 
     @line_magic("killbgscripts")
     def killbgscripts(self, _nouse_=''):
         """Kill all BG processes started by %%script and its family."""
         self.kill_bg_processes()
         print("All background processes were killed.")
 
     def kill_bg_processes(self):
         """Kill all BG processes which are still running."""
         if not self.bg_processes:
             return
         for p in self.bg_processes:
             if p.returncode is None:
                 try:
                     p.send_signal(signal.SIGINT)
                 except:
                     pass
         time.sleep(0.1)
         self._gc_bg_processes()
         if not self.bg_processes:
             return
         for p in self.bg_processes:
             if p.returncode is None:
                 try:
                     p.terminate()
                 except:
                     pass
         time.sleep(0.1)
         self._gc_bg_processes()
         if not self.bg_processes:
             return
         for p in self.bg_processes:
             if p.returncode is None:
                 try:
                     p.kill()
                 except:
                     pass
         self._gc_bg_processes()
 
     def _gc_bg_processes(self):
         self.bg_processes = [p for p in self.bg_processes if p.returncode is None]

IPython/core/tests/test_interactiveshell.py

@@ -1,1072 +1,1082
 # -*- coding: utf-8 -*-
 """Tests for the key interactiveshell module.
 
 Historically the main classes in interactiveshell have been under-tested.  This
 module should grow as many single-method tests as possible to trap many of the
 recurring bugs we seem to encounter with high-level interaction.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import asyncio
 import ast
 import os
 import signal
 import shutil
 import sys
 import tempfile
 import unittest
 from unittest import mock
 
 from os.path import join
 
 from IPython.core.error import InputRejected
 from IPython.core.inputtransformer import InputTransformer
 from IPython.core import interactiveshell
 from IPython.testing.decorators import (
     skipif, skip_win32, onlyif_unicode_paths, onlyif_cmds_exist,
 )
 from IPython.testing import tools as tt
 from IPython.utils.process import find_cmd
 
 #-----------------------------------------------------------------------------
 # Globals
 #-----------------------------------------------------------------------------
 # This is used by every single test, no point repeating it ad nauseam
 
 #-----------------------------------------------------------------------------
 # Tests
 #-----------------------------------------------------------------------------
 
 class DerivedInterrupt(KeyboardInterrupt):
     pass
 
 class InteractiveShellTestCase(unittest.TestCase):
     def test_naked_string_cells(self):
         """Test that cells with only naked strings are fully executed"""
         # First, single-line inputs
         ip.run_cell('"a"\n')
         self.assertEqual(ip.user_ns['_'], 'a')
         # And also multi-line cells
         ip.run_cell('"""a\nb"""\n')
         self.assertEqual(ip.user_ns['_'], 'a\nb')
 
     def test_run_empty_cell(self):
         """Just make sure we don't get a horrible error with a blank
         cell of input. Yes, I did overlook that."""
         old_xc = ip.execution_count
         res = ip.run_cell('')
         self.assertEqual(ip.execution_count, old_xc)
         self.assertEqual(res.execution_count, None)
 
     def test_run_cell_multiline(self):
         """Multi-block, multi-line cells must execute correctly.
         """
         src = '\n'.join(["x=1",
                          "y=2",
                          "if 1:",
                          "    x += 1",
                          "    y += 1",])
         res = ip.run_cell(src)
         self.assertEqual(ip.user_ns['x'], 2)
         self.assertEqual(ip.user_ns['y'], 3)
         self.assertEqual(res.success, True)
         self.assertEqual(res.result, None)
 
     def test_multiline_string_cells(self):
         "Code sprinkled with multiline strings should execute (GH-306)"
         ip.run_cell('tmp=0')
         self.assertEqual(ip.user_ns['tmp'], 0)
         res = ip.run_cell('tmp=1;"""a\nb"""\n')
         self.assertEqual(ip.user_ns['tmp'], 1)
         self.assertEqual(res.success, True)
         self.assertEqual(res.result, "a\nb")
 
     def test_dont_cache_with_semicolon(self):
         "Ending a line with semicolon should not cache the returned object (GH-307)"
         oldlen = len(ip.user_ns['Out'])
         for cell in ['1;', '1;1;']:
             res = ip.run_cell(cell, store_history=True)
             newlen = len(ip.user_ns['Out'])
             self.assertEqual(oldlen, newlen)
             self.assertIsNone(res.result)
         i = 0
         #also test the default caching behavior
         for cell in ['1', '1;1']:
             ip.run_cell(cell, store_history=True)
             newlen = len(ip.user_ns['Out'])
             i += 1
             self.assertEqual(oldlen+i, newlen)
 
     def test_syntax_error(self):
         res = ip.run_cell("raise = 3")
         self.assertIsInstance(res.error_before_exec, SyntaxError)
 
     def test_In_variable(self):
         "Verify that In variable grows with user input (GH-284)"
         oldlen = len(ip.user_ns['In'])
         ip.run_cell('1;', store_history=True)
         newlen = len(ip.user_ns['In'])
         self.assertEqual(oldlen+1, newlen)
         self.assertEqual(ip.user_ns['In'][-1],'1;')
         
     def test_magic_names_in_string(self):
         ip.run_cell('a = """\n%exit\n"""')
         self.assertEqual(ip.user_ns['a'], '\n%exit\n')
     
     def test_trailing_newline(self):
         """test that running !(command) does not raise a SyntaxError"""
         ip.run_cell('!(true)\n', False)
         ip.run_cell('!(true)\n\n\n', False)
     
     def test_gh_597(self):
         """Pretty-printing lists of objects with non-ascii reprs may cause
         problems."""
         class Spam(object):
             def __repr__(self):
                 return "\xe9"*50
         import IPython.core.formatters
         f = IPython.core.formatters.PlainTextFormatter()
         f([Spam(),Spam()])
     
 
     def test_future_flags(self):
         """Check that future flags are used for parsing code (gh-777)"""
         ip.run_cell('from __future__ import barry_as_FLUFL')
         try:
             ip.run_cell('prfunc_return_val = 1 <> 2')
             assert 'prfunc_return_val' in ip.user_ns
         finally:
             # Reset compiler flags so we don't mess up other tests.
             ip.compile.reset_compiler_flags()
 
     def test_can_pickle(self):
         "Can we pickle objects defined interactively (GH-29)"
         ip = get_ipython()
         ip.reset()
         ip.run_cell(("class Mylist(list):\n"
                      "    def __init__(self,x=[]):\n"
                      "        list.__init__(self,x)"))
         ip.run_cell("w=Mylist([1,2,3])")
         
         from pickle import dumps
         
         # We need to swap in our main module - this is only necessary
         # inside the test framework, because IPython puts the interactive module
         # in place (but the test framework undoes this).
         _main = sys.modules['__main__']
         sys.modules['__main__'] = ip.user_module
         try:
             res = dumps(ip.user_ns["w"])
         finally:
             sys.modules['__main__'] = _main
         self.assertTrue(isinstance(res, bytes))
         
     def test_global_ns(self):
         "Code in functions must be able to access variables outside them."
         ip = get_ipython()
         ip.run_cell("a = 10")
         ip.run_cell(("def f(x):\n"
                      "    return x + a"))
         ip.run_cell("b = f(12)")
         self.assertEqual(ip.user_ns["b"], 22)
 
     def test_bad_custom_tb(self):
         """Check that InteractiveShell is protected from bad custom exception handlers"""
         ip.set_custom_exc((IOError,), lambda etype,value,tb: 1/0)
         self.assertEqual(ip.custom_exceptions, (IOError,))
         with tt.AssertPrints("Custom TB Handler failed", channel='stderr'):
             ip.run_cell(u'raise IOError("foo")')
         self.assertEqual(ip.custom_exceptions, ())
 
     def test_bad_custom_tb_return(self):
         """Check that InteractiveShell is protected from bad return types in custom exception handlers"""
         ip.set_custom_exc((NameError,),lambda etype,value,tb, tb_offset=None: 1)
         self.assertEqual(ip.custom_exceptions, (NameError,))
         with tt.AssertPrints("Custom TB Handler failed", channel='stderr'):
             ip.run_cell(u'a=abracadabra')
         self.assertEqual(ip.custom_exceptions, ())
 
     def test_drop_by_id(self):
         myvars = {"a":object(), "b":object(), "c": object()}
         ip.push(myvars, interactive=False)
         for name in myvars:
             assert name in ip.user_ns, name
             assert name in ip.user_ns_hidden, name
         ip.user_ns['b'] = 12
         ip.drop_by_id(myvars)
         for name in ["a", "c"]:
             assert name not in ip.user_ns, name
             assert name not in ip.user_ns_hidden, name
         assert ip.user_ns['b'] == 12
         ip.reset()
 
     def test_var_expand(self):
         ip.user_ns['f'] = u'Ca\xf1o'
         self.assertEqual(ip.var_expand(u'echo $f'), u'echo Ca\xf1o')
         self.assertEqual(ip.var_expand(u'echo {f}'), u'echo Ca\xf1o')
         self.assertEqual(ip.var_expand(u'echo {f[:-1]}'), u'echo Ca\xf1')
         self.assertEqual(ip.var_expand(u'echo {1*2}'), u'echo 2')
         
         self.assertEqual(ip.var_expand(u"grep x | awk '{print $1}'"), u"grep x | awk '{print $1}'")
 
         ip.user_ns['f'] = b'Ca\xc3\xb1o'
         # This should not raise any exception:
         ip.var_expand(u'echo $f')
    
     def test_var_expand_local(self):
         """Test local variable expansion in !system and %magic calls"""
         # !system
         ip.run_cell(
             "def test():\n"
             '    lvar = "ttt"\n'
             "    ret = !echo {lvar}\n"
             "    return ret[0]\n"
         )
         res = ip.user_ns["test"]()
         self.assertIn("ttt", res)
 
         # %magic
         ip.run_cell(
             "def makemacro():\n"
             '    macroname = "macro_var_expand_locals"\n'
             "    %macro {macroname} codestr\n"
         )
         ip.user_ns["codestr"] = "str(12)"
         ip.run_cell("makemacro()")
         self.assertIn("macro_var_expand_locals", ip.user_ns)
 
     def test_var_expand_self(self):
         """Test variable expansion with the name 'self', which was failing.
         
         See https://github.com/ipython/ipython/issues/1878#issuecomment-7698218
         """
         ip.run_cell(
             "class cTest:\n"
             '  classvar="see me"\n'
             "  def test(self):\n"
             "    res = !echo Variable: {self.classvar}\n"
             "    return res[0]\n"
         )
         self.assertIn("see me", ip.user_ns["cTest"]().test())
 
     def test_bad_var_expand(self):
         """var_expand on invalid formats shouldn't raise"""
         # SyntaxError
         self.assertEqual(ip.var_expand(u"{'a':5}"), u"{'a':5}")
         # NameError
         self.assertEqual(ip.var_expand(u"{asdf}"), u"{asdf}")
         # ZeroDivisionError
         self.assertEqual(ip.var_expand(u"{1/0}"), u"{1/0}")
     
     def test_silent_postexec(self):
         """run_cell(silent=True) doesn't invoke pre/post_run_cell callbacks"""
         pre_explicit = mock.Mock()
         pre_always = mock.Mock()
         post_explicit = mock.Mock()
         post_always = mock.Mock()
         all_mocks = [pre_explicit, pre_always, post_explicit, post_always]
         
         ip.events.register('pre_run_cell', pre_explicit)
         ip.events.register('pre_execute', pre_always)
         ip.events.register('post_run_cell', post_explicit)
         ip.events.register('post_execute', post_always)
         
         try:
             ip.run_cell("1", silent=True)
             assert pre_always.called
             assert not pre_explicit.called
             assert post_always.called
             assert not post_explicit.called
             # double-check that non-silent exec did what we expected
             # silent to avoid
             ip.run_cell("1")
             assert pre_explicit.called
             assert post_explicit.called
             info, = pre_explicit.call_args[0]
             result, = post_explicit.call_args[0]
             self.assertEqual(info, result.info)
             # check that post hooks are always called
             [m.reset_mock() for m in all_mocks]
             ip.run_cell("syntax error")
             assert pre_always.called
             assert pre_explicit.called
             assert post_always.called
             assert post_explicit.called
             info, = pre_explicit.call_args[0]
             result, = post_explicit.call_args[0]
             self.assertEqual(info, result.info)
         finally:
             # remove post-exec
             ip.events.unregister('pre_run_cell', pre_explicit)
             ip.events.unregister('pre_execute', pre_always)
             ip.events.unregister('post_run_cell', post_explicit)
             ip.events.unregister('post_execute', post_always)
     
     def test_silent_noadvance(self):
         """run_cell(silent=True) doesn't advance execution_count"""
         ec = ip.execution_count
         # silent should force store_history=False
         ip.run_cell("1", store_history=True, silent=True)
         
         self.assertEqual(ec, ip.execution_count)
         # double-check that non-silent exec did what we expected
         # silent to avoid
         ip.run_cell("1", store_history=True)
         self.assertEqual(ec+1, ip.execution_count)
     
     def test_silent_nodisplayhook(self):
         """run_cell(silent=True) doesn't trigger displayhook"""
         d = dict(called=False)
         
         trap = ip.display_trap
         save_hook = trap.hook
         
         def failing_hook(*args, **kwargs):
             d['called'] = True
         
         try:
             trap.hook = failing_hook
             res = ip.run_cell("1", silent=True)
             self.assertFalse(d['called'])
             self.assertIsNone(res.result)
             # double-check that non-silent exec did what we expected
             # silent to avoid
             ip.run_cell("1")
             self.assertTrue(d['called'])
         finally:
             trap.hook = save_hook
 
     def test_ofind_line_magic(self):
         from IPython.core.magic import register_line_magic
         
         @register_line_magic
         def lmagic(line):
             "A line magic"
 
         # Get info on line magic
-        lfind = ip._ofind('lmagic')
-        info = dict(found=True, isalias=False, ismagic=True,
-                    namespace = 'IPython internal', obj= lmagic.__wrapped__,
-                    parent = None)
+        lfind = ip._ofind("lmagic")
+        info = dict(
+            found=True,
+            isalias=False,
+            ismagic=True,
+            namespace="IPython internal",
+            obj=lmagic,
+            parent=None,
+        )
         self.assertEqual(lfind, info)
         
     def test_ofind_cell_magic(self):
         from IPython.core.magic import register_cell_magic
         
         @register_cell_magic
         def cmagic(line, cell):
             "A cell magic"
 
         # Get info on cell magic
-        find = ip._ofind('cmagic')
-        info = dict(found=True, isalias=False, ismagic=True,
-                    namespace = 'IPython internal', obj= cmagic.__wrapped__,
-                    parent = None)
+        find = ip._ofind("cmagic")
+        info = dict(
+            found=True,
+            isalias=False,
+            ismagic=True,
+            namespace="IPython internal",
+            obj=cmagic,
+            parent=None,
+        )
         self.assertEqual(find, info)
 
     def test_ofind_property_with_error(self):
         class A(object):
             @property
             def foo(self):
                 raise NotImplementedError()
         a = A()
 
         found = ip._ofind('a.foo', [('locals', locals())])
         info = dict(found=True, isalias=False, ismagic=False,
                     namespace='locals', obj=A.foo, parent=a)
         self.assertEqual(found, info)
 
     def test_ofind_multiple_attribute_lookups(self):
         class A(object):
             @property
             def foo(self):
                 raise NotImplementedError()
 
         a = A()
         a.a = A()
         a.a.a = A()
 
         found = ip._ofind('a.a.a.foo', [('locals', locals())])
         info = dict(found=True, isalias=False, ismagic=False,
                     namespace='locals', obj=A.foo, parent=a.a.a)
         self.assertEqual(found, info)
 
     def test_ofind_slotted_attributes(self):
         class A(object):
             __slots__ = ['foo']
             def __init__(self):
                 self.foo = 'bar'
 
         a = A()
         found = ip._ofind('a.foo', [('locals', locals())])
         info = dict(found=True, isalias=False, ismagic=False,
                     namespace='locals', obj=a.foo, parent=a)
         self.assertEqual(found, info)
 
         found = ip._ofind('a.bar', [('locals', locals())])
         info = dict(found=False, isalias=False, ismagic=False,
                     namespace=None, obj=None, parent=a)
         self.assertEqual(found, info)
 
     def test_ofind_prefers_property_to_instance_level_attribute(self):
         class A(object):
             @property
             def foo(self):
                 return 'bar'
         a = A()
         a.__dict__["foo"] = "baz"
         self.assertEqual(a.foo, "bar")
         found = ip._ofind("a.foo", [("locals", locals())])
         self.assertIs(found["obj"], A.foo)
 
     def test_custom_syntaxerror_exception(self):
         called = []
         def my_handler(shell, etype, value, tb, tb_offset=None):
             called.append(etype)
             shell.showtraceback((etype, value, tb), tb_offset=tb_offset)
 
         ip.set_custom_exc((SyntaxError,), my_handler)
         try:
             ip.run_cell("1f")
             # Check that this was called, and only once.
             self.assertEqual(called, [SyntaxError])
         finally:
             # Reset the custom exception hook
             ip.set_custom_exc((), None)
 
     def test_custom_exception(self):
         called = []
         def my_handler(shell, etype, value, tb, tb_offset=None):
             called.append(etype)
             shell.showtraceback((etype, value, tb), tb_offset=tb_offset)
         
         ip.set_custom_exc((ValueError,), my_handler)
         try:
             res = ip.run_cell("raise ValueError('test')")
             # Check that this was called, and only once.
             self.assertEqual(called, [ValueError])
             # Check that the error is on the result object
             self.assertIsInstance(res.error_in_exec, ValueError)
         finally:
             # Reset the custom exception hook
             ip.set_custom_exc((), None)
     
     @mock.patch("builtins.print")
     def test_showtraceback_with_surrogates(self, mocked_print):
         values = []
 
         def mock_print_func(value, sep=" ", end="\n", file=sys.stdout, flush=False):
             values.append(value)
             if value == chr(0xD8FF):
                 raise UnicodeEncodeError("utf-8", chr(0xD8FF), 0, 1, "")
 
         # mock builtins.print
         mocked_print.side_effect = mock_print_func
 
         # ip._showtraceback() is replaced in globalipapp.py.
         # Call original method to test.
         interactiveshell.InteractiveShell._showtraceback(ip, None, None, chr(0xD8FF))
 
         self.assertEqual(mocked_print.call_count, 2)
         self.assertEqual(values, [chr(0xD8FF), "\\ud8ff"])
 
     def test_mktempfile(self):
         filename = ip.mktempfile()
         # Check that we can open the file again on Windows
         with open(filename, 'w') as f:
             f.write('abc')
 
         filename = ip.mktempfile(data='blah')
         with open(filename, 'r') as f:
             self.assertEqual(f.read(), 'blah')
 
     def test_new_main_mod(self):
         # Smoketest to check that this accepts a unicode module name
         name = u'jiefmw'
         mod = ip.new_main_mod(u'%s.py' % name, name)
         self.assertEqual(mod.__name__, name)
 
     def test_get_exception_only(self):
         try:
             raise KeyboardInterrupt
         except KeyboardInterrupt:
             msg = ip.get_exception_only()
         self.assertEqual(msg, 'KeyboardInterrupt\n')
 
         try:
             raise DerivedInterrupt("foo")
         except KeyboardInterrupt:
             msg = ip.get_exception_only()
         self.assertEqual(msg, 'IPython.core.tests.test_interactiveshell.DerivedInterrupt: foo\n')
 
     def test_inspect_text(self):
         ip.run_cell('a = 5')
         text = ip.object_inspect_text('a')
         self.assertIsInstance(text, str)
 
     def test_last_execution_result(self):
         """ Check that last execution result gets set correctly (GH-10702) """
         result = ip.run_cell('a = 5; a')
         self.assertTrue(ip.last_execution_succeeded)
         self.assertEqual(ip.last_execution_result.result, 5)
 
         result = ip.run_cell('a = x_invalid_id_x')
         self.assertFalse(ip.last_execution_succeeded)
         self.assertFalse(ip.last_execution_result.success)
         self.assertIsInstance(ip.last_execution_result.error_in_exec, NameError)
 
     def test_reset_aliasing(self):
         """ Check that standard posix aliases work after %reset. """
         if os.name != 'posix':
             return
 
         ip.reset()
         for cmd in ('clear', 'more', 'less', 'man'):
             res = ip.run_cell('%' + cmd)
             self.assertEqual(res.success, True)
 
 
 class TestSafeExecfileNonAsciiPath(unittest.TestCase):
 
     @onlyif_unicode_paths
     def setUp(self):
         self.BASETESTDIR = tempfile.mkdtemp()
         self.TESTDIR = join(self.BASETESTDIR, u"åäö")
         os.mkdir(self.TESTDIR)
         with open(join(self.TESTDIR, u"åäötestscript.py"), "w") as sfile:
             sfile.write("pass\n")
         self.oldpath = os.getcwd()
         os.chdir(self.TESTDIR)
         self.fname = u"åäötestscript.py"
 
     def tearDown(self):
         os.chdir(self.oldpath)
         shutil.rmtree(self.BASETESTDIR)
 
     @onlyif_unicode_paths
     def test_1(self):
         """Test safe_execfile with non-ascii path
         """
         ip.safe_execfile(self.fname, {}, raise_exceptions=True)
 
 class ExitCodeChecks(tt.TempFileMixin):
 
     def setUp(self):
         self.system = ip.system_raw
 
     def test_exit_code_ok(self):
         self.system('exit 0')
         self.assertEqual(ip.user_ns['_exit_code'], 0)
 
     def test_exit_code_error(self):
         self.system('exit 1')
         self.assertEqual(ip.user_ns['_exit_code'], 1)
     
     @skipif(not hasattr(signal, 'SIGALRM'))
     def test_exit_code_signal(self):
         self.mktmp("import signal, time\n"
                    "signal.setitimer(signal.ITIMER_REAL, 0.1)\n"
                    "time.sleep(1)\n")
         self.system("%s %s" % (sys.executable, self.fname))
         self.assertEqual(ip.user_ns['_exit_code'], -signal.SIGALRM)
     
     @onlyif_cmds_exist("csh")
     def test_exit_code_signal_csh(self):
         SHELL = os.environ.get('SHELL', None)
         os.environ['SHELL'] = find_cmd("csh")
         try:
             self.test_exit_code_signal()
         finally:
             if SHELL is not None:
                 os.environ['SHELL'] = SHELL
             else:
                 del os.environ['SHELL']
 
 
 class TestSystemRaw(ExitCodeChecks):
 
     def setUp(self):
         super().setUp()
         self.system = ip.system_raw
 
     @onlyif_unicode_paths
     def test_1(self):
         """Test system_raw with non-ascii cmd
         """
         cmd = u'''python -c "'åäö'"   '''
         ip.system_raw(cmd)
 
     @mock.patch('subprocess.call', side_effect=KeyboardInterrupt)
     @mock.patch('os.system', side_effect=KeyboardInterrupt)
     def test_control_c(self, *mocks):
         try:
             self.system("sleep 1 # wont happen")
         except KeyboardInterrupt:
             self.fail(
                 "system call should intercept "
                 "keyboard interrupt from subprocess.call"
             )
         self.assertEqual(ip.user_ns["_exit_code"], -signal.SIGINT)
 
     def test_magic_warnings(self):
         for magic_cmd in ("ls", "pip", "conda", "cd"):
             with self.assertWarnsRegex(Warning, "You executed the system command"):
                 ip.system_raw(magic_cmd)
 
 # TODO: Exit codes are currently ignored on Windows.
 class TestSystemPipedExitCode(ExitCodeChecks):
 
     def setUp(self):
         super().setUp()
         self.system = ip.system_piped
 
     @skip_win32
     def test_exit_code_ok(self):
         ExitCodeChecks.test_exit_code_ok(self)
 
     @skip_win32
     def test_exit_code_error(self):
         ExitCodeChecks.test_exit_code_error(self)
 
     @skip_win32
     def test_exit_code_signal(self):
         ExitCodeChecks.test_exit_code_signal(self)
 
 class TestModules(tt.TempFileMixin):
     def test_extraneous_loads(self):
         """Test we're not loading modules on startup that we shouldn't.
         """
         self.mktmp("import sys\n"
                    "print('numpy' in sys.modules)\n"
                    "print('ipyparallel' in sys.modules)\n"
                    "print('ipykernel' in sys.modules)\n"
                    )
         out = "False\nFalse\nFalse\n"
         tt.ipexec_validate(self.fname, out)
 
 class Negator(ast.NodeTransformer):
     """Negates all number literals in an AST."""
 
     # for python 3.7 and earlier
     def visit_Num(self, node):
         node.n = -node.n
         return node
 
     # for python 3.8+
     def visit_Constant(self, node):
         if isinstance(node.value, int):
             return self.visit_Num(node)
         return node
 
 class TestAstTransform(unittest.TestCase):
     def setUp(self):
         self.negator = Negator()
         ip.ast_transformers.append(self.negator)
     
     def tearDown(self):
         ip.ast_transformers.remove(self.negator)
     
     def test_run_cell(self):
         with tt.AssertPrints('-34'):
             ip.run_cell('print (12 + 22)')
         
         # A named reference to a number shouldn't be transformed.
         ip.user_ns['n'] = 55
         with tt.AssertNotPrints('-55'):
             ip.run_cell('print (n)')
     
     def test_timeit(self):
         called = set()
         def f(x):
             called.add(x)
         ip.push({'f':f})
         
         with tt.AssertPrints("std. dev. of"):
             ip.run_line_magic("timeit", "-n1 f(1)")
         self.assertEqual(called, {-1})
         called.clear()
 
         with tt.AssertPrints("std. dev. of"):
             ip.run_cell_magic("timeit", "-n1 f(2)", "f(3)")
         self.assertEqual(called, {-2, -3})
     
     def test_time(self):
         called = []
         def f(x):
             called.append(x)
         ip.push({'f':f})
         
         # Test with an expression
         with tt.AssertPrints("Wall time: "):
             ip.run_line_magic("time", "f(5+9)")
         self.assertEqual(called, [-14])
         called[:] = []
         
         # Test with a statement (different code path)
         with tt.AssertPrints("Wall time: "):
             ip.run_line_magic("time", "a = f(-3 + -2)")
         self.assertEqual(called, [5])
     
     def test_macro(self):
         ip.push({'a':10})
         # The AST transformation makes this do a+=-1
         ip.define_macro("amacro", "a+=1\nprint(a)")
         
         with tt.AssertPrints("9"):
             ip.run_cell("amacro")
         with tt.AssertPrints("8"):
             ip.run_cell("amacro")
 
 class TestMiscTransform(unittest.TestCase):
 
 
     def test_transform_only_once(self):
         cleanup = 0
         line_t = 0
         def count_cleanup(lines):
             nonlocal cleanup
             cleanup += 1
             return lines
 
         def count_line_t(lines):
             nonlocal line_t
             line_t += 1
             return lines
 
         ip.input_transformer_manager.cleanup_transforms.append(count_cleanup)
         ip.input_transformer_manager.line_transforms.append(count_line_t)
 
         ip.run_cell('1')
 
         assert cleanup == 1
         assert line_t == 1
 
 class IntegerWrapper(ast.NodeTransformer):
     """Wraps all integers in a call to Integer()"""
 
     # for Python 3.7 and earlier
 
     # for Python 3.7 and earlier
     def visit_Num(self, node):
         if isinstance(node.n, int):
             return ast.Call(func=ast.Name(id='Integer', ctx=ast.Load()),
                             args=[node], keywords=[])
         return node
 
     # For Python 3.8+
     def visit_Constant(self, node):
         if isinstance(node.value, int):
             return self.visit_Num(node)
         return node
 
 
 class TestAstTransform2(unittest.TestCase):
     def setUp(self):
         self.intwrapper = IntegerWrapper()
         ip.ast_transformers.append(self.intwrapper)
         
         self.calls = []
         def Integer(*args):
             self.calls.append(args)
             return args
         ip.push({"Integer": Integer})
     
     def tearDown(self):
         ip.ast_transformers.remove(self.intwrapper)
         del ip.user_ns['Integer']
     
     def test_run_cell(self):
         ip.run_cell("n = 2")
         self.assertEqual(self.calls, [(2,)])
         
         # This shouldn't throw an error
         ip.run_cell("o = 2.0")
         self.assertEqual(ip.user_ns['o'], 2.0)
     
     def test_timeit(self):
         called = set()
         def f(x):
             called.add(x)
         ip.push({'f':f})
 
         with tt.AssertPrints("std. dev. of"):
             ip.run_line_magic("timeit", "-n1 f(1)")
         self.assertEqual(called, {(1,)})
         called.clear()
 
         with tt.AssertPrints("std. dev. of"):
             ip.run_cell_magic("timeit", "-n1 f(2)", "f(3)")
         self.assertEqual(called, {(2,), (3,)})
 
 class ErrorTransformer(ast.NodeTransformer):
     """Throws an error when it sees a number."""
 
     # for Python 3.7 and earlier
     def visit_Num(self, node):
         raise ValueError("test")
 
     # for Python 3.8+
     def visit_Constant(self, node):
         if isinstance(node.value, int):
             return self.visit_Num(node)
         return node
 
 
 class TestAstTransformError(unittest.TestCase):
     def test_unregistering(self):
         err_transformer = ErrorTransformer()
         ip.ast_transformers.append(err_transformer)
         
         with self.assertWarnsRegex(UserWarning, "It will be unregistered"):
             ip.run_cell("1 + 2")
         
         # This should have been removed.
         self.assertNotIn(err_transformer, ip.ast_transformers)
 
 
 class StringRejector(ast.NodeTransformer):
     """Throws an InputRejected when it sees a string literal.
 
     Used to verify that NodeTransformers can signal that a piece of code should
     not be executed by throwing an InputRejected.
     """
     
     #for python 3.7 and earlier
     def visit_Str(self, node):
         raise InputRejected("test")
 
     # 3.8 only
     def visit_Constant(self, node):
         if isinstance(node.value, str):
             raise InputRejected("test")
         return node
 
 
 class TestAstTransformInputRejection(unittest.TestCase):
 
     def setUp(self):
         self.transformer = StringRejector()
         ip.ast_transformers.append(self.transformer)
 
     def tearDown(self):
         ip.ast_transformers.remove(self.transformer)
 
     def test_input_rejection(self):
         """Check that NodeTransformers can reject input."""
 
         expect_exception_tb = tt.AssertPrints("InputRejected: test")
         expect_no_cell_output = tt.AssertNotPrints("'unsafe'", suppress=False)
 
         # Run the same check twice to verify that the transformer is not
         # disabled after raising.
         with expect_exception_tb, expect_no_cell_output:
             ip.run_cell("'unsafe'")
 
         with expect_exception_tb, expect_no_cell_output:
             res = ip.run_cell("'unsafe'")
 
         self.assertIsInstance(res.error_before_exec, InputRejected)
 
 def test__IPYTHON__():
     # This shouldn't raise a NameError, that's all
     __IPYTHON__
 
 
 class DummyRepr(object):
     def __repr__(self):
         return "DummyRepr"
     
     def _repr_html_(self):
         return "<b>dummy</b>"
     
     def _repr_javascript_(self):
         return "console.log('hi');", {'key': 'value'}
     
 
 def test_user_variables():
     # enable all formatters
     ip.display_formatter.active_types = ip.display_formatter.format_types
     
     ip.user_ns['dummy'] = d = DummyRepr()
     keys = {'dummy', 'doesnotexist'}
     r = ip.user_expressions({ key:key for key in keys})
 
     assert keys == set(r.keys())
     dummy = r["dummy"]
     assert {"status", "data", "metadata"} == set(dummy.keys())
     assert dummy["status"] == "ok"
     data = dummy["data"]
     metadata = dummy["metadata"]
     assert data.get("text/html") == d._repr_html_()
     js, jsmd = d._repr_javascript_()
     assert data.get("application/javascript") == js
     assert metadata.get("application/javascript") == jsmd
 
     dne = r["doesnotexist"]
     assert dne["status"] == "error"
     assert dne["ename"] == "NameError"
 
     # back to text only
     ip.display_formatter.active_types = ['text/plain']
     
 def test_user_expression():
     # enable all formatters
     ip.display_formatter.active_types = ip.display_formatter.format_types
     query = {
         'a' : '1 + 2',
         'b' : '1/0',
     }
     r = ip.user_expressions(query)
     import pprint
     pprint.pprint(r)
     assert set(r.keys()) == set(query.keys())
     a = r["a"]
     assert {"status", "data", "metadata"} == set(a.keys())
     assert a["status"] == "ok"
     data = a["data"]
     metadata = a["metadata"]
     assert data.get("text/plain") == "3"
 
     b = r["b"]
     assert b["status"] == "error"
     assert b["ename"] == "ZeroDivisionError"
 
     # back to text only
     ip.display_formatter.active_types = ['text/plain']
 
 
 class TestSyntaxErrorTransformer(unittest.TestCase):
     """Check that SyntaxError raised by an input transformer is handled by run_cell()"""
 
     @staticmethod
     def transformer(lines):
         for line in lines:
             pos = line.find('syntaxerror')
             if pos >= 0:
                 e = SyntaxError('input contains "syntaxerror"')
                 e.text = line
                 e.offset = pos + 1
                 raise e
         return lines
 
     def setUp(self):
         ip.input_transformers_post.append(self.transformer)
 
     def tearDown(self):
         ip.input_transformers_post.remove(self.transformer)
 
     def test_syntaxerror_input_transformer(self):
         with tt.AssertPrints('1234'):
             ip.run_cell('1234')
         with tt.AssertPrints('SyntaxError: invalid syntax'):
             ip.run_cell('1 2 3')   # plain python syntax error
         with tt.AssertPrints('SyntaxError: input contains "syntaxerror"'):
             ip.run_cell('2345  # syntaxerror')  # input transformer syntax error
         with tt.AssertPrints('3456'):
             ip.run_cell('3456')
 
 
 class TestWarningSuppression(unittest.TestCase):
     def test_warning_suppression(self):
         ip.run_cell("import warnings")
         try:
             with self.assertWarnsRegex(UserWarning, "asdf"):
                 ip.run_cell("warnings.warn('asdf')")
             # Here's the real test -- if we run that again, we should get the
             # warning again. Traditionally, each warning was only issued once per
             # IPython session (approximately), even if the user typed in new and
             # different code that should have also triggered the warning, leading
             # to much confusion.
             with self.assertWarnsRegex(UserWarning, "asdf"):
                 ip.run_cell("warnings.warn('asdf')")
         finally:
             ip.run_cell("del warnings")
 
 
     def test_deprecation_warning(self):
         ip.run_cell("""
 import warnings
 def wrn():
     warnings.warn(
         "I AM  A WARNING",
         DeprecationWarning
     )
         """)
         try:
             with self.assertWarnsRegex(DeprecationWarning, "I AM  A WARNING"):
                 ip.run_cell("wrn()")
         finally:
             ip.run_cell("del warnings")
             ip.run_cell("del wrn")
 
 
 class TestImportNoDeprecate(tt.TempFileMixin):
 
     def setUp(self):
         """Make a valid python temp file."""
         self.mktmp("""
 import warnings
 def wrn():
     warnings.warn(
         "I AM  A WARNING",
         DeprecationWarning
     )
 """)
         super().setUp()
 
     def test_no_dep(self):
         """
         No deprecation warning should be raised from imported functions
         """
         ip.run_cell("from {} import wrn".format(self.fname))
 
         with tt.AssertNotPrints("I AM  A WARNING"):
             ip.run_cell("wrn()")
         ip.run_cell("del wrn")
 
 
 def test_custom_exc_count():
     hook = mock.Mock(return_value=None)
     ip.set_custom_exc((SyntaxError,), hook)
     before = ip.execution_count
     ip.run_cell("def foo()", store_history=True)
     # restore default excepthook
     ip.set_custom_exc((), None)
     assert hook.call_count == 1
     assert ip.execution_count == before + 1
 
 
 def test_run_cell_async():
     loop = asyncio.get_event_loop_policy().get_event_loop()
     ip.run_cell("import asyncio")
     coro = ip.run_cell_async("await asyncio.sleep(0.01)\n5")
     assert asyncio.iscoroutine(coro)
     result = loop.run_until_complete(coro)
     assert isinstance(result, interactiveshell.ExecutionResult)
     assert result.result == 5
 
 
 def test_should_run_async():
     assert not ip.should_run_async("a = 5")
     assert ip.should_run_async("await x")
     assert ip.should_run_async("import asyncio; await asyncio.sleep(1)")
 
 
 def test_set_custom_completer():
     num_completers = len(ip.Completer.matchers)
 
     def foo(*args, **kwargs):
         return "I'm a completer!"
 
     ip.set_custom_completer(foo, 0)
 
     # check that we've really added a new completer
     assert len(ip.Completer.matchers) == num_completers + 1
 
     # check that the first completer is the function we defined
     assert ip.Completer.matchers[0]() == "I'm a completer!"
 
     # clean up
     ip.Completer.custom_matchers.pop()

IPython/extensions/storemagic.py

@@ -1,233 +1,236
 # -*- coding: utf-8 -*-
 """
 %store magic for lightweight persistence.
 
 Stores variables, aliases and macros in IPython's database.
 
 To automatically restore stored variables at startup, add this to your
 :file:`ipython_config.py` file::
 
   c.StoreMagics.autorestore = True
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import inspect, os, sys, textwrap
 
 from IPython.core.error import UsageError
 from IPython.core.magic import Magics, magics_class, line_magic
+from IPython.testing.skipdoctest import skip_doctest
 from traitlets import Bool
 
 
 def restore_aliases(ip, alias=None):
     staliases = ip.db.get('stored_aliases', {})
     if alias is None:
         for k,v in staliases.items():
             #print "restore alias",k,v # dbg
             #self.alias_table[k] = v
             ip.alias_manager.define_alias(k,v)
     else:
         ip.alias_manager.define_alias(alias, staliases[alias])
 
 
 def refresh_variables(ip):
     db = ip.db
     for key in db.keys('autorestore/*'):
         # strip autorestore
         justkey = os.path.basename(key)
         try:
             obj = db[key]
         except KeyError:
             print("Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % justkey)
             print("The error was:", sys.exc_info()[0])
         else:
             #print "restored",justkey,"=",obj #dbg
             ip.user_ns[justkey] = obj
 
 
 def restore_dhist(ip):
     ip.user_ns['_dh'] = ip.db.get('dhist',[])
 
 
 def restore_data(ip):
     refresh_variables(ip)
     restore_aliases(ip)
     restore_dhist(ip)
 
 
 @magics_class
 class StoreMagics(Magics):
     """Lightweight persistence for python variables.
 
     Provides the %store magic."""
 
     autorestore = Bool(False, help=
         """If True, any %store-d variables will be automatically restored
         when IPython starts.
         """
     ).tag(config=True)
 
     def __init__(self, shell):
         super(StoreMagics, self).__init__(shell=shell)
         self.shell.configurables.append(self)
         if self.autorestore:
             restore_data(self.shell)
 
+    @skip_doctest
     @line_magic
     def store(self, parameter_s=''):
         """Lightweight persistence for python variables.
 
         Example::
 
           In [1]: l = ['hello',10,'world']
           In [2]: %store l
+          Stored 'l' (list)
           In [3]: exit
 
           (IPython session is closed and started again...)
 
           ville@badger:~$ ipython
           In [1]: l
           NameError: name 'l' is not defined
           In [2]: %store -r
           In [3]: l
           Out[3]: ['hello', 10, 'world']
 
         Usage:
 
         * ``%store``          - Show list of all variables and their current
                                 values
         * ``%store spam bar`` - Store the *current* value of the variables spam
                                 and bar to disk
         * ``%store -d spam``  - Remove the variable and its value from storage
         * ``%store -z``       - Remove all variables from storage
         * ``%store -r``       - Refresh all variables, aliases and directory history
                                 from store (overwrite current vals)
         * ``%store -r spam bar`` - Refresh specified variables and aliases from store
                                    (delete current val)
         * ``%store foo >a.txt``  - Store value of foo to new file a.txt
         * ``%store foo >>a.txt`` - Append value of foo to file a.txt
 
         It should be noted that if you change the value of a variable, you
         need to %store it again if you want to persist the new value.
 
         Note also that the variables will need to be pickleable; most basic
         python types can be safely %store'd.
 
         Also aliases can be %store'd across sessions.
         To remove an alias from the storage, use the %unalias magic.
         """
 
         opts,argsl = self.parse_options(parameter_s,'drz',mode='string')
         args = argsl.split()
         ip = self.shell
         db = ip.db
         # delete
         if 'd' in opts:
             try:
                 todel = args[0]
             except IndexError as e:
                 raise UsageError('You must provide the variable to forget') from e
             else:
                 try:
                     del db['autorestore/' + todel]
                 except BaseException as e:
                     raise UsageError("Can't delete variable '%s'" % todel) from e
         # reset
         elif 'z' in opts:
             for k in db.keys('autorestore/*'):
                 del db[k]
 
         elif 'r' in opts:
             if args:
                 for arg in args:
                     try:
                         obj = db['autorestore/' + arg]
                     except KeyError:
                         try:
                             restore_aliases(ip, alias=arg)
                         except KeyError:
                             print("no stored variable or alias %s" % arg)
                     else:
                         ip.user_ns[arg] = obj
             else:
                 restore_data(ip)
 
         # run without arguments -> list variables & values
         elif not args:
             vars = db.keys('autorestore/*')
             vars.sort()
             if vars:
                 size = max(map(len, vars))
             else:
                 size = 0
 
             print('Stored variables and their in-db values:')
             fmt = '%-'+str(size)+'s -> %s'
             get = db.get
             for var in vars:
                 justkey = os.path.basename(var)
                 # print 30 first characters from every var
                 print(fmt % (justkey, repr(get(var, '<unavailable>'))[:50]))
 
         # default action - store the variable
         else:
             # %store foo >file.txt or >>file.txt
             if len(args) > 1 and args[1].startswith('>'):
                 fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
                 if args[1].startswith('>>'):
                     fil = open(fnam, 'a')
                 else:
                     fil = open(fnam, 'w')
                 with fil:
                     obj = ip.ev(args[0])
                     print("Writing '%s' (%s) to file '%s'." % (args[0],
                         obj.__class__.__name__, fnam))
 
                     if not isinstance (obj, str):
                         from pprint import pprint
                         pprint(obj, fil)
                     else:
                         fil.write(obj)
                         if not obj.endswith('\n'):
                             fil.write('\n')
 
                 return
 
             # %store foo
             for arg in args:
                 try:
                     obj = ip.user_ns[arg]
                 except KeyError:
                     # it might be an alias
                     name = arg
                     try:
                         cmd = ip.alias_manager.retrieve_alias(name)
                     except ValueError as e:
                         raise UsageError("Unknown variable '%s'" % name) from e
 
                     staliases = db.get('stored_aliases',{})
                     staliases[name] = cmd
                     db['stored_aliases'] = staliases
                     print("Alias stored: %s (%s)" % (name, cmd))
                     return
 
                 else:
                     modname = getattr(inspect.getmodule(obj), '__name__', '')
                     if modname == '__main__':
                         print(textwrap.dedent("""\
                         Warning:%s is %s
                         Proper storage of interactively declared classes (or instances
                         of those classes) is not possible! Only instances
                         of classes in real modules on file system can be %%store'd.
                         """ % (arg, obj) ))
                         return
                     #pickled = pickle.dumps(obj)
                     db[ 'autorestore/' + arg ] = obj
                     print("Stored '%s' (%s)" % (arg, obj.__class__.__name__))
 
 
 def load_ipython_extension(ip):
     """Load the extension in IPython."""
     ip.register_magics(StoreMagics)
 

IPython/terminal/magics.py

@@ -1,213 +1,215
 """Extra magics for terminal use."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 from logging import error
 import os
 import sys
 
 from IPython.core.error import TryNext, UsageError
 from IPython.core.magic import Magics, magics_class, line_magic
 from IPython.lib.clipboard import ClipboardEmpty
+from IPython.testing.skipdoctest import skip_doctest
 from IPython.utils.text import SList, strip_email_quotes
 from IPython.utils import py3compat
 
 def get_pasted_lines(sentinel, l_input=py3compat.input, quiet=False):
     """ Yield pasted lines until the user enters the given sentinel value.
     """
     if not quiet:
         print("Pasting code; enter '%s' alone on the line to stop or use Ctrl-D." \
               % sentinel)
         prompt = ":"
     else:
         prompt = ""
     while True:
         try:
             l = l_input(prompt)
             if l == sentinel:
                 return
             else:
                 yield l
         except EOFError:
             print('<EOF>')
             return
 
 
 @magics_class
 class TerminalMagics(Magics):
     def __init__(self, shell):
         super(TerminalMagics, self).__init__(shell)
 
     def store_or_execute(self, block, name):
         """ Execute a block, or store it in a variable, per the user's request.
         """
         if name:
             # If storing it for further editing
             self.shell.user_ns[name] = SList(block.splitlines())
             print("Block assigned to '%s'" % name)
         else:
             b = self.preclean_input(block)
             self.shell.user_ns['pasted_block'] = b
             self.shell.using_paste_magics = True
             try:
                 self.shell.run_cell(b)
             finally:
                 self.shell.using_paste_magics = False
 
     def preclean_input(self, block):
         lines = block.splitlines()
         while lines and not lines[0].strip():
             lines = lines[1:]
         return strip_email_quotes('\n'.join(lines))
 
     def rerun_pasted(self, name='pasted_block'):
         """ Rerun a previously pasted command.
         """
         b = self.shell.user_ns.get(name)
 
         # Sanity checks
         if b is None:
             raise UsageError('No previous pasted block available')
         if not isinstance(b, str):
             raise UsageError(
                 "Variable 'pasted_block' is not a string, can't execute")
 
         print("Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b)))
         self.shell.run_cell(b)
 
     @line_magic
     def autoindent(self, parameter_s = ''):
         """Toggle autoindent on/off (deprecated)"""
         self.shell.set_autoindent()
         print("Automatic indentation is:",['OFF','ON'][self.shell.autoindent])
 
+    @skip_doctest
     @line_magic
     def cpaste(self, parameter_s=''):
         """Paste & execute a pre-formatted code block from clipboard.
 
         You must terminate the block with '--' (two minus-signs) or Ctrl-D
         alone on the line. You can also provide your own sentinel with '%paste
         -s %%' ('%%' is the new sentinel for this operation).
 
         The block is dedented prior to execution to enable execution of method
         definitions. '>' and '+' characters at the beginning of a line are
         ignored, to allow pasting directly from e-mails, diff files and
         doctests (the '...' continuation prompt is also stripped).  The
         executed block is also assigned to variable named 'pasted_block' for
         later editing with '%edit pasted_block'.
 
         You can also pass a variable name as an argument, e.g. '%cpaste foo'.
         This assigns the pasted block to variable 'foo' as string, without
         dedenting or executing it (preceding >>> and + is still stripped)
 
         '%cpaste -r' re-executes the block previously entered by cpaste.
         '%cpaste -q' suppresses any additional output messages.
 
         Do not be alarmed by garbled output on Windows (it's a readline bug).
         Just press enter and type -- (and press enter again) and the block
         will be what was just pasted.
 
         Shell escapes are not supported (yet).
 
         See also
         --------
         paste: automatically pull code from clipboard.
 
         Examples
         --------
         ::
 
           In [8]: %cpaste
           Pasting code; enter '--' alone on the line to stop.
           :>>> a = ["world!", "Hello"]
           :>>> print(" ".join(sorted(a)))
           :--
           Hello world!
 
         ::
           In [8]: %cpaste
           Pasting code; enter '--' alone on the line to stop.
           :>>> %alias_magic t timeit
           :>>> %t -n1 pass
           :--
           Created `%t` as an alias for `%timeit`.
           Created `%%t` as an alias for `%%timeit`.
           354 ns ± 224 ns per loop (mean ± std. dev. of 7 runs, 1 loop each)
         """
         opts, name = self.parse_options(parameter_s, 'rqs:', mode='string')
         if 'r' in opts:
             self.rerun_pasted()
             return
 
         quiet = ('q' in opts)
 
         sentinel = opts.get('s', u'--')
         block = '\n'.join(get_pasted_lines(sentinel, quiet=quiet))
         self.store_or_execute(block, name)
 
     @line_magic
     def paste(self, parameter_s=''):
         """Paste & execute a pre-formatted code block from clipboard.
 
         The text is pulled directly from the clipboard without user
         intervention and printed back on the screen before execution (unless
         the -q flag is given to force quiet mode).
 
         The block is dedented prior to execution to enable execution of method
         definitions. '>' and '+' characters at the beginning of a line are
         ignored, to allow pasting directly from e-mails, diff files and
         doctests (the '...' continuation prompt is also stripped).  The
         executed block is also assigned to variable named 'pasted_block' for
         later editing with '%edit pasted_block'.
 
         You can also pass a variable name as an argument, e.g. '%paste foo'.
         This assigns the pasted block to variable 'foo' as string, without
         executing it (preceding >>> and + is still stripped).
 
         Options:
 
           -r: re-executes the block previously entered by cpaste.
 
           -q: quiet mode: do not echo the pasted text back to the terminal.
 
         IPython statements (magics, shell escapes) are not supported (yet).
 
         See also
         --------
         cpaste: manually paste code into terminal until you mark its end.
         """
         opts, name = self.parse_options(parameter_s, 'rq', mode='string')
         if 'r' in opts:
             self.rerun_pasted()
             return
         try:
             block = self.shell.hooks.clipboard_get()
         except TryNext as clipboard_exc:
             message = getattr(clipboard_exc, 'args')
             if message:
                 error(message[0])
             else:
                 error('Could not get text from the clipboard.')
             return
         except ClipboardEmpty as e:
             raise UsageError("The clipboard appears to be empty") from e
 
         # By default, echo back to terminal unless quiet mode is requested
         if 'q' not in opts:
             write = self.shell.write
             write(self.shell.pycolorize(block))
             if not block.endswith('\n'):
                 write('\n')
             write("## -- End pasted text --\n")
 
         self.store_or_execute(block, name)
 
     # Class-level: add a '%cls' magic only on Windows
     if sys.platform == 'win32':
         @line_magic
         def cls(self, s):
             """Clear screen.
             """
             os.system("cls")