docs/source/overview.txt

.. _overview:

============
Introduction
============

Overview
========

One of Python's most useful features is its interactive interpreter.
This system allows very fast testing of ideas without the overhead of
creating test files as is typical in most programming languages.
However, the interpreter supplied with the standard Python distribution
is somewhat limited for extended interactive use.

The goal of IPython is to create a comprehensive environment for
interactive and exploratory computing.  To support, this goal, IPython
has two main components:

	* An enhanced interactive Python shell.
	* An architecture for interactive parallel computing.

All of IPython is open source (released under the revised BSD license).

Enhanced interactive Python shell
=================================

IPython's interactive shell (`ipython`), has the following goals:

   1. Provide an interactive shell superior to Python's default. IPython
      has many features for object introspection, system shell access,
      and its own special command system for adding functionality when
      working interactively. It tries to be a very efficient environment
      both for Python code development and for exploration of problems
      using Python objects (in situations like data analysis).
   2. Serve as an embeddable, ready to use interpreter for your own
      programs. IPython can be started with a single call from inside
      another program, providing access to the current namespace. This
      can be very useful both for debugging purposes and for situations
      where a blend of batch-processing and interactive exploration are
      needed.
   3. Offer a flexible framework which can be used as the base
      environment for other systems with Python as the underlying
      language. Specifically scientific environments like Mathematica,
      IDL and Matlab inspired its design, but similar ideas can be
      useful in many fields.
   4. Allow interactive testing of threaded graphical toolkits. IPython
      has support for interactive, non-blocking control of GTK, Qt and
      WX applications via special threading flags. The normal Python
      shell can only do this for Tkinter applications.

Main features of the interactive shell
--------------------------------------

	* Dynamic object introspection. One can access docstrings, function
	  definition prototypes, source code, source files and other details
	  of any object accessible to the interpreter with a single
	  keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
	* Searching through modules and namespaces with :samp:`*` wildcards, both
	  when using the :samp:`?` system and via the :samp:`%psearch` command.
	* Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
	  This works for keywords, modules, methods, variables and files in the
	  current directory. This is supported via the readline library, and
	  full access to configuring readline's behavior is provided. 
	  Custom completers can be implemented easily for different purposes
	  (system commands, magic arguments etc.)
	* Numbered input/output prompts with command history (persistent
	  across sessions and tied to each profile), full searching in this
	  history and caching of all input and output.
	* User-extensible 'magic' commands. A set of commands prefixed with
	  :samp:`%` is available for controlling IPython itself and provides
	  directory control, namespace information and many aliases to
	  common system shell commands.
	* Alias facility for defining your own system aliases.
	* Complete system shell access. Lines starting with :samp:`!` are passed
	  directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd` 
	  captures shell output into python variables for further use.
	* Background execution of Python commands in a separate thread.
	  IPython has an internal job manager called jobs, and a
	  conveninence backgrounding magic function called :samp:`%bg`.
	* The ability to expand python variables when calling the system
	  shell. In a shell command, any python variable prefixed with :samp:`$` is
	  expanded. A double :samp:`$$` allows passing a literal :samp:`$` to the shell (for
	  access to shell and environment variables like :envvar:`PATH`).
	* Filesystem navigation, via a magic :samp:`%cd` command, along with a
	  persistent bookmark system (using :samp:`%bookmark`) for fast access to
	  frequently visited directories.
	* A lightweight persistence framework via the :samp:`%store` command, which
	  allows you to save arbitrary Python variables. These get restored
	  automatically when your session restarts.
	* Automatic indentation (optional) of code as you type (through the
	  readline library).
	* Macro system for quickly re-executing multiple lines of previous
	  input with a single name. Macros can be stored persistently via
	  :samp:`%store` and edited via :samp:`%edit`.
	* Session logging (you can then later use these logs as code in your
	  programs). Logs can optionally timestamp all input, and also store
	  session output (marked as comments, so the log remains valid
	  Python source code).
	* Session restoring: logs can be replayed to restore a previous
	  session to the state where you left it.
	* Verbose and colored exception traceback printouts. Easier to parse
	  visually, and in verbose mode they produce a lot of useful
	  debugging information (basically a terminal version of the cgitb
	  module).
	* Auto-parentheses: callable objects can be executed without
	  parentheses: :samp:`sin 3` is automatically converted to :samp:`sin(3)`.
	* Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
	  auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
	  automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
	  becomes :samp:`my_function("a b")`.
	* Extensible input syntax. You can define filters that pre-process
	  user input to simplify input in special situations. This allows
	  for example pasting multi-line code fragments which start with
	  :samp:`>>>` or :samp:`...` such as those from other python sessions or the
	  standard Python documentation.
	* Flexible configuration system. It uses a configuration file which
	  allows permanent setting of all command-line options, module
	  loading, code and file execution. The system allows recursive file
	  inclusion, so you can have a base file with defaults and layers
	  which load other customizations for particular projects.
	* Embeddable. You can call IPython as a python shell inside your own
	  python programs. This can be used both for debugging code or for
	  providing interactive abilities to your programs with knowledge
	  about the local namespaces (very useful in debugging and data
	  analysis situations).
	* Easy debugger access. You can set IPython to call up an enhanced
	  version of the Python debugger (pdb) every time there is an
	  uncaught exception. This drops you inside the code which triggered
	  the exception with all the data live and it is possible to
	  navigate the stack to rapidly isolate the source of a bug. The
	  :samp:`%run` magic command (with the :samp:`-d` option) can run any script under
	  pdb's control, automatically setting initial breakpoints for you.
	  This version of pdb has IPython-specific improvements, including
	  tab-completion and traceback coloring support. For even easier
	  debugger access, try :samp:`%debug` after seeing an exception. winpdb is 
	  also supported, see ipy_winpdb extension.
	* Profiler support. You can run single statements (similar to
	  :samp:`profile.run()`) or complete programs under the profiler's control.
	  While this is possible with standard cProfile or profile modules,
	  IPython wraps this functionality with magic commands (see :samp:`%prun`
	  and :samp:`%run -p`) convenient for rapid interactive work.
	* Doctest support. The special :samp:`%doctest_mode` command toggles a mode
	  that allows you to paste existing doctests (with leading :samp:`>>>`
	  prompts and whitespace) and uses doctest-compatible prompts and
	  output, so you can use IPython sessions as doctest code.

Interactive parallel computing
==============================

Increasingly, parallel computer hardware, such as multicore CPUs, clusters and supercomputers, is becoming ubiquitous. Over the last 3 years, we have developed an
architecture within IPython that allows such hardware to be used quickly and easily
from Python. Moreover, this architecture is designed to support interactive and
collaborative parallel computing.

For more information, see our :ref:`overview <parallel_index>` of using IPython for
parallel computing.

Portability and Python requirements
-----------------------------------

As of the 0.9 release, IPython requires Python 2.4 or greater.  We have
not begun to test IPython on Python 2.6 or 3.0, but we expect it will
work with some minor changes.

IPython is known to work on the following operating systems:

	* Linux
	* AIX
	* Most other Unix-like OSs (Solaris, BSD, etc.)
	* Mac OS X
	* Windows (CygWin, XP, Vista, etc.)

See :ref:`here <install_index>` for instructions on how to install IPython.