From 55645bdc18fc9ba95efa4bf7b22d9d8077ba687e 2015-09-19 22:17:21 From: Matthias Bussonnier Date: 2015-09-19 22:17:21 Subject: [PATCH] python-diff --- diff --git a/docs/source/interactive/python-ipython-diff.rst b/docs/source/interactive/python-ipython-diff.rst new file mode 100644 index 0000000..431b742 --- /dev/null +++ b/docs/source/interactive/python-ipython-diff.rst @@ -0,0 +1,251 @@ +================== +IPython vs IPython +================== + +This document is meant to highlight the main differences between the python +language and what are the specific construct you can do only in IPython. + +Unless expressed otherwise all of the construct you will see here will raise a +``SyntaxError`` if run in a pure Python shell, or if executing in a Python +script. + +Each of these features are describe more in details in further part of the documentation. + + +Quick overview: +=============== + + +All the following construct are valid IPython syntax : + +.. code-block:: + + ? + +.. code-block:: + + ?object + + +.. code-block:: + + object? + +.. code-block:: + + *patern*? + +.. code-block:: + + %shell like --syntax + +.. code-block:: + + !ls + +.. code-block:: + + my_files =! ls ~/ + for i,file in enumerate(my_file): + raw = !echo $file + !echo {files[0].upper()} $raw + + +.. code-block:: + + %%perl magic --function + @months = ("July", "August", "September"); + print $months[0]; + + +Each of these construct is compile by IPython into valid python code and will +do most of the time what you expect it will do. Let see each of these example +in more detail. + + + + + +Accessing help +============== + +As IPython is mostly an interactive shell, the question mark is a simple +shortcut to get help. A question mark alone will bring up the IPython help: + +.. code-block:: + + In[1]:? + + IPython -- An enhanced Interactive Python + ========================================= + + IPython offers a combination of convenient shell features, special commands + and a history mechanism for both input (command history) and output (results + caching, similar to Mathematica). It is intended to be a fully compatible + replacement for the standard Python interpreter, while offering vastly + improved functionality and flexibility. + + At your system command line, type 'ipython -h' to see the command line + options available. This document only describes interactive features. + + MAIN FEATURES + ------------- + ... + +A single question mark before, or after an object available in current +namespace will show help relative to this object: + +.. code-block:: + + In [6]: object? + Docstring: The most base type + Type: type + + +A double question mark will try to pull out more information about the object, +and if possible display the python source code of this object. + +.. code-block:: + + In[1]: import collections + In[2]: collection.Counter? + + Init signature: collections.Counter(*args, **kwds) + Source: + class Counter(dict): + '''Dict subclass for counting hashable items. Sometimes called a bag + or multiset. Elements are stored as dictionary keys and their counts + are stored as dictionary values. + + >>> c = Counter('abcdeabcdabcaba') # count elements from a string + + >>> c.most_common(3) # three most common elements + [('a', 5), ('b', 4), ('c', 3)] + >>> sorted(c) # list all unique elements + ['a', 'b', 'c', 'd', 'e'] + >>> ''.join(sorted(c.elements())) # list elements with repetitions + 'aaaaabbbbcccdde' + ... + + + +If you are looking for an object, the use of wildcards ``*`` in conjonction +with question mark will allow you to search current namespace for object with +mathcing names: + +.. code-block:: + In [24]: *int*? + FloatingPointError + int + print + + +Shell Assignment +================ + + +When doing interactive computing it is common to need to access the underlying shell. +This is doable through th use of the exclamation mark ``!`` (or bang). + +This allow to execute simple command when present in beginning of line: + +.. code-block:: + + In[1]: !pwd + /User/home/ + +Change directory: + +.. code-block:: + + In[1]: !cd /var/etc + +Or edit file: + +.. code-block:: + + In[1]: !mvim myfile.txt + + +The line after the bang can can call any program installed in the underlying +shell, and support variable expansion in the form of ``$variable`` or ``{variable}``. +The later for of expansion support arbitrary python expression: + +.. code-block:: + + In[1]: file = 'myfile.txt' + + In[2]: !mv $file {file.upper()} + + +The bang can also be present in the right hand side of an assignment, just +after the equal sign, or separated from it by a white space. In which case the +standard output of the command after the bang ``!`` will be spilt out into line +in a list-like object (:see:`IPython Slist`) and assign to the left hand side. + +This allow you for example to put th list of files of the current working directory in a variable: + +.. code-block:: + + In[1]: my_files != ls + + +You can combine the different possibilities in for loops, condition, functions...: + +.. code-block:: + + my_files =! ls ~/ + b = "backup file" + for i,file in enumerate(my_file): + raw = !echo $backup $file + !cp $file {file.split('.')[0]+'.bak'} + + +Magics +------ + +Magics function are often present in the form of shell-like syntax, but are +under the hood python function. The syntax and assignment possibility are +similar to the one with the bang (``~``) syntax, but with more flexibility and +power. Magic function start with a percent sign (``%``) or double percent (``%%``). + +A magic call with a sign percent will act only one line: + +.. code-block:: + + In[1]: %xmode + Exception reporting mode: Verbose + +And support assignment: + +.. code-block:: + + In [1]: results = %timeit -r1 -n1 -o list(range(1000)) + 1 loops, best of 1: 21.1 µs per loop + + In [2]: results + Out[2]: + +Magic with two percent sign can spread over multiple lines, but do not support assignment: + +.. code-block:: + + In[1]: %%bash + ... : echo "My shell is:" $SHELL + ... : echo "My disk usage is:" + ... : df -h + My shell is: /usr/local/bin/bash + My disk usage is: + Filesystem Size Used Avail Capacity iused ifree %iused Mounted on + /dev/disk1 233Gi 216Gi 16Gi 94% 56788108 4190706 93% / + devfs 190Ki 190Ki 0Bi 100% 656 0 100% /dev + map -hosts 0Bi 0Bi 0Bi 100% 0 0 100% /net + map auto_home 0Bi 0Bi 0Bi 100% 0 0 100% /hom + + +Combining it all +---------------- + +.. code-block:: + + find a snippet that comboine all that into one thing !