From 434bb4e73705332145a434fa389985817bc42884 2011-11-26 18:06:49 From: Thomas Kluyver Date: 2011-11-26 18:06:49 Subject: [PATCH] Improve and update interactive docs. --- diff --git a/docs/source/interactive/reference.txt b/docs/source/interactive/reference.txt index 39e9d4e..46a172f 100644 --- a/docs/source/interactive/reference.txt +++ b/docs/source/interactive/reference.txt @@ -652,47 +652,33 @@ typing ``!ls`` will run 'ls' in the current directory. Manual capture of command output -------------------------------- -If the input line begins with two exclamation marks, !!, the command is -executed but its output is captured and returned as a python list, split -on newlines. Any output sent by the subprocess to standard error is -printed separately, so that the resulting list only captures standard -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. The direct use of -%sc is now deprecated, and you should ise the ``var = !cmd`` syntax -instead. +You can assign the result of a system command to a Python variable with the +syntax ``myfiles = !ls``. This gets machine readable output from stdout +(e.g. without colours), and splits on newlines. To explicitly get this sort of +output without assigning to a variable, use two exclamation marks (``!!ls``) or +the ``%sx`` magic command. + +The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s`` +returns a string delimited by newlines or spaces, respectively. ``myfiles.p`` +produces `path objects `_ from the list items. IPython also allows you to expand the value of python variables when -making system calls. Any python variable or expression which you prepend -with $ will get expanded before the system call is made:: +making system calls. Wrap variables or expressions in {braces}:: - In [1]: pyvar='Hello world' - In [2]: !echo "A python variable: $pyvar" + In [1]: pyvar = 'Hello world' + In [2]: !echo "A python variable: {pyvar}" A python variable: Hello world + In [3]: import math + In [4]: x = 8 + In [5]: !echo {math.factorial(x)} + 40320 -If you want the shell to actually see a literal $, you need to type it -twice:: - - In [3]: !echo "A system variable: $$HOME" - A system variable: /home/fperez - -You can pass arbitrary expressions, though you'll need to delimit them -with {} if there is ambiguity as to the extent of the expression:: +For simple cases, you can alternatively prepend $ to a variable name:: - In [5]: x=10 - In [6]: y=20 - In [13]: !echo $x+y - 10+y - In [7]: !echo ${x+y} - 30 - -Even object attributes can be expanded:: - - In [12]: !echo $sys.argv + In [6]: !echo $sys.argv [/home/fperez/usr/bin/ipython] - + In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $ + A system variable: /home/fperez System command aliases ---------------------- diff --git a/docs/source/interactive/tutorial.txt b/docs/source/interactive/tutorial.txt index 01adac8..0ca22b0 100644 --- a/docs/source/interactive/tutorial.txt +++ b/docs/source/interactive/tutorial.txt @@ -74,9 +74,9 @@ After an exception occurs, you can call ``%debug`` to jump into the Python debugger (pdb) and examine the problem. Alternatively, if you call ``%pdb``, IPython will automatically start the debugger on any uncaught exception. You can print variables, see code, execute statements and even walk up and down the -call stack to track down the true source of the problem. Running programs with -%run and pdb active can be an efficient way to develop and debug code, in many -cases eliminating the need for print statements or external debugging tools. +call stack to track down the true source of the problem. This can be an efficient +way to develop and debug code, in many cases eliminating the need for print +statements or external debugging tools. You can also step through a program from the beginning by calling ``%run -d theprogram.py``. @@ -88,10 +88,9 @@ IPython stores both the commands you enter, and the results it produces. You can easily go through previous commands with the up- and down-arrow keys, or access your history in more sophisticated ways. -Input and output history are kept in variables called ``In`` and ``Out``, which -can both be indexed by the prompt number on which they occurred, e.g. ``In[4]``. -The last three objects in output history are also kept in variables named ``_``, -``__`` and ``___``. +Input and output history are kept in variables called ``In`` and ``Out``, keyed +by the prompt numbers, e.g. ``In[4]``. The last three objects in output history +are also kept in variables named ``_``, ``__`` and ``___``. You can use the ``%history`` magic function to examine past input and output. Input history from previous sessions is saved in a database, and IPython can be