Extensions for syntax processing
Keywords: manual

Subsections

- Pasting of code starting with ``>>>` ' or ``...` '
- Input of physical quantities with units

#
Extensions for syntax processing

This isn't for the faint of heart, because the potential for breaking things is quite high. But it can be a very powerful and useful feature. In a nutshell, you can redefine the way IPython processes the user input line to accept new, special extensions to the syntax without needing to change any of IPython's own code.

In the `IPython/Extensions` directory you will find some examples supplied, which we will briefly describe now. These can be used `as is' (and both provide very useful functionality), or you can use them as a starting point for writing your own extensions.

## Pasting of code starting with ``»>` ' or ``...` '

In the python tutorial it is common to find code examples which have been taken from real python sessions. The problem with those is that all the lines begin with either ``>>>` ' or ``...` ', which makes it impossible to paste them all at once. One must instead do a line by line manual copying, carefully removing the leading extraneous characters.

This extension identifies those starting characters and removes them from the input automatically, so that one can paste multi-line examples directly into IPython, saving a lot of time. Please look at the file `InterpreterPasteInput.py` in the `IPython/Extensions` directory for details on how this is done.

IPython comes with a special profile enabling this feature, called `tutorial`. Simply start IPython via ``ipython -p tutorial'` and the feature will be available. In a normal IPython session you can activate the feature by importing the corresponding module with:
`In [1]: import IPython.Extensions.InterpreterPasteInput`

The following is a 'screenshot' of how things work when this extension is on, copying an example from the standard tutorial:

`IPython profile: tutorial`
``
`*** Pasting of code with ">>>" or "..." has been enabled.`
``
`In [1]: >>> def fib2(n): # return Fibonacci series up to n`
`...: ... """Return a list containing the Fibonacci series up to n."""`
`...: ... result = []`
`...: ... a, b = 0, 1`
`...: ... while b < n:`
`...: ... result.append(b) # see below`
`...: ... a, b = b, a+b`
`...: ... return result`
`...:`
``
`In [2]: fib2(10)`
`Out[2]: [1, 1, 2, 3, 5, 8]`

Note that as currently written, this extension does not recognize IPython's prompts for pasting. Those are more complicated, since the user can change them very easily, they involve numbers and can vary in length. One could however extract all the relevant information from the IPython instance and build an appropriate regular expression. This is left as an exercise for the reader.

## Input of physical quantities with units

The module `PhysicalQInput` allows a simplified form of input for physical quantities with units. This file is meant to be used in conjunction with the `PhysicalQInteractive` module (in the same directory) and `Physics.PhysicalQuantities` from Konrad Hinsen's ScientificPython (`http://starship.python.net/crew/hinsen/scientific.html`).

The `Physics.PhysicalQuantities` module defines `PhysicalQuantity` objects, but these must be declared as instances of a class. For example, to define `v` as a velocity of 3 m/s, normally you would write:
`In [1]: v = PhysicalQuantity(3,'m/s')`

Using the `PhysicalQ_Input` extension this can be input instead as:
`In [1]: v = 3 m/s`
which is much more convenient for interactive use (even though it is blatantly invalid Python syntax).

The `physics` profile supplied with IPython (enabled via `'ipython -p physics'`) uses these extensions, which you can also activate with:

`from math import * # math MUST be imported BEFORE PhysicalQInteractive`
`from IPython.Extensions.PhysicalQInteractive import *`
`import IPython.Extensions.PhysicalQInput`