From 95ed0855ae23e55c10b46903db911265aa1cdd58 2016-06-01 11:19:02 From: Matthias Bussonnier Date: 2016-06-01 11:19:02 Subject: [PATCH] Add some documentation on how to configure prompts. --- diff --git a/docs/source/config/details.rst b/docs/source/config/details.rst index c8b01c7..3f7414b 100644 --- a/docs/source/config/details.rst +++ b/docs/source/config/details.rst @@ -2,52 +2,6 @@ Specific config details ======================= -Prompts -======= - -In the terminal, the format of the input and output prompts can be -customised. This does not currently affect other frontends. - -The following codes in the prompt string will be substituted into the -prompt string: - -====== =================================== ===================================================== -Short Long Notes -====== =================================== ===================================================== -%n,\\# {color.number}{count}{color.prompt} history counter with bolding -\\N {count} history counter without bolding -\\D {dots} series of dots the same width as the history counter -\\T {time} current time -\\w {cwd} current working directory -\\W {cwd_last} basename of CWD -\\Xn {cwd_x[n]} Show the last n terms of the CWD. n=0 means show all. -\\Yn {cwd_y[n]} Like \Xn, but show '~' for $HOME -\\h hostname, up to the first '.' -\\H full hostname -\\u username (from the $USER environment variable) -\\v IPython version -\\$ root symbol ("$" for normal user or "#" for root) -``\\`` escaped '\\' -\\n newline -\\r carriage return -n/a {color.} set terminal colour - see below for list of names -====== =================================== ===================================================== - -Available colour names are: Black, BlinkBlack, BlinkBlue, BlinkCyan, -BlinkGreen, BlinkLightGray, BlinkPurple, BlinkRed, BlinkYellow, Blue, -Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, LightGreen, -LightPurple, LightRed, Purple, Red, White, Yellow. The selected colour -scheme also defines the names *prompt* and *number*. Finally, the name -*normal* resets the terminal to its default colour. - -So, this config:: - - c.PromptManager.in_template = "{color.LightGreen}{time}{color.Yellow} \u{color.normal}>>>" - -will produce input prompts with the time in light green, your username -in yellow, and a ``>>>`` prompt in the default terminal colour. - - .. _termcolour: Terminal Colors @@ -84,27 +38,10 @@ These have shown problems: extensions. Once Gary's readline library is installed, the normal WinXP/2k command prompt works perfectly. -Currently the following color schemes are available: - - * NoColor: uses no color escapes at all (all escapes are empty '' '' - strings). This 'scheme' is thus fully safe to use in any terminal. - * Linux: works well in Linux console type environments: dark - background with light fonts. It uses bright colors for - information, so it is difficult to read if you have a light - colored background. - * LightBG: the basic colors are similar to those in the Linux scheme - but darker. It is easy to read in terminals with light backgrounds. - IPython uses colors for two main groups of things: prompts and tracebacks which are directly printed to the terminal, and the object introspection system which passes large sets of data through a pager. -If you are seeing garbage sequences in your terminal and no colour, you -may need to disable colours: run ``%colors NoColor`` inside IPython, or -add this to a config file:: - - c.InteractiveShell.colors = 'NoColor' - Colors in the pager ------------------- diff --git a/docs/source/config/intro.rst b/docs/source/config/intro.rst index f91e701..d3ab800 100644 --- a/docs/source/config/intro.rst +++ b/docs/source/config/intro.rst @@ -73,11 +73,6 @@ Example config file c.InteractiveShell.editor = 'nano' c.InteractiveShell.xmode = 'Context' - c.PromptManager.in_template = 'In [\#]: ' - c.PromptManager.in2_template = ' .\D.: ' - c.PromptManager.out_template = 'Out[\#]: ' - c.PromptManager.justify = True - c.PrefilterManager.multi_line_specials = True c.AliasManager.user_aliases = [ diff --git a/docs/source/interactive/shell.rst b/docs/source/interactive/shell.rst index 4ba0f54..5724efb 100644 --- a/docs/source/interactive/shell.rst +++ b/docs/source/interactive/shell.rst @@ -63,20 +63,46 @@ switching to any of them. Type ``cd?`` for more details. Prompt customization ==================== -Here are some prompt configurations you can try out interactively by using the -``%config`` magic:: - - %config PromptManager.in_template = r'{color.LightGreen}\u@\h{color.LightBlue}[{color.LightCyan}\Y1{color.LightBlue}]{color.Green}|\#> ' - %config PromptManager.in2_template = r'{color.Green}|{color.LightGreen}\D{color.Green}> ' - %config PromptManager.out_template = r'<\#> ' - - -You can change the prompt configuration to your liking permanently by editing -``ipython_config.py``:: - - c.PromptManager.in_template = r'{color.LightGreen}\u@\h{color.LightBlue}[{color.LightCyan}\Y1{color.LightBlue}]{color.Green}|\#> ' - c.PromptManager.in2_template = r'{color.Green}|{color.LightGreen}\D{color.Green}> ' - c.PromptManager.out_template = r'<\#> ' +Starting at IPython 5.0 the prompt customisation is done by subclassing :class:`IPython.terminal.prompts.Prompt`. + +The custom ``Prompt`` receive the current IPython shell instance as first +argument, which by default is stored as the ``shell`` attribute of the object. +The class can implement optional methods for each of the available prompt types: + + - ``in_prompt_tokens(self, cli=None)``, input prompt , default to ``In [1]`` + - ``continuation_prompt_tokens(self, cli=None, width=None)``, continuation prompt for multi lines (default `...:`) + - ``rewrite_prompt_tokens(self)`` + - ``out_prompt_tokens(self)`` + +Each of these methods should return a list of `(TokenType, Token)` pairs. See documentation of `prompt_toolkit` and/or `Pygments`. + +Here is an example of Prompt class that will insert the current working directory in front of a prompt: + + +.. codeblock:: python + + 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, ' >>>')] + +To set the new prompt, assign it to the `prompts` attribute of the IPython shell: + +.. codeblock:: python + + In[2]: ip = get_ipython() + ...: ip.prompts = MyPrompt(ip) + + ~/ >>> # it works + + +See ``IPython/example/utils/cwd_prompt.py`` for an example of how to write an +extensions that customise prompts. + Read more about the :ref:`configuration system ` for details on how to find ``ipython_config.py``. diff --git a/examples/utils/cwd_prompt.py b/examples/utils/cwd_prompt.py new file mode 100644 index 0000000..1d1b03a --- /dev/null +++ b/examples/utils/cwd_prompt.py @@ -0,0 +1,26 @@ +"""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 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 + + + +