Fix documentation of functions using magic_arguments

IPython/core/magics/basic.py

@@ -1,647 +1,648 b''
 """Implementation of basic 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
 #-----------------------------------------------------------------------------
 from __future__ import print_function
 
 # Stdlib
 import io
 import json
 import sys
 from pprint import pformat
 
 # Our own packages
 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
 from IPython.utils.path import unquote_filename
 from IPython.utils.py3compat import unicode_type
 from IPython.utils.warn import warn, error
 
 #-----------------------------------------------------------------------------
 # Magics class implementation
 #-----------------------------------------------------------------------------
 
 class MagicsDisplay(object):
     def __init__(self, magics_manager):
         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(magics['line'])),
                '',
                'Available cell magics:',
                cesc + ('  '+cesc).join(sorted(magics['cell'])),
                '',
                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 json.dumps(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'."""
 
     @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."""
     )
     @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'
         """
         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)
 
         # 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)
 
         if args.line:
             mman.register_alias(name, target, 'line')
             print('Created `%s%s` as an alias for `%s%s`.' % (
                 magic_escapes['line'], name,
                 magic_escapes['line'], target))
 
         if args.cell:
             mman.register_alias(name, target, 'cell')
             print('Created `%s%s` as an alias for `%s%s`.' % (
                 magic_escapes['cell'], name,
                 magic_escapes['cell'], target))
 
     @line_magic
     def lsmagic(self, parameter_s=''):
         """List currently available magic functions."""
         return MagicsDisplay(self.shell.magics_manager)
 
     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:]
             if mode == 'rest':
                 rest_docs = []
         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 you 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 profile(self, parameter_s=''):
         """Print your currently active IPython profile."""
         from IPython.core.application import BaseIPythonApplication
         if BaseIPythonApplication.initialized():
             print(BaseIPythonApplication.instance().profile)
         else:
             error("profile is an application-level value, but you don't appear to be in an IPython application")
 
     @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]))
 
 
         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
 
         import IPython.utils.rlineimpl as readline
 
         if not shell.colors_force and \
                 not readline.have_readline and \
                 (sys.platform == "win32" or sys.platform == "cli"):
             msg = """\
 Proper color support under MS Windows requires the pyreadline library.
 You can find it at:
 http://ipython.org/pyreadline.html
 Gary's readline needs the ctypes module, from:
 http://starship.python.net/crew/theller/ctypes
 (Note that ctypes is already part of Python versions 2.5 and newer).
 
 Defaulting color scheme to 'NoColor'"""
             new_scheme = 'NoColor'
             warn(msg)
 
         # readline option is 0
         if not shell.colors_force and not shell.has_readline:
             new_scheme = 'NoColor'
 
         # Set prompt colors
         try:
             shell.prompt_manager.color_scheme = new_scheme
         except:
             color_switch_err('prompt')
         else:
             shell.colors = \
                    shell.prompt_manager.color_scheme_table.active_scheme_name
         # 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 and Verbose.
 
         If called without arguments, acts as a toggle."""
 
         def xmode_switch_err(name):
             warn('Error changing %s exception modes.\n%s' %
                  (name,sys.exc_info()[1]))
 
         shell = self.shell
         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
         pm = shell.prompt_manager
         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_prompts_pad_left',pm.justify)
         save_dstore('rc_separate_in',shell.separate_in)
         save_dstore('rc_active_types',disp_formatter.active_types)
         save_dstore('prompt_templates',(pm.in_template, pm.in2_template, pm.out_template))
 
         if mode == False:
             # turn on
             pm.in_template = '>>> '
             pm.in2_template = '... '
             pm.out_template = ''
 
             # Prompt separators like plain python
             shell.separate_in = ''
             shell.separate_out = ''
             shell.separate_out2 = ''
 
             pm.justify = False
 
             ptformatter.pprint = False
             disp_formatter.active_types = ['text/plain']
 
             shell.magic('xmode Plain')
         else:
             # turn off
             pm.in_template, pm.in2_template, pm.out_template = dstore.prompt_templates
 
             shell.separate_in = dstore.rc_separate_in
 
             shell.separate_out = dstore.rc_separate_out
             shell.separate_out2 = dstore.rc_separate_out2
 
             pm.justify = dstore.rc_prompts_pad_left
 
             ptformatter.pprint = dstore.rc_pprint
             disp_formatter.active_types = dstore.rc_active_types
 
             shell.magic('xmode ' + dstore.xmode)
 
         # Store new mode and inform
         dstore.mode = bool(1-int(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 gtk     # enable PyGTK event loop integration
             %gui gtk3    # enable Gtk3 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='Export IPython history as a notebook. The filename argument '
              'is used to specify the notebook name and format. For example '
              'a filename of notebook.ipynb will result in a notebook name '
              'of "notebook" and a format of "json". Likewise using a ".py" '
              'file extension will write the notebook as a Python script'
     )
     @magic_arguments.argument(
         '-f', '--format',
         help='Convert an existing IPython notebook to a new format. This option '
              'specifies the new format and can have the values: json, py. '
              'The target filename is chosen automatically based on the new '
              'format. The filename argument gives the name of the source file.'
     )
     @magic_arguments.argument(
         'filename', type=unicode_type,
         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
         or can convert an existing notebook file into a different format. For
         example, to export the history to "foo.ipynb" do "%notebook -e foo.ipynb".
         To export the history to "foo.py" do "%notebook -e foo.py". To convert
         "foo.ipynb" to "foo.json" do "%notebook -f json foo.ipynb". Possible
         formats include (json/ipynb, py).
         """
         args = magic_arguments.parse_argstring(self.notebook, s)
 
         from IPython.nbformat import current
         args.filename = unquote_filename(args.filename)
         if args.export:
             fname, name, format = current.parse_filename(args.filename)
             cells = []
             hist = list(self.shell.history_manager.get_range())
             for session, prompt_number, input in hist[:-1]:
                 cells.append(current.new_code_cell(prompt_number=prompt_number,
                                                    input=input))
             worksheet = current.new_worksheet(cells=cells)
             nb = current.new_notebook(name=name,worksheets=[worksheet])
             with io.open(fname, 'w', encoding='utf-8') as f:
                 current.write(nb, f, format);
         elif args.format is not None:
             old_fname, old_name, old_format = current.parse_filename(args.filename)
             new_format = args.format
             if new_format == u'xml':
                 raise ValueError('Notebooks cannot be written as xml.')
             elif new_format == u'ipynb' or new_format == u'json':
                 new_fname = old_name + u'.ipynb'
                 new_format = u'json'
             elif new_format == u'py':
                 new_fname = old_name + u'.py'
             else:
                 raise ValueError('Invalid notebook format: %s' % new_format)
             with io.open(old_fname, 'r', encoding='utf-8') as f:
                 nb = current.read(f, old_format)
             with io.open(new_fname, 'w', encoding='utf-8') as f:
                 current.write(nb, f, new_format)

IPython/extensions/cythonmagic.py

@@ -1,341 +1,345 b''
 # -*- coding: utf-8 -*-
 """
 =====================
 Cython related magics
 =====================
 
 Magic command interface for interactive work with Cython
 
 .. note::
 
   The ``Cython`` package needs to be installed separately. It
   can be obtained using ``easy_install`` or ``pip``.
 
 Usage
 =====
 
 To enable the magics below, execute ``%load_ext cythonmagic``.
 
 ``%%cython``
 
 {CYTHON_DOC}
 
 ``%%cython_inline``
 
 {CYTHON_INLINE_DOC}
 
 ``%%cython_pyximport``
 
 {CYTHON_PYXIMPORT_DOC}
 
 Author:
 * Brian Granger
 
 Parts of this code were taken from Cython.inline.
 """
 #-----------------------------------------------------------------------------
 # Copyright (C) 2010-2011, 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.
 #-----------------------------------------------------------------------------
 
 from __future__ import print_function
 
 import imp
 import io
 import os
 import re
 import sys
 import time
 
 try:
     reload
 except NameError:   # Python 3
     from imp import reload
 
 try:
     import hashlib
 except ImportError:
     import md5 as hashlib
 
 from distutils.core import Distribution, Extension
 from distutils.command.build_ext import build_ext
 
 from IPython.core import display
 from IPython.core import magic_arguments
 from IPython.core.magic import Magics, magics_class, cell_magic
 from IPython.utils import py3compat
 from IPython.utils.path import get_ipython_cache_dir
