Merge pull request #10600 from Carreau/whatsnew

Regen What's new

docs/source/whatsnew/development.rst

@@ -1,20 +1,21 b''
 =====================
  Development version
 =====================
 
 This document describes in-flight development work.
 
 .. warning::
 
     Please do not edit this file by hand (doing so will likely cause merge
     conflicts for other Pull Requests). Instead, create a new file in the
     `docs/source/whatsnew/pr` folder
 
 
+
 .. DO NOT EDIT THIS LINE BEFORE RELEASE. FEATURE INSERTION POINT.
 
 
 Backwards incompatible changes
 ------------------------------
 
 .. DO NOT EDIT THIS LINE BEFORE RELEASE. INCOMPAT INSERTION POINT.

docs/source/whatsnew/version5.rst

@@ -1,344 +1,346 b''
 ============
  5.x Series
 ============
 
+.. _whatsnew540:
+
 IPython 5.4
 ===========
 
 IPython 5.4-LTS is the first release of IPython after the release of the 6.x
 series which is Python 3 only. It backports most of the new exposed API
 additions made in IPython 6.0 and 6.1 and avoid having to write conditional
 logics depending of the version of IPython.
 
 Please upgrade to pip 9 or greater before upgrading IPython. 
 Failing to do so on Python 2 may lead to a broken IPython install.
 
 Configurable TerminalInteractiveShell
 -------------------------------------
 
 Backported from the 6.x branch as an exceptional new feature. See
 :ghpull:`10373` and :ghissue:`10364`
 
 IPython gained a new ``c.TerminalIPythonApp.interactive_shell_class`` option
 that allow to customize the class used to start the terminal frontend. This
 should allow user to use custom interfaces, like reviving the former readline
 interface which is now a separate package not maintained by the core team.
 
 
 Define ``_repr_mimebundle_``
 ----------------------------
 
 Object can now define `_repr_mimebundle_` in place of multiple `_repr_*_`
 methods and return a full mimebundle. This greatly simplify many implementation
 and allow to publish custom mimetypes (like geojson, plotly, dataframes....).
 See the ``Cutom Display Logic`` example notebook for more informations.
 
 Execution Heuristics
 --------------------
 
 The heuristic for execution in the command line interface is now more biased
 toward executing for single statement. While in IPython 4.x and before a single
 line would be executed when enter is pressed, IPython 5.x would insert a new
 line. For single line statement this is not true anymore and if a single line is
 valid Python, IPython will execute it regardless of the cursor position. Use
 :kbd:`Ctrl-O` to insert a new line. :ghpull:`10489`
 
 
 Implement Display IDs
 ---------------------
 
 Implement display id and ability to update a given display. This should greatly
 simplify a lot of code by removing the need for widgets and allow other frontend
 to implement things like progress-bars.  See :ghpull:`10048`
 
 Miscs
 -----
 
 * ``_mp_main_`` is not reloaded which fixes issues with multiprocessing.
   :ghpull:`10523`
 * Use user colorscheme in Pdb as well :ghpull:`10479`
 * Faster shutdown. :ghpull:`10408` 
 * Fix a crash in reverse search. :ghpull:`10371`
 * added ``Completer.backslash_combining_completions`` boolean option to
  deactivate backslash-tab completion that may conflict with windows path.
 
 IPython 5.3
 ===========
 
 Released on February 24th, 2017. Remarkable changes and fixes:
 
 * Fix a bug in ``set_next_input`` leading to a crash of terminal IPython.
   :ghpull:`10231`, :ghissue:`10296`, :ghissue:`10229`
 * Always wait for editor inputhook for terminal IPython :ghpull:`10239`,
   :ghpull:`10240`
 * Disable ``_ipython_display_`` in terminal :ghpull:`10249`, :ghpull:`10274`
 * Update terminal colors to be more visible by default on windows
   :ghpull:`10260`, :ghpull:`10238`, :ghissue:`10281`
 * Add Ctrl-Z shortcut (suspend) in terminal debugger :ghpull:`10254`,
   :ghissue:`10273`
 * Indent on new line by looking at the text before the cursor :ghpull:`10264`,
   :ghpull:`10275`, :ghissue:`9283`
 * Update QtEventloop integration to fix some matplotlib integration issues
   :ghpull:`10201`, :ghpull:`10311`, :ghissue:`10201`
 * Respect completions display style in terminal debugger :ghpull:`10305`,
   :ghpull:`10313`
 * Add a config option ``TerminalInteractiveShell.extra_open_editor_shortcuts``
   to enable extra shortcuts to open the input in an editor. These are :kbd:`v`
   in vi mode, and :kbd:`C-X C-E` in emacs mode (:ghpull:`10330`).
   The :kbd:`F2` shortcut is always enabled.
 
 IPython 5.2.2
 =============
 
 * Fix error when starting with ``IPCompleter.limit_to__all__`` configured.
 
 IPython 5.2.1
 =============
 
 * Fix tab completion in the debugger. :ghpull:`10223`
 
 IPython 5.2
 ===========
 
 Released on January 29th, 2017. Remarkable changes and fixes:
 
 * restore IPython's debugger to raise on quit. :ghpull:`10009`
 * The configuration value ``c.TerminalInteractiveShell.highlighting_style`` can
   now directly take a class argument for custom color style. :ghpull:`9848`
 * Correctly handle matplotlib figures dpi :ghpull:`9868`
 * Deprecate ``-e`` flag for the ``%notebook`` magic that had no effects.
   :ghpull:`9872`
 * You can now press F2 while typing at a terminal prompt to edit the contents
   in your favourite terminal editor. Set the :envvar:`EDITOR` environment
   variable to pick which editor is used. :ghpull:`9929`
 * sdists will now only be ``.tar.gz`` as per upstream PyPI requirements.
   :ghpull:`9925`
 * :any:`IPython.core.debugger` have gained a ``set_trace()`` method for
   convenience. :ghpull:`9947`
 * The 'smart command mode' added to the debugger in 5.0 was removed, as more
   people preferred the previous behaviour. Therefore, debugger commands such as
   ``c`` will act as debugger commands even when ``c`` is defined as a variable.
   :ghpull:`10050`
 * Fixes OS X event loop issues at startup, :ghpull:`10150`
 * Deprecate the ``%autoindent`` magic. :ghpull:`10176`
 * Emit a :any:`DeprecationWarning` when setting the deprecated
   ``limit_to_all`` option of the completer. :ghpull:`10198`
 * The :cellmagic:`capture` magic can now capture the result of a cell (from an
   expression on the last line), as well as printed and displayed output.
   :ghpull:`9851`.
 
 
 Changes of behavior to :any:`InteractiveShellEmbed`.
 
 :any:`InteractiveShellEmbed` interactive behavior have changed a bit in between
 5.1 and 5.2. By default ``%kill_embedded`` magic will prevent further invocation
 of the current ``call location`` instead of preventing further invocation of
 the current instance creation location. For most use case this will not change
 much for you, though previous behavior was confusing and less consistent with
 previous IPython versions.
 
 You can now deactivate instances by using ``%kill_embedded --instance`` flag,
 (or ``-i`` in short). The ``%kill_embedded`` magic also gained a
 ``--yes``/``-y`` option which skip confirmation step, and  ``-x``/``--exit``
 which also exit the current embedded call without asking for confirmation.
 
 See :ghpull:`10207`.
 
 
 
 IPython 5.1
 ===========
 
 * Broken ``%timeit`` on Python2 due to the use of ``__qualname__``. :ghpull:`9804`
 * Restore ``%gui qt`` to create and return a ``QApplication`` if necessary. :ghpull:`9789`
 * Don't set terminal title by default. :ghpull:`9801`
 * Preserve indentation when inserting newlines with ``Ctrl-O``. :ghpull:`9770`
 * Restore completion in debugger. :ghpull:`9785`
 * Deprecate ``IPython.core.debugger.Tracer()`` in favor of simpler, newer, APIs. :ghpull:`9731`
 * Restore ``NoOpContext`` context manager removed by mistake, and add `DeprecationWarning`. :ghpull:`9765`
 * Add option allowing ``Prompt_toolkit`` to use 24bits colors. :ghpull:`9736`
 * Fix for closing interactive matplotlib windows on OS X. :ghpull:`9854`
 * An embedded interactive shell instance can be used more than once. :ghpull:`9843`
 * More robust check for whether IPython is in a terminal. :ghpull:`9833`
 * Better pretty-printing of dicts on PyPy. :ghpull:`9827`
 * Some coloured output now looks better on dark background command prompts in Windows.
   :ghpull:`9838`
 * Improved tab completion of paths on Windows . :ghpull:`9826`
 * Fix tkinter event loop integration on Python 2 with ``future`` installed. :ghpull:`9824`
 * Restore ``Ctrl-\`` as a shortcut to quit IPython.
 * Make ``get_ipython()`` accessible when modules are imported by startup files. :ghpull:`9818`
 * Add support for running directories containing a ``__main__.py`` file with the
   ``ipython`` command. :ghpull:`9813`
 
 
 True Color feature
 ------------------
 
 ``prompt_toolkit`` uses pygments styles for syntax highlighting. By default, the
 colors specified in the style are approximated using a standard 256-color
 palette. ``prompt_toolkit`` also supports 24bit, a.k.a. "true", a.k.a. 16-million
 color escape sequences which enable compatible terminals to display the exact
 colors specified instead of an approximation. This true_color option exposes
 that capability in prompt_toolkit to the IPython shell.
 
 Here is a good source for the current state of true color support in various
 terminal emulators and software projects: https://gist.github.com/XVilka/8346728
 
 
 
 IPython 5.0
 ===========
 
 Released July 7, 2016
 
 New terminal interface
 ----------------------
 
 IPython 5 features a major upgrade to the terminal interface, bringing live
 syntax highlighting as you type, proper multiline editing and multiline paste,
 and tab completions that don't clutter up your history.
 
 .. image:: ../_images/ptshell_features.png
     :alt: New terminal interface features
     :align: center
     :target: ../_images/ptshell_features.png
 
 These features are provided by the Python library `prompt_toolkit
 <http://python-prompt-toolkit.readthedocs.io/en/stable/>`__, which replaces
 ``readline`` throughout our terminal interface.
 
 Relying on this pure-Python, cross platform module also makes it simpler to
 install IPython. We have removed dependencies on ``pyreadline`` for Windows and
 ``gnureadline`` for Mac.
 
 Backwards incompatible changes
 ------------------------------
 
 - The ``%install_ext`` magic function, deprecated since 4.0, has now been deleted.
   You can distribute and install extensions as packages on PyPI.
 - Callbacks registered while an event is being handled will now only be called
   for subsequent events; previously they could be called for the current event.
   Similarly, callbacks removed while handling an event *will* always get that
   event. See :ghissue:`9447` and :ghpull:`9453`.
 - Integration with pydb has been removed since pydb development has been stopped
   since 2012, and pydb is not installable from PyPI.
 - The ``autoedit_syntax`` option has apparently been broken for many years.
   It has been removed.
 
 New terminal interface
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The overhaul of the terminal interface will probably cause a range of minor
 issues for existing users.
 This is inevitable for such a significant change, and we've done our best to
 minimise these issues.
 Some changes that we're aware of, with suggestions on how to handle them:
 
 IPython no longer uses readline configuration (``~/.inputrc``). We hope that
 the functionality you want (e.g. vi input mode) will be available by configuring
 IPython directly (see :doc:`/config/options/terminal`).
 If something's missing, please file an issue.
 
 The ``PromptManager`` class has been removed, and the prompt machinery simplified.
 See :ref:`custom_prompts` to customise prompts with the new machinery.
 
 :mod:`IPython.core.debugger` now provides a plainer interface.
 :mod:`IPython.terminal.debugger` contains the terminal debugger using
 prompt_toolkit.
 
 There are new options to configure the colours used in syntax highlighting.
 We have tried to integrate them with our classic  ``--colors`` option and
 ``%colors`` magic, but there's a mismatch in possibilities, so some configurations
 may produce unexpected results. See :ref:`termcolour` for more information.
 
 The new interface is not compatible with Emacs 'inferior-shell' feature. To
 continue using this, add the ``--simple-prompt`` flag to the command Emacs
 runs. This flag disables most IPython features, relying on Emacs to provide
 things like tab completion.
 
 Provisional Changes
 -------------------
 
 Provisional changes are experimental functionality that may, or may not, make
 it into a future version of IPython, and which API may change without warnings.
 Activating these features and using these API are at your own risk, and may have
 security implication for your system, especially if used with the Jupyter notebook,
 
 When running via the Jupyter notebook interfaces, or other compatible client,
 you can enable rich documentation experimental functionality:
 
 When the ``docrepr`` package is installed setting the boolean flag
 ``InteractiveShell.sphinxify_docstring`` to ``True``, will process the various
 object through sphinx before displaying them (see the ``docrepr`` package
 documentation for more information.
 
 You need to also enable the IPython pager display rich HTML representation
 using the ``InteractiveShell.enable_html_pager`` boolean configuration option.
 As usual you can set these configuration options globally in your configuration
 files, alternatively you can turn them on dynamically using the following
 snippet:
 
 .. code-block:: python
 
     ip = get_ipython()
     ip.sphinxify_docstring = True
     ip.enable_html_pager = True
 
 
 You can test the effect of various combinations of the above configuration in
 the Jupyter notebook, with things example like :
 
 .. code-block:: ipython
 
     import numpy as np
     np.histogram?
 
 
 This is part of an effort to make Documentation in Python richer and provide in
 the long term if possible dynamic examples that can contain math, images,
 widgets... As stated above this is nightly experimental feature with a lot of
 (fun) problem to solve. We would be happy to get your feedback and expertise on
 it.
 
 
 
 Deprecated Features
 -------------------
 
 Some deprecated features are listed in this section. Don't forget to enable
 ``DeprecationWarning`` as an error if you are using IPython in a Continuous
 Integration setup or in your testing in general:
 
 .. code-block:: python
 
     import warnings
     warnings.filterwarnings('error', '.*', DeprecationWarning, module='yourmodule.*')
 
 
 - ``hooks.fix_error_editor`` seems unused and is pending deprecation.
 - `IPython/core/excolors.py:ExceptionColors` is  deprecated.
 - `IPython.core.InteractiveShell:write()` is deprecated; use `sys.stdout` instead.
 - `IPython.core.InteractiveShell:write_err()` is deprecated; use `sys.stderr` instead.
 - The `formatter` keyword argument to `Inspector.info` in `IPython.core.oinspec` has no effect.
 - The `global_ns` keyword argument of IPython Embed was deprecated, and has no effect. Use `module` keyword argument instead.
 
 
 Known Issues:
 -------------
 
 - ``<Esc>`` Key does not dismiss the completer and does not clear the current
   buffer. This is an on purpose modification due to current technical
   limitation. Cf :ghpull:`9572`. Escape the control character which is used
   for other shortcut, and there is no practical way to distinguish. Use Ctr-G
   or Ctrl-C as an alternative.
 
 - Cannot use ``Shift-Enter`` and ``Ctrl-Enter`` to submit code in terminal. cf
   :ghissue:`9587` and :ghissue:`9401`. In terminal there is no practical way to
   distinguish these key sequences from a normal new line return.
 
 - ``PageUp`` and ``pageDown`` do not move through completion menu.
 
 - Color styles might not adapt to terminal emulator themes. This will need new
   version of Pygments to be released, and can be mitigated with custom themes.
 
 

docs/source/whatsnew/version6.rst

@@ -1,188 +1,241 b''
 ============
  6.x Series
 ============
 
+.. _whatsnew610:
+
+IPython 6.1
+===========
+
+- Quotes in a filename are always escaped during tab-completion on non-Windows.
+  :ghpull:`10069`
+
+- Variables now shadow magics in autocompletion. See :ghissue:`4877` and :ghpull:`10542`.
+
+- Added the ability to add parameters to alias_magic. For example ::
+
+    In [2]: %alias_magic hist history --params "-l 2" --line
+    Created `%hist` as an alias for `%history -l 2`.
+
+    In [3]: hist
+    %alias_magic hist history --params "-l 30" --line
+    %alias_magic hist history --params "-l 2" --line
+
+Previously it was only possible to have an alias attached to a single function,
+and you would have to pass in the given parameters every time::
+
+    In [4]: %alias_magic hist history --line
+    Created `%hist` as an alias for `%history`.
+
+    In [5]: hist -l 2
+    hist
+    %alias_magic hist history --line
+
+- To suppress log state messages, you can now either use ``%logstart -q``, pass
+  ``--LoggingMagics.quiet=True`` on the command line, or set
+  ``c.LoggingMagics.quiet=True`` in your configuration file.
+
+- An additional flag ``--TerminalInteractiveShell.term_title_format`` is
+  introduced to allow the user to control the format of the terminal title.  It
+  is specified as a python format string, and currently the only variable it
+  will format is ``{cwd}``.
+
+
+The following changes were also added to IPython 5.4, see :ref:`what's new in IPython 5.4 <whatsnew540>`
+for more detail description:
+
+- ``TerminalInteractiveShell`` is configurable and can be configured to
+  (re)-use the readline interface.
+
+- objects can now define a ``_repr_mimebundle_``
+
+- Execution heuristics improve for single line statements
+- ``display()`` can now return a display id to update display areas.
+
+
+.. _whatsnew600:
+
 IPython 6.0
 ===========
 
 Released April 19th, 2017
 
 IPython 6 features a major improvement in the completion machinery which is now
 capable of completing non-executed code. It is also the first version of IPython
 to stop compatibility with Python 2, which is still supported on the bugfix only
 5.x branch. Read below for a non-exhaustive list of new features.
 
 Make sure you have pip > 9.0 before upgrading.
 You should be able to update by using:
 
 .. code::
 
     pip install ipython --upgrade
 
 
 .. note::
 
     If your pip version is greater than or equal to pip 9.0.1 you will automatically get
     the most recent version of IPython compatible with your system: on Python 2 you 
     will get the latest IPython 5.x bugfix, while in Python 3
     you will get the latest 6.x stable version.
 
 New completion API and Interface
 --------------------------------
 
 The completer Completion API has seen an overhaul, and the new completer has
 plenty of improvements both from the end users of terminal IPython and for
 consumers of the API.
 
 This new API is capable of pulling completions from :any:`jedi`, thus allowing
 type inference on non-executed code. If :any:`jedi` is installed, completions like
 the following are now possible without code evaluation:
 
     >>> data = ['Number of users', 123_456]
     ... data[0].<tab>
 
 That is to say, IPython is now capable of inferring that `data[0]` is a string,
 and will suggest completions like `.capitalize`. The completion power of IPython
 will increase with new Jedi releases, and a number of bug-fixes and more completions
 are already available on the development version of :any:`jedi` if you are curious.
 
 With the help of prompt toolkit, types of completions can be shown in the
 completer interface:
 
 .. image:: ../_images/jedi_type_inference_60.png
     :alt: Jedi showing ability to do type inference
     :align: center
     :width: 400px
     :target: ../_images/jedi_type_inference_60.png
 
 The appearance of the completer is controlled by the
 ``c.TerminalInteractiveShell.display_completions`` option that will show the
 type differently depending on the value among ``'column'``, ``'multicolumn'``
 and ``'readlinelike'``
 
 The use of Jedi also fulfills a number of requests and fixes a number of bugs
 like case-insensitive completion and completion after division operator: See
 :ghpull:`10182`.
 
 Extra patches and updates will be needed to the :mod:`ipykernel` package for
 this feature to be available to other clients like Jupyter Notebook, Lab,
 Nteract, Hydrogen...
 
 The use of Jedi should be barely noticeable on recent machines, but 
 can be slower on older ones.  To tweak the performance, the amount
 of time given to Jedi to compute type inference can be adjusted with
 ``c.IPCompleter.jedi_compute_type_timeout``. The objects whose type were not
 inferred will be shown as ``<unknown>``. Jedi can also be completely deactivated
 by using the ``c.Completer.use_jedi=False`` option.
 
 
 The old ``Completer.complete()`` API is waiting deprecation and should be
 replaced replaced by ``Completer.completions()`` in the near future. Feedback on
 the current state of the API and suggestions are welcome.
 
 Python 3 only codebase
 ----------------------
 
 One of the large challenges in IPython 6.0 has been the adoption of a pure
 Python 3 codebase, which has led to upstream patches in pip,
 pypi and warehouse to make sure Python 2 systems still upgrade to the latest
 compatible Python version.
 
 We remind our Python 2 users that IPython 5 is still compatible with Python 2.7,
 still maintained and will get regular releases. Using pip 9+, upgrading IPython will
 automatically upgrade to the latest version compatible with your system.
 
 .. warning::
 
   If you are on a system using an older version of pip on Python 2, pip may
   still install IPython 6.0 on your system, and IPython will refuse to start.
   You can fix this by upgrading pip, and reinstalling ipython, or forcing pip to
   install an earlier version: ``pip install 'ipython<6'``
 
 The ability to use only Python 3 on the code base of IPython brings a number
 of advantages. Most of the newly written code make use of `optional function type
 annotation <https://www.python.org/dev/peps/pep-0484/>`_ leading to clearer code
 and better documentation.
 
 The total size of the repository has also decreased by about 1500 lines (for the 
 first time excluding the big split for 4.0). The decrease is potentially
 a bit more for the sour as some documents like this one are append only and
 are about 300 lines long.
 
 The removal of the Python2/Python3 shim layer has made the code quite a lot clearer and
 more idiomatic in a number of locations, and much friendlier to work with and
 understand. We hope to further embrace Python 3 capabilities in the next release
 cycle and introduce more of the Python 3 only idioms (yield from, kwarg only,
 general unpacking) in the IPython code base, and see if we can take advantage
 of these to improve user experience with better error messages and
 hints.
 
 
 Configurable TerminalInteractiveShell, readline interface
 ---------------------------------------------------------
 
 IPython gained a new ``c.TerminalIPythonApp.interactive_shell_class`` option
 that allows customizing the class used to start the terminal frontend. This
 should allow a user to use custom interfaces, like reviving the former readline
 interface which is now a separate package not actively maintained by the core
 team. See the project to bring back the readline interface: `rlipython
 <https://github.com/ipython/rlipython>`_.
 
 This change will be backported to the IPython 5.x series.
 
 Misc improvements
 -----------------
 
 
 - The :cellmagic:`capture` magic can now capture the result of a cell (from
   an expression on the last line), as well as printed and displayed output.
   :ghpull:`9851`.
 
 - Pressing Ctrl-Z in the terminal debugger now suspends IPython, as it already
   does in the main terminal prompt.
 
 - Autoreload can now reload ``Enum``. See :ghissue:`10232` and :ghpull:`10316`
 
 - IPython.display has gained a :any:`GeoJSON <IPython.display.GeoJSON>` object.
   :ghpull:`10288` and :ghpull:`10253`
 
 Functions Deprecated in 6.x Development cycle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Loading extensions from ``ipython_extension_dir`` prints a warning that this
   location is pending deprecation. This should only affect users still having
   extensions installed with ``%install_ext`` which has been deprecated since
   IPython 4.0, and removed in 5.0. Extensions still present in
   ``ipython_extension_dir`` may shadow more recently installed versions using
   pip. It is thus recommended to clean ``ipython_extension_dir`` of any
   extension now available as a package.
 
 
 - ``IPython.utils.warn`` was deprecated in IPython 4.0, and has now been removed.
   instead of ``IPython.utils.warn`` inbuilt :any:`warnings` module is used.
 
 
 - The function `IPython.core.oinspect.py:call_tip` is unused, was marked as
   deprecated (raising a `DeprecationWarning`) and marked for later removal.
   :ghpull:`10104`
 
 Backward incompatible changes
 ------------------------------
 
 Functions Removed in 6.x Development cycle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following functions have been removed in the
 development cycle marked for Milestone 6.0.
 
 - ``IPython/utils/process.py`` - ``is_cmd_found``
 - ``IPython/utils/process.py`` - ``pycmd2argv``
 
 - The `--deep-reload` flag and the corresponding options to inject `dreload` or
   `reload` into the interactive namespace have been removed. You have to
   explicitly import `reload` from `IPython.lib.deepreload` to use it.
 
 - The :magic:`profile` used to print the current IPython profile, and which
   was deprecated in IPython 2.0 does now raise a `DeprecationWarning` error when
   used. It is often confused with the :magic:`prun` and the deprecation removal
   should free up the ``profile`` name in future versions.