python-ipython-diff.rst
249 lines
| 6.4 KiB
| text/x-rst
|
RstLexer
Matthias Bussonnier
|
r21667 | ================= | ||
Python vs IPython | ||||
================= | ||||
Matthias Bussonnier
|
r21662 | |||
Matthias Bussonnier
|
r21667 | This document is meant to highlight the main differences between the Python | ||
Matthias Bussonnier
|
r21662 | 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 | ||||
klonuo
|
r22475 | script. | ||
Matthias Bussonnier
|
r21662 | |||
Each of these features are describe more in details in further part of the documentation. | ||||
Quick overview: | ||||
=============== | ||||
Min RK
|
r21713 | All the following construct are valid IPython syntax: | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: ? | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: ?object | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: object? | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: *pattern*? | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: %shell like --syntax | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: !ls | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: my_files =! ls ~/ | ||
In [1]: for i,file in enumerate(my_file): | ||||
...: raw = !echo $file | ||||
...: !echo {files[0].upper()} $raw | ||||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: %%perl magic --function | ||
...: @months = ("July", "August", "September"); | ||||
...: print $months[0]; | ||||
klonuo
|
r22475 | |||
Matthias Bussonnier
|
r21662 | |||
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: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | In [1]: ? | ||
Matthias Bussonnier
|
r21662 | |||
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: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
In [6]: object? | ||||
Docstring: The most base type | ||||
Type: type | ||||
A double question mark will try to pull out more information about the object, | ||||
klonuo
|
r22475 | and if possible display the python source code of this object. | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
In[1]: import collections | ||||
Matthias Bussonnier
|
r21667 | In[2]: collection.Counter?? | ||
Matthias Bussonnier
|
r21662 | |||
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' | ||||
... | ||||
Matthias Bussonnier
|
r21667 | If you are looking for an object, the use of wildcards ``*`` in conjunction | ||
Matthias Bussonnier
|
r21662 | with question mark will allow you to search current namespace for object with | ||
Matthias Bussonnier
|
r21667 | matching names: | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | In [24]: *int*? | ||
FloatingPointError | ||||
int | ||||
Shell Assignment | ||||
================ | ||||
When doing interactive computing it is common to need to access the underlying shell. | ||||
klonuo
|
r22475 | This is doable through the use of the exclamation mark ``!`` (or bang). | ||
Matthias Bussonnier
|
r21662 | |||
This allow to execute simple command when present in beginning of line: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
In[1]: !pwd | ||||
/User/home/ | ||||
Change directory: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
In[1]: !cd /var/etc | ||||
Or edit file: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
In[1]: !mvim myfile.txt | ||||
Matthias Bussonnier
|
r21667 | The line after the bang can call any program installed in the underlying | ||
Matthias Bussonnier
|
r21662 | shell, and support variable expansion in the form of ``$variable`` or ``{variable}``. | ||
Matthias Bussonnier
|
r21667 | The later form of expansion supports arbitrary python expression: | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
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 | ||||
Matthias Bussonnier
|
r21667 | standard output of the command after the bang ``!`` will be split out into lines | ||
klonuo
|
r22481 | in a list-like object and assign to the left hand side. | ||
Matthias Bussonnier
|
r21662 | |||
Matthias Bussonnier
|
r21667 | This allow you for example to put the list of files of the current working directory in a variable: | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
In[1]: my_files != ls | ||||
You can combine the different possibilities in for loops, condition, functions...: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
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 | ||||
Matthias Bussonnier
|
r21667 | similar to the one with the bang (``!``) syntax, but with more flexibility and | ||
klonuo
|
r22475 | power. Magic function start with a percent sign (``%``) or double percent (``%%``). | ||
Matthias Bussonnier
|
r21662 | |||
A magic call with a sign percent will act only one line: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
In[1]: %xmode | ||||
Exception reporting mode: Verbose | ||||
And support assignment: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
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]: <TimeitResult : 1 loops, best of 1: 21.1 µs per loop> | ||||
Magic with two percent sign can spread over multiple lines, but do not support assignment: | ||||
Min RK
|
r21713 | .. code-block:: ipython | ||
Matthias Bussonnier
|
r21662 | |||
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 | ||||
---------------- | ||||
Min RK
|
r21713 | :: | ||
Matthias Bussonnier
|
r21662 | |||
Min RK
|
r21713 | find a snippet that combine all that into one thing! | ||