+from IPython.utils.text import dedent
 
 import Cython
 from Cython.Compiler.Errors import CompileError
 from Cython.Build.Dependencies import cythonize
 
 
 @magics_class
 class CythonMagics(Magics):
 
     def __init__(self, shell):
         super(CythonMagics,self).__init__(shell)
         self._reloads = {}
         self._code_cache = {}
 
     def _import_all(self, module):
         for k,v in module.__dict__.items():
             if not k.startswith('__'):
                 self.shell.push({k:v})
 
     @cell_magic
     def cython_inline(self, line, cell):
         """Compile and run a Cython code cell using Cython.inline.
 
         This magic simply passes the body of the cell to Cython.inline
         and returns the result. If the variables `a` and `b` are defined
         in the user's namespace, here is a simple example that returns
         their sum::
 
             %%cython_inline
             return a+b
 
         For most purposes, we recommend the usage of the `%%cython` magic.
         """
         locs = self.shell.user_global_ns
         globs = self.shell.user_ns
         return Cython.inline(cell, locals=locs, globals=globs)
 
     @cell_magic
     def cython_pyximport(self, line, cell):
         """Compile and import a Cython code cell using pyximport.
 
         The contents of the cell are written to a `.pyx` file in the current
         working directory, which is then imported using `pyximport`. This
         magic requires a module name to be passed::
 
             %%cython_pyximport modulename
             def f(x):
                 return 2.0*x
 
         The compiled module is then imported and all of its symbols are
         injected into the user's namespace. For most purposes, we recommend
         the usage of the `%%cython` magic.
         """
         module_name = line.strip()
         if not module_name:
             raise ValueError('module name must be given')
         fname = module_name + '.pyx'
         with io.open(fname, 'w', encoding='utf-8') as f:
             f.write(cell)
         if 'pyximport' not in sys.modules:
             import pyximport
             pyximport.install(reload_support=True)
         if module_name in self._reloads:
             module = self._reloads[module_name]
             reload(module)
         else:
             __import__(module_name)
             module = sys.modules[module_name]
             self._reloads[module_name] = module
         self._import_all(module)
 
     @magic_arguments.magic_arguments()
     @magic_arguments.argument(
         '-c', '--compile-args', action='append', default=[],
         help="Extra flags to pass to compiler via the `extra_compile_args` "
              "Extension flag (can be specified  multiple times)."
     )
     @magic_arguments.argument(
         '--link-args', action='append', default=[],
         help="Extra flags to pass to linker via the `extra_link_args` "
              "Extension flag (can be specified  multiple times)."
     )
     @magic_arguments.argument(
         '-l', '--lib', action='append', default=[],
         help="Add a library to link the extension against (can be specified "
              "multiple times)."
     )
     @magic_arguments.argument(
         '-n', '--name',
         help="Specify a name for the Cython module."
     )
     @magic_arguments.argument(
         '-L', dest='library_dirs', metavar='dir', action='append', default=[],
         help="Add a path to the list of libary directories (can be specified "
              "multiple times)."
     )
     @magic_arguments.argument(
         '-I', '--include', action='append', default=[],
         help="Add a path to the list of include directories (can be specified "
              "multiple times)."
     )
     @magic_arguments.argument(
         '-+', '--cplus', action='store_true', default=False,
         help="Output a C++ rather than C file."
     )
     @magic_arguments.argument(
         '-f', '--force', action='store_true', default=False,
         help="Force the compilation of a new module, even if the source has been "
              "previously compiled."
     )
     @magic_arguments.argument(
         '-a', '--annotate', action='store_true', default=False,
         help="Produce a colorized HTML version of the source."
     )
     @cell_magic
     def cython(self, line, cell):
         """Compile and import everything from a Cython code cell.
 
         The contents of the cell are written to a `.pyx` file in the
         directory `IPYTHONDIR/cython` using a filename with the hash of the
         code. This file is then cythonized and compiled. The resulting module
         is imported and all of its symbols are injected into the user's
         namespace. The usage is similar to that of `%%cython_pyximport` but
         you don't have to pass a module name::
 
             %%cython
             def f(x):
                 return 2.0*x
 
         To compile OpenMP codes, pass the required  `--compile-args`
         and `--link-args`.  For example with gcc::
 
             %%cython --compile-args=-fopenmp --link-args=-fopenmp
             ...
         """
         args = magic_arguments.parse_argstring(self.cython, line)
         code = cell if cell.endswith('\n') else cell+'\n'
         lib_dir = os.path.join(get_ipython_cache_dir(), 'cython')
         quiet = True
         key = code, sys.version_info, sys.executable, Cython.__version__
 
         if not os.path.exists(lib_dir):
             os.makedirs(lib_dir)
 
         if args.force:
             # Force a new module name by adding the current time to the
             # key which is hashed to determine the module name.
             key += time.time(),
 
         if args.name:
             module_name = py3compat.unicode_to_str(args.name)
         else:
             module_name = "_cython_magic_" + hashlib.md5(str(key).encode('utf-8')).hexdigest()
         module_path = os.path.join(lib_dir, module_name + self.so_ext)
 
         have_module = os.path.isfile(module_path)
         need_cythonize = not have_module
 
         if args.annotate:
             html_file = os.path.join(lib_dir, module_name + '.html')
             if not os.path.isfile(html_file):
                 need_cythonize = True
 
         if need_cythonize:
             c_include_dirs = args.include
             if 'numpy' in code:
                 import numpy
                 c_include_dirs.append(numpy.get_include())
             pyx_file = os.path.join(lib_dir, module_name + '.pyx')
             pyx_file = py3compat.cast_bytes_py2(pyx_file, encoding=sys.getfilesystemencoding())
             with io.open(pyx_file, 'w', encoding='utf-8') as f:
                 f.write(code)
             extension = Extension(
                 name = module_name,
                 sources = [pyx_file],
                 include_dirs = c_include_dirs,
                 library_dirs = args.library_dirs,
                 extra_compile_args = args.compile_args,
                 extra_link_args = args.link_args,
                 libraries = args.lib,
                 language = 'c++' if args.cplus else 'c',
             )
             build_extension = self._get_build_extension()
             try:
                 opts = dict(
                     quiet=quiet,
                     annotate = args.annotate,
                     force = True,
                     )
                 build_extension.extensions = cythonize([extension], **opts)
             except CompileError:
                 return
 
         if not have_module:
             build_extension.build_temp = os.path.dirname(pyx_file)
             build_extension.build_lib  = lib_dir
             build_extension.run()
             self._code_cache[key] = module_name
 
         module = imp.load_dynamic(module_name, module_path)
         self._import_all(module)
 
         if args.annotate:
             try:
                 with io.open(html_file, encoding='utf-8') as f:
                     annotated_html = f.read()
             except IOError as e:
                 # File could not be opened. Most likely the user has a version
                 # of Cython before 0.15.1 (when `cythonize` learned the
                 # `force` keyword argument) and has already compiled this
                 # exact source without annotation.
                 print('Cython completed successfully but the annotated '
                       'source could not be read.', file=sys.stderr)
                 print(e, file=sys.stderr)
             else:
                 return display.HTML(self.clean_annotated_html(annotated_html))
 
     @property
     def so_ext(self):
         """The extension suffix for compiled modules."""
         try:
             return self._so_ext
         except AttributeError:
             self._so_ext = self._get_build_extension().get_ext_filename('')
             return self._so_ext
 
     def _clear_distutils_mkpath_cache(self):
         """clear distutils mkpath cache
         
         prevents distutils from skipping re-creation of dirs that have been removed
         """
         try:
             from distutils.dir_util import _path_created
         except ImportError:
             pass
         else:
             _path_created.clear()
     
     def _get_build_extension(self):
         self._clear_distutils_mkpath_cache()
         dist = Distribution()
         config_files = dist.find_config_files()
         try:
             config_files.remove('setup.cfg')
         except ValueError:
             pass
         dist.parse_config_files(config_files)
         build_extension = build_ext(dist)
         build_extension.finalize_options()
         return build_extension
 
     @staticmethod
     def clean_annotated_html(html):
         """Clean up the annotated HTML source.
 
         Strips the link to the generated C or C++ file, which we do not
         present to the user.
         """
         r = re.compile('<p>Raw output: <a href="(.*)">(.*)</a>')
         html = '\n'.join(l for l in html.splitlines() if not r.match(l))
         return html
 
 __doc__ = __doc__.format(
-                CYTHON_DOC = ' '*8 + CythonMagics.cython.__doc__,
-                CYTHON_INLINE_DOC = ' '*8 + CythonMagics.cython_inline.__doc__,
-                CYTHON_PYXIMPORT_DOC = ' '*8 + CythonMagics.cython_pyximport.__doc__,
+                # rST doesn't see the -+ flag as part of an option list, so we
+                # hide it from the module-level docstring.
+                CYTHON_DOC = dedent(CythonMagics.cython.__doc__\
+                            .replace('-+, --cplus','--cplus    ')),
+                CYTHON_INLINE_DOC = dedent(CythonMagics.cython_inline.__doc__),
+                CYTHON_PYXIMPORT_DOC = dedent(CythonMagics.cython_pyximport.__doc__),
 )
 
 def load_ipython_extension(ip):
     """Load the extension in IPython."""
     ip.register_magics(CythonMagics)

