Include reviews from `@tornaria`

docs/source/config/details.rst

@@ -1,323 +1,321 b''
 =======================
 Specific config details
 =======================
 
 .. _custom_prompts:
 
 Custom Prompts
 ==============
 
 .. versionchanged:: 5.0
 
 From IPython 5, prompts are produced as a list of Pygments tokens, which are
 tuples of (token_type, text). You can customise prompts by writing a method
 which generates a list of tokens.
 
 There are four kinds of prompt:
 
 * The **in** prompt is shown before the first line of input
   (default like ``In [1]:``).
 * The **continuation** prompt is shown before further lines of input
   (default like ``...:``).
 * The **rewrite** prompt is shown to highlight how special syntax has been
   interpreted (default like ``----->``).
 * The **out** prompt is shown before the result from evaluating the input
   (default like ``Out[1]:``).
 
 Custom prompts are supplied together as a class. If you want to customise only
 some of the prompts, inherit from :class:`IPython.terminal.prompts.Prompts`,
 which defines the defaults. The required interface is like this:
 
 .. class:: MyPrompts(shell)
 
    Prompt style definition. *shell* is a reference to the
    :class:`~.TerminalInteractiveShell` instance.
 
-   .. method:: in_prompt_tokens(cli=None)
+   .. method:: in_prompt_tokens()
                continuation_prompt_tokens(self, width=None)
                rewrite_prompt_tokens()
                out_prompt_tokens()
 
       Return the respective prompts as lists of ``(token_type, text)`` tuples.
 
       For continuation prompts, *width* is an integer representing the width of
       the prompt area in terminal columns.
 
-      *cli*, where used, is the prompt_toolkit ``CommandLineInterface`` instance.
-      This is mainly for compatibility with the API prompt_toolkit expects.
 
 Here is an example Prompt class that will show the current working directory
 in the input prompt:
 
 .. code-block:: python
 
     from IPython.terminal.prompts import Prompts, Token
     import os
 
     class MyPrompt(Prompts):
-         def in_prompt_tokens(self, cli=None):
+         def in_prompt_tokens(self):
              return [(Token, os.getcwd()),
                      (Token.Prompt, ' >>>')]
 
 To set the new prompt, assign it to the ``prompts`` attribute of the IPython
 shell:
 
 .. code-block:: python
 
     In [2]: ip = get_ipython()
        ...: ip.prompts = MyPrompt(ip)
 
     /home/bob >>> # it works
 
 See ``IPython/example/utils/cwd_prompt.py`` for an example of how to write
 extensions to customise prompts.
 
 Inside IPython or in a startup script, you can use a custom prompts class
 by setting ``get_ipython().prompts`` to an *instance* of the class.
 In configuration, ``TerminalInteractiveShell.prompts_class`` may be set to
 either the class object, or a string of its full importable name.
 
 To include invisible terminal control sequences in a prompt, use
 ``Token.ZeroWidthEscape`` as the token type. Tokens with this type are ignored
 when calculating the width.
 
 Colours in the prompt are determined by the token types and the highlighting
 style; see below for more details. The tokens used in the default prompts are
 ``Prompt``, ``PromptNum``, ``OutPrompt`` and ``OutPromptNum``.
 
 .. _termcolour:
 
 Terminal Colors
 ===============
 
 .. versionchanged:: 5.0
 
 There are two main configuration options controlling colours.
 
 ``InteractiveShell.colors`` sets the colour of tracebacks and object info (the
 output from e.g. ``zip?``). It may also affect other things if the option below
 is set to ``'legacy'``. It has four case-insensitive values:
 ``'nocolor', 'neutral', 'linux', 'lightbg'``. The default is *neutral*, which
 should be legible on either dark or light terminal backgrounds. *linux* is
 optimised for dark backgrounds and *lightbg* for light ones.
 
 ``TerminalInteractiveShell.highlighting_style`` determines prompt colours and
 syntax highlighting. It takes the name (as a string) or class (as a subclass of
 ``pygments.style.Style``) of a Pygments style, or the special value ``'legacy'``
 to pick a style in accordance with ``InteractiveShell.colors``.
 
 You can see the Pygments styles available on your system by running::
 
     from pygments.styles import get_all_styles
     list(get_all_styles())
 
 Additionally, ``TerminalInteractiveShell.highlighting_style_overrides`` can override
 specific styles in the highlighting. It should be a dictionary mapping Pygments
 token types to strings defining the style. See `Pygments' documentation
 <http://pygments.org/docs/styles/#creating-own-styles>`__ for the language used
 to define styles.
 
 Colors in the pager
 -------------------
 
 On some systems, the default pager has problems with ANSI colour codes.
 To configure your default pager to allow these:
 
 1. Set the environment PAGER variable to ``less``.
 2. Set the environment LESS variable to ``-r`` (plus any other options
    you always want to pass to less by default). This tells less to
    properly interpret control sequences, which is how color
    information is given to your terminal.
 
 .. _editors:
 
 Editor configuration
 ====================
 
 IPython can integrate with text editors in a number of different ways:
 
 * Editors (such as `(X)Emacs`_, vim_ and TextMate_) can
   send code to IPython for execution.
 
 * IPython's ``%edit`` magic command can open an editor of choice to edit
   a code block.
 
 The %edit command (and its alias %ed) will invoke the editor set in your
 environment as :envvar:`EDITOR`. If this variable is not set, it will default
 to vi under Linux/Unix and to notepad under Windows. You may want to set this
 variable properly and to a lightweight editor which doesn't take too long to
 start (that is, something other than a new instance of Emacs). This way you
 can edit multi-line code quickly and with the power of a real editor right
 inside IPython.
 
 You can also control the editor by setting :attr:`TerminalInteractiveShell.editor`
 in :file:`ipython_config.py`.
 
 Vim
 ---
 
 Paul Ivanov's `vim-ipython <https://github.com/ivanov/vim-ipython>`_ provides
 powerful IPython integration for vim.
 
 .. _emacs:
 
 (X)Emacs
 --------
 
 If you are a dedicated Emacs user, and want to use Emacs when IPython's
 ``%edit`` magic command is called you should set up the Emacs server so that
 new requests are handled by the original process. This means that almost no
 time is spent in handling the request (assuming an Emacs process is already
 running). For this to work, you need to set your EDITOR environment variable
 to 'emacsclient'. The code below, supplied by Francois Pinard, can then be
 used in your :file:`.emacs` file to enable the server:
 
 .. code-block:: common-lisp
 
     (defvar server-buffer-clients)
     (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
       (server-start)
       (defun fp-kill-server-with-buffer-routine ()
         (and server-buffer-clients (server-done)))
       (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
 
 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
 currently (X)Emacs and IPython get along very well in other ways.
 
 With (X)EMacs >= 24, You can enable IPython in python-mode with:
 
 .. code-block:: common-lisp
 
     (require 'python)
     (setq python-shell-interpreter "ipython")
 
 .. _`(X)Emacs`: http://www.gnu.org/software/emacs/
 .. _TextMate: http://macromates.com/
 .. _vim: http://www.vim.org/
 
 .. _custom_keyboard_shortcuts:
 
 Keyboard Shortcuts
 ==================
 
 .. versionadded:: 8.11
 
 You can modify, disable or modify keyboard shortcuts for IPython Terminal using
 :std:configtrait:`TerminalInteractiveShell.shortcuts` traitlet.
 
 The list of shortcuts is available in the Configuring IPython :ref:`terminal-shortcuts-list` section.
 
 Advanced configuration
 ----------------------
 
 .. versionchanged:: 5.0
 
 Creating custom commands requires adding custom code to a
 :ref:`startup file <startup_files>`::
 
     from IPython import get_ipython
     from prompt_toolkit.enums import DEFAULT_BUFFER
     from prompt_toolkit.keys import Keys
     from prompt_toolkit.filters import HasFocus, HasSelection, ViInsertMode, EmacsInsertMode
 
     ip = get_ipython()
     insert_mode = ViInsertMode() | EmacsInsertMode()
 
     def insert_unexpected(event):
         buf = event.current_buffer
         buf.insert_text('The Spanish Inquisition')
     # Register the shortcut if IPython is using prompt_toolkit
     if getattr(ip, 'pt_app', None):
         registry = ip.pt_app.key_bindings
         registry.add_binding(Keys.ControlN,
                          filter=(HasFocus(DEFAULT_BUFFER)
                                  & ~HasSelection()
                                  & insert_mode))(insert_unexpected)
 
 
 Here is a second example that bind the key sequence ``j``, ``k`` to switch to
 VI input mode to ``Normal`` when in insert mode::
 
    from IPython import get_ipython
    from prompt_toolkit.enums import DEFAULT_BUFFER
    from prompt_toolkit.filters import HasFocus, ViInsertMode
    from prompt_toolkit.key_binding.vi_state import InputMode
 
    ip = get_ipython()
 
    def switch_to_navigation_mode(event):
       vi_state = event.cli.vi_state
       vi_state.input_mode = InputMode.NAVIGATION
 
    if getattr(ip, 'pt_app', None):
       registry = ip.pt_app.key_bindings
       registry.add_binding(u'j',u'k',
                            filter=(HasFocus(DEFAULT_BUFFER)
                                     & ViInsertMode()))(switch_to_navigation_mode)
 
 For more information on filters and what you can do with the ``event`` object,
 `see the prompt_toolkit docs
 <https://python-prompt-toolkit.readthedocs.io/en/latest/pages/asking_for_input.html#adding-custom-key-bindings>`__.
 
 
 Enter to execute
 ----------------
 
 In the Terminal IPython shell – which by default uses the ``prompt_toolkit``
 interface, the semantic meaning of pressing the :kbd:`Enter` key can be
 ambiguous. In some case :kbd:`Enter` should execute code, and in others it
 should add a new line. IPython uses heuristics to decide whether to execute or
 insert a new line at cursor position. For example, if we detect that the current
 code is not valid Python, then the user is likely editing code and the right
 behavior is to likely to insert a new line. If the current code is a simple
 statement like `ord('*')`, then the right behavior is likely to execute. Though
 the exact desired semantics often varies from users to users.
 
 As the exact behavior of :kbd:`Enter` is ambiguous, it has been special cased
 to allow users to completely configure the behavior they like. Hence you can
 have enter always execute code. If you prefer fancier behavior, you need to get
 your hands dirty and read the ``prompt_toolkit`` and IPython documentation
 though. See :ghpull:`10500`, set the
 ``c.TerminalInteractiveShell.handle_return`` option and get inspiration from the
 following example that only auto-executes the input if it begins with a bang or
 a modulo character (``!`` or ``%``). To use the following code, add it to your
 IPython configuration::
 
     def custom_return(shell):
 
         """This function is required by the API. It takes a reference to
         the shell, which is the same thing `get_ipython()` evaluates to.
         This function must return a function that handles each keypress
         event. That function, named `handle` here, references `shell`
         by closure."""
 
         def handle(event):
 
             """This function is called each time `Enter` is pressed,
             and takes a reference to a Prompt Toolkit event object.
             If the current input starts with a bang or modulo, then
             the input is executed, otherwise a newline is entered,
             followed by any spaces needed to auto-indent."""
 
             # set up a few handy references to nested items...
 
             buffer = event.current_buffer
             document = buffer.document
             text = document.text
 
             if text.startswith('!') or text.startswith('%'): # execute the input...
 
                 buffer.accept_action.validate_and_handle(event.cli, buffer)
 
             else: # insert a newline with auto-indentation...
 
                 if document.line_count > 1: text = text[:document.cursor_position]
                 indent = shell.check_complete(text)[1]
                 buffer.insert_text('\n' + indent)
             
                 # if you just wanted a plain newline without any indentation, you
                 # could use `buffer.insert_text('\n')` instead of the lines above
 
         return handle
 
     c.TerminalInteractiveShell.handle_return = custom_return

examples/Embedding/embed_class_long.py

@@ -1,145 +1,145 b''
 #!/usr/bin/env python
 """An example of how to embed an IPython shell into a running program.
 
 Please see the documentation in the IPython.Shell module for more details.
 
 The accompanying file embed_class_short.py has quick code fragments for
 embedding which you can cut and paste in your code once you understand how
 things work.
 
 The code in this file is deliberately extra-verbose, meant for learning."""
 
 # The basics to get you going:
 
 # IPython injects get_ipython into builtins, so you can know if you have nested
 # copies running.
 
 # Try running this code both at the command line and from inside IPython (with
 # %run example-embed.py)
 
 from IPython.terminal.prompts import Prompts, Token
+from traitlets.config.loader import Config
 
 class CustomPrompt(Prompts):
 
-    def in_prompt_tokens(self, cli=None):
+    def in_prompt_tokens(self):
 
        return [
             (Token.Prompt, 'In <'),
             (Token.PromptNum, str(self.shell.execution_count)),
             (Token.Prompt, '>: '),
             ]
 
     def out_prompt_tokens(self):
        return [
             (Token.OutPrompt, 'Out<'),
             (Token.OutPromptNum, str(self.shell.execution_count)),
             (Token.OutPrompt, '>: '),
         ]
  
 
-from traitlets.config.loader import Config
 try:
     get_ipython
 except NameError:
     nested = 0
     cfg = Config()
     cfg.TerminalInteractiveShell.prompts_class=CustomPrompt
 else:
     print("Running nested copies of IPython.")
     print("The prompts for the nested copy have been modified")
     cfg = Config()
     nested = 1
 
 # First import the embeddable shell class
 from IPython.terminal.embed import InteractiveShellEmbed
 
 # Now create an instance of the embeddable shell. The first argument is a
 # string with options exactly as you would type them if you were starting
 # IPython at the system command line. Any parameters you want to define for
 # configuration can thus be specified here.
 ipshell = InteractiveShellEmbed(config=cfg,
                        banner1 = 'Dropping into IPython',
                        exit_msg = 'Leaving Interpreter, back to program.')
 
 # Make a second instance, you can have as many as you want.
 ipshell2 = InteractiveShellEmbed(config=cfg,
                         banner1 = 'Second IPython instance.')
 
 print('\nHello. This is printed from the main controller program.\n')
 
 # You can then call ipshell() anywhere you need it (with an optional
 # message):
 ipshell('***Called from top level. '
         'Hit Ctrl-D to exit interpreter and continue program.\n'
         'Note that if you use %kill_embedded, you can fully deactivate\n'
         'This embedded instance so it will never turn on again')
 
 print('\nBack in caller program, moving along...\n')
 
 #---------------------------------------------------------------------------
 # More details:
 
 # InteractiveShellEmbed instances don't print the standard system banner and
 # messages. The IPython banner (which actually may contain initialization
 # messages) is available as get_ipython().banner in case you want it.
 
 # InteractiveShellEmbed instances print the following information every time they
 # start:
 
 # - A global startup banner.
 
 # - A call-specific header string, which you can use to indicate where in the
 # execution flow the shell is starting.
 
 # They also print an exit message every time they exit.
 
 # Both the startup banner and the exit message default to None, and can be set
 # either at the instance constructor or at any other time with the
 # by setting the banner and exit_msg attributes.
 
 # The shell instance can be also put in 'dummy' mode globally or on a per-call
 # basis. This gives you fine control for debugging without having to change
 # code all over the place.
 
 # The code below illustrates all this.
 
 
 # This is how the global banner and exit_msg can be reset at any point
 ipshell.banner2 = 'Entering interpreter - New Banner'
 ipshell.exit_msg = 'Leaving interpreter - New exit_msg'
 
 def foo(m):
     s = 'spam'
     ipshell('***In foo(). Try %whos, or print s or m:')
     print('foo says m = ',m)
 
 def bar(n):
     s = 'eggs'
     ipshell('***In bar(). Try %whos, or print s or n:')
     print('bar says n = ',n)
     
 # Some calls to the above functions which will trigger IPython:
 print('Main program calling foo("eggs")\n')
 foo('eggs')
 
 # The shell can be put in 'dummy' mode where calls to it silently return. This
 # allows you, for example, to globally turn off debugging for a program with a
 # single call.
 ipshell.dummy_mode = True
 print('\nTrying to call IPython which is now "dummy":')
 ipshell()
 print('Nothing happened...')
 # The global 'dummy' mode can still be overridden for a single call
 print('\nOverriding dummy mode manually:')
 ipshell(dummy=False)
 
 # Reactivate the IPython shell
 ipshell.dummy_mode = False
 
 print('You can even have multiple embedded instances:')
 ipshell2()
 
 print('\nMain program calling bar("spam")\n')
 bar('spam')
 
 print('Main program finished. Bye!')

examples/utils/cwd_prompt.py

@@ -1,26 +1,25 b''
 """This is an example that shows how to create new prompts for IPython
 """
 
 from IPython.terminal.prompts import Prompts, Token
 import os
 
 class MyPrompt(Prompts):
 
-     def in_prompt_tokens(self, cli=None):
-         return [(Token, os.getcwd()),
-                 (Token.Prompt, '>>>')]
+    def in_prompt_tokens(self):
+        return [
+                (Token, os.getcwd()),
+                (Token.Prompt, ">>>")
+               ]
+
 
 def load_ipython_extension(shell):
     new_prompts = MyPrompt(shell)
     new_prompts.old_prompts = shell.prompts
     shell.prompts = new_prompts
 
 def unload_ipython_extension(shell):
     if not hasattr(shell.prompts, 'old_prompts'):
         print("cannot unload")
     else:
         shell.prompts = shell.prompts.old_prompts
-
-
-
-