IPython as a system shell
Keywords: manual

Subsections

- Aliases
- Special syntax
- Useful functions and modules
- Directory management
- Prompt customization

#
IPython as a system shell

IPython ships with a special profile called `pysh`, which you can activate at the command line as ``ipython -p pysh'`. This loads `InterpreterExec`, along with some additional facilities and a prompt customized for filesystem navigation.

Note that this does not make IPython a full-fledged system shell. In particular, it has no job control, so if you type Ctrl-Z (under Unix), you'll suspend pysh itself, not the process you just started.

What the shell profile allows you to do is to use the convenient and powerful syntax of Python to do quick scripting at the command line. Below we describe some of its features.

## Aliases

All of your `$PATH` has been loaded as IPython aliases, so you should be able to type any normal system command and have it executed. See `%alias?` and `%unalias?` for details on the alias facilities. See also `%rehash?` and `%rehashx?` for details on the mechanism used to load `$PATH`.

## Special syntax

Any lines which begin with ``~'`, ``/'` and ``.'` will be executed as shell commands instead of as Python code. The special escapes below are also recognized. `!cmd` is valid in single or multi-line input, all others are only valid in single-line input:

`!cmd`
  pass `cmd' directly to the shell
`!!cmd`
  execute `cmd' and return output as a list (split on `\n')
`$var=cmd`
  capture output of cmd into var, as a string
`$$var=cmd`
  capture output of cmd into var, as a list (split on `\n')

The `$`/`$$` syntaxes make Python variables from system output, which you can later use for further scripting. The converse is also possible: when executing an alias or calling to the system via `!`/`!!`, you can expand any python variable or expression by prepending it with `$`. Full details of the allowed syntax can be found in Python's PEP 215.

A few brief examples will illustrate these (note that the indentation below may be incorrectly displayed):

`fperez[~/test]|3> !ls *s.py`
`scopes.py strings.py`

ls is an internal alias, so there's no need to use `!`:

`fperez[~/test]|4> ls *s.py`
`scopes.py* strings.py`

!!ls will return the output into a Python variable:

`fperez[~/test]|5> !!ls *s.py`
`<5> ['scopes.py', 'strings.py']`
`fperez[~/test]|6> print _5`
`['scopes.py', 'strings.py']`

`$` and `$$` allow direct capture to named variables:

`fperez[~/test]|7> $astr = ls *s.py`
`fperez[~/test]|8> astr`
`<8> 'scopes.py\nstrings.py'`

`fperez[~/test]|9> $$alist = ls *s.py`
`fperez[~/test]|10> alist`
`<10> ['scopes.py', 'strings.py']`

alist is now a normal python list you can loop over. Using `$` will expand back the python values when alias calls are made:

`fperez[~/test]|11> for f in alist:`
`|..> print 'file',f,`
`|..> wc -l $f`
`|..>`
`file scopes.py 13 scopes.py`
`file strings.py 4 strings.py`

Note that you may need to protect your variables with braces if you want to append strings to their names. To copy all files in alist to `.bak` extensions, you must use:

`fperez[~/test]|12> for f in alist:`
`|..> cp $f ${f}.bak`

If you try using `$f.bak`, you'll get an AttributeError exception saying that your string object doesn't have a `.bak` attribute. This is because the `$` expansion mechanism allows you to expand full Python expressions:

`fperez[~/test]|13> echo "sys.platform is: $sys.platform"`
`sys.platform is: linux2`

IPython's input history handling is still active, which allows you to rerun a single block of multi-line input by simply using exec:
`fperez[~/test]|14> $$alist = ls *.eps`
`fperez[~/test]|15> exec _i11`
`file image2.eps 921 image2.eps`
`file image.eps 921 image.eps`

While these are new special-case syntaxes, they are designed to allow very efficient use of the shell with minimal typing. At an interactive shell prompt, conciseness of expression wins over readability.

## Useful functions and modules

The os, sys and shutil modules from the Python standard library are automatically loaded. Some additional functions, useful for shell usage, are listed below. You can request more help about them with ``?`'.

`shell`
  - execute a command in the underlying system shell
`system`
  - like `shell()`, but return the exit status of the command
`sout`
  - capture the output of a command as a string
`lout`
  - capture the output of a command as a list (split on `\n')
`getoutputerror`
  - capture (output,error) of a shell commandss

`sout`/`lout` are the functional equivalents of `$`/`$$`. They are provided to allow you to capture system output in the middle of true python code, function definitions, etc (where `$` and `$$` are invalid).

## Directory management

Since each command passed by pysh to the underlying system is executed in a subshell which exits immediately, you can NOT use !cd to navigate the filesystem.

Pysh provides its own builtin ``%cd`' magic command to move in the filesystem (the `%` is not required with automagic on). It also maintains a list of visited directories (use `%dhist` to see it) and allows direct switching to any of them. Type ``cd?`' for more details.

`%pushd`, `%popd` and `%dirs` are provided for directory stack handling.

## Prompt customization

The supplied `ipythonrc-pysh` profile comes with an example of a very colored and detailed prompt, mainly to serve as an illustration. The valid escape sequences, besides color names, are:

\#
  - Prompt number.
\D
  - Dots, as many as there are digits in \# (so they align).
\w
  - Current working directory (cwd).
\W
  - Basename of current working directory.
\XN
  - Where N=0..5. N terms of the cwd, with $HOME written as ~.
\YN
  - Where N=0..5. Like XN, but if ~ is term N+1 it's also shown.
\u
  - Username.
\H
  - Full hostname.
\h
  - Hostname up to first '.'
\$
  - Root symbol ($ or #).
\t
  - Current time, in H:M:S format.
\v
  - IPython release version.
\n
  - Newline.
\r
  - Carriage return.
\\
  - An explicitly escaped '\'.

You can configure your prompt colors using any ANSI color escape. Each color escape sets the color for any subsequent text, until another escape comes in and changes things. The valid color escapes are:

\C_Black
\C_Blue
\C_Brown
\C_Cyan
\C_DarkGray
\C_Green
\C_LightBlue
\C_LightCyan
\C_LightGray
\C_LightGreen
\C_LightPurple
\C_LightRed
\C_Purple
\C_Red
\C_White
\C_Yellow
\C_Normal
  Stop coloring, defaults to your terminal settings.