IPython/extensions/octavemagic.py

@@ -1,371 +1,374 b''
 # -*- coding: utf-8 -*-
 """
 ===========
 octavemagic
 ===========
 
 Magics for interacting with Octave via oct2py.
 
 .. note::
 
   The ``oct2py`` module needs to be installed separately and
   can be obtained using ``easy_install`` or ``pip``.
 
   You will also need a working copy of GNU Octave.
 
 Usage
 =====
 
 To enable the magics below, execute ``%load_ext octavemagic``.
 
 ``%octave``
 
 {OCTAVE_DOC}
 
 ``%octave_push``
 
 {OCTAVE_PUSH_DOC}
 
 ``%octave_pull``
 
 {OCTAVE_PULL_DOC}
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2012 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 tempfile
 from glob import glob
 from shutil import rmtree
 
 import numpy as np
 import oct2py
 from xml.dom import minidom
 
 from IPython.core.displaypub import publish_display_data
 from IPython.core.magic import (Magics, magics_class, line_magic,
                                 line_cell_magic, needs_local_scope)
 from IPython.testing.skipdoctest import skip_doctest
 from IPython.core.magic_arguments import (
     argument, magic_arguments, parse_argstring
 )
 from IPython.utils.py3compat import unicode_to_str
+from IPython.utils.text import dedent
 
 class OctaveMagicError(oct2py.Oct2PyError):
     pass
 
 _mimetypes = {'png' : 'image/png',
              'svg' : 'image/svg+xml',
              'jpg' : 'image/jpeg',
               'jpeg': 'image/jpeg'}
 
 @magics_class
 class OctaveMagics(Magics):
     """A set of magics useful for interactive work with Octave via oct2py.
     """
     def __init__(self, shell):
         """
         Parameters
         ----------
         shell : IPython shell
 
         """
         super(OctaveMagics, self).__init__(shell)
         self._oct = oct2py.Oct2Py()
         self._plot_format = 'png'
 
         # Allow publish_display_data to be overridden for
         # testing purposes.
         self._publish_display_data = publish_display_data
 
 
     def _fix_gnuplot_svg_size(self, image, size=None):
         """
         GnuPlot SVGs do not have height/width attributes.  Set
         these to be the same as the viewBox, so that the browser
         scales the image correctly.
 
         Parameters
         ----------
         image : str
             SVG data.
         size : tuple of int
             Image width, height.
 
         """
         (svg,) = minidom.parseString(image).getElementsByTagName('svg')
         viewbox = svg.getAttribute('viewBox').split(' ')
 
         if size is not None:
             width, height = size
         else:
             width, height = viewbox[2:]
 
         svg.setAttribute('width', '%dpx' % width)
         svg.setAttribute('height', '%dpx' % height)
         return svg.toxml()
 
 
     @skip_doctest
     @line_magic
     def octave_push(self, line):
         '''
         Line-level magic that pushes a variable to Octave.
 
         `line` should be made up of whitespace separated variable names in the
         IPython namespace::
 
             In [7]: import numpy as np
 
             In [8]: X = np.arange(5)
 
             In [9]: X.mean()
             Out[9]: 2.0
 
             In [10]: %octave_push X
 
             In [11]: %octave mean(X)
             Out[11]: 2.0
 
         '''
         inputs = line.split(' ')
         for input in inputs:
             input = unicode_to_str(input)
             self._oct.put(input, self.shell.user_ns[input])
 
 
     @skip_doctest
     @line_magic
     def octave_pull(self, line):
         '''
         Line-level magic that pulls a variable from Octave.
 
+        ::
+
             In [18]: _ = %octave x = [1 2; 3 4]; y = 'hello'
 
             In [19]: %octave_pull x y
 
             In [20]: x
             Out[20]:
             array([[ 1.,  2.],
                    [ 3.,  4.]])
 
             In [21]: y
             Out[21]: 'hello'
 
         '''
         outputs = line.split(' ')
         for output in outputs:
             output = unicode_to_str(output)
             self.shell.push({output: self._oct.get(output)})
 
 
     @skip_doctest
     @magic_arguments()
     @argument(
         '-i', '--input', action='append',
         help='Names of input variables to be pushed to Octave. Multiple names '
              'can be passed, separated by commas with no whitespace.'
         )
     @argument(
         '-o', '--output', action='append',
         help='Names of variables to be pulled from Octave after executing cell '
              'body. Multiple names can be passed, separated by commas with no '
              'whitespace.'
         )
     @argument(
         '-s', '--size', action='store',
         help='Pixel size of plots, "width,height". Default is "-s 400,250".'
         )
     @argument(
         '-f', '--format', action='store',
         help='Plot format (png, svg or jpg).'
         )
 
     @needs_local_scope
     @argument(
         'code',
         nargs='*',
         )
     @line_cell_magic
     def octave(self, line, cell=None, local_ns=None):
         '''
         Execute code in Octave, and pull some of the results back into the
-        Python namespace.
+        Python namespace::
 
             In [9]: %octave X = [1 2; 3 4]; mean(X)
             Out[9]: array([[ 2., 3.]])
 
         As a cell, this will run a block of Octave code, without returning any
         value::
 
             In [10]: %%octave
                ....: p = [-2, -1, 0, 1, 2]
                ....: polyout(p, 'x')
 
             -2*x^4 - 1*x^3 + 0*x^2 + 1*x^1 + 2
 
-        In the notebook, plots are published as the output of the cell, e.g.
+        In the notebook, plots are published as the output of the cell, e.g.::
 
-        %octave plot([1 2 3], [4 5 6])
+            %octave plot([1 2 3], [4 5 6])
 
         will create a line plot.
 
         Objects can be passed back and forth between Octave and IPython via the
         -i and -o flags in line::
 
             In [14]: Z = np.array([1, 4, 5, 10])
 
             In [15]: %octave -i Z mean(Z)
             Out[15]: array([ 5.])
 
 
             In [16]: %octave -o W W = Z * mean(Z)
             Out[16]: array([  5.,  20.,  25.,  50.])
 
             In [17]: W
             Out[17]: array([  5.,  20.,  25.,  50.])
 
         The size and format of output plots can be specified::
 
             In [18]: %%octave -s 600,800 -f svg
                 ...: plot([1, 2, 3]);
 
         '''
         args = parse_argstring(self.octave, line)
 
         # arguments 'code' in line are prepended to the cell lines
         if cell is None:
             code = ''
             return_output = True
         else:
             code = cell
             return_output = False
 
         code = ' '.join(args.code) + code
 
         # if there is no local namespace then default to an empty dict
         if local_ns is None:
             local_ns = {}
 
         if args.input:
             for input in ','.join(args.input).split(','):
                 input = unicode_to_str(input)
                 try:
                     val = local_ns[input]
                 except KeyError:
                     val = self.shell.user_ns[input]
                 self._oct.put(input, val)
 
         # generate plots in a temporary directory
         plot_dir = tempfile.mkdtemp().replace('\\', '/')
         if args.size is not None:
             size = args.size
         else:
             size = '400,240'
 
         if args.format is not None:
             plot_format = args.format
         else:
             plot_format = 'png'
 
         pre_call = '''
         global __ipy_figures = [];
         page_screen_output(0);
 
         function fig_create(src, event)
           global __ipy_figures;
           __ipy_figures(size(__ipy_figures) + 1) = src;
           set(src, "visible", "off");
         end
 
         set(0, 'DefaultFigureCreateFcn', @fig_create);
 
         close all;
         clear ans;
 
         # ___<end_pre_call>___ #
         '''
 
         post_call = '''
         # ___<start_post_call>___ #
 
         # Save output of the last execution
         if exist("ans") == 1
           _ = ans;
         else
           _ = nan;
         end
 
         for f = __ipy_figures
           outfile = sprintf('%(plot_dir)s/__ipy_oct_fig_%%03d.png', f);
           try
             print(f, outfile, '-d%(plot_format)s', '-tight', '-S%(size)s');
           end
         end
 
         ''' % locals()
 
         code = ' '.join((pre_call, code, post_call))
         try:
             text_output = self._oct.run(code, verbose=False)
         except (oct2py.Oct2PyError) as exception:
             msg = exception.message
             msg = msg.split('# ___<end_pre_call>___ #')[1]
             msg = msg.split('# ___<start_post_call>___ #')[0]
             raise OctaveMagicError('Octave could not complete execution.  '
                                    'Traceback (currently broken in oct2py): %s'
                                    % msg)
 
         key = 'OctaveMagic.Octave'
         display_data = []
 
         # Publish text output
         if text_output:
             display_data.append((key, {'text/plain': text_output}))
 
         # Publish images
         images = [open(imgfile, 'rb').read() for imgfile in \
                   glob("%s/*" % plot_dir)]
         rmtree(plot_dir)
 
         plot_mime_type = _mimetypes.get(plot_format, 'image/png')
         width, height = [int(s) for s in size.split(',')]
         for image in images:
             if plot_format == 'svg':
                 image = self._fix_gnuplot_svg_size(image, size=(width, height))
             display_data.append((key, {plot_mime_type: image}))
 
         if args.output:
             for output in ','.join(args.output).split(','):
                 output = unicode_to_str(output)
                 self.shell.push({output: self._oct.get(output)})
 
         for source, data in display_data:
             self._publish_display_data(source, data)
 
         if return_output:
             ans = self._oct.get('_')
 
             # Unfortunately, Octave doesn't have a "None" object,
             # so we can't return any NaN outputs
             if np.isscalar(ans) and np.isnan(ans):
                 ans = None
 
             return ans
 
 
 __doc__ = __doc__.format(
-    OCTAVE_DOC = ' '*8 + OctaveMagics.octave.__doc__,
-    OCTAVE_PUSH_DOC = ' '*8 + OctaveMagics.octave_push.__doc__,
-    OCTAVE_PULL_DOC = ' '*8 + OctaveMagics.octave_pull.__doc__
+    OCTAVE_DOC = dedent(OctaveMagics.octave.__doc__),
+    OCTAVE_PUSH_DOC = dedent(OctaveMagics.octave_push.__doc__),
+    OCTAVE_PULL_DOC = dedent(OctaveMagics.octave_pull.__doc__)
     )
 
 
 def load_ipython_extension(ip):
     """Load the extension in IPython."""
     ip.register_magics(OctaveMagics)

IPython/extensions/rmagic.py

@@ -1,695 +1,696 b''
 # -*- coding: utf-8 -*-
 """
 ======
 Rmagic
 ======
 
 Magic command interface for interactive work with R via rpy2
 
 .. note::
 
   The ``rpy2`` package needs to be installed separately. It
   can be obtained using ``easy_install`` or ``pip``.
 
   You will also need a working copy of R.
 
 Usage
 =====
 
 To enable the magics below, execute ``%load_ext rmagic``.
 
 ``%R``
 
 {R_DOC}
 
 ``%Rpush``
 
 {RPUSH_DOC}
 
 ``%Rpull``
 
 {RPULL_DOC}
 
 ``%Rget``
 
 {RGET_DOC}
 
 """
 from __future__ import print_function
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2012 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 sys
 import tempfile
 from glob import glob
 from shutil import rmtree
 
 # numpy and rpy2 imports
 
 import numpy as np
 
 import rpy2.rinterface as ri
 import rpy2.robjects as ro
 try:
     from rpy2.robjects import pandas2ri
     pandas2ri.activate()
 except ImportError:
     pandas2ri = None
     from rpy2.robjects import numpy2ri
     numpy2ri.activate()
 
 # IPython imports
 
 from IPython.core.displaypub import publish_display_data
 from IPython.core.magic import (Magics, magics_class, line_magic,
                                 line_cell_magic, needs_local_scope)
 from IPython.testing.skipdoctest import skip_doctest
 from IPython.core.magic_arguments import (
     argument, magic_arguments, parse_argstring
 )
 from IPython.external.simplegeneric import generic
 from IPython.utils.py3compat import (str_to_unicode, unicode_to_str, PY3,
                                      unicode_type)
+from IPython.utils.text import dedent
 
 class RInterpreterError(ri.RRuntimeError):
     """An error when running R code in a %%R magic cell."""
     def __init__(self, line, err, stdout):
         self.line = line
         self.err = err.rstrip()
         self.stdout = stdout.rstrip()
     
     def __unicode__(self):
         s = 'Failed to parse and evaluate line %r.\nR error message: %r' % \
                 (self.line, self.err)
         if self.stdout and (self.stdout != self.err):
             s += '\nR stdout:\n' + self.stdout
         return s
     
     if PY3:
         __str__ = __unicode__
     else:
         def __str__(self):
             return unicode_to_str(unicode(self), 'utf-8')
 
 def Rconverter(Robj, dataframe=False):
     """
     Convert an object in R's namespace to one suitable
     for ipython's namespace.
 
     For a data.frame, it tries to return a structured array.
     It first checks for colnames, then names.
     If all are NULL, it returns np.asarray(Robj), else
     it tries to construct a recarray
 
     Parameters
     ----------
 
     Robj: an R object returned from rpy2
     """
     is_data_frame = ro.r('is.data.frame')
     colnames = ro.r('colnames')
     rownames = ro.r('rownames') # with pandas, these could be used for the index
     names = ro.r('names')
 
     if dataframe:
         as_data_frame = ro.r('as.data.frame')
         cols = colnames(Robj)
         _names = names(Robj)
         if cols != ri.NULL:
             Robj = as_data_frame(Robj)
             names = tuple(np.array(cols))
         elif _names != ri.NULL:
             names = tuple(np.array(_names))
         else: # failed to find names
             return np.asarray(Robj)
         Robj = np.rec.fromarrays(Robj, names = names)
     return np.asarray(Robj)
 
 @generic
 def pyconverter(pyobj):
     """Convert Python objects to R objects. Add types using the decorator:
     
     @pyconverter.when_type
     """
     return pyobj
 
 # The default conversion for lists seems to make them a nested list. That has
 # some advantages, but is rarely convenient, so for interactive use, we convert
 # lists to a numpy array, which becomes an R vector.
 @pyconverter.when_type(list)
 def pyconverter_list(pyobj):
     return np.asarray(pyobj)
 
 if pandas2ri is None:
     # pandas2ri was new in rpy2 2.3.3, so for now we'll fallback to pandas'
     # conversion function.
     try:
         from pandas import DataFrame
         from pandas.rpy.common import convert_to_r_dataframe
         @pyconverter.when_type(DataFrame)
         def pyconverter_dataframe(pyobj):
             return convert_to_r_dataframe(pyobj, strings_as_factors=True)
     except ImportError:
         pass
 
 @magics_class
 class RMagics(Magics):
     """A set of magics useful for interactive work with R via rpy2.
     """
 
     def __init__(self, shell, Rconverter=Rconverter,
                  pyconverter=pyconverter,
                  cache_display_data=False):
         """
         Parameters
         ----------
 
         shell : IPython shell
         
         Rconverter : callable
             To be called on values taken from R before putting them in the
             IPython namespace.
 
         pyconverter : callable
             To be called on values in ipython namespace before 
             assigning to variables in rpy2.
 
         cache_display_data : bool
             If True, the published results of the final call to R are 
             cached in the variable 'display_cache'.
 
         """
         super(RMagics, self).__init__(shell)
         self.cache_display_data = cache_display_data
 
         self.r = ro.R()
 
         self.Rstdout_cache = []
         self.pyconverter = pyconverter
         self.Rconverter = Rconverter
 
     def eval(self, line):
         '''
         Parse and evaluate a line of R code with rpy2.
         Returns the output to R's stdout() connection, 
         the value generated by evaluating the code, and a
         boolean indicating whether the return value would be
         visible if the line of code were evaluated in an R REPL.
         
         R Code evaluation and visibility determination are
         done via an R call of the form withVisible({<code>})
         
         '''
         old_writeconsole = ri.get_writeconsole()
         ri.set_writeconsole(self.write_console)
         try:
             res = ro.r("withVisible({%s})" % line)
             value = res[0] #value (R object)
             visible = ro.conversion.ri2py(res[1])[0] #visible (boolean)
         except (ri.RRuntimeError, ValueError) as exception:
             warning_or_other_msg = self.flush() # otherwise next return seems to have copy of error
             raise RInterpreterError(line, str_to_unicode(str(exception)), warning_or_other_msg)
         text_output = self.flush()
         ri.set_writeconsole(old_writeconsole)
         return text_output, value, visible
 
     def write_console(self, output):
         '''
         A hook to capture R's stdout in a cache.
         '''
         self.Rstdout_cache.append(output)
 
     def flush(self):
         '''
         Flush R's stdout cache to a string, returning the string.
         '''
         value = ''.join([str_to_unicode(s, 'utf-8') for s in self.Rstdout_cache])
         self.Rstdout_cache = []
         return value
 
     @skip_doctest
     @needs_local_scope
     @line_magic
     def Rpush(self, line, local_ns=None):
         '''
         A line-level magic for R that pushes
         variables from python to rpy2. The line should be made up
         of whitespace separated variable names in the IPython
         namespace::
 
             In [7]: import numpy as np
 
             In [8]: X = np.array([4.5,6.3,7.9])
 
             In [9]: X.mean()
             Out[9]: 6.2333333333333343
 
             In [10]: %Rpush X
 
             In [11]: %R mean(X)
             Out[11]: array([ 6.23333333])
 
         '''
         if local_ns is None:
             local_ns = {}
 
         inputs = line.split(' ')
         for input in inputs:
             try:
                 val = local_ns[input]
             except KeyError:
                 try:
                     val = self.shell.user_ns[input]
                 except KeyError:
                     # reraise the KeyError as a NameError so that it looks like
                     # the standard python behavior when you use an unnamed
                     # variable
                     raise NameError("name '%s' is not defined" % input)
 
             self.r.assign(input, self.pyconverter(val))
 
     @skip_doctest
     @magic_arguments()
     @argument(
         '-d', '--as_dataframe', action='store_true',
         default=False,
         help='Convert objects to data.frames before returning to ipython.'
         )
     @argument(
         'outputs',
         nargs='*',
         )
     @line_magic
     def Rpull(self, line):
         '''
         A line-level magic for R that pulls
         variables from python to rpy2::
 
             In [18]: _ = %R x = c(3,4,6.7); y = c(4,6,7); z = c('a',3,4)
 
             In [19]: %Rpull x  y z
 
             In [20]: x
             Out[20]: array([ 3. ,  4. ,  6.7])
 
             In [21]: y
             Out[21]: array([ 4.,  6.,  7.])
 
             In [22]: z
             Out[22]:
             array(['a', '3', '4'],
                   dtype='|S1')
 
 
         If --as_dataframe, then each object is returned as a structured array
         after first passed through "as.data.frame" in R before
         being calling self.Rconverter. 
         This is useful when a structured array is desired as output, or
         when the object in R has mixed data types. 
         See the %%R docstring for more examples.
 
         Notes
         -----
 
         Beware that R names can have '.' so this is not fool proof.
         To avoid this, don't name your R objects with '.'s...
 
         '''
         args = parse_argstring(self.Rpull, line)
         outputs = args.outputs
         for output in outputs:
             self.shell.push({output:self.Rconverter(self.r(output),dataframe=args.as_dataframe)})
 
     @skip_doctest
     @magic_arguments()
     @argument(
         '-d', '--as_dataframe', action='store_true',
         default=False,
         help='Convert objects to data.frames before returning to ipython.'
         )
     @argument(
         'output',
         nargs=1,
         type=str,
         )
     @line_magic
     def Rget(self, line):
         '''
         Return an object from rpy2, possibly as a structured array (if possible).
         Similar to Rpull except only one argument is accepted and the value is 
         returned rather than pushed to self.shell.user_ns::
 
             In [3]: dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')]
 
             In [4]: datapy = np.array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5, 'e')], dtype=dtype)
 
             In [5]: %R -i datapy
 
             In [6]: %Rget datapy
             Out[6]: 
             array([['1', '2', '3', '4'],
                    ['2', '3', '2', '5'],
                    ['a', 'b', 'c', 'e']], 
                   dtype='|S1')
 
             In [7]: %Rget -d datapy
             Out[7]: 
             array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5.0, 'e')], 
                   dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')])
 
         '''
         args = parse_argstring(self.Rget, line)
         output = args.output
         return self.Rconverter(self.r(output[0]),dataframe=args.as_dataframe)
 
 
     @skip_doctest
     @magic_arguments()
     @argument(
         '-i', '--input', action='append',
         help='Names of input variable from shell.user_ns to be assigned to R variables of the same names after calling self.pyconverter. Multiple names can be passed separated only by commas with no whitespace.'
         )
     @argument(
         '-o', '--output', action='append',
         help='Names of variables to be pushed from rpy2 to shell.user_ns after executing cell body and applying self.Rconverter. Multiple names can be passed separated only by commas with no whitespace.'
         )
     @argument(
         '-w', '--width', type=int,
         help='Width of png plotting device sent as an argument to *png* in R.'
         )
     @argument(
         '-h', '--height', type=int,
         help='Height of png plotting device sent as an argument to *png* in R.'
         )
 
     @argument(
         '-d', '--dataframe', action='append',
         help='Convert these objects to data.frames and return as structured arrays.'
         )
     @argument(
         '-u', '--units', type=unicode_type, choices=["px", "in", "cm", "mm"],
         help='Units of png plotting device sent as an argument to *png* in R. One of ["px", "in", "cm", "mm"].'
         )
     @argument(
         '-r', '--res', type=int,
         help='Resolution of png plotting device sent as an argument to *png* in R. Defaults to 72 if *units* is one of ["in", "cm", "mm"].'
         )
     @argument(
         '-p', '--pointsize', type=int,
         help='Pointsize of png plotting device sent as an argument to *png* in R.'
         )
     @argument(
         '-b', '--bg',
         help='Background of png plotting device sent as an argument to *png* in R.'
         )
     @argument(
         '-n', '--noreturn',
         help='Force the magic to not return anything.',
         action='store_true',
         default=False
         )
     @argument(
         'code',
         nargs='*',
         )
     @needs_local_scope
     @line_cell_magic
     def R(self, line, cell=None, local_ns=None):
         '''
         Execute code in R, and pull some of the results back into the Python namespace.
 
         In line mode, this will evaluate an expression and convert the returned value to a Python object.
         The return value is determined by rpy2's behaviour of returning the result of evaluating the
         final line. 
 
         Multiple R lines can be executed by joining them with semicolons::
 
             In [9]: %R X=c(1,4,5,7); sd(X); mean(X)
             Out[9]: array([ 4.25])
 
         In cell mode, this will run a block of R code. The resulting value
         is printed if it would printed be when evaluating the same code 
         within a standard R REPL.
         
         Nothing is returned to python by default in cell mode::
 
             In [10]: %%R
                ....: Y = c(2,4,3,9)
                ....: summary(lm(Y~X))
 
             Call:
             lm(formula = Y ~ X)
 
             Residuals:
                 1     2     3     4
              0.88 -0.24 -2.28  1.64
 
             Coefficients:
                         Estimate Std. Error t value Pr(>|t|)
             (Intercept)   0.0800     2.3000   0.035    0.975
             X             1.0400     0.4822   2.157    0.164
 
             Residual standard error: 2.088 on 2 degrees of freedom
             Multiple R-squared: 0.6993,Adjusted R-squared: 0.549
             F-statistic: 4.651 on 1 and 2 DF,  p-value: 0.1638
 
         In the notebook, plots are published as the output of the cell::
 
             %R plot(X, Y)
 
         will create a scatter plot of X bs Y.
 
         If cell is not None and line has some R code, it is prepended to
         the R code in cell.
 
         Objects can be passed back and forth between rpy2 and python via the -i -o flags in line::
 
             In [14]: Z = np.array([1,4,5,10])
 
             In [15]: %R -i Z mean(Z)
             Out[15]: array([ 5.])
 
 
             In [16]: %R -o W W=Z*mean(Z)
             Out[16]: array([  5.,  20.,  25.,  50.])
 
             In [17]: W
             Out[17]: array([  5.,  20.,  25.,  50.])
 
         The return value is determined by these rules:
 
         * If the cell is not None, the magic returns None.
 
         * If the cell evaluates as False, the resulting value is returned
           unless the final line prints something to the console, in
           which case None is returned.
 
         * If the final line results in a NULL value when evaluated
           by rpy2, then None is returned.
 
         * No attempt is made to convert the final value to a structured array.
           Use the --dataframe flag or %Rget to push / return a structured array.
 
         * If the -n flag is present, there is no return value.
 
         * A trailing ';' will also result in no return value as the last
           value in the line is an empty string.
 
         The --dataframe argument will attempt to return structured arrays. 
         This is useful for dataframes with
         mixed data types. Note also that for a data.frame, 
         if it is returned as an ndarray, it is transposed::
 
             In [18]: dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')]
 
             In [19]: datapy = np.array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5, 'e')], dtype=dtype)
 
             In [20]: %%R -o datar
             datar = datapy
                ....: 
 
             In [21]: datar
             Out[21]: 
             array([['1', '2', '3', '4'],
                    ['2', '3', '2', '5'],
                    ['a', 'b', 'c', 'e']], 
                   dtype='|S1')
 
             In [22]: %%R -d datar
             datar = datapy
                ....: 
 
             In [23]: datar
             Out[23]: 
             array([(1, 2.9, 'a'), (2, 3.5, 'b'), (3, 2.1, 'c'), (4, 5.0, 'e')], 
                   dtype=[('x', '<i4'), ('y', '<f8'), ('z', '|S1')])
 
         The --dataframe argument first tries colnames, then names.
         If both are NULL, it returns an ndarray (i.e. unstructured)::
 
             In [1]: %R mydata=c(4,6,8.3); NULL
 
             In [2]: %R -d mydata
 
             In [3]: mydata
             Out[3]: array([ 4. ,  6. ,  8.3])
 
             In [4]: %R names(mydata) = c('a','b','c'); NULL
 
             In [5]: %R -d mydata
 
             In [6]: mydata
             Out[6]: 
             array((4.0, 6.0, 8.3), 
                   dtype=[('a', '<f8'), ('b', '<f8'), ('c', '<f8')])
 
             In [7]: %R -o mydata
 
             In [8]: mydata
             Out[8]: array([ 4. ,  6. ,  8.3])
 
         '''
 
         args = parse_argstring(self.R, line)
 
         # arguments 'code' in line are prepended to
         # the cell lines
 
         if cell is None:
             code = ''
             return_output = True
             line_mode = True
         else:
             code = cell
             return_output = False
             line_mode = False
 
         code = ' '.join(args.code) + code
 
         # if there is no local namespace then default to an empty dict
         if local_ns is None:
             local_ns = {}
 
         if args.input:
             for input in ','.join(args.input).split(','):
                 try:
                     val = local_ns[input]
                 except KeyError:
                     try:
                         val = self.shell.user_ns[input]
                     except KeyError:
                         raise NameError("name '%s' is not defined" % input)
                 self.r.assign(input, self.pyconverter(val))
 
         if getattr(args, 'units') is not None:
             if args.units != "px" and getattr(args, 'res') is None:
                 args.res = 72
             args.units = '"%s"' % args.units
 
         png_argdict = dict([(n, getattr(args, n)) for n in ['units', 'res', 'height', 'width', 'bg', 'pointsize']])
         png_args = ','.join(['%s=%s' % (o,v) for o, v in png_argdict.items() if v is not None])
         # execute the R code in a temporary directory
 
         tmpd = tempfile.mkdtemp()
         self.r('png("%s/Rplots%%03d.png",%s)' % (tmpd.replace('\\', '/'), png_args))
 
         text_output = ''
         try:
             if line_mode:
                 for line in code.split(';'):
                     text_result, result, visible = self.eval(line)
                     text_output += text_result
                 if text_result:
                     # the last line printed something to the console so we won't return it
                     return_output = False
             else:
                 text_result, result, visible = self.eval(code)
                 text_output += text_result
                 if visible:
                     old_writeconsole = ri.get_writeconsole()
                     ri.set_writeconsole(self.write_console) 
                     ro.r.show(result)
                     text_output += self.flush()
                     ri.set_writeconsole(old_writeconsole)
         
         except RInterpreterError as e:
             print(e.stdout)
             if not e.stdout.endswith(e.err):
                 print(e.err)
             rmtree(tmpd)
             return
 
         self.r('dev.off()')
 
         # read out all the saved .png files
 
         images = [open(imgfile, 'rb').read() for imgfile in glob("%s/Rplots*png" % tmpd)]
 
         # now publish the images
         # mimicking IPython/zmq/pylab/backend_inline.py
         fmt = 'png'
         mimetypes = { 'png' : 'image/png', 'svg' : 'image/svg+xml' }
         mime = mimetypes[fmt]
 
         # publish the printed R objects, if any
 
         display_data = []
         if text_output:
             display_data.append(('RMagic.R', {'text/plain':text_output}))
 
         # flush text streams before sending figures, helps a little with output
         for image in images:
             # synchronization in the console (though it's a bandaid, not a real sln)
             sys.stdout.flush(); sys.stderr.flush()
             display_data.append(('RMagic.R', {mime: image}))
 
         # kill the temporary directory
         rmtree(tmpd)
 
         # try to turn every output into a numpy array
         # this means that output are assumed to be castable
         # as numpy arrays
 
         if args.output:
             for output in ','.join(args.output).split(','):
                 self.shell.push({output:self.Rconverter(self.r(output), dataframe=False)})
 
         if args.dataframe:
             for output in ','.join(args.dataframe).split(','):
                 self.shell.push({output:self.Rconverter(self.r(output), dataframe=True)})
 
         for tag, disp_d in display_data:
             publish_display_data(tag, disp_d)
 
         # this will keep a reference to the display_data
         # which might be useful to other objects who happen to use
         # this method
 
         if self.cache_display_data:
             self.display_cache = display_data
 
         # if in line mode and return_output, return the result as an ndarray
         if return_output and not args.noreturn:
             if result != ri.NULL:
                 return self.Rconverter(result, dataframe=False)
 
 __doc__ = __doc__.format(
-                R_DOC = ' '*8 + RMagics.R.__doc__,
-                RPUSH_DOC = ' '*8 + RMagics.Rpush.__doc__,
-                RPULL_DOC = ' '*8 + RMagics.Rpull.__doc__,
-                RGET_DOC = ' '*8 + RMagics.Rget.__doc__
+                R_DOC = dedent(RMagics.R.__doc__),
+                RPUSH_DOC = dedent(RMagics.Rpush.__doc__),
+                RPULL_DOC = dedent(RMagics.Rpull.__doc__),
+                RGET_DOC = dedent(RMagics.Rget.__doc__)
 )
 
 
 def load_ipython_extension(ip):
     """Load the extension in IPython."""
     ip.register_magics(RMagics)
     # Initialising rpy2 interferes with readline. Since, at this point, we've
     # probably just loaded rpy2, we reset the delimiters. See issue gh-2759.
     if ip.has_readline:
         ip.readline.set_completer_delims(ip.readline_delims)

IPython/parallel/client/magics.py

@@ -1,442 +1,441 b''
 # encoding: utf-8
 """
 =============
 parallelmagic
 =============
 
 Magic command interface for interactive parallel work.
 
 Usage
 =====
 
 ``%autopx``
 
 {AUTOPX_DOC}
 
 ``%px``
 
 {PX_DOC}
 
 ``%pxresult``
 
 {RESULT_DOC}
 
 ``%pxconfig``
 
 {CONFIG_DOC}
 
 """
 from __future__ import print_function
 
 #-----------------------------------------------------------------------------
 #  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.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import ast
 import re
 
 from IPython.core.error import UsageError
 from IPython.core.magic import Magics
 from IPython.core import magic_arguments
 from IPython.testing.skipdoctest import skip_doctest
+from IPython.utils.text import dedent
 
 #-----------------------------------------------------------------------------
 # Definitions of magic functions for use with IPython
 #-----------------------------------------------------------------------------
 
 
 NO_LAST_RESULT = "%pxresult recalls last %px result, which has not yet been used."
 
 def exec_args(f):
     """decorator for adding block/targets args for execution
     
     applied to %pxconfig and %%px
     """
     args = [
         magic_arguments.argument('-b', '--block', action="store_const",
             const=True, dest='block',
             help="use blocking (sync) execution",
         ),
         magic_arguments.argument('-a', '--noblock', action="store_const",
             const=False, dest='block',
             help="use non-blocking (async) execution",
         ),
         magic_arguments.argument('-t', '--targets', type=str,
             help="specify the targets on which to execute",
         ),
         magic_arguments.argument('--local', action="store_const",
             const=True, dest="local",
             help="also execute the cell in the local namespace",
         ),
         magic_arguments.argument('--verbose', action="store_const",
             const=True, dest="set_verbose",
             help="print a message at each execution",
         ),
         magic_arguments.argument('--no-verbose', action="store_const",
             const=False, dest="set_verbose",
             help="don't print any messages",
         ),
     ]
     for a in args:
         f = a(f)
     return f
 
 def output_args(f):
     """decorator for output-formatting args
     
     applied to %pxresult and %%px
     """
     args = [
         magic_arguments.argument('-r', action="store_const", dest='groupby',
             const='order',
             help="collate outputs in order (same as group-outputs=order)"
         ),
         magic_arguments.argument('-e', action="store_const", dest='groupby',
             const='engine',
             help="group outputs by engine (same as group-outputs=engine)"
         ),
         magic_arguments.argument('--group-outputs', dest='groupby', type=str,
             choices=['engine', 'order', 'type'], default='type',
             help="""Group the outputs in a particular way.
             
             Choices are:
             
