Merged Ville files

doc/do_sphinx.py

@@ -0,0 +1,4 b''
+import os
+def oscmd(c):
+	os.system(c)
+oscmd('sphinx-build -d build/doctrees source build/html')
  No newline at end of file

doc/source/conf.py

@@ -0,0 +1,132 b''
+# -*- coding: utf-8 -*-
+#
+# IPython documentation build configuration file, created by
+# sphinx-quickstart.py on Sat Mar 29 15:36:13 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys
+
+# If your extensions are in another directory, add it here.
+#sys.path.append('some/directory')
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
+#extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'ipython'
+
+# General substitutions.
+project = 'IPython'
+copyright = '2008, IPython team'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.8.3'
+# The full version, including alpha/beta/rc tags.
+release = '0.8.3'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Content template for the index page.
+#html_index = ''
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'IPythondoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+#latex_documents = []
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True

IPython/Extensions/ipy_leo.py

@@ -374,7 +374,6 b' def push_ipython_script(node):'
         hstart = len(ip.IP.input_hist)
         script = node.script()
         
-        script = g.splitLines(script + '\n')
         ip.user_ns['_p'] = node
         ip.runlines(script)
         ip.user_ns.pop('_p',None)

IPython/ipapi.py

@@ -273,6 +273,7 b' class IPApi:'
             """
             res = []
             lines = script.splitlines()
+
             level = 0
             for l in lines:
                 lstripped = l.lstrip()
@@ -280,9 +281,19 b' class IPApi:'
                 if not stripped:
                     continue
                 newlevel = len(l) - len(lstripped)
-                if level > 0 and newlevel == 0 and not stripped.endswith(':'):
+                def is_secondary_block_start(s):
+                    if not s.endswith(':'):
+                        return False
+                    if (s.startswith('elif') or 
+                        s.startswith('else') or 
+                        s.startswith('except') or
+                        s.startswith('finally')):
+                        return True
+                        
+                if level > 0 and newlevel == 0 and not is_secondary_block_start(stripped): 
                     # add empty line
                     res.append('')
+                    
                 res.append(l)
                 level = newlevel
             return '\n'.join(res) + '\n'
@@ -292,7 +303,7 b' class IPApi:'
         else:
             script = '\n'.join(lines)
         clean=cleanup_ipy_script(script)
-
+        # print "_ip.runlines() script:\n",clean #dbg
         self.IP.runlines(clean)
     def to_user_ns(self,vars, interactive = True):
         """Inject a group of variables into the IPython user namespace.

IPython/ipmaker.py

@@ -210,7 +210,7 b" object? -> Details about 'object'. ?object also works, ?? prints more."
                       editor = '0',
                       gthread = 0,
                       help = 0,
-                      interact = 1,
+                      interact = 0,
                       ipythondir = ipythondir_def,
                       log = 0,
                       logfile = '',

doc/examples/leo_bridge_demo.leo

@@ -3,7 +3,7 b''
 <leo_file>
 <leo_header file_format="2" tnodes="0" max_tnode_index="0" clone_windows="0"/>
 <globals body_outline_ratio="0.307814992026">
-	<global_window_position top="180" left="223" height="627" width="1280"/>
+	<global_window_position top="257" left="131" height="627" width="1280"/>
 	<global_log_window_position top="0" left="0" height="0" width="0"/>
 </globals>
 <preferences/>
@@ -38,18 +38,18 b''
 <v t="vivainio.20080219230342"><vh>slist to leo</vh></v>
 </v>
 </v>
-<v t="vivainio.20080218195413"><vh>Class tests</vh>
+<v t="vivainio.20080218195413" a="E"><vh>Class tests</vh>
 <v t="vivainio.20080218200509"><vh>csvr</vh></v>
 <v t="vivainio.20080218191007"><vh>tempfile</vh></v>
 <v t="vivainio.20080218195413.1"><vh>rfile</vh></v>
 <v t="vivainio.20080219225804"><vh>strlist</vh></v>
 </v>
+<v t="vivainio.20080222201226" a="V"><vh>IPython script push tests</vh></v>
 <v t="vivainio.20080218201219" a="E"><vh>Direct variables</vh>
-<v t="vivainio.20080222201226"><vh>NewHeadline</vh></v>
 <v t="vivainio.20080218201219.2"><vh>bar</vh></v>
 </v>
 <v t="vivainio.20080316144536" a="E"><vh>pylab tests</vh>
-<v t="vivainio.20080316145539.2" a="TV"><vh>Generate testarr</vh></v>
+<v t="vivainio.20080316145539.2"><vh>Generate testarr</vh></v>
 <v t="vivainio.20080316085925"><vh>testarr</vh></v>
 <v t="vivainio.20080316085950"><vh>Call plotter on testarr</vh></v>
 </v>
@@ -128,21 +128,45 b' def format_slist(obj):'
 <t tx="vivainio.20080222193236">?</t>
 <t tx="vivainio.20080222193236.1">@wrap
 @nocolor</t>
-<t tx="vivainio.20080222201226">1+2
+<t tx="vivainio.20080222201226"># test ipython script 'cleanup' with complex blocks
+1+2
 print "hello"
 3+4
 
 def f(x):
     return x.upper()
 
-f('hello world')
 
 if 0:
     print "foo"
 else:
     print "bar"
 
-</t>
+def g():
+    pass
+
+g()
+
+if 1:
+    if 1:
+        print "hello"
+
+        print "world"
+
+if 1:
+    print "hello"
+
+    print "word"
+else:
+    print "foo"
+
+    print "bar"
+    print "baz"
+
+try:
+    raise Exception
+except:
+    print "exc ok"</t>
 <t tx="vivainio.20080222202211"></t>
 <t tx="vivainio.20080222202211.1" ipython="7d71005506636f6f7264737101284b0c4bde747102732e">@cl rfile
 hello

