


IPYTHON(1)                                             IPYTHON(1)


NAME
       ipython - An Enhanced Interactive Python

SYNOPSIS
       ipython [options] files...

DESCRIPTION
       An  interactive Python shell with automatic history (input and output),
       dynamic object introspection, easier configuration, command completion,
       access  to  the system shell, integration with numerical and scientific
       computing tools, and more.

SPECIAL THREADING OPTIONS
       The following special options are ONLY valid at the  beginning  of  the
       command line, and not later.  This is because they control the initial-
       ization of ipython itself, before the normal option-handling  mechanism
       is active.

       -gthread, -qthread, -q4thread, -wthread, -pylab
              Only  ONE of these can be given, and it can only be given as the
              first option passed to IPython (it will have no  effect  in  any
              other  position).   They  provide threading support for the GTK,
              QT3, QT4 and WXWidgets toolkits, for the matplotlib library  and
              Twisted reactor.

              With  any  of  the  first four options, IPython starts running a
              separate thread for the graphical toolkit's operation,  so  that
              you  can  open  and  control  graphical  elements from within an
              IPython command line, without blocking.  All four provide essen-
              tially  the  same  functionality, respectively for GTK, QT3, QT4
              and WXWidgets (via their Python interfaces).

              Note that with -wthread, you can additionally use the -wxversion
              option  to  request  a  specific version of wx to be used.  This
              requires that you have the wxversion  Python  module  installed,
              which is part of recent wxPython distributions.

              If  -pylab  is given, IPython loads special support for the mat-
              plotlib  library  (http://matplotlib.sourceforge.net),  allowing
              interactive  usage  of  any  of  its  backends as defined in the
              user's .matplotlibrc file.  It automatically activates  GTK,  QT
              or  WX threading for IPyhton if the choice of matplotlib backend
              requires it.  It also modifies the  %run  command  to  correctly
              execute  (without  blocking)  any  matplotlib-based script which
              calls show() at the end.

       -tk    The -g/q/q4/wthread options, and -pylab (if matplotlib  is  con-
              figured  to use GTK, QT or WX), will normally block Tk graphical
              interfaces.  This means that when GTK, QT  or  WX  threading  is
              active,  any attempt to open a Tk GUI will result in a dead win-
              dow, and possibly cause the Python  interpreter  to  crash.   An
              extra  option,  -tk, is available to address this issue.  It can
              ONLY be given as a SECOND option after any of the  above  (-gth-
              read, -qthread, -wthread or -pylab).



                        November 30, 2004                       1





IPYTHON(1)                                             IPYTHON(1)


              If  -tk  is  given,  IPython will try to coordinate Tk threading
              with GTK, QT or WX.  This is however potentially unreliable, and
              you  will have to test on your platform and Python configuration
              to determine whether  it  works  for  you.   Debian  users  have
              reported  success, apparently due to the fact that Debian builds
              all of Tcl, Tk, Tkinter and Python with pthreads support.  Under
              other  Linux  environments  (such as Fedora Core 2), this option
              has caused random crashes and lockups of the Python interpreter.
              Under other operating systems (Mac OSX and Windows), you'll need
              to try it to find out,  since  currently  no  user  reports  are
              available.

              There  is  unfortunately no way for IPython to determine at run-
              time whether -tk will work reliably or not, so you will need  to
              do some experiments before relying on it for regular work.

REGULAR OPTIONS
       After  the above threading options have been given, regular options can
       follow in any order.  All options can be abbreviated to their  shortest
       non-ambiguous  form  and  are case-sensitive.  One or two dashes can be
       used.  Some options have an alternate short form, indicated after a  |.

       Most  options  can  also be set from your ipythonrc configuration file.
       See the provided examples for assistance.  Options given on the comman-
       dline override the values set in the ipythonrc file.

       All  options  with  a  [no]  prepended can be specified in negated form
       (-nooption instead of -option) to turn the feature off.

       -h, --help
              Show summary of options.

       -autocall <val>
              Make IPython automatically call any callable object even if  you
              didn't  type explicit parentheses. For example, 'str 43' becomes
              str(43) automatically.  The value can be '0' to disable the fea-
              ture, '1' for 'smart' autocall, where it is not applied if there
              are no more arguments on the line, and '2' for 'full'  autocall,
              where  all callable objects are automatically called (even if no
              arguments are present).  The default is '1'.

       -[no]autoindent
              Turn automatic indentation on/off.

       -[no]automagic
              Make magic commands automatic (without needing their first char-
              acter  to  be  %).   Type  %magic at the IPython prompt for more
              information.

       -[no]autoedit_syntax
              When a syntax error occurs after editing a  file,  automatically
              open the file to the trouble causing line for convenient fixing.





                        November 30, 2004                       2





IPYTHON(1)                                             IPYTHON(1)


       -[no]banner
              Print the intial information banner (default on).

       -c <command>
              Execute the given command string, and  set  sys.argv  to  ['c'].
              This  is  similar  to  the -c option in the normal Python inter-
              preter.

       -cache_size|cs <n>
              Size of the output cache (maximum number of entries to  hold  in
              memory).   The default is 1000, you can change it permanently in
              your config file.  Setting  it  to  0  completely  disables  the
              caching  system,  and  the  minimum value accepted is 20 (if you
              provide a value less than 20, it is reset to 0 and a warning  is
              issued).   This  limit is defined because otherwise you'll spend
              more time re-flushing a too small cache than working.

       -classic|cl
              Gives IPython a similar feel to the classic Python prompt.

       -colors <scheme>
              Color scheme for prompts  and  exception  reporting.   Currently
              implemented: NoColor, Linux, and LightBG.

       -[no]color_info
              IPython can display information about objects via a set of func-
              tions, and optionally can use colors for this, syntax highlight-
              ing  source  code  and various other elements.  However, because
              this information is passed through a  pager  (like  'less')  and
              many pagers get confused with color codes, this option is off by
              default.  You can test it and turn it  on  permanently  in  your
              ipythonrc  file if it works for you.  As a reference, the 'less'
              pager supplied with Mandrake 8.2 works ok, but  that  in  RedHat
              7.2 doesn't.

              Test it and turn it on permanently if it works with your system.
              The magic function @color_info allows you to toggle this  inter-
              actively for testing.

       -[no]confirm_exit
              Set  to  confirm  when you try to exit IPython with an EOF (Con-
              trol-D in Unix, Control-Z/Enter in Windows). Note that using the
              magic  functions  @Exit  or  @Quit  you can force a direct exit,
              bypassing any confirmation.

       -[no]debug
              Show information about the loading process. Very useful  to  pin
              down  problems  with  your configuration files or to get details
              about session restores.

       -[no]deep_reload
              IPython can use the deep_reload module which reloads changes  in
              modules  recursively  (it replaces the reload() function, so you
              don't need to change anything to use it). deep_reload() forces a



                        November 30, 2004                       3





IPYTHON(1)                                             IPYTHON(1)


              full  reload  of  modules whose code may have changed, which the
              default reload() function does not.

              When deep_reload is off, IPython will use the  normal  reload(),
              but  deep_reload will still be available as dreload(). This fea-
              ture is off by default [which means that you  have  both  normal
              reload() and dreload()].

       -editor <name>
              Which  editor to use with the @edit command. By default, IPython
              will honor your EDITOR environment variable (if not set,  vi  is
              the Unix default and notepad the Windows one). Since this editor
              is invoked on the fly by IPython and is meant for editing  small
              code  snippets,  you may want to use a small, lightweight editor
              here (in case your default EDITOR is something like Emacs).

       -ipythondir <name>
              The name of your  IPython  configuration  directory  IPYTHONDIR.
              This  can  also  be  specified  through the environment variable
              IPYTHONDIR.

       -log|l Generate  a  log  file  of  all  input.  The   file   is   named
              ipython_log.py  in  your  current directory (which prevents logs
              from multiple IPython sessions from trampling each  other).  You
              can  use this to later restore a session by loading your logfile
              as a file to be executed with option -logplay (see below).

       -logfile|lf
              Specify the name of your logfile.

       -logplay|lp
              Replay a previous log. For restoring a session as close as  pos-
              sible  to  the state you left it in, use this option (don't just
              run the logfile). With -logplay, IPython will try to reconstruct
              the  previous  working environment in full, not just execute the
              commands in the logfile.

              When a session is restored, logging is automatically  turned  on
              again  with  the  name of the logfile it was invoked with (it is
              read from the log header). So once you've turned logging on  for
              a  session,  you can quit IPython and reload it as many times as
              you want and it will continue to log  its  history  and  restore
              from the beginning every time.

              Caveats: there are limitations in this option. The history vari-
              ables _i*,_* and _dh don't get restored properly. In the  future
              we  will  try  to  implement  full session saving by writing and
              retrieving a snapshot of the memory state of  IPython.  But  our
              first   attempts  failed  because  of  inherent  limitations  of
              Python's Pickle module, so this may have to wait.

       -[no]messages
              Print messages which IPython collects about its startup  process
              (default on).



                        November 30, 2004                       4





IPYTHON(1)                                             IPYTHON(1)


       -[no]pdb
              Automatically  call the pdb debugger after every uncaught excep-
              tion. If you are used to debugging  using  pdb,  this  puts  you
              automatically  inside of it after any call (either in IPython or
              in code called by it) which triggers  an  exception  which  goes
              uncaught.

       -pydb  Makes  IPython  use  the third party "pydb" package as debugger,
              instead of pdb. Requires that pydb is installed.

       -[no]pprint
              IPython can optionally use the pprint  (pretty  printer)  module
              for  displaying results. pprint tends to give a nicer display of
              nested data structures. If you like it, you can turn it on  per-
              manently in your config file (default off).

       -profile|p <name>
              Assume  that your config file is ipythonrc-<name> (looks in cur-
              rent dir first, then in IPYTHONDIR). This is a quick way to keep
              and  load  multiple config files for different tasks, especially
              if you use the include option of config files. You  can  keep  a
              basic  IPYTHONDIR/ipythonrc  file and then have other 'profiles'
              which include this one and  load  extra  things  for  particular
              tasks. For example:

              1) $HOME/.ipython/ipythonrc : load basic things you always want.
              2) $HOME/.ipython/ipythonrc-math :  load  (1)  and  basic  math-
              related modules.
              3)  $HOME/.ipython/ipythonrc-numeric  : load (1) and Numeric and
              plotting modules.

              Since it is possible to create an endless loop by having  circu-
              lar  file  inclusions, IPython will stop if it reaches 15 recur-
              sive inclusions.

       -prompt_in1|pi1 <string>
              Specify the string used for input prompts. Note that if you  are
              using numbered prompts, the number is represented with a '\#' in
              the string. Don't forget to quote strings with  spaces  embedded
              in them. Default: 'In [\#]: '.

              Most  bash-like  escapes  can  be  used  to  customize IPython's
              prompts, as well as a few additional ones which are IPython-spe-
              cific.   All valid prompt escapes are described in detail in the
              Customization section of the IPython HTML/PDF manual.

       -prompt_in2|pi2 <string>
              Similar to the previous option, but used  for  the  continuation
              prompts.  The special sequence '\D' is similar to '\#', but with
              all digits replaced dots (so  you  can  have  your  continuation
              prompt  aligned  with  your  input prompt). Default: '   .\D.: '
              (note three spaces at the start for alignment with 'In [\#]').





                        November 30, 2004                       5