-            type: group outputs of all engines by type (stdout, stderr, displaypub, etc.).
-            
-            engine: display all output for each engine together.
-
-            order: like type, but individual displaypub output from each engine is collated.
-                For example, if multiple plots are generated by each engine, the first
-                figure of each engine will be displayed, then the second of each, etc.
+            **type**: group outputs of all engines by type (stdout, stderr, displaypub, etc.).
+            **engine**: display all output for each engine together.
+            **order**: like type, but individual displaypub output from each engine is collated.
+              For example, if multiple plots are generated by each engine, the first
+              figure of each engine will be displayed, then the second of each, etc.
             """
         ),
         magic_arguments.argument('-o', '--out', dest='save_name', type=str,
             help="""store the AsyncResult object for this computation
                  in the global namespace under this name.
             """
         ),
     ]
     for a in args:
         f = a(f)
     return f
 
 class ParallelMagics(Magics):
     """A set of magics useful when controlling a parallel IPython cluster.
     """
     
     # magic-related
     magics = None
     registered = True
     
     # suffix for magics
     suffix = ''
     # A flag showing if autopx is activated or not
     _autopx = False
     # the current view used by the magics:
     view = None
     # last result cache for %pxresult
     last_result = None
     # verbose flag
     verbose = False
     
     def __init__(self, shell, view, suffix=''):
         self.view = view
         self.suffix = suffix
         
         # register magics
         self.magics = dict(cell={},line={})
         line_magics = self.magics['line']
         
         px = 'px' + suffix
         if not suffix:
             # keep %result for legacy compatibility
             line_magics['result'] = self.result
         
         line_magics['pxresult' + suffix] = self.result
         line_magics[px] = self.px
         line_magics['pxconfig' + suffix] = self.pxconfig
         line_magics['auto' + px] = self.autopx
         
         self.magics['cell'][px] = self.cell_px
         
         super(ParallelMagics, self).__init__(shell=shell)
     
     def _eval_target_str(self, ts):
         if ':' in ts:
             targets = eval("self.view.client.ids[%s]" % ts)
         elif 'all' in ts:
             targets = 'all'
         else:
             targets = eval(ts)
         return targets
     
     @magic_arguments.magic_arguments()
     @exec_args
     def pxconfig(self, line):
         """configure default targets/blocking for %px magics"""
         args = magic_arguments.parse_argstring(self.pxconfig, line)
         if args.targets:
             self.view.targets = self._eval_target_str(args.targets)
         if args.block is not None:
             self.view.block = args.block
         if args.set_verbose is not None:
             self.verbose = args.set_verbose
 
     @magic_arguments.magic_arguments()
     @output_args
     @skip_doctest
     def result(self, line=''):
         """Print the result of the last asynchronous %px command.
         
         This lets you recall the results of %px computations after
         asynchronous submission (block=False).
 
         Examples
         --------
         ::
 
             In [23]: %px os.getpid()
             Async parallel execution on engine(s): all
 
             In [24]: %pxresult
             Out[8:10]: 60920
             Out[9:10]: 60921
             Out[10:10]: 60922
             Out[11:10]: 60923
         """
         args = magic_arguments.parse_argstring(self.result, line)
         
         if self.last_result is None:
             raise UsageError(NO_LAST_RESULT)
         
         self.last_result.get()
         self.last_result.display_outputs(groupby=args.groupby)
 
     @skip_doctest
     def px(self, line=''):
         """Executes the given python command in parallel.
         
         Examples
         --------
         ::
 
             In [24]: %px a = os.getpid()
             Parallel execution on engine(s): all
             
             In [25]: %px print a
             [stdout:0] 1234
             [stdout:1] 1235
             [stdout:2] 1236
             [stdout:3] 1237
         """
         return self.parallel_execute(line)
         
     def parallel_execute(self, cell, block=None, groupby='type', save_name=None):
         """implementation used by %px and %%parallel"""
 
         # defaults:
         block = self.view.block if block is None else block
         
         base = "Parallel" if block else "Async parallel"
         
         targets = self.view.targets
         if isinstance(targets, list) and len(targets) > 10:
             str_targets = str(targets[:4])[:-1] + ', ..., ' + str(targets[-4:])[1:]
         else:
             str_targets = str(targets)
         if self.verbose:
             print(base + " execution on engine(s): %s" % str_targets)
         
         result = self.view.execute(cell, silent=False, block=False)
         self.last_result = result
         
         if save_name:
             self.shell.user_ns[save_name] = result
         
         if block:
             result.get()
             result.display_outputs(groupby)
         else:
             # return AsyncResult only on non-blocking submission
             return result
 
     @magic_arguments.magic_arguments()
     @exec_args
     @output_args
     @skip_doctest
     def cell_px(self, line='', cell=None):
         """Executes the cell in parallel.
         
         Examples
         --------
         ::
 
             In [24]: %%px --noblock
                ....: a = os.getpid()
             Async parallel execution on engine(s): all
             
             In [25]: %%px
                ....: print a
             [stdout:0] 1234
             [stdout:1] 1235
             [stdout:2] 1236
             [stdout:3] 1237
         """
         
         args = magic_arguments.parse_argstring(self.cell_px, line)
         
         if args.targets:
             save_targets = self.view.targets
             self.view.targets = self._eval_target_str(args.targets)
         # if running local, don't block until after local has run
         block = False if args.local else args.block
         try:
             ar = self.parallel_execute(cell, block=block,
                                 groupby=args.groupby,
                                 save_name=args.save_name,
             )
         finally:
             if args.targets:
                 self.view.targets = save_targets
         
         # run locally after submitting remote
         block = self.view.block if args.block is None else args.block
         if args.local:
             self.shell.run_cell(cell)
             # now apply blocking behavor to remote execution
             if block:
                 ar.get()
                 ar.display_outputs(args.groupby)
         if not block:
             return ar
     
     @skip_doctest
     def autopx(self, line=''):
         """Toggles auto parallel mode.
 
         Once this is called, all commands typed at the command line are send to
         the engines to be executed in parallel. To control which engine are
         used, the ``targets`` attribute of the view before
         entering ``%autopx`` mode.
 
 
         Then you can do the following::
 
             In [25]: %autopx
             %autopx to enabled
 
             In [26]: a = 10
             Parallel execution on engine(s): [0,1,2,3]
             In [27]: print a
             Parallel execution on engine(s): [0,1,2,3]
             [stdout:0] 10
             [stdout:1] 10
             [stdout:2] 10
             [stdout:3] 10
 
 
             In [27]: %autopx
             %autopx disabled
         """
         if self._autopx:
             self._disable_autopx()
         else:
             self._enable_autopx()
 
     def _enable_autopx(self):
         """Enable %autopx mode by saving the original run_cell and installing
         pxrun_cell.
         """
         # override run_cell
         self._original_run_cell = self.shell.run_cell
         self.shell.run_cell = self.pxrun_cell
 
         self._autopx = True
         print("%autopx enabled")
 
     def _disable_autopx(self):
         """Disable %autopx by restoring the original InteractiveShell.run_cell.
         """
         if self._autopx:
             self.shell.run_cell = self._original_run_cell
             self._autopx = False
             print("%autopx disabled")
 
     def pxrun_cell(self, raw_cell, store_history=False, silent=False):
         """drop-in replacement for InteractiveShell.run_cell.
 
         This executes code remotely, instead of in the local namespace.
 
         See InteractiveShell.run_cell for details.
         """
 
         if (not raw_cell) or raw_cell.isspace():
             return
 
         ipself = self.shell
 
         with ipself.builtin_trap:
             cell = ipself.prefilter_manager.prefilter_lines(raw_cell)
 
             # Store raw and processed history
             if store_history:
                 ipself.history_manager.store_inputs(ipself.execution_count,
                                                   cell, raw_cell)
 
             # ipself.logger.log(cell, raw_cell)
 
             cell_name = ipself.compile.cache(cell, ipself.execution_count)
 
             try:
                 ast.parse(cell, filename=cell_name)
             except (OverflowError, SyntaxError, ValueError, TypeError,
                     MemoryError):
                 # Case 1
                 ipself.showsyntaxerror()
                 ipself.execution_count += 1
                 return None
             except NameError:
                 # ignore name errors, because we don't know the remote keys
                 pass
 
         if store_history:
             # Write output to the database. Does nothing unless
             # history output logging is enabled.
             ipself.history_manager.store_output(ipself.execution_count)
             # Each cell is a *single* input, regardless of how many lines it has
             ipself.execution_count += 1
         if re.search(r'get_ipython\(\)\.magic\(u?["\']%?autopx', cell):
             self._disable_autopx()
             return False
         else:
             try:
                 result = self.view.execute(cell, silent=False, block=False)
             except:
                 ipself.showtraceback()
                 return True
             else:
                 if self.view.block:
                     try:
                         result.get()
                     except:
                         self.shell.showtraceback()
                         return True
                     else:
                         with ipself.builtin_trap:
                             result.display_outputs()
                 return False
 
 
 __doc__ = __doc__.format(
-                AUTOPX_DOC = ' '*8 + ParallelMagics.autopx.__doc__,
-                PX_DOC = ' '*8 + ParallelMagics.px.__doc__,
-                RESULT_DOC = ' '*8 + ParallelMagics.result.__doc__,
-                CONFIG_DOC = ' '*8 + ParallelMagics.pxconfig.__doc__,
+                AUTOPX_DOC = dedent(ParallelMagics.autopx.__doc__),
+                PX_DOC = dedent(ParallelMagics.px.__doc__),
+                RESULT_DOC = dedent(ParallelMagics.result.__doc__),
+                CONFIG_DOC = dedent(ParallelMagics.pxconfig.__doc__),
 )