doc/source/ipython.rst

@@ -53,6 +53,7 b' which tries to:'
 
 
 Main features
+-------------
 
 * Dynamic object introspection. One can access docstrings, function
   definition prototypes, source code, source files and other details
@@ -228,24 +229,31 b' manner. If you download the tar archive, the process is:'
       ipython with the -upgrade option and it will do this automatically
       for you.
    3. IPython uses distutils, so you can install it by simply typing at
-      the system prompt (don't type the $)
+      the system prompt (don't type the $)::
+      
       	$ python setup.py install
+      	
       Note that this assumes you have root access to your machine. If
       you don't have root access or don't want IPython to go in the
-      default python directories, you'll need to use the |--home| option
-      (or |--prefix|). For example:
-      |$ python setup.py install --home $HOME/local|
+      default python directories, you'll need to use the ``--home`` option
+      (or ``--prefix``). For example::
+      
+      	$ python setup.py install --home $HOME/local
+      	
       will install IPython into $HOME/local and its subdirectories
       (creating them if necessary).
-      You can type
-      |$ python setup.py --help|
+      You can type::
+      
+      	$ python setup.py --help
+      	
       for more details.
-      Note that if you change the default location for |--home| at
+      
+      Note that if you change the default location for ``--home`` at
       installation, IPython may end up installed at a location which is
       not part of your $PYTHONPATH environment variable. In this case,
       you'll need to configure this variable to include the actual
       directory where the IPython/ directory ended (typically the value
-      you give to |--home| plus /lib/python).
+      you give to ``--home`` plus /lib/python).
 
 
 Mac OSX information
@@ -280,10 +288,14 b' and GTK apps. Under OSX, however, this requires that ipython is'
 installed by calling the special pythonw script at installation time,
 which takes care of coordinating things with Apple's graphical environment.
 
-So when installing under OSX, it is best to use the following command: 
-| $ sudo pythonw setup.py install --install-scripts=/usr/local/bin|
+So when installing under OSX, it is best to use the following command:: 
+
+	$ sudo pythonw setup.py install --install-scripts=/usr/local/bin
+
 or
-| $ sudo pythonw setup.py install --install-scripts=/usr/bin|
+
+	$ sudo pythonw setup.py install --install-scripts=/usr/bin
+	
 depending on where you like to keep hand-installed executables.
 
 The resulting script will have an appropriate shebang line (the first
@@ -294,7 +306,7 b' does not work and has a shebang line that points to, for example, just'
 build/scripts-<python-version> directory. Delete that directory and
 rerun the setup.py.
 
-It is also a good idea to use the special flag |--install-scripts| as
+It is also a good idea to use the special flag ``--install-scripts`` as
 indicated above, to ensure that the ipython scripts end up in a location
 which is part of your $PATH. Otherwise Apple's Python will put the
 scripts in an internal directory not available by default at the command
@@ -591,10 +603,14 b' Input/Output prompts and exception tracebacks'
 You can test whether the colored prompts and tracebacks work on your
 system interactively by typing '%colors Linux' at the prompt (use
 '%colors LightBG' if your terminal has a light background). If the input
-prompt shows garbage like:
+prompt shows garbage like::
+
     [0;32mIn [[1;32m1[0;32m]: [0;00m
-instead of (in color) something like:
+                               
+instead of (in color) something like::
+    
     In [1]:
+        
 this means that your terminal doesn't properly handle color escape
 sequences. You can go to a 'no color' mode by typing '%colors NoColor'.
 
@@ -665,11 +681,11 b' the previous section, you may need to set also in your .emacs file::'
     (setq ansi-color-for-comint-mode t) 
 
 
-Notes::
+Notes:
 
     * There is one caveat you should be aware of: you must start the
       IPython shell before attempting to execute any code regions via
-      C-c |. Simply type C-c ! to start IPython before passing any code
+      ``C-c |``. Simply type C-c ! to start IPython before passing any code
       regions to the interpreter, and you shouldn't experience any
       problems.
       This is due to a bug in Python itself, which has been fixed for
@@ -1035,7 +1051,7 b' 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 |.
+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 example for more details on what the options do. Options
@@ -1373,6 +1389,7 b' typing %magic at the prompt, but that will also give you information'
 about magic commands you may have added as part of your personal
 customizations.
 
+::
 
 	%Exit: Exit IPython without confirmation.
 	
@@ -1712,8 +1729,8 b' Arguments:'
 	
 	If arguments are given, the following possibilites exist:
 	
-    - The arguments are numbers or pairs of colon-separated numbers (like 1
-    4:8 9). These are interpreted as lines of previous input to be loaded
+	    - The arguments are numbers or pairs of dash-separated numbers (like 1
+	      4-8 9). These are interpreted as lines of previous input to be loaded
 	      into the editor. The syntax is the same of the %macro command.
 	
 	    - If the argument doesn't start with a number, it is evaluated as a
@@ -1735,7 +1752,7 b' editors (like kedit and gedit up to Gnome 2.8) do not understand the'
 	'+NUMBER' parameter necessary for this feature. Good editors like
 	(X)Emacs, vi, jed, pico and joe all do.
 	
-- If the argument is not found as a variable, IPython will look for a
+	If the argument is not found as a variable, IPython will look for a
 	file with that name (adding .py if necessary) and load it into the
 	editor. It will execute its contents with execfile() when you exit,
 	loading any code in the file into your interactive namespace.
@@ -2200,9 +2217,9 b' this system, only pure python code and magic commands.'
 	This version explicitly checks that every entry in $PATH is a file with
 	execute access (os.X_OK), so it is much slower than %rehash.
 	
-Under Windows, it checks executability as a match agains a '|'-separated
+	Under Windows, it checks executability as a match agains a ``|``-separated
 	string of extensions, stored in the IPython config variable
-win_exec_ext. This defaults to 'exe|com|bat'.
+	win_exec_ext. This defaults to ``exe|com|bat``.
 	
 	This function also resets the root module cache of module completer,
 	used on slow filesystems.
@@ -2611,6 +2628,7 b' If called without arguments, acts as a toggle.'
 
 
 Access to the standard Python help
+----------------------------------
 
 As of Python 2.1, a help system is available with access to object
 docstrings and the Python manuals. Simply type 'help' (no quotes) to
@@ -2622,6 +2640,7 b' your environment variable PYTHONDOCS for this feature to work correctly.'
 
 
 Dynamic object information
+--------------------------
 
 Typing ?word or word? prints detailed information about an object. If
 certain strings in the object are too long (docstrings, code, etc.) they
@@ -2663,6 +2682,7 b' are not really defined as separate identifiers. Try for example typing'
 
 
 Readline-based features
+-----------------------
 
 These features require the GNU readline library, so they won't work if
 your Python installation lacks readline support. We will first describe
@@ -2820,7 +2840,6 b' Any input line beginning with a ! character is passed verbatim (minus'
 the !, of course) to the underlying operating system. For example,
 typing !ls will run 'ls' in the current directory.
 
-
 Manual capture of command output
 --------------------------------
 
@@ -2832,10 +2851,9 b' output. The !! syntax is a shorthand for the %sx magic command.'
 
 Finally, the %sc magic (short for 'shell capture') is similar to %sx,
 but allowing more fine-grained control of the capture details, and
-storing the result directly into a named variable.
-
-See Sec. 6.2 <#sec:magic> for details on the magics %sc and %sx, or use
-IPython's own help (sc? and sx?) for further details.
+storing the result directly into a named variable. The direct use of 
+%sc is now deprecated, and you should ise the ``var = !cmd`` syntax
+instead.
 
 IPython also allows you to expand the value of python variables when
 making system calls. Any python variable or expression which you prepend
@@ -3004,7 +3022,8 b' Directory history'
 
 Your history of visited directories is kept in the global list _dh, and
 the magic %cd command can be used to go to any entry in that list. The
-%dhist command allows you to view this history.
+%dhist command allows you to view this history. do ``cd -<TAB`` to
+conventiently view the directory history.
 
 
 Automatic parentheses and quotes
@@ -3078,6 +3097,23 b" won't work::"
 Customization
 =============
 
+There are 2 ways to configure IPython - the old way of using ipythonrc
+files (an INI-file like format), and the new way that involves editing
+your ipy_user_conf.py. Both configuration systems work at the same
+time, so you can set your options in both, but if you are hesitating
+about which alternative to choose, we recommend the ipy_user_conf.py
+approach, as it will give you more power and control in the long
+run. However, there are few options such as pylab_import_all that can
+only be specified in ipythonrc file or command line - the reason for
+this is that they are needed before IPython has been started up, and
+the IPApi object used in ipy_user_conf.py is not yet available at that
+time. A hybrid approach of specifying a few options in ipythonrc and
+doing the more advanced configuration in ipy_user_conf.py is also
+possible.
+
+The ipythonrc approach
+----------------------
+
 As we've already mentioned, IPython reads a configuration file which can
 be specified at the command line (-rcfile) or which by default is
 assumed to be called ipythonrc. Such a file is looked for in the current
@@ -3118,7 +3154,7 b' Each of these options may appear as many times as you need it in the file.'
     * [import_some <mod> <f1> <f2> ...:] import functions with 'from
       <mod> import <f1>,<f2>,...'
     * [import_all <mod1> <mod2> ...:] for each module listed import
-      functions with 'from <mod> import *'
+      functions with ``from <mod> import *``.
     * [execute <python code>:] give any single-line python code to be
       executed.
     * [execfile <filename>:] execute the python file given with an
@@ -3136,7 +3172,6 b' Each of these options may appear as many times as you need it in the file.'
       normal system shell.
 
 
-
 Sample ipythonrc file
 ---------------------
 
@@ -3779,47 +3814,135 b' reproduce it here for reference::'
     #************************* end of file <ipythonrc> ************************
 
 
+ipy_user_conf.py
+----------------
+
+There should be a simple template ipy_user_conf.py file in your
+~/.ipython directory. It is a plain python module that is imported
+during IPython startup, so you can do pretty much what you want there
+- import modules, configure extensions, change options, define magic
+commands, put variables and functions in the IPython namespace,
+etc. You use the IPython extension api object, acquired by
+IPython.ipapi.get() and documented in the "IPython extension API"
+chapter, to interact with IPython. A sample ipy_user_conf.py is listed
+below for reference::
+
+    # Most of your config files and extensions will probably start
+    # with this import
+
+    import IPython.ipapi
+    ip = IPython.ipapi.get()
+
+    # You probably want to uncomment this if you did %upgrade -nolegacy
+    # import ipy_defaults    
+
+    import os   
+
+    def main():   
+
+        #ip.dbg.debugmode = True
+        ip.dbg.debug_stack()
+
+        # uncomment if you want to get ipython -p sh behaviour
+        # without having to use command line switches  
+        import ipy_profile_sh
+        import jobctrl
+
+        # Configure your favourite editor?
+        # Good idea e.g. for %edit os.path.isfile
+
+        #import ipy_editors
+
+        # Choose one of these:
+
+        #ipy_editors.scite()
+        #ipy_editors.scite('c:/opt/scite/scite.exe')
+        #ipy_editors.komodo()
+        #ipy_editors.idle()
+        # ... or many others, try 'ipy_editors??' after import to see them
+
+        # Or roll your own:
+        #ipy_editors.install_editor("c:/opt/jed +$line $file")
+
+
+        o = ip.options
+        # An example on how to set options
+        #o.autocall = 1
+        o.system_verbose = 0
+
+        #import_all("os sys")
+        #execf('~/_ipython/ns.py')
+
+
+        # -- prompt
+        # A different, more compact set of prompts from the default ones, that
+        # always show your current location in the filesystem:
+
+        #o.prompt_in1 = r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Normal\n\C_Green|\#>'
+        #o.prompt_in2 = r'.\D: '
+        #o.prompt_out = r'[\#] '
+
+        # Try one of these color settings if you can't read the text easily
+        # autoexec is a list of IPython commands to execute on startup
+        #o.autoexec.append('%colors LightBG')
+        #o.autoexec.append('%colors NoColor')
+        o.autoexec.append('%colors Linux')
+
+
+    # some config helper functions you can use 
+    def import_all(modules):
+        """ Usage: import_all("os sys") """ 
+        for m in modules.split():
+            ip.ex("from %s import *" % m)
+
+    def execf(fname):
+        """ Execute a file in user namespace """
+        ip.ex('execfile("%s")' % os.path.expanduser(fname))
+
+    main()
+
+
 
 Fine-tuning your prompt
 -----------------------
 
 IPython's prompts can be customized using a syntax similar to that of
 the bash shell. Many of bash's escapes are supported, as well as a few
-additional ones. We list them below:
+additional ones. We list them below::
 
-*\#*
+    \#
         the prompt/history count number. This escape is automatically
         wrapped in the coloring codes for the currently active color scheme. 
-*\N*
+    \N
         the 'naked' prompt/history count number: this is just the number
         itself, without any coloring applied to it. This lets you produce
         numbered prompts with your own colors. 
-*\D*
+    \D
         the prompt/history count, with the actual digits replaced by dots.
         Used mainly in continuation prompts (prompt_in2) 
-*\w*
+    \w
         the current working directory 
-*\W*
+    \W
         the basename of current working directory 
-*\Xn*
+    \Xn
         where $n=0\ldots5.$ The current working directory, with $HOME
         replaced by ~, and filtered out to contain only $n$ path elements 
-*\Yn*
+    \Yn
         Similar to \Xn, but with the $n+1$ element included if it is ~ (this
         is similar to the behavior of the %cn escapes in tcsh) 
-*\u*
+    \u
         the username of the current user 
-*\$*
+    \$
         if the effective UID is 0, a #, otherwise a $ 
-*\h*
+    \h
         the hostname up to the first '.' 
-*\H*
+    \H
         the hostname 
-*\n*
+    \n
         a newline 
-*\r*
+    \r
         a carriage return 
-*\v*
+    \v
         IPython version string 
 
 In addition to these, ANSI color escapes can be insterted into the
@@ -3848,7 +3971,7 b' default prompts::'
     prompt_in2 '   .\D.:' 
     prompt_out 'Out[\#]:'
 
-which look like this:
+which look like this::
 
     In [1]: 1+2 
     Out[1]: 3
@@ -4166,7 +4289,6 b' code fragments in your programs which are ready for cut and paste::'
 Using the Python debugger (pdb)
 ===============================
 
-
 Running entire programs via pdb
 -------------------------------
 
@@ -4212,7 +4334,7 b' uncaught exception is triggered by your code.'
 
 For stand-alone use of the feature in your programs which do not use
 IPython at all, put the following lines toward the top of your 'main'
-routine:
+routine::
 
     import sys,IPython.ultraTB  
     sys.excepthook = IPython.ultraTB.FormattedTB(mode='Verbose',
@@ -4242,7 +4364,7 b" supplied, which we will briefly describe now. These can be used 'as is'"
 starting point for writing your own extensions.
 
 
-Pasting of code starting with '»> ' or '... '
+Pasting of code starting with '>>> ' or '... '
 ----------------------------------------------
 
 In the python tutorial it is common to find code examples which have
@@ -4304,6 +4426,7 b" Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython"
 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: 
@@ -4318,235 +4441,286 b' from math import * # math MUST be imported BEFORE PhysicalQInteractive'
 from IPython.Extensions.PhysicalQInteractive import * 
 import IPython.Extensions.PhysicalQInput
 
-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.
+IPython as a system shell - the 'Sh' profile
+============================================
+
+The 'sh' profile optimizes IPython for system shell usage. Apart from
+certain job control functionality that is present in unix (ctrl+z does
+"suspend"), the sh profile should provide you with most of the
+functionality you use daily in system shell, and more. Invoke IPython
+in 'sh' profile by doing 'ipython -p sh', or (in win32) by launching
+the "pysh" shortcut in start menu.
+
+If you want to use the features of sh profile as your defaults (which
+might be a good idea if you use other profiles a lot of the time but
+still want the convenience of sh profile), add ``import ipy_profile_sh``
+to your ~/.ipython/ipy_user_conf.py.
 
-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.
+The 'sh' profile is different from the default profile in that:
 
-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.
+ * Prompt shows the current directory
+ * Spacing between prompts and input is more compact (no padding with
+   empty lines). The startup banner is more compact as well.
+ * System commands are directly available (in alias table) without
+   requesting %rehashx - however, if you install new programs along
+   your PATH, you might want to run %rehashx to update the persistent
+   alias table
+ * Macros are stored in raw format by default. That is, instead of
+   '_ip.system("cat foo"), the macro will contain text 'cat foo')
+ * Autocall is in full mode
+ * Calling "up" does "cd .."
 
+The 'sh' profile is different from the now-obsolete (and unavailable)
+'pysh' profile in that:
+
+ * '$$var = command' and '$var = command' syntax is not supported
+ * anymore. Use 'var = !command' instead (incidentally, this is
+ * available in all IPython profiles). Note that !!command *will*
+ * work.
 
 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
+able to type any normal system command and have it executed. See
+%alias?  and %unalias? for details on the alias facilities. See also
 %rehashx? for details on the mechanism used to load $PATH.
 
 
-Special syntax
---------------
+Directory management
+--------------------
+
+Since each command passed by ipython to the underlying system is executed
+in a subshell which exits immediately, you can NOT use !cd to navigate
+the filesystem.
 
-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::
+IPython 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.
 
-*!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 list
+%pushd, %popd and %dirs are provided for directory stack handling.
 
-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)::
+Enabled extensions
+------------------
 
-    fperez[~/test]|3> !ls *s.py  
-    scopes.py strings.py
+Some extensions, listed below, are enabled as default in this profile.
 
-ls is an internal alias, so there's no need to use !::
+envpersist
+++++++++++
 
-    fperez[~/test]|4> ls *s.py  
-    scopes.py* strings.py
+%env can be used to "remember" environment variable manipulations. Examples::
 
-!!ls will return the output into a Python variable FIXME!!!::
+	%env - Show all environment variables
+	%env VISUAL=jed  - set VISUAL to jed
+	%env PATH+=;/foo - append ;foo to PATH
+	%env PATH+=;/bar - also append ;bar to PATH
+	%env PATH-=/wbin; - prepend /wbin; to PATH
+	%env -d VISUAL   - forget VISUAL persistent val
+	%env -p          - print all persistent env modifications
 
-    fperez[~/test]|5> !!ls *s.py  
-                  <5> ['scopes.py', 'strings.py']  
-    fperez[~/test]|6> print _5  
-    ['scopes.py', 'strings.py']
+ipy_which
++++++++++
 
-$ and $$ allow direct capture to named variables:
+%which magic command. Like 'which' in unix, but knows about ipython aliases.
 
-fperez[~/test]|7> $astr = ls *s.py  
-fperez[~/test]|8> astr  
-              <8> 'scopes.py\nstrings.py'
+Example::
 
-fperez[~/test]|9> $$alist = ls *s.py  
-fperez[~/test]|10> alist  
-              <10> ['scopes.py', 'strings.py']
+ [C:/ipython]|14> %which st
+ st -> start .
+ [C:/ipython]|15> %which d
+ d -> dir /w /og /on
+ [C:/ipython]|16> %which cp
+ cp -> cp
+   == c:\bin\cp.exe
+ c:\bin\cp.exe
 
-alist is now a normal python list you can loop over. Using $ will expand
-back the python values when alias calls are made:
+ipy_app_completers
+++++++++++++++++++
 
-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
+Custom tab completers for some apps like svn, hg, bzr, apt-get. Try 'apt-get install <TAB>' in debian/ubuntu.
 
-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::
+ipy_rehashdir
++++++++++++++
 
-    fperez[~/test]|12> for f in alist:  
-                  |..>    cp $f ${f}.bak
+Allows you to add system command aliases for commands that are not along your path. Let's say that you just installed Putty and want to be able to invoke it without adding it to path, you can create the alias for it with rehashdir::
 
-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::
+ [~]|22> cd c:/opt/PuTTY/
+ [c:opt/PuTTY]|23> rehashdir .
+              <23> ['pageant', 'plink', 'pscp', 'psftp', 'putty', 'puttygen', 'unins000']
 
-    fperez[~/test]|13> echo "sys.platform is: $sys.platform"  
-    sys.platform is: linux2
+Now, you can execute any of those commams directly::
 
-IPython's input history handling is still active, which allows you to
-rerun a single block of multi-line input by simply using exec::
+ [c:opt/PuTTY]|24> cd
+ [~]|25> putty
 
-    fperez[~/test]|14> $$alist = ls *.eps  
-    fperez[~/test]|15> exec _i11  
-    file image2.eps 921 image2.eps  
-    file image.eps 921 image.eps
+(the putty window opens).
 
-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.
+If you want to store the alias so that it will always be available, do '%store putty'. If you want to %store all these aliases persistently, just do it in a for loop::
 
+ [~]|27> for a in _23:
+    |..>     %store $a
+    |..>
+    |..>
+ Alias stored: pageant (0, 'c:\\opt\\PuTTY\\pageant.exe')
+ Alias stored: plink (0, 'c:\\opt\\PuTTY\\plink.exe')
+ Alias stored: pscp (0, 'c:\\opt\\PuTTY\\pscp.exe')
+ Alias stored: psftp (0, 'c:\\opt\\PuTTY\\psftp.exe')
+ ...
 
-Useful functions and modules
-----------------------------
+mglob
++++++
 
-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 '?'.
+Provide the magic function %mglob, which makes it easier (than the 'find' command) to collect (possibly recursive) file lists. Examples::
 
-*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 
+ [c:/ipython]|9> mglob *.py
+ [c:/ipython]|10> mglob *.py rec:*.txt
+ [c:/ipython]|19> workfiles = %mglob !.svn/ !.hg/ !*_Data/ !*.bak rec:.
 
-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).
+Note that the first 2 calls will put the file list in result history (_, _9, _10), and the last one will assign it to 'workfiles'.
 
 
-Directory management
+Prompt customization
 --------------------
 
-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.
+The sh profile uses the following prompt configurations::
 
-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.
+    o.prompt_in1= r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#>'
+    o.prompt_in2= r'\C_Green|\C_LightGreen\D\C_Green>'
 
-%pushd, %popd and %dirs are provided for directory stack handling.
+You can change the prompt configuration to your liking by editing
+ipy_user_conf.py.  
+
+String lists
+============
 
+String lists (IPython.genutils.SList) are handy way to process output
+from system commands. They are produced by ``var = !cmd`` syntax.
 
-    Prompt customization
+First, we acquire the output of 'ls -l'::
+
+    [Q:doc/examples]|2> lines = !ls -l
+     ==
+    ['total 23',
+     '-rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py',
+     '-rw-rw-rw- 1 ville None 1927 Sep 30  2006 example-embed-short.py',
+     '-rwxrwxrwx 1 ville None 4606 Sep  1 17:15 example-embed.py',
+     '-rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py',
+     '-rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py',
+     '-rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py',
+     '-rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc']
+
+Now, let's take a look at the contents of 'lines' (the first number is
+the list element number)::
+
+    [Q:doc/examples]|3> lines
+                    <3> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
 
-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:
+    0: total 23
+    1: -rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py
+    2: -rw-rw-rw- 1 ville None 1927 Sep 30  2006 example-embed-short.py
+    3: -rwxrwxrwx 1 ville None 4606 Sep  1 17:15 example-embed.py
+    4: -rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py
+    5: -rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py
+    6: -rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py
+    7: -rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc
 
-*\#*
-    - Prompt number, wrapped in the color escapes for the input prompt
-    (determined by the current color scheme). 
-*\N*
-    - Just the prompt counter number, without any coloring wrappers. You
-    can thus customize the actual prompt colors manually. 
-*\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 '\'. 
+Now, let's filter out the 'embed' lines::
 
-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:
+    [Q:doc/examples]|4> l2 = lines.grep('embed',prune=1)
+    [Q:doc/examples]|5> l2
+                    <5> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
 
-*\C_Black*
+    0: total 23
+    1: -rw-rw-rw- 1 ville None 1163 Sep 30  2006 example-demo.py
+    2: -rwxrwxrwx 1 ville None 1017 Sep 30  2006 example-gnuplot.py
+    3: -rwxrwxrwx 1 ville None  339 Jun 11 18:01 extension.py
+    4: -rwxrwxrwx 1 ville None  113 Dec 20  2006 seteditor.py
+    5: -rwxrwxrwx 1 ville None  245 Dec 12  2006 seteditor.pyc
 
-*\C_Blue*
+Now, we want strings having just file names and permissions::
 
-*\C_Brown*
+    [Q:doc/examples]|6> l2.fields(8,0)
+                    <6> SList (.p, .n, .l, .s, .grep(), .fields() available). Value:
 
-*\C_Cyan*
+    0: total
+    1: example-demo.py -rw-rw-rw-
+    2: example-gnuplot.py -rwxrwxrwx
+    3: extension.py -rwxrwxrwx
+    4: seteditor.py -rwxrwxrwx
+    5: seteditor.pyc -rwxrwxrwx
 
-*\C_DarkGray*
+Note how the line with 'total' does not raise IndexError.
 
-*\C_Green*
+If you want to split these (yielding lists), call fields() without
+arguments::
 
-*\C_LightBlue*
+    [Q:doc/examples]|7> _.fields()
+                    <7>
+    [['total'],
+     ['example-demo.py', '-rw-rw-rw-'],
+     ['example-gnuplot.py', '-rwxrwxrwx'],
+     ['extension.py', '-rwxrwxrwx'],
+     ['seteditor.py', '-rwxrwxrwx'],
+     ['seteditor.pyc', '-rwxrwxrwx']]
 
-*\C_LightCyan*
+If you want to pass these separated with spaces to a command (typical
+for lists if files), use the .s property::
 
-*\C_LightGray*
 
-*\C_LightGreen*
+    [Q:doc/examples]|13> files = l2.fields(8).s
+    [Q:doc/examples]|14> files
+                    <14> 'example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc'
+    [Q:doc/examples]|15> ls $files
+    example-demo.py  example-gnuplot.py  extension.py  seteditor.py  seteditor.pyc
 
-*\C_LightPurple*
+SLists are inherited from normal python lists, so every list method is
+available::
 
-*\C_LightRed*
+    [Q:doc/examples]|21> lines.append('hey')
 
-*\C_Purple*
 
-*\C_Red*
+Real world example: remove all files outside version control
+------------------------------------------------------------
 
-*\C_White*
+First, capture output of "hg status"::
 
-*\C_Yellow*
+    [Q:/ipython]|28> out = !hg status
+     ==
+    ['M IPython\\Extensions\\ipy_kitcfg.py',
+     'M IPython\\Extensions\\ipy_rehashdir.py',
+    ...
+     '? build\\lib\\IPython\\Debugger.py',
+     '? build\\lib\\IPython\\Extensions\\InterpreterExec.py',
+     '? build\\lib\\IPython\\Extensions\\InterpreterPasteInput.py',
+    ...
+
+(lines starting with ? are not under version control).
+
+::
+
+    [Q:/ipython]|35> junk = out.grep(r'^\?').fields(1)
+    [Q:/ipython]|36> junk
+                <36> SList (.p, .n, .l, .s, .grep(), .fields() availab
+    ...
+    10: build\bdist.win32\winexe\temp\_ctypes.py
+    11: build\bdist.win32\winexe\temp\_hashlib.py
+    12: build\bdist.win32\winexe\temp\_socket.py
+
+Now we can just remove these files by doing 'rm $junk.s'. 
+
+The .s, .n, .p properties
+-------------------------
+
+The '.s' property returns one string where lines are separated by
+single space (for convenient passing to system commands). The '.n'
+property return one string where the lines are separated by '\n'
+(i.e. the original output of the function). If the items in string
+list are file names, '.p' can be used to get a list of "path" objects
+for convenient file manipulation.
 
-*\C_Normal*
-    Stop coloring, defaults to your terminal settings. 
 
 Threading support
 =================
@@ -4595,8 +4769,10 b' value can be read by using the sys.getcheckinterval() function, and it'
 can be reset via sys.setcheckinterval(N). This switching of threads can
 cause subtly confusing effects if one of your threads is doing file I/O.
 In text mode, most systems only flush file buffers when they encounter a
-'\n'. An instruction as simple as 
+'\n'. An instruction as simple as:: 
+
   print >> filehandle, ''hello world''
+
 actually consists of several bytecodes, so it is possible that the
 newline does not reach your file before the next thread switch.
 Similarly, if you are writing to a file in binary mode, the file won't
@@ -4608,6 +4784,7 b' example) a GUI application which will read data generated by files'
 written to from the IPython thread, the safest approach is to open all
 of your files in unbuffered mode (the third argument to the file/open
 function is the buffering value)::
+
   filehandle = open(filename,mode,0)
 
 This is obviously a brute force way of avoiding race conditions with the
@@ -4738,6 +4915,258 b" mechanism (Sec. 7.3 <node7.html#sec:profiles>): ''ipython -pylab -p"
 myprofile'' will load the profile defined in ipythonrc-myprofile after
 configuring matplotlib.
 
+IPython Extension Api
+=====================
+
+IPython api (defined in IPython/ipapi.py) is the public api that
+should be used for
+
+ * Configuration of user preferences (.ipython/ipy_user_conf.py)
+ * Creating new profiles (.ipython/ipy_profile_PROFILENAME.py)
+ * Writing extensions 
+
+Note that by using the extension api for configuration (editing
+ipy_user_conf.py instead of ipythonrc), you get better validity checks
+and get richer functionality - for example, you can import an
+extension and call functions in it to configure it for your purposes.
+
+For an example extension (the 'sh' profile), see
+IPython/Extensions/ipy_profile_sh.py.
+
+For the last word on what's available, see the source code of
+IPython/ipapi.py.
+
+
+Getting started
+---------------
+
+If you want to define an extension, create a normal python module that
+can be imported. The module will access IPython functionality through
+the 'ip' object defined below.
+
+If you are creating a new profile (e.g. foobar), name the module as
+'ipy_profile_foobar.py' and put it in your ~/.ipython directory. Then,
+when you start ipython with the '-p foobar' argument, the module is
+automatically imported on ipython startup.
+
+If you are just doing some per-user configuration, you can either 
+
+ * Put the commands directly into ipy_user_conf.py. 
+
+ * Create a new module with your customization code and import *that*
+   module in ipy_user_conf.py. This is preferable to the first approach,
+   because now you can reuse and distribute your customization code.
+
+Getting a handle to the api
+---------------------------
+
+Put this in the start of your module::
+
+    #!python
+    import IPython.ipapi
+    ip = IPython.ipapi.get()
+
+The 'ip' object will then be used for accessing IPython
+functionality. 'ip' will mean this api object in all the following
+code snippets. The same 'ip' that we just acquired is always
+accessible in interactive IPython sessions by the name _ip - play with
+it like this::
+
+    [~\_ipython]|81> a = 10
+    [~\_ipython]|82> _ip.e
+    _ip.ev           _ip.ex           _ip.expose_magic
+    [~\_ipython]|82> _ip.ev('a+13')
+                <82> 23
+
+The _ip object is also used in some examples in this document - it can
+be substituted by 'ip' in non-interactive use.
+
+Changing options
+----------------
+
+The ip object has 'options' attribute that can be used te get/set
+configuration options (just as in the ipythonrc file)::
+
+    o = ip.options
+    o.autocall = 2
+    o.automagic = 1
+
+Executing statements in IPython namespace with 'ex' and 'ev'
+------------------------------------------------------------
+
+Often, you want to e.g. import some module or define something that
+should be visible in IPython namespace. Use ``ip.ev`` to
+*evaluate* (calculate the value of) expression and ``ip.ex`` to
+'''execute''' a statement::
+
+    # path module will be visible to the interactive session
+    ip.ex("from path import path" )
+
+    # define a handy function 'up' that changes the working directory
+
+    ip.ex('import os')
+    ip.ex("def up(): os.chdir('..')")
+
+
+    # _i2 has the input history entry #2, print its value in uppercase.
+    print ip.ev('_i2.upper()')
+
+Accessing the IPython namespace
+-------------------------------
+
+ip.user_ns attribute has a dictionary containing the IPython global
+namespace (the namespace visible in the interactive session).
+
+::
+
+    [~\_ipython]|84> tauno = 555
+    [~\_ipython]|85> _ip.user_ns['tauno']
+                <85> 555
+
+Defining new magic commands
+---------------------------
+
+The following example defines a new magic command, %impall. What the
+command does should be obvious::
+
+    def doimp(self, arg):
+        ip = self.api
+        ip.ex("import %s; reload(%s); from %s import *" % (
+        arg,arg,arg)
+        )
+
+    ip.expose_magic('impall', doimp)
+
+Things to observe in this example:
+
+ * Define a function that implements the magic command using the 
+   ipapi methods defined in this document
+ * The first argument of the function is 'self', i.e. the 
+   interpreter object. It shouldn't be used directly. however. 
+   The interpreter object is probably *not* going to remain stable 
+   through IPython versions.
+ * Access the ipapi through 'self.api' instead of the global 'ip' object.
+ * All the text following the magic command on the command line is 
+   contained in the second argument
+ * Expose the magic by ip.expose_magic()
+
+
+Calling magic functions and system commands
+-------------------------------------------
+
+Use ip.magic() to execute a magic function, and ip.system() to execute
+a system command::
+
+    # go to a bookmark
+    ip.magic('%cd -b relfiles')
+
+    # execute 'ls -F' system command. Interchangeable with os.system('ls'), really.
+    ip.system('ls -F')
+
+Launching IPython instance from normal python code
+--------------------------------------------------
+
+Use ipapi.launch_new_instance() with an argument that specifies the
+namespace to use. This can be useful for trivially embedding IPython
+into your program. Here's an example of normal python program test.py
+('''without''' an existing IPython session) that launches an IPython
+interpreter and regains control when the interpreter is exited::
+
+    [ipython]|1> cat test.py
+    my_ns = dict(
+        kissa = 15,
+        koira = 16)
+    import IPython.ipapi
+    print "launching IPython instance"
+    IPython.ipapi.launch_new_instance(my_ns)
+    print "Exited IPython instance!"
+    print "New vals:",my_ns['kissa'], my_ns['koira']
+
+And here's what it looks like when run (note how we don't start it
+from an ipython session)::
+
+    Q:\ipython>python test.py
+    launching IPython instance
+    Py 2.5 (r25:51908, Sep 19 2006, 09:52:17) [MSC v.1310 32 bit (Intel)] IPy 0.7.3b3.r1975
+    [ipython]|1> kissa = 444
+    [ipython]|2> koira = 555
+    [ipython]|3> Exit
+    Exited IPython instance!
+    New vals: 444 555
+
+Accessing unexposed functionality
+---------------------------------
+
+There are still many features that are not exposed via the ipapi. If
+you can't avoid using them, you can use the functionality in
+InteractiveShell object (central IPython session class, defined in
+iplib.py) through ip.IP.
+
+For example::
+
+    [~]|7> _ip.IP.expand_aliases('np','myfile.py')
+       <7> 'c:/opt/Notepad++/notepad++.exe myfile.py'
+    [~]|8>
+
+Still, it's preferable that if you encounter such a feature, contact
+the IPython team and request that the functionality be exposed in a
+future version of IPython. Things not in ipapi are more likely to
+change over time.
+
+Provided extensions
+===================
+
+You can see the list of available extensions (and profiles) by doing
+``import ipy_<TAB>``. Some extensions don't have the ``ipy_`` prefix in
+module name, so you may need to see the contents of IPython/Extensions
+folder to see what's available.
+
+You can see a brief documentation of an extension by looking at the
+module docstring::
+
+    [c:p/ipython_main]|190> import ipy_fsops
+    [c:p/ipython_main]|191> ipy_fsops?
+
+    ...
+
+    Docstring:
+        File system operations
+
+    Contains: Simple variants of normal unix shell commands (icp, imv, irm,
+    imkdir, igrep).
+
+You can also install your own extensions - the recommended way is to
+just copy the module to ~/.ipython. Extensions are typically enabled
+by just importing them (e.g. in ipy_user_conf.py), but some extensions
+require additional steps, for example::
+
+    [c:p]|192> import ipy_traits_completer
+    [c:p]|193> ipy_traits_completer.activate()    
+
+Note that extensions, even if provided in the stock IPython
+installation, are not guaranteed to have the same requirements as the
+rest of IPython - an extension may require external libraries or a
+newer version of Python than what IPython officially requires. An
+extension may also be under a more restrictive license than IPython
+(e.g. ipy_bzr is under GPL).
+
+Just for reference, the list of bundled extensions at the time of
+writing is below:
+
+astyle.py clearcmd.py envpersist.py ext_rescapture.py ibrowse.py
+igrid.py InterpreterExec.py InterpreterPasteInput.py ipipe.py
+ipy_app_completers.py ipy_autoreload.py ipy_bzr.py ipy_completers.py
+ipy_constants.py ipy_defaults.py ipy_editors.py ipy_exportdb.py
+ipy_extutil.py ipy_fsops.py ipy_gnuglobal.py ipy_kitcfg.py
+ipy_legacy.py ipy_leo.py ipy_p4.py ipy_profile_doctest.py
+ipy_profile_none.py ipy_profile_scipy.py ipy_profile_sh.py
+ipy_profile_zope.py ipy_pydb.py ipy_rehashdir.py ipy_render.py
+ipy_server.py ipy_signals.py ipy_stock_completers.py
+ipy_system_conf.py ipy_traits_completer.py ipy_vimserver.py
+ipy_which.py ipy_workdir.py jobctrl.py ledit.py numeric_formats.py
+PhysicalQInput.py PhysicalQInteractive.py pickleshare.py
+pspersistence.py win32clip.py __init__.py
+
 Reporting bugs
 ==============
 
@@ -4773,6 +5202,7 b' Brief history'
 
 
 Origins
+-------
 
 The current IPython system grew out of the following three projects: