From 905a63be79aff8be11548e40e38cf7a1481a9c03 2008-07-22 14:14:04 From: Brian E Granger Date: 2008-07-22 14:14:04 Subject: [PATCH] Updated the main introduction to IPython in the Sphinx docs. --- diff --git a/docs/source/install/index.txt b/docs/source/install/index.txt index 537d42c..63dfae4 100644 --- a/docs/source/install/index.txt +++ b/docs/source/install/index.txt @@ -1,3 +1,5 @@ +.. _install_index: + ================== Installation ================== diff --git a/docs/source/overview.txt b/docs/source/overview.txt index 3877240..2b3320d 100644 --- a/docs/source/overview.txt +++ b/docs/source/overview.txt @@ -4,18 +4,6 @@ Introduction ============ -This is the official documentation for IPython 0.x series (i.e. what -we are used to refer to just as "IPython"). The original text of the -manual (most of which is still in place) has been authored by Fernando -Perez, but as recommended usage patterns and new features have -emerged, this manual has been updated to reflect that fact. Most of -the additions have been authored by Ville M. Vainio. - -The manual has been generated from reStructuredText source markup with -Sphinx, which should make it much easier to keep it up-to-date in the -future. Some reST artifacts and bugs may still be apparent in the -documentation, but this should improve as the toolchain matures. - Overview ======== @@ -25,8 +13,19 @@ 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. -IPython is a free software project (released under the BSD license) -which tries to: +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, @@ -50,140 +49,126 @@ which tries to: WX applications via special threading flags. The normal Python shell can only do this for Tkinter applications. - -Main features -------------- - -* 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 ('?', and using '??' provides additional detail). -* Searching through modules and namespaces with '*' wildcards, both - when using the '?' system and via the %psearch command. -* Completion in the local namespace, by typing 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 - % 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 ! are passed - directly to the system shell, and using !! or 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 %bg. -* The ability to expand python variables when calling the system - shell. In a shell command, any python variable prefixed with $ is - expanded. A double $$ allows passing a literal $ to the shell (for - access to shell and environment variables like $PATH). -* Filesystem navigation, via a magic %cd command, along with a - persistent bookmark system (using %bookmark) for fast access to - frequently visited directories. -* A lightweight persistence framework via the %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 - %store and edited via %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: 'sin 3' is automatically converted to 'sin(3)'. -* Auto-quoting: using ',' or ';' as the first character forces - auto-quoting of the rest of the line: ',my_function a b' becomes - automatically 'my_function("a","b")', while ';my_function a b' - becomes '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 - '>>>' or '...' 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 - %run magic command -with the -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 %debug after seeing an exception. winpdb is - also supported, see ipy_winpdb extension. -* Profiler support. You can run single statements (similar to - 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 '%prun' - and '%run -p') convenient for rapid interactive work. -* Doctest support. The special %doctest_mode command toggles a mode - that allows you to paste existing doctests (with leading '>>>' - prompts and whitespace) and uses doctest-compatible prompts and - output, so you can use IPython sessions as doctest code. - +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 ` of using IPython for +parallel computing. Portability and Python requirements ----------------------------------- -Python requirements: IPython requires with Python version 2.3 or newer. -If you are still using Python 2.2 and can not upgrade, the last version -of IPython which worked with Python 2.2 was 0.6.15, so you will have to -use that. - -IPython is developed under Linux, but it should work in any reasonable -Unix-type system (tested OK under Solaris and the BSD family, for which -a port exists thanks to Dryice Liu). - -Mac OS X: it works, apparently without any problems (thanks to Jim Boyle -at Lawrence Livermore for the information). Thanks to Andrea Riciputi, -Fink support is available. - -CygWin: it works mostly OK, though some users have reported problems -with prompt coloring. No satisfactory solution to this has been found so -far, you may want to disable colors permanently in the ipythonrc -configuration file if you experience problems. If you have proper color -support under cygwin, please post to the IPython mailing list so this -issue can be resolved for all users. - -Windows: it works well under Windows Vista/XP/2k, and I suspect NT should -behave similarly. Section "Installation under windows" describes -installation details for Windows, including some additional tools needed -on this platform. - -Windows 9x support is present, and has been reported to work fine (at -least on WinME). - -Location --------- - -IPython is generously hosted at http://ipython.scipy.org by the -Enthought, Inc and the SciPy project. This site offers downloads, -subversion access, mailing lists and a bug tracking system. I am very -grateful to Enthought (http://www.enthought.com) and all of the SciPy -team for their contribution. \ No newline at end of file +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 ` for instructions on how to install IPython. \ No newline at end of file diff --git a/docs/source/parallel/index.txt b/docs/source/parallel/index.txt index da5fe16..cc31f75 100644 --- a/docs/source/parallel/index.txt +++ b/docs/source/parallel/index.txt @@ -1,3 +1,5 @@ +.. _parallel_index: + ==================================== Using IPython for Parallel computing ====================================