##// END OF EJS Templates
Various small fixes to docs
klonuo -
Show More
@@ -1,18 +1,19 b''
1 ==================================
1 ==================================
2 Using IPython for interactive work
2 Using IPython for interactive work
3 ==================================
3 ==================================
4
4
5 .. toctree::
5 .. toctree::
6 :maxdepth: 2
6 :maxdepth: 2
7
7
8 tutorial
8 tutorial
9 magics
9 magics
10 plotting
10 plotting
11 reference
11 reference
12 shell
12 shell
13 tips
13 tips
14 python-ipython-diff
14
15
15 .. seealso::
16 .. seealso::
16
17
17 `A Qt Console for Jupyter <http://jupyter.org/qtconsole/>`__
18 `A Qt Console for Jupyter <http://jupyter.org/qtconsole/>`__
18 `The Jupyter Notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`__
19 `The Jupyter Notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`__
@@ -1,249 +1,249 b''
1 =================
1 =================
2 Python vs IPython
2 Python vs IPython
3 =================
3 =================
4
4
5 This document is meant to highlight the main differences between the Python
5 This document is meant to highlight the main differences between the Python
6 language and what are the specific construct you can do only in IPython.
6 language and what are the specific construct you can do only in IPython.
7
7
8 Unless expressed otherwise all of the construct you will see here will raise a
8 Unless expressed otherwise all of the construct you will see here will raise a
9 ``SyntaxError`` if run in a pure Python shell, or if executing in a Python
9 ``SyntaxError`` if run in a pure Python shell, or if executing in a Python
10 script.
10 script.
11
11
12 Each of these features are describe more in details in further part of the documentation.
12 Each of these features are describe more in details in further part of the documentation.
13
13
14
14
15 Quick overview:
15 Quick overview:
16 ===============
16 ===============
17
17
18
18
19 All the following construct are valid IPython syntax:
19 All the following construct are valid IPython syntax:
20
20
21 .. code-block:: ipython
21 .. code-block:: ipython
22
22
23 In [1]: ?
23 In [1]: ?
24
24
25 .. code-block:: ipython
25 .. code-block:: ipython
26
26
27 In [1]: ?object
27 In [1]: ?object
28
28
29
29
30 .. code-block:: ipython
30 .. code-block:: ipython
31
31
32 In [1]: object?
32 In [1]: object?
33
33
34 .. code-block:: ipython
34 .. code-block:: ipython
35
35
36 In [1]: *pattern*?
36 In [1]: *pattern*?
37
37
38 .. code-block:: ipython
38 .. code-block:: ipython
39
39
40 In [1]: %shell like --syntax
40 In [1]: %shell like --syntax
41
41
42 .. code-block:: ipython
42 .. code-block:: ipython
43
43
44 In [1]: !ls
44 In [1]: !ls
45
45
46 .. code-block:: ipython
46 .. code-block:: ipython
47
47
48 In [1]: my_files =! ls ~/
48 In [1]: my_files =! ls ~/
49 In [1]: for i,file in enumerate(my_file):
49 In [1]: for i,file in enumerate(my_file):
50 ...: raw = !echo $file
50 ...: raw = !echo $file
51 ...: !echo {files[0].upper()} $raw
51 ...: !echo {files[0].upper()} $raw
52
52
53
53
54 .. code-block:: ipython
54 .. code-block:: ipython
55
55
56 In [1]: %%perl magic --function
56 In [1]: %%perl magic --function
57 ...: @months = ("July", "August", "September");
57 ...: @months = ("July", "August", "September");
58 ...: print $months[0];
58 ...: print $months[0];
59
59
60
60
61 Each of these construct is compile by IPython into valid python code and will
61 Each of these construct is compile by IPython into valid python code and will
62 do most of the time what you expect it will do. Let see each of these example
62 do most of the time what you expect it will do. Let see each of these example
63 in more detail.
63 in more detail.
64
64
65
65
66 Accessing help
66 Accessing help
67 ==============
67 ==============
68
68
69 As IPython is mostly an interactive shell, the question mark is a simple
69 As IPython is mostly an interactive shell, the question mark is a simple
70 shortcut to get help. A question mark alone will bring up the IPython help:
70 shortcut to get help. A question mark alone will bring up the IPython help:
71
71
72 .. code-block:: ipython
72 .. code-block:: ipython
73
73
74 In [1]: ?
74 In [1]: ?
75
75
76 IPython -- An enhanced Interactive Python
76 IPython -- An enhanced Interactive Python
77 =========================================
77 =========================================
78
78
79 IPython offers a combination of convenient shell features, special commands
79 IPython offers a combination of convenient shell features, special commands
80 and a history mechanism for both input (command history) and output (results
80 and a history mechanism for both input (command history) and output (results
81 caching, similar to Mathematica). It is intended to be a fully compatible
81 caching, similar to Mathematica). It is intended to be a fully compatible
82 replacement for the standard Python interpreter, while offering vastly
82 replacement for the standard Python interpreter, while offering vastly
83 improved functionality and flexibility.
83 improved functionality and flexibility.
84
84
85 At your system command line, type 'ipython -h' to see the command line
85 At your system command line, type 'ipython -h' to see the command line
86 options available. This document only describes interactive features.
86 options available. This document only describes interactive features.
87
87
88 MAIN FEATURES
88 MAIN FEATURES
89 -------------
89 -------------
90 ...
90 ...
91
91
92 A single question mark before, or after an object available in current
92 A single question mark before, or after an object available in current
93 namespace will show help relative to this object:
93 namespace will show help relative to this object:
94
94
95 .. code-block:: ipython
95 .. code-block:: ipython
96
96
97 In [6]: object?
97 In [6]: object?
98 Docstring: The most base type
98 Docstring: The most base type
99 Type: type
99 Type: type
100
100
101
101
102 A double question mark will try to pull out more information about the object,
102 A double question mark will try to pull out more information about the object,
103 and if possible display the python source code of this object.
103 and if possible display the python source code of this object.
104
104
105 .. code-block:: ipython
105 .. code-block:: ipython
106
106
107 In[1]: import collections
107 In[1]: import collections
108 In[2]: collection.Counter??
108 In[2]: collection.Counter??
109
109
110 Init signature: collections.Counter(*args, **kwds)
110 Init signature: collections.Counter(*args, **kwds)
111 Source:
111 Source:
112 class Counter(dict):
112 class Counter(dict):
113 '''Dict subclass for counting hashable items. Sometimes called a bag
113 '''Dict subclass for counting hashable items. Sometimes called a bag
114 or multiset. Elements are stored as dictionary keys and their counts
114 or multiset. Elements are stored as dictionary keys and their counts
115 are stored as dictionary values.
115 are stored as dictionary values.
116
116
117 >>> c = Counter('abcdeabcdabcaba') # count elements from a string
117 >>> c = Counter('abcdeabcdabcaba') # count elements from a string
118
118
119 >>> c.most_common(3) # three most common elements
119 >>> c.most_common(3) # three most common elements
120 [('a', 5), ('b', 4), ('c', 3)]
120 [('a', 5), ('b', 4), ('c', 3)]
121 >>> sorted(c) # list all unique elements
121 >>> sorted(c) # list all unique elements
122 ['a', 'b', 'c', 'd', 'e']
122 ['a', 'b', 'c', 'd', 'e']
123 >>> ''.join(sorted(c.elements())) # list elements with repetitions
123 >>> ''.join(sorted(c.elements())) # list elements with repetitions
124 'aaaaabbbbcccdde'
124 'aaaaabbbbcccdde'
125 ...
125 ...
126
126
127
127
128
128
129 If you are looking for an object, the use of wildcards ``*`` in conjunction
129 If you are looking for an object, the use of wildcards ``*`` in conjunction
130 with question mark will allow you to search current namespace for object with
130 with question mark will allow you to search current namespace for object with
131 matching names:
131 matching names:
132
132
133 .. code-block:: ipython
133 .. code-block:: ipython
134
134
135 In [24]: *int*?
135 In [24]: *int*?
136 FloatingPointError
136 FloatingPointError
137 int
137 int
138 print
138 print
139
139
140
140
141 Shell Assignment
141 Shell Assignment
142 ================
142 ================
143
143
144
144
145 When doing interactive computing it is common to need to access the underlying shell.
145 When doing interactive computing it is common to need to access the underlying shell.
146 This is doable through the use of the exclamation mark ``!`` (or bang).
146 This is doable through the use of the exclamation mark ``!`` (or bang).
147
147
148 This allow to execute simple command when present in beginning of line:
148 This allow to execute simple command when present in beginning of line:
149
149
150 .. code-block:: ipython
150 .. code-block:: ipython
151
151
152 In[1]: !pwd
152 In[1]: !pwd
153 /User/home/
153 /User/home/
154
154
155 Change directory:
155 Change directory:
156
156
157 .. code-block:: ipython
157 .. code-block:: ipython
158
158
159 In[1]: !cd /var/etc
159 In[1]: !cd /var/etc
160
160
161 Or edit file:
161 Or edit file:
162
162
163 .. code-block:: ipython
163 .. code-block:: ipython
164
164
165 In[1]: !mvim myfile.txt
165 In[1]: !mvim myfile.txt
166
166
167
167
168 The line after the bang can call any program installed in the underlying
168 The line after the bang can call any program installed in the underlying
169 shell, and support variable expansion in the form of ``$variable`` or ``{variable}``.
169 shell, and support variable expansion in the form of ``$variable`` or ``{variable}``.
170 The later form of expansion supports arbitrary python expression:
170 The later form of expansion supports arbitrary python expression:
171
171
172 .. code-block:: ipython
172 .. code-block:: ipython
173
173
174 In[1]: file = 'myfile.txt'
174 In[1]: file = 'myfile.txt'
175
175
176 In[2]: !mv $file {file.upper()}
176 In[2]: !mv $file {file.upper()}
177
177
178
178
179 The bang can also be present in the right hand side of an assignment, just
179 The bang can also be present in the right hand side of an assignment, just
180 after the equal sign, or separated from it by a white space. In which case the
180 after the equal sign, or separated from it by a white space. In which case the
181 standard output of the command after the bang ``!`` will be split out into lines
181 standard output of the command after the bang ``!`` will be split out into lines
182 in a list-like object (:see:`IPython Slist`) and assign to the left hand side.
182 in a list-like object (:ref:`IPython Slist`) and assign to the left hand side.
183
183
184 This allow you for example to put the list of files of the current working directory in a variable:
184 This allow you for example to put the list of files of the current working directory in a variable:
185
185
186 .. code-block:: ipython
186 .. code-block:: ipython
187
187
188 In[1]: my_files != ls
188 In[1]: my_files != ls
189
189
190
190
191 You can combine the different possibilities in for loops, condition, functions...:
191 You can combine the different possibilities in for loops, condition, functions...:
192
192
193 .. code-block:: ipython
193 .. code-block:: ipython
194
194
195 my_files =! ls ~/
195 my_files =! ls ~/
196 b = "backup file"
196 b = "backup file"
197 for i,file in enumerate(my_file):
197 for i,file in enumerate(my_file):
198 raw = !echo $backup $file
198 raw = !echo $backup $file
199 !cp $file {file.split('.')[0]+'.bak'}
199 !cp $file {file.split('.')[0]+'.bak'}
200
200
201
201
202 Magics
202 Magics
203 ------
203 ------
204
204
205 Magics function are often present in the form of shell-like syntax, but are
205 Magics function are often present in the form of shell-like syntax, but are
206 under the hood python function. The syntax and assignment possibility are
206 under the hood python function. The syntax and assignment possibility are
207 similar to the one with the bang (``!``) syntax, but with more flexibility and
207 similar to the one with the bang (``!``) syntax, but with more flexibility and
208 power. Magic function start with a percent sign (``%``) or double percent (``%%``).
208 power. Magic function start with a percent sign (``%``) or double percent (``%%``).
209
209
210 A magic call with a sign percent will act only one line:
210 A magic call with a sign percent will act only one line:
211
211
212 .. code-block:: ipython
212 .. code-block:: ipython
213
213
214 In[1]: %xmode
214 In[1]: %xmode
215 Exception reporting mode: Verbose
215 Exception reporting mode: Verbose
216
216
217 And support assignment:
217 And support assignment:
218
218
219 .. code-block:: ipython
219 .. code-block:: ipython
220
220
221 In [1]: results = %timeit -r1 -n1 -o list(range(1000))
221 In [1]: results = %timeit -r1 -n1 -o list(range(1000))
222 1 loops, best of 1: 21.1 Β΅s per loop
222 1 loops, best of 1: 21.1 Β΅s per loop
223
223
224 In [2]: results
224 In [2]: results
225 Out[2]: <TimeitResult : 1 loops, best of 1: 21.1 Β΅s per loop>
225 Out[2]: <TimeitResult : 1 loops, best of 1: 21.1 Β΅s per loop>
226
226
227 Magic with two percent sign can spread over multiple lines, but do not support assignment:
227 Magic with two percent sign can spread over multiple lines, but do not support assignment:
228
228
229 .. code-block:: ipython
229 .. code-block:: ipython
230
230
231 In[1]: %%bash
231 In[1]: %%bash
232 ... : echo "My shell is:" $SHELL
232 ... : echo "My shell is:" $SHELL
233 ... : echo "My disk usage is:"
233 ... : echo "My disk usage is:"
234 ... : df -h
234 ... : df -h
235 My shell is: /usr/local/bin/bash
235 My shell is: /usr/local/bin/bash
236 My disk usage is:
236 My disk usage is:
237 Filesystem Size Used Avail Capacity iused ifree %iused Mounted on
237 Filesystem Size Used Avail Capacity iused ifree %iused Mounted on
238 /dev/disk1 233Gi 216Gi 16Gi 94% 56788108 4190706 93% /
238 /dev/disk1 233Gi 216Gi 16Gi 94% 56788108 4190706 93% /
239 devfs 190Ki 190Ki 0Bi 100% 656 0 100% /dev
239 devfs 190Ki 190Ki 0Bi 100% 656 0 100% /dev
240 map -hosts 0Bi 0Bi 0Bi 100% 0 0 100% /net
240 map -hosts 0Bi 0Bi 0Bi 100% 0 0 100% /net
241 map auto_home 0Bi 0Bi 0Bi 100% 0 0 100% /hom
241 map auto_home 0Bi 0Bi 0Bi 100% 0 0 100% /hom
242
242
243
243
244 Combining it all
244 Combining it all
245 ----------------
245 ----------------
246
246
247 ::
247 ::
248
248
249 find a snippet that combine all that into one thing!
249 find a snippet that combine all that into one thing!
@@ -1,998 +1,998 b''
1 =================
1 =================
2 IPython reference
2 IPython reference
3 =================
3 =================
4
4
5 .. _command_line_options:
5 .. _command_line_options:
6
6
7 Command-line usage
7 Command-line usage
8 ==================
8 ==================
9
9
10 You start IPython with the command::
10 You start IPython with the command::
11
11
12 $ ipython [options] files
12 $ ipython [options] files
13
13
14 If invoked with no options, it executes all the files listed in sequence
14 If invoked with no options, it executes all the files listed in sequence
15 and drops you into the interpreter while still acknowledging any options
15 and drops you into the interpreter while still acknowledging any options
16 you may have set in your ipython_config.py. This behavior is different from
16 you may have set in your ipython_config.py. This behavior is different from
17 standard Python, which when called as python -i will only execute one
17 standard Python, which when called as python -i will only execute one
18 file and ignore your configuration setup.
18 file and ignore your configuration setup.
19
19
20 Please note that some of the configuration options are not available at
20 Please note that some of the configuration options are not available at
21 the command line, simply because they are not practical here. Look into
21 the command line, simply because they are not practical here. Look into
22 your configuration files for details on those. There are separate configuration
22 your configuration files for details on those. There are separate configuration
23 files for each profile, and the files look like :file:`ipython_config.py` or
23 files for each profile, and the files look like :file:`ipython_config.py` or
24 :file:`ipython_config_{frontendname}.py`. Profile directories look like
24 :file:`ipython_config_{frontendname}.py`. Profile directories look like
25 :file:`profile_{profilename}` and are typically installed in the :envvar:`IPYTHONDIR` directory,
25 :file:`profile_{profilename}` and are typically installed in the :envvar:`IPYTHONDIR` directory,
26 which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
26 which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
27 resolves to :file:`C:\\Users\\{YourUserName}` in most instances.
27 resolves to :file:`C:\\Users\\{YourUserName}` in most instances.
28
28
29 Command-line Options
29 Command-line Options
30 --------------------
30 --------------------
31
31
32 To see the options IPython accepts, use ``ipython --help`` (and you probably
32 To see the options IPython accepts, use ``ipython --help`` (and you probably
33 should run the output through a pager such as ``ipython --help | less`` for
33 should run the output through a pager such as ``ipython --help | less`` for
34 more convenient reading). This shows all the options that have a single-word
34 more convenient reading). This shows all the options that have a single-word
35 alias to control them, but IPython lets you configure all of its objects from
35 alias to control them, but IPython lets you configure all of its objects from
36 the command-line by passing the full class name and a corresponding value; type
36 the command-line by passing the full class name and a corresponding value; type
37 ``ipython --help-all`` to see this full list. For example::
37 ``ipython --help-all`` to see this full list. For example::
38
38
39 ipython --matplotlib qt
39 ipython --matplotlib qt
40
40
41 is equivalent to::
41 is equivalent to::
42
42
43 ipython --TerminalIPythonApp.matplotlib='qt'
43 ipython --TerminalIPythonApp.matplotlib='qt'
44
44
45 Note that in the second form, you *must* use the equal sign, as the expression
45 Note that in the second form, you *must* use the equal sign, as the expression
46 is evaluated as an actual Python assignment. While in the above example the
46 is evaluated as an actual Python assignment. While in the above example the
47 short form is more convenient, only the most common options have a short form,
47 short form is more convenient, only the most common options have a short form,
48 while any configurable variable in IPython can be set at the command-line by
48 while any configurable variable in IPython can be set at the command-line by
49 using the long form. This long form is the same syntax used in the
49 using the long form. This long form is the same syntax used in the
50 configuration files, if you want to set these options permanently.
50 configuration files, if you want to set these options permanently.
51
51
52
52
53 Interactive use
53 Interactive use
54 ===============
54 ===============
55
55
56 IPython is meant to work as a drop-in replacement for the standard interactive
56 IPython is meant to work as a drop-in replacement for the standard interactive
57 interpreter. As such, any code which is valid python should execute normally
57 interpreter. As such, any code which is valid python should execute normally
58 under IPython (cases where this is not true should be reported as bugs). It
58 under IPython (cases where this is not true should be reported as bugs). It
59 does, however, offer many features which are not available at a standard python
59 does, however, offer many features which are not available at a standard python
60 prompt. What follows is a list of these.
60 prompt. What follows is a list of these.
61
61
62
62
63 Caution for Windows users
63 Caution for Windows users
64 -------------------------
64 -------------------------
65
65
66 Windows, unfortunately, uses the '\\' character as a path separator. This is a
66 Windows, unfortunately, uses the '\\' character as a path separator. This is a
67 terrible choice, because '\\' also represents the escape character in most
67 terrible choice, because '\\' also represents the escape character in most
68 modern programming languages, including Python. For this reason, using '/'
68 modern programming languages, including Python. For this reason, using '/'
69 character is recommended if you have problems with ``\``. However, in Windows
69 character is recommended if you have problems with ``\``. However, in Windows
70 commands '/' flags options, so you can not use it for the root directory. This
70 commands '/' flags options, so you can not use it for the root directory. This
71 means that paths beginning at the root must be typed in a contrived manner
71 means that paths beginning at the root must be typed in a contrived manner
72 like: ``%copy \opt/foo/bar.txt \tmp``
72 like: ``%copy \opt/foo/bar.txt \tmp``
73
73
74 .. _magic:
74 .. _magic:
75
75
76 Magic command system
76 Magic command system
77 --------------------
77 --------------------
78
78
79 IPython will treat any line whose first character is a % as a special
79 IPython will treat any line whose first character is a % as a special
80 call to a 'magic' function. These allow you to control the behavior of
80 call to a 'magic' function. These allow you to control the behavior of
81 IPython itself, plus a lot of system-type features. They are all
81 IPython itself, plus a lot of system-type features. They are all
82 prefixed with a % character, but parameters are given without
82 prefixed with a % character, but parameters are given without
83 parentheses or quotes.
83 parentheses or quotes.
84
84
85 Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
85 Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
86 only the rest of the current line, but all lines below them as well, in the
86 only the rest of the current line, but all lines below them as well, in the
87 current execution block. Cell magics can in fact make arbitrary modifications
87 current execution block. Cell magics can in fact make arbitrary modifications
88 to the input they receive, which need not even be valid Python code at all.
88 to the input they receive, which need not even be valid Python code at all.
89 They receive the whole block as a single string.
89 They receive the whole block as a single string.
90
90
91 As a line magic example, the :magic:`cd` magic works just like the OS command of
91 As a line magic example, the :magic:`cd` magic works just like the OS command of
92 the same name::
92 the same name::
93
93
94 In [8]: %cd
94 In [8]: %cd
95 /home/fperez
95 /home/fperez
96
96
97 The following uses the builtin :magic:`timeit` in cell mode::
97 The following uses the builtin :magic:`timeit` in cell mode::
98
98
99 In [10]: %%timeit x = range(10000)
99 In [10]: %%timeit x = range(10000)
100 ...: min(x)
100 ...: min(x)
101 ...: max(x)
101 ...: max(x)
102 ...:
102 ...:
103 1000 loops, best of 3: 438 us per loop
103 1000 loops, best of 3: 438 us per loop
104
104
105 In this case, ``x = range(10000)`` is called as the line argument, and the
105 In this case, ``x = range(10000)`` is called as the line argument, and the
106 block with ``min(x)`` and ``max(x)`` is called as the cell body. The
106 block with ``min(x)`` and ``max(x)`` is called as the cell body. The
107 :magic:`timeit` magic receives both.
107 :magic:`timeit` magic receives both.
108
108
109 If you have 'automagic' enabled (as it is by default), you don't need to type in
109 If you have 'automagic' enabled (as it is by default), you don't need to type in
110 the single ``%`` explicitly for line magics; IPython will scan its internal
110 the single ``%`` explicitly for line magics; IPython will scan its internal
111 list of magic functions and call one if it exists. With automagic on you can
111 list of magic functions and call one if it exists. With automagic on you can
112 then just type ``cd mydir`` to go to directory 'mydir'::
112 then just type ``cd mydir`` to go to directory 'mydir'::
113
113
114 In [9]: cd mydir
114 In [9]: cd mydir
115 /home/fperez/mydir
115 /home/fperez/mydir
116
116
117 Cell magics *always* require an explicit ``%%`` prefix, automagic
117 Cell magics *always* require an explicit ``%%`` prefix, automagic
118 calling only works for line magics.
118 calling only works for line magics.
119
119
120 The automagic system has the lowest possible precedence in name searches, so
120 The automagic system has the lowest possible precedence in name searches, so
121 you can freely use variables with the same names as magic commands. If a magic
121 you can freely use variables with the same names as magic commands. If a magic
122 command is 'shadowed' by a variable, you will need the explicit ``%`` prefix to
122 command is 'shadowed' by a variable, you will need the explicit ``%`` prefix to
123 use it:
123 use it:
124
124
125 .. sourcecode:: ipython
125 .. sourcecode:: ipython
126
126
127 In [1]: cd ipython # %cd is called by automagic
127 In [1]: cd ipython # %cd is called by automagic
128 /home/fperez/ipython
128 /home/fperez/ipython
129
129
130 In [2]: cd=1 # now cd is just a variable
130 In [2]: cd=1 # now cd is just a variable
131
131
132 In [3]: cd .. # and doesn't work as a function anymore
132 In [3]: cd .. # and doesn't work as a function anymore
133 File "<ipython-input-3-9fedb3aff56c>", line 1
133 File "<ipython-input-3-9fedb3aff56c>", line 1
134 cd ..
134 cd ..
135 ^
135 ^
136 SyntaxError: invalid syntax
136 SyntaxError: invalid syntax
137
137
138
138
139 In [4]: %cd .. # but %cd always works
139 In [4]: %cd .. # but %cd always works
140 /home/fperez
140 /home/fperez
141
141
142 In [5]: del cd # if you remove the cd variable, automagic works again
142 In [5]: del cd # if you remove the cd variable, automagic works again
143
143
144 In [6]: cd ipython
144 In [6]: cd ipython
145
145
146 /home/fperez/ipython
146 /home/fperez/ipython
147
147
148 Line magics, if they return a value, can be assigned to a variable using the syntax
148 Line magics, if they return a value, can be assigned to a variable using the syntax
149 ``l = %sx ls`` (which in this particular case returns the result of `ls` as a python list).
149 ``l = %sx ls`` (which in this particular case returns the result of `ls` as a python list).
150 See :ref:`below <manual_capture>` for more information.
150 See :ref:`below <manual_capture>` for more information.
151
151
152 Type ``%magic`` for more information, including a list of all available magic
152 Type ``%magic`` for more information, including a list of all available magic
153 functions at any time and their docstrings. You can also type
153 functions at any time and their docstrings. You can also type
154 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
154 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
155 information on the '?' system) to get information about any particular magic
155 information on the '?' system) to get information about any particular magic
156 function you are interested in.
156 function you are interested in.
157
157
158 The API documentation for the :mod:`IPython.core.magic` module contains the full
158 The API documentation for the :mod:`IPython.core.magic` module contains the full
159 docstrings of all currently available magic commands.
159 docstrings of all currently available magic commands.
160
160
161 .. seealso::
161 .. seealso::
162
162
163 :doc:`magics`
163 :doc:`magics`
164 A list of the line and cell magics available in IPython by default
164 A list of the line and cell magics available in IPython by default
165
165
166 :ref:`defining_magics`
166 :ref:`defining_magics`
167 How to define and register additional magic functions
167 How to define and register additional magic functions
168
168
169
169
170 Access to the standard Python help
170 Access to the standard Python help
171 ----------------------------------
171 ----------------------------------
172
172
173 Simply type ``help()`` to access Python's standard help system. You can
173 Simply type ``help()`` to access Python's standard help system. You can
174 also type ``help(object)`` for information about a given object, or
174 also type ``help(object)`` for information about a given object, or
175 ``help('keyword')`` for information on a keyword. You may need to configure your
175 ``help('keyword')`` for information on a keyword. You may need to configure your
176 PYTHONDOCS environment variable for this feature to work correctly.
176 PYTHONDOCS environment variable for this feature to work correctly.
177
177
178 .. _dynamic_object_info:
178 .. _dynamic_object_info:
179
179
180 Dynamic object information
180 Dynamic object information
181 --------------------------
181 --------------------------
182
182
183 Typing ``?word`` or ``word?`` prints detailed information about an object. If
183 Typing ``?word`` or ``word?`` prints detailed information about an object. If
184 certain strings in the object are too long (e.g. function signatures) they get
184 certain strings in the object are too long (e.g. function signatures) they get
185 snipped in the center for brevity. This system gives access variable types and
185 snipped in the center for brevity. This system gives access variable types and
186 values, docstrings, function prototypes and other useful information.
186 values, docstrings, function prototypes and other useful information.
187
187
188 If the information will not fit in the terminal, it is displayed in a pager
188 If the information will not fit in the terminal, it is displayed in a pager
189 (``less`` if available, otherwise a basic internal pager).
189 (``less`` if available, otherwise a basic internal pager).
190
190
191 Typing ``??word`` or ``word??`` gives access to the full information, including
191 Typing ``??word`` or ``word??`` gives access to the full information, including
192 the source code where possible. Long strings are not snipped.
192 the source code where possible. Long strings are not snipped.
193
193
194 The following magic functions are particularly useful for gathering
194 The following magic functions are particularly useful for gathering
195 information about your working environment:
195 information about your working environment:
196
196
197 * :magic:`pdoc` **<object>**: Print (or run through a pager if too long) the
197 * :magic:`pdoc` **<object>**: Print (or run through a pager if too long) the
198 docstring for an object. If the given object is a class, it will
198 docstring for an object. If the given object is a class, it will
199 print both the class and the constructor docstrings.
199 print both the class and the constructor docstrings.
200 * :magic:`pdef` **<object>**: Print the call signature for any callable
200 * :magic:`pdef` **<object>**: Print the call signature for any callable
201 object. If the object is a class, print the constructor information.
201 object. If the object is a class, print the constructor information.
202 * :magic:`psource` **<object>**: Print (or run through a pager if too long)
202 * :magic:`psource` **<object>**: Print (or run through a pager if too long)
203 the source code for an object.
203 the source code for an object.
204 * :magic:`pfile` **<object>**: Show the entire source file where an object was
204 * :magic:`pfile` **<object>**: Show the entire source file where an object was
205 defined via a pager, opening it at the line where the object
205 defined via a pager, opening it at the line where the object
206 definition begins.
206 definition begins.
207 * :magic:`who`/:magic:`whos`: These functions give information about identifiers
207 * :magic:`who`/:magic:`whos`: These functions give information about identifiers
208 you have defined interactively (not things you loaded or defined
208 you have defined interactively (not things you loaded or defined
209 in your configuration files). %who just prints a list of
209 in your configuration files). %who just prints a list of
210 identifiers and %whos prints a table with some basic details about
210 identifiers and %whos prints a table with some basic details about
211 each identifier.
211 each identifier.
212
212
213 The dynamic object information functions (?/??, ``%pdoc``,
213 The dynamic object information functions (?/??, ``%pdoc``,
214 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
214 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
215 directly on variables. For example, after doing ``import os``, you can use
215 directly on variables. For example, after doing ``import os``, you can use
216 ``os.path.abspath??``.
216 ``os.path.abspath??``.
217
217
218 .. _readline:
218 .. _readline:
219
219
220 Readline-based features
220 Readline-based features
221 -----------------------
221 -----------------------
222
222
223 These features require the GNU readline library, so they won't work if your
223 These features require the GNU readline library, so they won't work if your
224 Python installation lacks readline support. We will first describe the default
224 Python installation lacks readline support. We will first describe the default
225 behavior IPython uses, and then how to change it to suit your preferences.
225 behavior IPython uses, and then how to change it to suit your preferences.
226
226
227
227
228 Command line completion
228 Command line completion
229 +++++++++++++++++++++++
229 +++++++++++++++++++++++
230
230
231 At any time, hitting TAB will complete any available python commands or
231 At any time, hitting TAB will complete any available python commands or
232 variable names, and show you a list of the possible completions if
232 variable names, and show you a list of the possible completions if
233 there's no unambiguous one. It will also complete filenames in the
233 there's no unambiguous one. It will also complete filenames in the
234 current directory if no python names match what you've typed so far.
234 current directory if no python names match what you've typed so far.
235
235
236
236
237 Search command history
237 Search command history
238 ++++++++++++++++++++++
238 ++++++++++++++++++++++
239
239
240 IPython provides two ways for searching through previous input and thus
240 IPython provides two ways for searching through previous input and thus
241 reduce the need for repetitive typing:
241 reduce the need for repetitive typing:
242
242
243 1. Start typing, and then use the up and down arrow keys (or :kbd:`Ctrl-p`
243 1. Start typing, and then use the up and down arrow keys (or :kbd:`Ctrl-p`
244 and :kbd:`Ctrl-n`) to search through only the history items that match
244 and :kbd:`Ctrl-n`) to search through only the history items that match
245 what you've typed so far.
245 what you've typed so far.
246 2. Hit :kbd:`Ctrl-r`: to open a search prompt. Begin typing and the system
246 2. Hit :kbd:`Ctrl-r`: to open a search prompt. Begin typing and the system
247 searches your history for lines that contain what you've typed so
247 searches your history for lines that contain what you've typed so
248 far, completing as much as it can.
248 far, completing as much as it can.
249
249
250 IPython will save your input history when it leaves and reload it next
250 IPython will save your input history when it leaves and reload it next
251 time you restart it. By default, the history file is named
251 time you restart it. By default, the history file is named
252 :file:`.ipython/profile_{name}/history.sqlite`.
252 :file:`.ipython/profile_{name}/history.sqlite`.
253
253
254 Autoindent
254 Autoindent
255 ++++++++++
255 ++++++++++
256
256
257 Starting with 5.0, IPython uses `prompt_toolkit` in place of ``readline``,
257 Starting with 5.0, IPython uses `prompt_toolkit` in place of ``readline``,
258 it thus can recognize lines ending in ':' and indent the next line,
258 it thus can recognize lines ending in ':' and indent the next line,
259 while also un-indenting automatically after 'raise' or 'return',
259 while also un-indenting automatically after 'raise' or 'return',
260 and support real multi-line editing as well as syntactic coloration
260 and support real multi-line editing as well as syntactic coloration
261 during edition.
261 during edition.
262
262
263 This feature does not use the ``readline`` library anymore, so it will
263 This feature does not use the ``readline`` library anymore, so it will
264 not honor your :file:`~/.inputrc` configuration (or whatever
264 not honor your :file:`~/.inputrc` configuration (or whatever
265 file your :envvar:`INPUTRC` environment variable points to).
265 file your :envvar:`INPUTRC` environment variable points to).
266
266
267 In particular if you want to change the input mode to ``vi``, you will need to
267 In particular if you want to change the input mode to ``vi``, you will need to
268 set the ``TerminalInteractiveShell.editing_mode`` configuration option of IPython.
268 set the ``TerminalInteractiveShell.editing_mode`` configuration option of IPython.
269
269
270 Session logging and restoring
270 Session logging and restoring
271 -----------------------------
271 -----------------------------
272
272
273 You can log all input from a session either by starting IPython with the
273 You can log all input from a session either by starting IPython with the
274 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
274 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
275 or by activating the logging at any moment with the magic function :magic:`logstart`.
275 or by activating the logging at any moment with the magic function :magic:`logstart`.
276
276
277 Log files can later be reloaded by running them as scripts and IPython
277 Log files can later be reloaded by running them as scripts and IPython
278 will attempt to 'replay' the log by executing all the lines in it, thus
278 will attempt to 'replay' the log by executing all the lines in it, thus
279 restoring the state of a previous session. This feature is not quite
279 restoring the state of a previous session. This feature is not quite
280 perfect, but can still be useful in many cases.
280 perfect, but can still be useful in many cases.
281
281
282 The log files can also be used as a way to have a permanent record of
282 The log files can also be used as a way to have a permanent record of
283 any code you wrote while experimenting. Log files are regular text files
283 any code you wrote while experimenting. Log files are regular text files
284 which you can later open in your favorite text editor to extract code or
284 which you can later open in your favorite text editor to extract code or
285 to 'clean them up' before using them to replay a session.
285 to 'clean them up' before using them to replay a session.
286
286
287 The :magic:`logstart` function for activating logging in mid-session is used as
287 The :magic:`logstart` function for activating logging in mid-session is used as
288 follows::
288 follows::
289
289
290 %logstart [log_name [log_mode]]
290 %logstart [log_name [log_mode]]
291
291
292 If no name is given, it defaults to a file named 'ipython_log.py' in your
292 If no name is given, it defaults to a file named 'ipython_log.py' in your
293 current working directory, in 'rotate' mode (see below).
293 current working directory, in 'rotate' mode (see below).
294
294
295 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
295 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
296 history up to that point and then continues logging.
296 history up to that point and then continues logging.
297
297
298 %logstart takes a second optional parameter: logging mode. This can be
298 %logstart takes a second optional parameter: logging mode. This can be
299 one of (note that the modes are given unquoted):
299 one of (note that the modes are given unquoted):
300
300
301 * [over:] overwrite existing log_name.
301 * [over:] overwrite existing log_name.
302 * [backup:] rename (if exists) to log_name~ and start log_name.
302 * [backup:] rename (if exists) to log_name~ and start log_name.
303 * [append:] well, that says it.
303 * [append:] well, that says it.
304 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
304 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
305
305
306 The :magic:`logoff` and :magic:`logon` functions allow you to temporarily stop and
306 The :magic:`logoff` and :magic:`logon` functions allow you to temporarily stop and
307 resume logging to a file which had previously been started with
307 resume logging to a file which had previously been started with
308 %logstart. They will fail (with an explanation) if you try to use them
308 %logstart. They will fail (with an explanation) if you try to use them
309 before logging has been started.
309 before logging has been started.
310
310
311 .. _system_shell_access:
311 .. _system_shell_access:
312
312
313 System shell access
313 System shell access
314 -------------------
314 -------------------
315
315
316 Any input line beginning with a ! character is passed verbatim (minus
316 Any input line beginning with a ! character is passed verbatim (minus
317 the !, of course) to the underlying operating system. For example,
317 the !, of course) to the underlying operating system. For example,
318 typing ``!ls`` will run 'ls' in the current directory.
318 typing ``!ls`` will run 'ls' in the current directory.
319
319
320 .. _manual_capture:
320 .. _manual_capture:
321
321
322 Manual capture of command output and magic output
322 Manual capture of command output and magic output
323 -------------------------------------------------
323 -------------------------------------------------
324
324
325 You can assign the result of a system command to a Python variable with the
325 You can assign the result of a system command to a Python variable with the
326 syntax ``myfiles = !ls``. Similarly, the result of a magic (as long as it returns
326 syntax ``myfiles = !ls``. Similarly, the result of a magic (as long as it returns
327 a value) can be assigned to a variable. For example, the syntax ``myfiles = %sx ls``
327 a value) can be assigned to a variable. For example, the syntax ``myfiles = %sx ls``
328 is equivalent to the above system command example (the :magic:`sx` magic runs a shell command
328 is equivalent to the above system command example (the :magic:`sx` magic runs a shell command
329 and captures the output). Each of these gets machine
329 and captures the output). Each of these gets machine
330 readable output from stdout (e.g. without colours), and splits on newlines. To
330 readable output from stdout (e.g. without colours), and splits on newlines. To
331 explicitly get this sort of output without assigning to a variable, use two
331 explicitly get this sort of output without assigning to a variable, use two
332 exclamation marks (``!!ls``) or the :magic:`sx` magic command without an assignment.
332 exclamation marks (``!!ls``) or the :magic:`sx` magic command without an assignment.
333 (However, ``!!`` commands cannot be assigned to a variable.)
333 (However, ``!!`` commands cannot be assigned to a variable.)
334
334
335 The captured list in this example has some convenience features. ``myfiles.n`` or ``myfiles.s``
335 The captured list in this example has some convenience features. ``myfiles.n`` or ``myfiles.s``
336 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
336 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
337 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
337 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
338 See :ref:`string_lists` for details.
338 See :ref:`string_lists` for details.
339
339
340 IPython also allows you to expand the value of python variables when
340 IPython also allows you to expand the value of python variables when
341 making system calls. Wrap variables or expressions in {braces}::
341 making system calls. Wrap variables or expressions in {braces}::
342
342
343 In [1]: pyvar = 'Hello world'
343 In [1]: pyvar = 'Hello world'
344 In [2]: !echo "A python variable: {pyvar}"
344 In [2]: !echo "A python variable: {pyvar}"
345 A python variable: Hello world
345 A python variable: Hello world
346 In [3]: import math
346 In [3]: import math
347 In [4]: x = 8
347 In [4]: x = 8
348 In [5]: !echo {math.factorial(x)}
348 In [5]: !echo {math.factorial(x)}
349 40320
349 40320
350
350
351 For simple cases, you can alternatively prepend $ to a variable name::
351 For simple cases, you can alternatively prepend $ to a variable name::
352
352
353 In [6]: !echo $sys.argv
353 In [6]: !echo $sys.argv
354 [/home/fperez/usr/bin/ipython]
354 [/home/fperez/usr/bin/ipython]
355 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
355 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
356 A system variable: /home/fperez
356 A system variable: /home/fperez
357
357
358 Note that `$$` is used to represent a literal `$`.
358 Note that `$$` is used to represent a literal `$`.
359
359
360 System command aliases
360 System command aliases
361 ----------------------
361 ----------------------
362
362
363 The :magic:`alias` magic function allows you to define magic functions which are in fact
363 The :magic:`alias` magic function allows you to define magic functions which are in fact
364 system shell commands. These aliases can have parameters.
364 system shell commands. These aliases can have parameters.
365
365
366 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
366 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
367
367
368 Then, typing ``alias_name params`` will execute the system command 'cmd
368 Then, typing ``alias_name params`` will execute the system command 'cmd
369 params' (from your underlying operating system).
369 params' (from your underlying operating system).
370
370
371 You can also define aliases with parameters using %s specifiers (one per
371 You can also define aliases with parameters using %s specifiers (one per
372 parameter). The following example defines the parts function as an
372 parameter). The following example defines the parts function as an
373 alias to the command 'echo first %s second %s' where each %s will be
373 alias to the command 'echo first %s second %s' where each %s will be
374 replaced by a positional parameter to the call to %parts::
374 replaced by a positional parameter to the call to %parts::
375
375
376 In [1]: %alias parts echo first %s second %s
376 In [1]: %alias parts echo first %s second %s
377 In [2]: parts A B
377 In [2]: parts A B
378 first A second B
378 first A second B
379 In [3]: parts A
379 In [3]: parts A
380 ERROR: Alias <parts> requires 2 arguments, 1 given.
380 ERROR: Alias <parts> requires 2 arguments, 1 given.
381
381
382 If called with no parameters, :magic:`alias` prints the table of currently
382 If called with no parameters, :magic:`alias` prints the table of currently
383 defined aliases.
383 defined aliases.
384
384
385 The :magic:`rehashx` magic allows you to load your entire $PATH as
385 The :magic:`rehashx` magic allows you to load your entire $PATH as
386 ipython aliases. See its docstring for further details.
386 ipython aliases. See its docstring for further details.
387
387
388
388
389 .. _dreload:
389 .. _dreload:
390
390
391 Recursive reload
391 Recursive reload
392 ----------------
392 ----------------
393
393
394 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
394 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
395 module: changes made to any of its dependencies will be reloaded without
395 module: changes made to any of its dependencies will be reloaded without
396 having to exit. To start using it, do::
396 having to exit. To start using it, do::
397
397
398 from IPython.lib.deepreload import reload as dreload
398 from IPython.lib.deepreload import reload as dreload
399
399
400
400
401 Verbose and colored exception traceback printouts
401 Verbose and colored exception traceback printouts
402 -------------------------------------------------
402 -------------------------------------------------
403
403
404 IPython provides the option to see very detailed exception tracebacks,
404 IPython provides the option to see very detailed exception tracebacks,
405 which can be especially useful when debugging large programs. You can
405 which can be especially useful when debugging large programs. You can
406 run any Python file with the %run function to benefit from these
406 run any Python file with the %run function to benefit from these
407 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
407 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
408 be colored (if your terminal supports it) which makes them much easier
408 be colored (if your terminal supports it) which makes them much easier
409 to parse visually.
409 to parse visually.
410
410
411 See the magic :magic:`xmode` and :magic:`colors` functions for details.
411 See the magic :magic:`xmode` and :magic:`colors` functions for details.
412
412
413 These features are basically a terminal version of Ka-Ping Yee's cgitb
413 These features are basically a terminal version of Ka-Ping Yee's cgitb
414 module, now part of the standard Python library.
414 module, now part of the standard Python library.
415
415
416
416
417 .. _input_caching:
417 .. _input_caching:
418
418
419 Input caching system
419 Input caching system
420 --------------------
420 --------------------
421
421
422 IPython offers numbered prompts (In/Out) with input and output caching
422 IPython offers numbered prompts (In/Out) with input and output caching
423 (also referred to as 'input history'). All input is saved and can be
423 (also referred to as 'input history'). All input is saved and can be
424 retrieved as variables (besides the usual arrow key recall), in
424 retrieved as variables (besides the usual arrow key recall), in
425 addition to the :magic:`rep` magic command that brings a history entry
425 addition to the :magic:`rep` magic command that brings a history entry
426 up for editing on the next command line.
426 up for editing on the next command line.
427
427
428 The following variables always exist:
428 The following variables always exist:
429
429
430 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
430 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
431 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
431 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
432 overwrite In with a variable of your own, you can remake the assignment to the
432 overwrite In with a variable of your own, you can remake the assignment to the
433 internal list with a simple ``In=_ih``.
433 internal list with a simple ``In=_ih``.
434
434
435 Additionally, global variables named _i<n> are dynamically created (<n>
435 Additionally, global variables named _i<n> are dynamically created (<n>
436 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
436 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
437
437
438 For example, what you typed at prompt 14 is available as ``_i14``, ``_ih[14]``
438 For example, what you typed at prompt 14 is available as ``_i14``, ``_ih[14]``
439 and ``In[14]``.
439 and ``In[14]``.
440
440
441 This allows you to easily cut and paste multi line interactive prompts
441 This allows you to easily cut and paste multi line interactive prompts
442 by printing them out: they print like a clean string, without prompt
442 by printing them out: they print like a clean string, without prompt
443 characters. You can also manipulate them like regular variables (they
443 characters. You can also manipulate them like regular variables (they
444 are strings), modify or exec them.
444 are strings), modify or exec them.
445
445
446 You can also re-execute multiple lines of input easily by using the
446 You can also re-execute multiple lines of input easily by using the
447 magic :magic:`rerun` or :magic:`macro` functions. The macro system also allows you to re-execute
447 magic :magic:`rerun` or :magic:`macro` functions. The macro system also allows you to re-execute
448 previous lines which include magic function calls (which require special
448 previous lines which include magic function calls (which require special
449 processing). Type %macro? for more details on the macro system.
449 processing). Type %macro? for more details on the macro system.
450
450
451 A history function :magic:`history` allows you to see any part of your input
451 A history function :magic:`history` allows you to see any part of your input
452 history by printing a range of the _i variables.
452 history by printing a range of the _i variables.
453
453
454 You can also search ('grep') through your history by typing
454 You can also search ('grep') through your history by typing
455 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
455 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
456 etc. You can bring history entries listed by '%hist -g' up for editing
456 etc. You can bring history entries listed by '%hist -g' up for editing
457 with the %recall command, or run them immediately with :magic:`rerun`.
457 with the %recall command, or run them immediately with :magic:`rerun`.
458
458
459 .. _output_caching:
459 .. _output_caching:
460
460
461 Output caching system
461 Output caching system
462 ---------------------
462 ---------------------
463
463
464 For output that is returned from actions, a system similar to the input
464 For output that is returned from actions, a system similar to the input
465 cache exists but using _ instead of _i. Only actions that produce a
465 cache exists but using _ instead of _i. Only actions that produce a
466 result (NOT assignments, for example) are cached. If you are familiar
466 result (NOT assignments, for example) are cached. If you are familiar
467 with Mathematica, IPython's _ variables behave exactly like
467 with Mathematica, IPython's _ variables behave exactly like
468 Mathematica's % variables.
468 Mathematica's % variables.
469
469
470 The following variables always exist:
470 The following variables always exist:
471
471
472 * [_] (a single underscore): stores previous output, like Python's
472 * [_] (a single underscore): stores previous output, like Python's
473 default interpreter.
473 default interpreter.
474 * [__] (two underscores): next previous.
474 * [__] (two underscores): next previous.
475 * [___] (three underscores): next-next previous.
475 * [___] (three underscores): next-next previous.
476
476
477 Additionally, global variables named _<n> are dynamically created (<n>
477 Additionally, global variables named _<n> are dynamically created (<n>
478 being the prompt counter), such that the result of output <n> is always
478 being the prompt counter), such that the result of output <n> is always
479 available as _<n> (don't use the angle brackets, just the number, e.g.
479 available as _<n> (don't use the angle brackets, just the number, e.g.
480 ``_21``).
480 ``_21``).
481
481
482 These variables are also stored in a global dictionary (not a
482 These variables are also stored in a global dictionary (not a
483 list, since it only has entries for lines which returned a result)
483 list, since it only has entries for lines which returned a result)
484 available under the names _oh and Out (similar to _ih and In). So the
484 available under the names _oh and Out (similar to _ih and In). So the
485 output from line 12 can be obtained as ``_12``, ``Out[12]`` or ``_oh[12]``. If you
485 output from line 12 can be obtained as ``_12``, ``Out[12]`` or ``_oh[12]``. If you
486 accidentally overwrite the Out variable you can recover it by typing
486 accidentally overwrite the Out variable you can recover it by typing
487 ``Out=_oh`` at the prompt.
487 ``Out=_oh`` at the prompt.
488
488
489 This system obviously can potentially put heavy memory demands on your
489 This system obviously can potentially put heavy memory demands on your
490 system, since it prevents Python's garbage collector from removing any
490 system, since it prevents Python's garbage collector from removing any
491 previously computed results. You can control how many results are kept
491 previously computed results. You can control how many results are kept
492 in memory with the configuration option ``InteractiveShell.cache_size``.
492 in memory with the configuration option ``InteractiveShell.cache_size``.
493 If you set it to 0, output caching is disabled. You can also use the :magic:`reset`
493 If you set it to 0, output caching is disabled. You can also use the :magic:`reset`
494 and :magic:`xdel` magics to clear large items from memory.
494 and :magic:`xdel` magics to clear large items from memory.
495
495
496 Directory history
496 Directory history
497 -----------------
497 -----------------
498
498
499 Your history of visited directories is kept in the global list _dh, and
499 Your history of visited directories is kept in the global list _dh, and
500 the magic :magic:`cd` command can be used to go to any entry in that list. The
500 the magic :magic:`cd` command can be used to go to any entry in that list. The
501 :magic:`dhist` command allows you to view this history. Do ``cd -<TAB>`` to
501 :magic:`dhist` command allows you to view this history. Do ``cd -<TAB>`` to
502 conveniently view the directory history.
502 conveniently view the directory history.
503
503
504
504
505 Automatic parentheses and quotes
505 Automatic parentheses and quotes
506 --------------------------------
506 --------------------------------
507
507
508 These features were adapted from Nathan Gray's LazyPython. They are
508 These features were adapted from Nathan Gray's LazyPython. They are
509 meant to allow less typing for common situations.
509 meant to allow less typing for common situations.
510
510
511 Callable objects (i.e. functions, methods, etc) can be invoked like this
511 Callable objects (i.e. functions, methods, etc) can be invoked like this
512 (notice the commas between the arguments)::
512 (notice the commas between the arguments)::
513
513
514 In [1]: callable_ob arg1, arg2, arg3
514 In [1]: callable_ob arg1, arg2, arg3
515 ------> callable_ob(arg1, arg2, arg3)
515 ------> callable_ob(arg1, arg2, arg3)
516
516
517 .. note::
517 .. note::
518 This feature is disabled by default. To enable it, use the ``%autocall``
518 This feature is disabled by default. To enable it, use the ``%autocall``
519 magic command. The commands below with special prefixes will always work,
519 magic command. The commands below with special prefixes will always work,
520 however.
520 however.
521
521
522 You can force automatic parentheses by using '/' as the first character
522 You can force automatic parentheses by using '/' as the first character
523 of a line. For example::
523 of a line. For example::
524
524
525 In [2]: /globals # becomes 'globals()'
525 In [2]: /globals # becomes 'globals()'
526
526
527 Note that the '/' MUST be the first character on the line! This won't work::
527 Note that the '/' MUST be the first character on the line! This won't work::
528
528
529 In [3]: print /globals # syntax error
529 In [3]: print /globals # syntax error
530
530
531 In most cases the automatic algorithm should work, so you should rarely
531 In most cases the automatic algorithm should work, so you should rarely
532 need to explicitly invoke /. One notable exception is if you are trying
532 need to explicitly invoke /. One notable exception is if you are trying
533 to call a function with a list of tuples as arguments (the parenthesis
533 to call a function with a list of tuples as arguments (the parenthesis
534 will confuse IPython)::
534 will confuse IPython)::
535
535
536 In [4]: zip (1,2,3),(4,5,6) # won't work
536 In [4]: zip (1,2,3),(4,5,6) # won't work
537
537
538 but this will work::
538 but this will work::
539
539
540 In [5]: /zip (1,2,3),(4,5,6)
540 In [5]: /zip (1,2,3),(4,5,6)
541 ------> zip ((1,2,3),(4,5,6))
541 ------> zip ((1,2,3),(4,5,6))
542 Out[5]: [(1, 4), (2, 5), (3, 6)]
542 Out[5]: [(1, 4), (2, 5), (3, 6)]
543
543
544 IPython tells you that it has altered your command line by displaying
544 IPython tells you that it has altered your command line by displaying
545 the new command line preceded by ``--->``.
545 the new command line preceded by ``--->``.
546
546
547 You can force automatic quoting of a function's arguments by using ``,``
547 You can force automatic quoting of a function's arguments by using ``,``
548 or ``;`` as the first character of a line. For example::
548 or ``;`` as the first character of a line. For example::
549
549
550 In [1]: ,my_function /home/me # becomes my_function("/home/me")
550 In [1]: ,my_function /home/me # becomes my_function("/home/me")
551
551
552 If you use ';' the whole argument is quoted as a single string, while ',' splits
552 If you use ';' the whole argument is quoted as a single string, while ',' splits
553 on whitespace::
553 on whitespace::
554
554
555 In [2]: ,my_function a b c # becomes my_function("a","b","c")
555 In [2]: ,my_function a b c # becomes my_function("a","b","c")
556
556
557 In [3]: ;my_function a b c # becomes my_function("a b c")
557 In [3]: ;my_function a b c # becomes my_function("a b c")
558
558
559 Note that the ',' or ';' MUST be the first character on the line! This
559 Note that the ',' or ';' MUST be the first character on the line! This
560 won't work::
560 won't work::
561
561
562 In [4]: x = ,my_function /home/me # syntax error
562 In [4]: x = ,my_function /home/me # syntax error
563
563
564 IPython as your default Python environment
564 IPython as your default Python environment
565 ==========================================
565 ==========================================
566
566
567 Python honors the environment variable :envvar:`PYTHONSTARTUP` and will
567 Python honors the environment variable :envvar:`PYTHONSTARTUP` and will
568 execute at startup the file referenced by this variable. If you put the
568 execute at startup the file referenced by this variable. If you put the
569 following code at the end of that file, then IPython will be your working
569 following code at the end of that file, then IPython will be your working
570 environment anytime you start Python::
570 environment anytime you start Python::
571
571
572 import os, IPython
572 import os, IPython
573 os.environ['PYTHONSTARTUP'] = '' # Prevent running this again
573 os.environ['PYTHONSTARTUP'] = '' # Prevent running this again
574 IPython.start_ipython()
574 IPython.start_ipython()
575 raise SystemExit
575 raise SystemExit
576
576
577 The ``raise SystemExit`` is needed to exit Python when
577 The ``raise SystemExit`` is needed to exit Python when
578 it finishes, otherwise you'll be back at the normal Python ``>>>``
578 it finishes, otherwise you'll be back at the normal Python ``>>>``
579 prompt.
579 prompt.
580
580
581 This is probably useful to developers who manage multiple Python
581 This is probably useful to developers who manage multiple Python
582 versions and don't want to have correspondingly multiple IPython
582 versions and don't want to have correspondingly multiple IPython
583 versions. Note that in this mode, there is no way to pass IPython any
583 versions. Note that in this mode, there is no way to pass IPython any
584 command-line options, as those are trapped first by Python itself.
584 command-line options, as those are trapped first by Python itself.
585
585
586 .. _Embedding:
586 .. _Embedding:
587
587
588 Embedding IPython
588 Embedding IPython
589 =================
589 =================
590
590
591 You can start a regular IPython session with
591 You can start a regular IPython session with
592
592
593 .. sourcecode:: python
593 .. sourcecode:: python
594
594
595 import IPython
595 import IPython
596 IPython.start_ipython(argv=[])
596 IPython.start_ipython(argv=[])
597
597
598 at any point in your program. This will load IPython configuration,
598 at any point in your program. This will load IPython configuration,
599 startup files, and everything, just as if it were a normal IPython session.
599 startup files, and everything, just as if it were a normal IPython session.
600
600
601 It is also possible to embed an IPython shell in a namespace in your Python code.
601 It is also possible to embed an IPython shell in a namespace in your Python code.
602 This allows you to evaluate dynamically the state of your code,
602 This allows you to evaluate dynamically the state of your code,
603 operate with your variables, analyze them, etc. Note however that
603 operate with your variables, analyze them, etc. Note however that
604 any changes you make to values while in the shell do not propagate back
604 any changes you make to values while in the shell do not propagate back
605 to the running code, so it is safe to modify your values because you
605 to the running code, so it is safe to modify your values because you
606 won't break your code in bizarre ways by doing so.
606 won't break your code in bizarre ways by doing so.
607
607
608 .. note::
608 .. note::
609
609
610 At present, embedding IPython cannot be done from inside IPython.
610 At present, embedding IPython cannot be done from inside IPython.
611 Run the code samples below outside IPython.
611 Run the code samples below outside IPython.
612
612
613 This feature allows you to easily have a fully functional python
613 This feature allows you to easily have a fully functional python
614 environment for doing object introspection anywhere in your code with a
614 environment for doing object introspection anywhere in your code with a
615 simple function call. In some cases a simple print statement is enough,
615 simple function call. In some cases a simple print statement is enough,
616 but if you need to do more detailed analysis of a code fragment this
616 but if you need to do more detailed analysis of a code fragment this
617 feature can be very valuable.
617 feature can be very valuable.
618
618
619 It can also be useful in scientific computing situations where it is
619 It can also be useful in scientific computing situations where it is
620 common to need to do some automatic, computationally intensive part and
620 common to need to do some automatic, computationally intensive part and
621 then stop to look at data, plots, etc.
621 then stop to look at data, plots, etc.
622 Opening an IPython instance will give you full access to your data and
622 Opening an IPython instance will give you full access to your data and
623 functions, and you can resume program execution once you are done with
623 functions, and you can resume program execution once you are done with
624 the interactive part (perhaps to stop again later, as many times as
624 the interactive part (perhaps to stop again later, as many times as
625 needed).
625 needed).
626
626
627 The following code snippet is the bare minimum you need to include in
627 The following code snippet is the bare minimum you need to include in
628 your Python programs for this to work (detailed examples follow later)::
628 your Python programs for this to work (detailed examples follow later)::
629
629
630 from IPython import embed
630 from IPython import embed
631
631
632 embed() # this call anywhere in your program will start IPython
632 embed() # this call anywhere in your program will start IPython
633
633
634 You can also embed an IPython *kernel*, for use with qtconsole, etc. via
634 You can also embed an IPython *kernel*, for use with qtconsole, etc. via
635 ``IPython.embed_kernel()``. This should function work the same way, but you can
635 ``IPython.embed_kernel()``. This should function work the same way, but you can
636 connect an external frontend (``ipython qtconsole`` or ``ipython console``),
636 connect an external frontend (``ipython qtconsole`` or ``ipython console``),
637 rather than interacting with it in the terminal.
637 rather than interacting with it in the terminal.
638
638
639 You can run embedded instances even in code which is itself being run at
639 You can run embedded instances even in code which is itself being run at
640 the IPython interactive prompt with '%run <filename>'. Since it's easy
640 the IPython interactive prompt with '%run <filename>'. Since it's easy
641 to get lost as to where you are (in your top-level IPython or in your
641 to get lost as to where you are (in your top-level IPython or in your
642 embedded one), it's a good idea in such cases to set the in/out prompts
642 embedded one), it's a good idea in such cases to set the in/out prompts
643 to something different for the embedded instances. The code examples
643 to something different for the embedded instances. The code examples
644 below illustrate this.
644 below illustrate this.
645
645
646 You can also have multiple IPython instances in your program and open
646 You can also have multiple IPython instances in your program and open
647 them separately, for example with different options for data
647 them separately, for example with different options for data
648 presentation. If you close and open the same instance multiple times,
648 presentation. If you close and open the same instance multiple times,
649 its prompt counters simply continue from each execution to the next.
649 its prompt counters simply continue from each execution to the next.
650
650
651 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
651 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
652 module for more details on the use of this system.
652 module for more details on the use of this system.
653
653
654 The following sample file illustrating how to use the embedding
654 The following sample file illustrating how to use the embedding
655 functionality is provided in the examples directory as embed_class_long.py.
655 functionality is provided in the examples directory as embed_class_long.py.
656 It should be fairly self-explanatory:
656 It should be fairly self-explanatory:
657
657
658 .. literalinclude:: ../../../examples/Embedding/embed_class_long.py
658 .. literalinclude:: ../../../examples/Embedding/embed_class_long.py
659 :language: python
659 :language: python
660
660
661 Once you understand how the system functions, you can use the following
661 Once you understand how the system functions, you can use the following
662 code fragments in your programs which are ready for cut and paste:
662 code fragments in your programs which are ready for cut and paste:
663
663
664 .. literalinclude:: ../../../examples/Embedding/embed_class_short.py
664 .. literalinclude:: ../../../examples/Embedding/embed_class_short.py
665 :language: python
665 :language: python
666
666
667 Using the Python debugger (pdb)
667 Using the Python debugger (pdb)
668 ===============================
668 ===============================
669
669
670 Running entire programs via pdb
670 Running entire programs via pdb
671 -------------------------------
671 -------------------------------
672
672
673 pdb, the Python debugger, is a powerful interactive debugger which
673 pdb, the Python debugger, is a powerful interactive debugger which
674 allows you to step through code, set breakpoints, watch variables,
674 allows you to step through code, set breakpoints, watch variables,
675 etc. IPython makes it very easy to start any script under the control
675 etc. IPython makes it very easy to start any script under the control
676 of pdb, regardless of whether you have wrapped it into a 'main()'
676 of pdb, regardless of whether you have wrapped it into a 'main()'
677 function or not. For this, simply type ``%run -d myscript`` at an
677 function or not. For this, simply type ``%run -d myscript`` at an
678 IPython prompt. See the :magic:`run` command's documentation for more details, including
678 IPython prompt. See the :magic:`run` command's documentation for more details, including
679 how to control where pdb will stop execution first.
679 how to control where pdb will stop execution first.
680
680
681 For more information on the use of the pdb debugger, see :ref:`debugger-commands`
681 For more information on the use of the pdb debugger, see :ref:`debugger-commands`
682 in the Python documentation.
682 in the Python documentation.
683
683
684 IPython extends the debugger with a few useful additions, like coloring of
684 IPython extends the debugger with a few useful additions, like coloring of
685 tracebacks. The debugger will adopt the color scheme selected for IPython.
685 tracebacks. The debugger will adopt the color scheme selected for IPython.
686
686
687 The ``where`` command has also been extended to take as argument the number of
687 The ``where`` command has also been extended to take as argument the number of
688 context line to show. This allows to a many line of context on shallow stack trace:
688 context line to show. This allows to a many line of context on shallow stack trace:
689
689
690 .. code::
690 .. code::
691 In [5]: def foo(x):
691 In [5]: def foo(x):
692 ...: 1
692 ...: 1
693 ...: 2
693 ...: 2
694 ...: 3
694 ...: 3
695 ...: return 1/x+foo(x-1)
695 ...: return 1/x+foo(x-1)
696 ...: 5
696 ...: 5
697 ...: 6
697 ...: 6
698 ...: 7
698 ...: 7
699 ...:
699 ...:
700
700
701 In[6]: foo(1)
701 In[6]: foo(1)
702 # ...
702 # ...
703 ipdb> where 8
703 ipdb> where 8
704 <ipython-input-6-9e45007b2b59>(1)<module>()
704 <ipython-input-6-9e45007b2b59>(1)<module>()
705 ----> 1 foo(1)
705 ----> 1 foo(1)
706
706
707 <ipython-input-5-7baadc3d1465>(5)foo()
707 <ipython-input-5-7baadc3d1465>(5)foo()
708 1 def foo(x):
708 1 def foo(x):
709 2 1
709 2 1
710 3 2
710 3 2
711 4 3
711 4 3
712 ----> 5 return 1/x+foo(x-1)
712 ----> 5 return 1/x+foo(x-1)
713 6 5
713 6 5
714 7 6
714 7 6
715 8 7
715 8 7
716
716
717 > <ipython-input-5-7baadc3d1465>(5)foo()
717 > <ipython-input-5-7baadc3d1465>(5)foo()
718 1 def foo(x):
718 1 def foo(x):
719 2 1
719 2 1
720 3 2
720 3 2
721 4 3
721 4 3
722 ----> 5 return 1/x+foo(x-1)
722 ----> 5 return 1/x+foo(x-1)
723 6 5
723 6 5
724 7 6
724 7 6
725 8 7
725 8 7
726
726
727
727
728 And less context on shallower Stack Trace:
728 And less context on shallower Stack Trace:
729
729
730 .. code::
730 .. code::
731 ipdb> where 1
731 ipdb> where 1
732 <ipython-input-13-afa180a57233>(1)<module>()
732 <ipython-input-13-afa180a57233>(1)<module>()
733 ----> 1 foo(7)
733 ----> 1 foo(7)
734
734
735 <ipython-input-5-7baadc3d1465>(5)foo()
735 <ipython-input-5-7baadc3d1465>(5)foo()
736 ----> 5 return 1/x+foo(x-1)
736 ----> 5 return 1/x+foo(x-1)
737
737
738 <ipython-input-5-7baadc3d1465>(5)foo()
738 <ipython-input-5-7baadc3d1465>(5)foo()
739 ----> 5 return 1/x+foo(x-1)
739 ----> 5 return 1/x+foo(x-1)
740
740
741 <ipython-input-5-7baadc3d1465>(5)foo()
741 <ipython-input-5-7baadc3d1465>(5)foo()
742 ----> 5 return 1/x+foo(x-1)
742 ----> 5 return 1/x+foo(x-1)
743
743
744 <ipython-input-5-7baadc3d1465>(5)foo()
744 <ipython-input-5-7baadc3d1465>(5)foo()
745 ----> 5 return 1/x+foo(x-1)
745 ----> 5 return 1/x+foo(x-1)
746
746
747
747
748 Post-mortem debugging
748 Post-mortem debugging
749 ---------------------
749 ---------------------
750
750
751 Going into a debugger when an exception occurs can be
751 Going into a debugger when an exception occurs can be
752 extremely useful in order to find the origin of subtle bugs, because pdb
752 extremely useful in order to find the origin of subtle bugs, because pdb
753 opens up at the point in your code which triggered the exception, and
753 opens up at the point in your code which triggered the exception, and
754 while your program is at this point 'dead', all the data is still
754 while your program is at this point 'dead', all the data is still
755 available and you can walk up and down the stack frame and understand
755 available and you can walk up and down the stack frame and understand
756 the origin of the problem.
756 the origin of the problem.
757
757
758 You can use the :magic:`debug` magic after an exception has occurred to start
758 You can use the :magic:`debug` magic after an exception has occurred to start
759 post-mortem debugging. IPython can also call debugger every time your code
759 post-mortem debugging. IPython can also call debugger every time your code
760 triggers an uncaught exception. This feature can be toggled with the :magic:`pdb` magic
760 triggers an uncaught exception. This feature can be toggled with the :magic:`pdb` magic
761 command, or you can start IPython with the ``--pdb`` option.
761 command, or you can start IPython with the ``--pdb`` option.
762
762
763 For a post-mortem debugger in your programs outside IPython,
763 For a post-mortem debugger in your programs outside IPython,
764 put the following lines toward the top of your 'main' routine::
764 put the following lines toward the top of your 'main' routine::
765
765
766 import sys
766 import sys
767 from IPython.core import ultratb
767 from IPython.core import ultratb
768 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
768 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
769 color_scheme='Linux', call_pdb=1)
769 color_scheme='Linux', call_pdb=1)
770
770
771 The mode keyword can be either 'Verbose' or 'Plain', giving either very
771 The mode keyword can be either 'Verbose' or 'Plain', giving either very
772 detailed or normal tracebacks respectively. The color_scheme keyword can
772 detailed or normal tracebacks respectively. The color_scheme keyword can
773 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
773 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
774 options which can be set in IPython with ``--colors`` and ``--xmode``.
774 options which can be set in IPython with ``--colors`` and ``--xmode``.
775
775
776 This will give any of your programs detailed, colored tracebacks with
776 This will give any of your programs detailed, colored tracebacks with
777 automatic invocation of pdb.
777 automatic invocation of pdb.
778
778
779 .. _pasting_with_prompts:
779 .. _pasting_with_prompts:
780
780
781 Pasting of code starting with Python or IPython prompts
781 Pasting of code starting with Python or IPython prompts
782 =======================================================
782 =======================================================
783
783
784 IPython is smart enough to filter out input prompts, be they plain Python ones
784 IPython is smart enough to filter out input prompts, be they plain Python ones
785 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``). You can
785 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``). You can
786 therefore copy and paste from existing interactive sessions without worry.
786 therefore copy and paste from existing interactive sessions without worry.
787
787
788 The following is a 'screenshot' of how things work, copying an example from the
788 The following is a 'screenshot' of how things work, copying an example from the
789 standard Python tutorial::
789 standard Python tutorial::
790
790
791 In [1]: >>> # Fibonacci series:
791 In [1]: >>> # Fibonacci series:
792
792
793 In [2]: ... # the sum of two elements defines the next
793 In [2]: ... # the sum of two elements defines the next
794
794
795 In [3]: ... a, b = 0, 1
795 In [3]: ... a, b = 0, 1
796
796
797 In [4]: >>> while b < 10:
797 In [4]: >>> while b < 10:
798 ...: ... print(b)
798 ...: ... print(b)
799 ...: ... a, b = b, a+b
799 ...: ... a, b = b, a+b
800 ...:
800 ...:
801 1
801 1
802 1
802 1
803 2
803 2
804 3
804 3
805 5
805 5
806 8
806 8
807
807
808 And pasting from IPython sessions works equally well::
808 And pasting from IPython sessions works equally well::
809
809
810 In [1]: In [5]: def f(x):
810 In [1]: In [5]: def f(x):
811 ...: ...: "A simple function"
811 ...: ...: "A simple function"
812 ...: ...: return x**2
812 ...: ...: return x**2
813 ...: ...:
813 ...: ...:
814
814
815 In [2]: f(3)
815 In [2]: f(3)
816 Out[2]: 9
816 Out[2]: 9
817
817
818 .. _gui_support:
818 .. _gui_support:
819
819
820 GUI event loop support
820 GUI event loop support
821 ======================
821 ======================
822
822
823 .. versionadded:: 0.11
823 .. versionadded:: 0.11
824 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
824 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
825
825
826 IPython has excellent support for working interactively with Graphical User
826 IPython has excellent support for working interactively with Graphical User
827 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
827 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
828 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
828 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
829 is extremely robust compared to our previous thread-based version. The
829 is extremely robust compared to our previous thread-based version. The
830 advantages of this are:
830 advantages of this are:
831
831
832 * GUIs can be enabled and disabled dynamically at runtime.
832 * GUIs can be enabled and disabled dynamically at runtime.
833 * The active GUI can be switched dynamically at runtime.
833 * The active GUI can be switched dynamically at runtime.
834 * In some cases, multiple GUIs can run simultaneously with no problems.
834 * In some cases, multiple GUIs can run simultaneously with no problems.
835 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
835 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
836 all of these things.
836 all of these things.
837
837
838 For users, enabling GUI event loop integration is simple. You simple use the
838 For users, enabling GUI event loop integration is simple. You simple use the
839 :magic:`gui` magic as follows::
839 :magic:`gui` magic as follows::
840
840
841 %gui [GUINAME]
841 %gui [GUINAME]
842
842
843 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
843 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
844 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
844 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
845
845
846 Thus, to use wxPython interactively and create a running :class:`wx.App`
846 Thus, to use wxPython interactively and create a running :class:`wx.App`
847 object, do::
847 object, do::
848
848
849 %gui wx
849 %gui wx
850
850
851 You can also start IPython with an event loop set up using the :option:`--gui`
851 You can also start IPython with an event loop set up using the `--gui`
852 flag::
852 flag::
853
853
854 $ ipython --gui=qt
854 $ ipython --gui=qt
855
855
856 For information on IPython's matplotlib_ integration (and the ``matplotlib``
856 For information on IPython's matplotlib_ integration (and the ``matplotlib``
857 mode) see :ref:`this section <matplotlib_support>`.
857 mode) see :ref:`this section <matplotlib_support>`.
858
858
859 For developers that want to use IPython's GUI event loop integration in the
859 For developers that want to use IPython's GUI event loop integration in the
860 form of a library, these capabilities are exposed in library form in the
860 form of a library, these capabilities are exposed in library form in the
861 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
861 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
862 Interested developers should see the module docstrings for more information,
862 Interested developers should see the module docstrings for more information,
863 but there are a few points that should be mentioned here.
863 but there are a few points that should be mentioned here.
864
864
865 First, the ``PyOSInputHook`` approach only works in command line settings
865 First, the ``PyOSInputHook`` approach only works in command line settings
866 where readline is activated. The integration with various eventloops
866 where readline is activated. The integration with various eventloops
867 is handled somewhat differently (and more simply) when using the standalone
867 is handled somewhat differently (and more simply) when using the standalone
868 kernel, as in the qtconsole and notebook.
868 kernel, as in the qtconsole and notebook.
869
869
870 Second, when using the ``PyOSInputHook`` approach, a GUI application should
870 Second, when using the ``PyOSInputHook`` approach, a GUI application should
871 *not* start its event loop. Instead all of this is handled by the
871 *not* start its event loop. Instead all of this is handled by the
872 ``PyOSInputHook``. This means that applications that are meant to be used both
872 ``PyOSInputHook``. This means that applications that are meant to be used both
873 in IPython and as standalone apps need to have special code to detects how the
873 in IPython and as standalone apps need to have special code to detects how the
874 application is being run. We highly recommend using IPython's support for this.
874 application is being run. We highly recommend using IPython's support for this.
875 Since the details vary slightly between toolkits, we point you to the various
875 Since the details vary slightly between toolkits, we point you to the various
876 examples in our source directory :file:`examples/Embedding` that demonstrate
876 examples in our source directory :file:`examples/Embedding` that demonstrate
877 these capabilities.
877 these capabilities.
878
878
879 Third, unlike previous versions of IPython, we no longer "hijack" (replace
879 Third, unlike previous versions of IPython, we no longer "hijack" (replace
880 them with no-ops) the event loops. This is done to allow applications that
880 them with no-ops) the event loops. This is done to allow applications that
881 actually need to run the real event loops to do so. This is often needed to
881 actually need to run the real event loops to do so. This is often needed to
882 process pending events at critical points.
882 process pending events at critical points.
883
883
884 Finally, we also have a number of examples in our source directory
884 Finally, we also have a number of examples in our source directory
885 :file:`examples/Embedding` that demonstrate these capabilities.
885 :file:`examples/Embedding` that demonstrate these capabilities.
886
886
887 PyQt and PySide
887 PyQt and PySide
888 ---------------
888 ---------------
889
889
890 .. attempt at explanation of the complete mess that is Qt support
890 .. attempt at explanation of the complete mess that is Qt support
891
891
892 When you use ``--gui=qt`` or ``--matplotlib=qt``, IPython can work with either
892 When you use ``--gui=qt`` or ``--matplotlib=qt``, IPython can work with either
893 PyQt4 or PySide. There are three options for configuration here, because
893 PyQt4 or PySide. There are three options for configuration here, because
894 PyQt4 has two APIs for QString and QVariant: v1, which is the default on
894 PyQt4 has two APIs for QString and QVariant: v1, which is the default on
895 Python 2, and the more natural v2, which is the only API supported by PySide.
895 Python 2, and the more natural v2, which is the only API supported by PySide.
896 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
896 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
897 uses v2, but you can still use any interface in your code, since the
897 uses v2, but you can still use any interface in your code, since the
898 Qt frontend is in a different process.
898 Qt frontend is in a different process.
899
899
900 The default will be to import PyQt4 without configuration of the APIs, thus
900 The default will be to import PyQt4 without configuration of the APIs, thus
901 matching what most applications would expect. It will fall back to PySide if
901 matching what most applications would expect. It will fall back to PySide if
902 PyQt4 is unavailable.
902 PyQt4 is unavailable.
903
903
904 If specified, IPython will respect the environment variable ``QT_API`` used
904 If specified, IPython will respect the environment variable ``QT_API`` used
905 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
905 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
906 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
906 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
907 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
907 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
908 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
908 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
909
909
910 If you launch IPython in matplotlib mode with ``ipython --matplotlib=qt``,
910 If you launch IPython in matplotlib mode with ``ipython --matplotlib=qt``,
911 then IPython will ask matplotlib which Qt library to use (only if QT_API is
911 then IPython will ask matplotlib which Qt library to use (only if QT_API is
912 *not set*), via the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or
912 *not set*), via the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or
913 older, then IPython will always use PyQt4 without setting the v2 APIs, since
913 older, then IPython will always use PyQt4 without setting the v2 APIs, since
914 neither v2 PyQt nor PySide work.
914 neither v2 PyQt nor PySide work.
915
915
916 .. warning::
916 .. warning::
917
917
918 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
918 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
919 to work with IPython's qt integration, because otherwise PyQt4 will be
919 to work with IPython's qt integration, because otherwise PyQt4 will be
920 loaded in an incompatible mode.
920 loaded in an incompatible mode.
921
921
922 It also means that you must *not* have ``QT_API`` set if you want to
922 It also means that you must *not* have ``QT_API`` set if you want to
923 use ``--gui=qt`` with code that requires PyQt4 API v1.
923 use ``--gui=qt`` with code that requires PyQt4 API v1.
924
924
925
925
926 .. _matplotlib_support:
926 .. _matplotlib_support:
927
927
928 Plotting with matplotlib
928 Plotting with matplotlib
929 ========================
929 ========================
930
930
931 matplotlib_ provides high quality 2D and 3D plotting for Python. matplotlib_
931 matplotlib_ provides high quality 2D and 3D plotting for Python. matplotlib_
932 can produce plots on screen using a variety of GUI toolkits, including Tk,
932 can produce plots on screen using a variety of GUI toolkits, including Tk,
933 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
933 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
934 scientific computing, all with a syntax compatible with that of the popular
934 scientific computing, all with a syntax compatible with that of the popular
935 Matlab program.
935 Matlab program.
936
936
937 To start IPython with matplotlib support, use the ``--matplotlib`` switch. If
937 To start IPython with matplotlib support, use the ``--matplotlib`` switch. If
938 IPython is already running, you can run the :magic:`matplotlib` magic. If no
938 IPython is already running, you can run the :magic:`matplotlib` magic. If no
939 arguments are given, IPython will automatically detect your choice of
939 arguments are given, IPython will automatically detect your choice of
940 matplotlib backend. You can also request a specific backend with
940 matplotlib backend. You can also request a specific backend with
941 ``%matplotlib backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx',
941 ``%matplotlib backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx',
942 'gtk', 'osx'. In the web notebook and Qt console, 'inline' is also a valid
942 'gtk', 'osx'. In the web notebook and Qt console, 'inline' is also a valid
943 backend value, which produces static figures inlined inside the application
943 backend value, which produces static figures inlined inside the application
944 window instead of matplotlib's interactive figures that live in separate
944 window instead of matplotlib's interactive figures that live in separate
945 windows.
945 windows.
946
946
947 .. _interactive_demos:
947 .. _interactive_demos:
948
948
949 Interactive demos with IPython
949 Interactive demos with IPython
950 ==============================
950 ==============================
951
951
952 IPython ships with a basic system for running scripts interactively in
952 IPython ships with a basic system for running scripts interactively in
953 sections, useful when presenting code to audiences. A few tags embedded
953 sections, useful when presenting code to audiences. A few tags embedded
954 in comments (so that the script remains valid Python code) divide a file
954 in comments (so that the script remains valid Python code) divide a file
955 into separate blocks, and the demo can be run one block at a time, with
955 into separate blocks, and the demo can be run one block at a time, with
956 IPython printing (with syntax highlighting) the block before executing
956 IPython printing (with syntax highlighting) the block before executing
957 it, and returning to the interactive prompt after each block. The
957 it, and returning to the interactive prompt after each block. The
958 interactive namespace is updated after each block is run with the
958 interactive namespace is updated after each block is run with the
959 contents of the demo's namespace.
959 contents of the demo's namespace.
960
960
961 This allows you to show a piece of code, run it and then execute
961 This allows you to show a piece of code, run it and then execute
962 interactively commands based on the variables just created. Once you
962 interactively commands based on the variables just created. Once you
963 want to continue, you simply execute the next block of the demo. The
963 want to continue, you simply execute the next block of the demo. The
964 following listing shows the markup necessary for dividing a script into
964 following listing shows the markup necessary for dividing a script into
965 sections for execution as a demo:
965 sections for execution as a demo:
966
966
967 .. literalinclude:: ../../../examples/IPython Kernel/example-demo.py
967 .. literalinclude:: ../../../examples/IPython Kernel/example-demo.py
968 :language: python
968 :language: python
969
969
970 In order to run a file as a demo, you must first make a Demo object out
970 In order to run a file as a demo, you must first make a Demo object out
971 of it. If the file is named myscript.py, the following code will make a
971 of it. If the file is named myscript.py, the following code will make a
972 demo::
972 demo::
973
973
974 from IPython.lib.demo import Demo
974 from IPython.lib.demo import Demo
975
975
976 mydemo = Demo('myscript.py')
976 mydemo = Demo('myscript.py')
977
977
978 This creates the mydemo object, whose blocks you run one at a time by
978 This creates the mydemo object, whose blocks you run one at a time by
979 simply calling the object with no arguments. Then call it to run each step
979 simply calling the object with no arguments. Then call it to run each step
980 of the demo::
980 of the demo::
981
981
982 mydemo()
982 mydemo()
983
983
984 Demo objects can be
984 Demo objects can be
985 restarted, you can move forward or back skipping blocks, re-execute the
985 restarted, you can move forward or back skipping blocks, re-execute the
986 last block, etc. See the :mod:`IPython.lib.demo` module and the
986 last block, etc. See the :mod:`IPython.lib.demo` module and the
987 :class:`~IPython.lib.demo.Demo` class for details.
987 :class:`~IPython.lib.demo.Demo` class for details.
988
988
989 Limitations: These demos are limited to
989 Limitations: These demos are limited to
990 fairly simple uses. In particular, you cannot break up sections within
990 fairly simple uses. In particular, you cannot break up sections within
991 indented code (loops, if statements, function definitions, etc.)
991 indented code (loops, if statements, function definitions, etc.)
992 Supporting something like this would basically require tracking the
992 Supporting something like this would basically require tracking the
993 internal execution state of the Python interpreter, so only top-level
993 internal execution state of the Python interpreter, so only top-level
994 divisions are allowed. If you want to be able to open an IPython
994 divisions are allowed. If you want to be able to open an IPython
995 instance at an arbitrary point in a program, you can use IPython's
995 instance at an arbitrary point in a program, you can use IPython's
996 :ref:`embedding facilities <Embedding>`.
996 :ref:`embedding facilities <Embedding>`.
997
997
998 .. include:: ../links.txt
998 .. include:: ../links.txt
@@ -1,269 +1,269 b''
1 .. _issues_list_3:
1 .. _issues_list_3:
2
2
3 Issues closed in the 3.x development cycle
3 Issues closed in the 3.x development cycle
4 ==========================================
4 ==========================================
5
5
6
6
7 Issues closed in 3.2.1
7 Issues closed in 3.2.1
8 ----------------------
8 ----------------------
9
9
10 GitHub stats for 2015/06/22 - 2015/07/12 (since 3.2)
10 GitHub stats for 2015/06/22 - 2015/07/12 (since 3.2)
11
11
12 These lists are automatically generated, and may be incomplete or contain duplicates.
12 These lists are automatically generated, and may be incomplete or contain duplicates.
13
13
14 We closed 1 issue and merged 3 pull requests.
14 We closed 1 issue and merged 3 pull requests.
15 The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.2.1>`_
15 The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.2.1>`__
16
16
17 The following 5 authors contributed 9 commits.
17 The following 5 authors contributed 9 commits.
18
18
19 * Benjamin Ragan-Kelley
19 * Benjamin Ragan-Kelley
20 * Matthias Bussonnier
20 * Matthias Bussonnier
21 * Nitin Dahyabhai
21 * Nitin Dahyabhai
22 * Sebastiaan Mathot
22 * Sebastiaan Mathot
23 * Thomas Kluyver
23 * Thomas Kluyver
24
24
25
25
26 Issues closed in 3.2
26 Issues closed in 3.2
27 --------------------
27 --------------------
28
28
29 GitHub stats for 2015/04/03 - 2015/06/21 (since 3.1)
29 GitHub stats for 2015/04/03 - 2015/06/21 (since 3.1)
30
30
31 These lists are automatically generated, and may be incomplete or contain duplicates.
31 These lists are automatically generated, and may be incomplete or contain duplicates.
32
32
33 We closed 7 issues and merged 30 pull requests.
33 We closed 7 issues and merged 30 pull requests.
34 The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.2>`_
34 The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.2>`__
35
35
36 The following 15 authors contributed 74 commits.
36 The following 15 authors contributed 74 commits.
37
37
38 * Benjamin Ragan-Kelley
38 * Benjamin Ragan-Kelley
39 * Brian Gough
39 * Brian Gough
40 * DamiΓ‘n Avila
40 * DamiΓ‘n Avila
41 * Ian Barfield
41 * Ian Barfield
42 * Jason Grout
42 * Jason Grout
43 * Jeff Hussmann
43 * Jeff Hussmann
44 * Jessica B. Hamrick
44 * Jessica B. Hamrick
45 * Kyle Kelley
45 * Kyle Kelley
46 * Matthias Bussonnier
46 * Matthias Bussonnier
47 * Nicholas Bollweg
47 * Nicholas Bollweg
48 * Randy Lai
48 * Randy Lai
49 * Scott Sanderson
49 * Scott Sanderson
50 * Sylvain Corlay
50 * Sylvain Corlay
51 * Thomas A Caswell
51 * Thomas A Caswell
52 * Thomas Kluyver
52 * Thomas Kluyver
53
53
54
54
55 Issues closed in 3.1
55 Issues closed in 3.1
56 --------------------
56 --------------------
57
57
58 GitHub stats for 2015/02/27 - 2015/04/03 (since 3.0)
58 GitHub stats for 2015/02/27 - 2015/04/03 (since 3.0)
59
59
60 These lists are automatically generated, and may be incomplete or contain duplicates.
60 These lists are automatically generated, and may be incomplete or contain duplicates.
61
61
62 We closed 46 issues and merged 133 pull requests.
62 We closed 46 issues and merged 133 pull requests.
63 The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.1>`__.
63 The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.1>`__.
64
64
65 The following 33 authors contributed 344 commits:
65 The following 33 authors contributed 344 commits:
66
66
67 * Abe Guerra
67 * Abe Guerra
68 * Adal Chiriliuc
68 * Adal Chiriliuc
69 * Benjamin Ragan-Kelley
69 * Benjamin Ragan-Kelley
70 * Brian Drawert
70 * Brian Drawert
71 * Fernando Perez
71 * Fernando Perez
72 * Gareth Elston
72 * Gareth Elston
73 * Gert-Ludwig Ingold
73 * Gert-Ludwig Ingold
74 * Giuseppe Venturini
74 * Giuseppe Venturini
75 * Jakob Gager
75 * Jakob Gager
76 * Jan Schulz
76 * Jan Schulz
77 * Jason Grout
77 * Jason Grout
78 * Jessica B. Hamrick
78 * Jessica B. Hamrick
79 * Jonathan Frederic
79 * Jonathan Frederic
80 * Justin Tyberg
80 * Justin Tyberg
81 * Lorena Pantano
81 * Lorena Pantano
82 * mashenjun
82 * mashenjun
83 * Mathieu
83 * Mathieu
84 * Matthias Bussonnier
84 * Matthias Bussonnier
85 * Morten Enemark Lund
85 * Morten Enemark Lund
86 * Naveen Nathan
86 * Naveen Nathan
87 * Nicholas Bollweg
87 * Nicholas Bollweg
88 * onesandzeroes
88 * onesandzeroes
89 * Patrick Snape
89 * Patrick Snape
90 * Peter Parente
90 * Peter Parente
91 * RickWinter
91 * RickWinter
92 * Robert Smith
92 * Robert Smith
93 * Ryan Nelson
93 * Ryan Nelson
94 * Scott Sanderson
94 * Scott Sanderson
95 * Sylvain Corlay
95 * Sylvain Corlay
96 * Thomas Kluyver
96 * Thomas Kluyver
97 * tmtabor
97 * tmtabor
98 * Wieland Hoffmann
98 * Wieland Hoffmann
99 * Yuval Langer
99 * Yuval Langer
100
100
101
101
102 Issues closed in 3.0
102 Issues closed in 3.0
103 --------------------
103 --------------------
104
104
105 GitHub stats for 2014/04/02 - 2015/02/13 (since 2.0)
105 GitHub stats for 2014/04/02 - 2015/02/13 (since 2.0)
106
106
107 These lists are automatically generated, and may be incomplete or contain duplicates.
107 These lists are automatically generated, and may be incomplete or contain duplicates.
108
108
109 We closed 469 issues and merged 925 pull requests.
109 We closed 469 issues and merged 925 pull requests.
110 The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.0>`__.
110 The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.0>`__.
111
111
112 The following 155 authors contributed 5975 commits.
112 The following 155 authors contributed 5975 commits.
113
113
114 * A.J. Holyoake
114 * A.J. Holyoake
115 * abalkin
115 * abalkin
116 * Adam Hodgen
116 * Adam Hodgen
117 * Adrian Price-Whelan
117 * Adrian Price-Whelan
118 * Amin Bandali
118 * Amin Bandali
119 * Andreas Amann
119 * Andreas Amann
120 * Andrew Dawes
120 * Andrew Dawes
121 * Andrew Jesaitis
121 * Andrew Jesaitis
122 * Andrew Payne
122 * Andrew Payne
123 * AnneTheAgile
123 * AnneTheAgile
124 * Aron Ahmadia
124 * Aron Ahmadia
125 * Ben Duffield
125 * Ben Duffield
126 * Benjamin ABEL
126 * Benjamin ABEL
127 * Benjamin Ragan-Kelley
127 * Benjamin Ragan-Kelley
128 * Benjamin Schultz
128 * Benjamin Schultz
129 * BjΓΆrn GrΓΌning
129 * BjΓΆrn GrΓΌning
130 * BjΓΆrn Linse
130 * BjΓΆrn Linse
131 * Blake Griffith
131 * Blake Griffith
132 * Boris Egorov
132 * Boris Egorov
133 * Brian E. Granger
133 * Brian E. Granger
134 * bsvh
134 * bsvh
135 * Carlos Cordoba
135 * Carlos Cordoba
136 * Cedric GESTES
136 * Cedric GESTES
137 * cel
137 * cel
138 * chebee7i
138 * chebee7i
139 * Christoph Gohlke
139 * Christoph Gohlke
140 * CJ Carey
140 * CJ Carey
141 * Cyrille Rossant
141 * Cyrille Rossant
142 * Dale Jung
142 * Dale Jung
143 * DamiΓ‘n Avila
143 * DamiΓ‘n Avila
144 * Damon Allen
144 * Damon Allen
145 * Daniel B. Vasquez
145 * Daniel B. Vasquez
146 * Daniel Rocco
146 * Daniel Rocco
147 * Daniel Wehner
147 * Daniel Wehner
148 * Dav Clark
148 * Dav Clark
149 * David Hirschfeld
149 * David Hirschfeld
150 * David Neto
150 * David Neto
151 * dexterdev
151 * dexterdev
152 * Dimitry Kloper
152 * Dimitry Kloper
153 * dongweiming
153 * dongweiming
154 * Doug Blank
154 * Doug Blank
155 * drevicko
155 * drevicko
156 * Dustin Rodriguez
156 * Dustin Rodriguez
157 * Eric Firing
157 * Eric Firing
158 * Eric Galloway
158 * Eric Galloway
159 * Erik M. Bray
159 * Erik M. Bray
160 * Erik Tollerud
160 * Erik Tollerud
161 * Ezequiel (Zac) Panepucci
161 * Ezequiel (Zac) Panepucci
162 * Fernando Perez
162 * Fernando Perez
163 * foogunlana
163 * foogunlana
164 * Francisco de la PeΓ±a
164 * Francisco de la PeΓ±a
165 * George Titsworth
165 * George Titsworth
166 * Gordon Ball
166 * Gordon Ball
167 * gporras
167 * gporras
168 * Grzegorz RoΕΌniecki
168 * Grzegorz RoΕΌniecki
169 * Helen ST
169 * Helen ST
170 * immerrr
170 * immerrr
171 * Ingolf Becker
171 * Ingolf Becker
172 * Jakob Gager
172 * Jakob Gager
173 * James Goppert
173 * James Goppert
174 * James Porter
174 * James Porter
175 * Jan Schulz
175 * Jan Schulz
176 * Jason Goad
176 * Jason Goad
177 * Jason Gors
177 * Jason Gors
178 * Jason Grout
178 * Jason Grout
179 * Jason Newton
179 * Jason Newton
180 * jdavidheiser
180 * jdavidheiser
181 * Jean-Christophe Jaskula
181 * Jean-Christophe Jaskula
182 * Jeff Hemmelgarn
182 * Jeff Hemmelgarn
183 * Jeffrey Bush
183 * Jeffrey Bush
184 * Jeroen Demeyer
184 * Jeroen Demeyer
185 * Jessica B. Hamrick
185 * Jessica B. Hamrick
186 * Jessica Frazelle
186 * Jessica Frazelle
187 * jhemmelg
187 * jhemmelg
188 * Jim Garrison
188 * Jim Garrison
189 * Joel Nothman
189 * Joel Nothman
190 * Johannes Feist
190 * Johannes Feist
191 * John Stowers
191 * John Stowers
192 * John Zwinck
192 * John Zwinck
193 * jonasc
193 * jonasc
194 * Jonathan Frederic
194 * Jonathan Frederic
195 * Juergen Hasch
195 * Juergen Hasch
196 * Julia Evans
196 * Julia Evans
197 * Justyna Ilczuk
197 * Justyna Ilczuk
198 * JΓΆrg Dietrich
198 * JΓΆrg Dietrich
199 * K.-Michael Aye
199 * K.-Michael Aye
200 * Kalibri
200 * Kalibri
201 * Kester Tong
201 * Kester Tong
202 * Kyle Kelley
202 * Kyle Kelley
203 * Kyle Rawlins
203 * Kyle Rawlins
204 * Lev Abalkin
204 * Lev Abalkin
205 * Manuel Riel
205 * Manuel Riel
206 * Martin Bergtholdt
206 * Martin Bergtholdt
207 * Martin Spacek
207 * Martin Spacek
208 * Mateusz Paprocki
208 * Mateusz Paprocki
209 * Mathieu
209 * Mathieu
210 * Matthias Bussonnier
210 * Matthias Bussonnier
211 * Maximilian Albert
211 * Maximilian Albert
212 * mbyt
212 * mbyt
213 * MechCoder
213 * MechCoder
214 * Mohan Raj Rajamanickam
214 * Mohan Raj Rajamanickam
215 * mvr
215 * mvr
216 * Narahari
216 * Narahari
217 * Nathan Goldbaum
217 * Nathan Goldbaum
218 * Nathan Heijermans
218 * Nathan Heijermans
219 * Nathaniel J. Smith
219 * Nathaniel J. Smith
220 * ncornette
220 * ncornette
221 * Nicholas Bollweg
221 * Nicholas Bollweg
222 * Nick White
222 * Nick White
223 * Nikolay Koldunov
223 * Nikolay Koldunov
224 * Nile Geisinger
224 * Nile Geisinger
225 * Olga Botvinnik
225 * Olga Botvinnik
226 * Osada Paranaliyanage
226 * Osada Paranaliyanage
227 * Pankaj Pandey
227 * Pankaj Pandey
228 * Pascal Bugnion
228 * Pascal Bugnion
229 * patricktokeeffe
229 * patricktokeeffe
230 * Paul Ivanov
230 * Paul Ivanov
231 * Peter Odding
231 * Peter Odding
232 * Peter Parente
232 * Peter Parente
233 * Peter WΓΌrtz
233 * Peter WΓΌrtz
234 * Phil Elson
234 * Phil Elson
235 * Phillip Nordwall
235 * Phillip Nordwall
236 * Pierre Gerold
236 * Pierre Gerold
237 * Pierre Haessig
237 * Pierre Haessig
238 * Raffaele De Feo
238 * Raffaele De Feo
239 * Ramiro GΓ³mez
239 * Ramiro GΓ³mez
240 * Reggie Pierce
240 * Reggie Pierce
241 * Remi Rampin
241 * Remi Rampin
242 * Renaud Richardet
242 * Renaud Richardet
243 * Richard Everson
243 * Richard Everson
244 * Scott Sanderson
244 * Scott Sanderson
245 * Silvia Vinyes
245 * Silvia Vinyes
246 * Simon Guillot
246 * Simon Guillot
247 * Spencer Nelson
247 * Spencer Nelson
248 * Stefan Zimmermann
248 * Stefan Zimmermann
249 * Steve Chan
249 * Steve Chan
250 * Steven Anton
250 * Steven Anton
251 * Steven Silvester
251 * Steven Silvester
252 * sunny
252 * sunny
253 * Susan Tan
253 * Susan Tan
254 * Sylvain Corlay
254 * Sylvain Corlay
255 * Tarun Gaba
255 * Tarun Gaba
256 * Thomas Ballinger
256 * Thomas Ballinger
257 * Thomas Kluyver
257 * Thomas Kluyver
258 * Thomas Robitaille
258 * Thomas Robitaille
259 * Thomas Spura
259 * Thomas Spura
260 * Tobias Oberstein
260 * Tobias Oberstein
261 * Torsten Bittner
261 * Torsten Bittner
262 * unknown
262 * unknown
263 * v923z
263 * v923z
264 * vaibhavsagar
264 * vaibhavsagar
265 * W. Trevor King
265 * W. Trevor King
266 * weichm
266 * weichm
267 * Xiuming Chen
267 * Xiuming Chen
268 * Yaroslav Halchenko
268 * Yaroslav Halchenko
269 * zah
269 * zah
@@ -1,43 +1,44 b''
1 .. Developers should add in this file, during each release cycle, information
1 .. Developers should add in this file, during each release cycle, information
2 .. about important changes they've made, in a summary format that's meant for
2 .. about important changes they've made, in a summary format that's meant for
3 .. end users. For each release we normally have three sections: features, bug
3 .. end users. For each release we normally have three sections: features, bug
4 .. fixes and api breakage.
4 .. fixes and api breakage.
5 .. Please remember to credit the authors of the contributions by name,
5 .. Please remember to credit the authors of the contributions by name,
6 .. especially when they are new users or developers who do not regularly
6 .. especially when they are new users or developers who do not regularly
7 .. participate in IPython's development.
7 .. participate in IPython's development.
8
8
9 .. _whatsnew_index:
9 .. _whatsnew_index:
10
10
11 =====================
11 =====================
12 What's new in IPython
12 What's new in IPython
13 =====================
13 =====================
14
14
15 This section documents the changes that have been made in various versions of
15 This section documents the changes that have been made in various versions of
16 IPython. Users should consult these pages to learn about new features, bug
16 IPython. Users should consult these pages to learn about new features, bug
17 fixes and backwards incompatibilities. Developers should summarize the
17 fixes and backwards incompatibilities. Developers should summarize the
18 development work they do here in a user friendly format.
18 development work they do here in a user friendly format.
19
19
20 .. toctree::
20 .. toctree::
21 :maxdepth: 1
21 :maxdepth: 1
22
22
23 version5
23 development
24 development
24 version4
25 version4
25 github-stats-4
26 github-stats-4
26 version3
27 version3
27 github-stats-3
28 github-stats-3
28 version3_widget_migration
29 version3_widget_migration
29 version2.0
30 version2.0
30 github-stats-2.0
31 github-stats-2.0
31 version1.0
32 version1.0
32 github-stats-1.0
33 github-stats-1.0
33 version0.13
34 version0.13
34 github-stats-0.13
35 github-stats-0.13
35 version0.12
36 version0.12
36 github-stats-0.12
37 github-stats-0.12
37 version0.11
38 version0.11
38 github-stats-0.11
39 github-stats-0.11
39 version0.10
40 version0.10
40 version0.9
41 version0.9
41 version0.8
42 version0.8
42
43
43
44
General Comments 0
You need to be logged in to leave comments. Login now