IPYTHON(1)                                             IPYTHON(1)


       -prompt_out|po <string>
              String  used  for  output  prompts,  also  uses   numbers   like
              prompt_in1.  Default: 'Out[\#]:'.

       -quick Start in bare bones mode (no config file loaded).

       -rcfile <name>
              Name  of  your  IPython  resource  configuration file.  normally
              IPython   loads   ipythonrc   (from   current   directory)    or
              IPYTHONDIR/ipythonrc.  If the loading of your config file fails,
              IPython starts with  a  bare  bones  configuration  (no  modules
              loaded at all).

       -[no]readline
              Use  the  readline library, which is needed to support name com-
              pletion and command history, among other things. It  is  enabled
              by  default,  but  may  cause  problems  for users of X/Emacs in
              Python comint or shell buffers.

              Note that emacs 'eterm' buffers (opened with M-x  term)  support
              IPython's  readline  and syntax coloring fine, only 'emacs' (M-x
              shell and C-c !)  buffers do not.

       -screen_length|sl <n>
              Number of lines of your screen.  This is used to control  print-
              ing  of  very  long strings.  Strings longer than this number of
              lines will be sent through a pager instead of directly  printed.

              The  default value for this is 0, which means IPython will auto-
              detect your screen size every time it  needs  to  print  certain
              potentially  long  strings  (this doesn't change the behavior of
              the 'print' keyword, it's only  triggered  internally).  If  for
              some  reason  this isn't working well (it needs curses support),
              specify it yourself. Otherwise don't change the default.

       -separate_in|si <string>
              Separator before input prompts.  Default '0.

       -separate_out|so <string>
              Separator before output prompts.  Default: 0 (nothing).

       -separate_out2|so2 <string>
              Separator after output prompts.  Default: 0 (nothing).

       -nosep Shorthand for '-separate_in 0 -separate_out 0 -separate_out2 0'.
              Simply removes all input/output separators.

       -upgrade
              Allows  you  to  upgrade  your IPYTHONDIR configuration when you
              install a new  version  of  IPython.   Since  new  versions  may
              include  new command lines options or example files, this copies
              updated ipythonrc-type files.  However, it backs up (with a .old
              extension)  all  files which it overwrites so that you can merge
              back any custimizations you might have in your personal files.



                        November 30, 2004                       6





IPYTHON(1)                                             IPYTHON(1)


       -Version
              Print version information and exit.

       -wxversion <string>
              Select a specific version of wxPython (used in conjunction  with
              -wthread).   Requires  the  wxversion  module,  part  of  recent
              wxPython distributions.

       -xmode <modename>
              Mode for exception reporting.  The valid modes are  Plain,  Con-
              text, and Verbose.

              - Plain: similar to python's normal traceback printing.

              -  Context:  prints  5  lines of context source code around each
              line in the traceback.

              - Verbose: similar to Context, but additionally prints the vari-
              ables currently visible where the exception happened (shortening
              their strings if too long).  This can potentially be very  slow,
              if  you happen to have a huge data structure whose string repre-
              sentation is complex to compute.  Your computer  may  appear  to
              freeze  for a while with cpu usage at 100%.  If this occurs, you
              can cancel the traceback with Ctrl-C (maybe hitting it more than
              once).

EMBEDDING
       It is possible to start an IPython instance inside your own Python pro-
       grams.  In the documentation example files there are some illustrations
       on how to do this.

       This  feature  allows  you  to  evalutate dynamically the state of your
       code, operate with your variables, analyze  them,  etc.   Note  however
       that any changes you make to values while in the shell do NOT propagate
       back to the running code, so it is safe to modify your  values  because
       you won't break your code in bizarre ways by doing so.

AUTHOR
       IPython  was  written by Fernando Perez <fperez@colorado.edu>, based on
       earlier  code  by  Janko  Hauser  <jh@comunit.de>  and  Nathaniel  Gray
       <n8gray@caltech.edu>.   This  manual  page  was written by Jack Moffitt
       <jack@xiph.org>, for the Debian project (but may be used by others).















                        November 30, 2004                       7


