##// END OF EJS Templates
upstream » ipython
RSS

Clone from https://github.com/ipython/ipython.git

Split material from tutorial page into introduction and tips pages.
Thomas Kluyver -
Show More
Show file before | Show file after | Hide comments
@@ -0,0 +1,129 b''
1 .. _tips:
2
3 =====================
4 IPython Tips & Tricks
5 =====================
6
7 The `IPython cookbook <http://ipython.scipy.org/moin/Cookbook>`_ details more
8 things you can do with IPython.
9
10 .. This is not in the current version:
11 .. Use IPython to present interactive demos
12 ----------------------------------------
13
14 .. Use the IPython.demo.Demo class to load any Python script as an interactive
15 demo. With a minimal amount of simple markup, you can control the execution of
16 the script, stopping as needed. See :ref:`here <interactive_demos>` for more.
17
18 Embed IPython in your programs
19 ------------------------------
20
21 A few lines of code are enough to load a complete IPython inside your own
22 programs, giving you the ability to work with your data interactively after
23 automatic processing has been completed. See :ref:`the embedding section <embedding>`.
24
25 Run doctests
26 ------------
27
28 Run your doctests from within IPython for development and debugging. The
29 special %doctest_mode command toggles a mode where the prompt, output and
30 exceptions display matches as closely as possible that of the default Python
31 interpreter. In addition, this mode allows you to directly paste in code that
32 contains leading '>>>' prompts, even if they have extra leading whitespace
33 (as is common in doctest files). This combined with the ``%history -t`` call
34 to see your translated history allows for an easy doctest workflow, where you
35 can go from doctest to interactive execution to pasting into valid Python code
36 as needed.
37
38 Suppress output
39 ---------------
40
41 Put a ';' at the end of a line to suppress the printing of output. This is
42 useful when doing calculations which generate long output you are not
43 interested in seeing.
44
45 Lightweight 'version control'
46 -----------------------------
47
48 When you call ``%edit`` with no arguments, IPython opens an empty editor
49 with a temporary file, and it returns the contents of your editing
50 session as a string variable. Thanks to IPython's output caching
51 mechanism, this is automatically stored::
52
53 In [1]: %edit
54
55 IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
56
57 Editing... done. Executing edited code...
58
59 hello - this is a temporary file
60
61 Out[1]: "print 'hello - this is a temporary file'\n"
62
63 Now, if you call ``%edit -p``, IPython tries to open an editor with the
64 same data as the last time you used %edit. So if you haven't used %edit
65 in the meantime, this same contents will reopen; however, it will be
66 done in a new file. This means that if you make changes and you later
67 want to find an old version, you can always retrieve it by using its
68 output number, via '%edit _NN', where NN is the number of the output
69 prompt.
70
71 Continuing with the example above, this should illustrate this idea::
72
73 In [2]: edit -p
74
75 IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
76
77 Editing... done. Executing edited code...
78
79 hello - now I made some changes
80
81 Out[2]: "print 'hello - now I made some changes'\n"
82
83 In [3]: edit _1
84
85 IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
86
87 Editing... done. Executing edited code...
88
89 hello - this is a temporary file
90
91 IPython version control at work :)
92
93 Out[3]: "print 'hello - this is a temporary file'\nprint 'IPython version control at work :)'\n"
94
95
96 This section was written after a contribution by Alexander Belchenko on
97 the IPython user list.
98
99 .. The section below needs to be updated for the new config system.
100
101 .. Effective logging
102 -----------------
103
104 .. A very useful suggestion sent in by Robert Kern follows:
105
106 .. I recently happened on a nifty way to keep tidy per-project log files. I
107 made a profile for my project (which is called "parkfield")::
108
109 include ipythonrc
110
111 # cancel earlier logfile invocation:
112
113 logfile ''
114
115 execute import time
116
117 execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
118
119 execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
120
121 .. I also added a shell alias for convenience::
122
123 alias parkfield="ipython --pylab profile=parkfield"
124
125 .. Now I have a nice little directory with everything I ever type in,
126 organized by project and date.
127
128
129
Show file before | Show file after | Hide comments
@@ -6,6 +6,7 b' Using IPython for interactive work'
6 :maxdepth: 2
6 :maxdepth: 2
7
7
8 tutorial.txt
8 tutorial.txt
9 tips.txt
9 reference.txt
10 reference.txt
10 shell.txt
11 shell.txt
11 qtconsole.txt
12 qtconsole.txt
Show file before | Show file after | Hide comments
@@ -1,336 +1,145 b''
1 .. _tutorial:
1 .. _tutorial:
2
2
3 ======================
3 ======================
4 Quick IPython tutorial
4 Introducing IPython
5 ======================
5 ======================
6
6
7 .. warning::
7 You don't need to know anything beyond Python to start using IPython – just type
8 commands as you would at the standard Python prompt. But IPython can do much
9 more than the standard prompt. Some key features are described here. For more
10 information, check the :ref:`tips page <tips>`, or look at examples in the
11 `IPython cookbook <http://ipython.scipy.org/moin/Cookbook>`_.
8
12
9 As of the 0.11 version of IPython, some of the features and APIs
13 If you've never used Python before, you might want to look at `the official
10 described in this section have been deprecated or are broken. Our plan
14 tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
11 is to continue to support these features, but they need to be updated
15 Python <http://diveintopython.org/toc/index.html>`_.
12 to take advantage of recent API changes. Furthermore, this section
13 of the documentation need to be updated to reflect all of these changes.
14
16
15 IPython can be used as an improved replacement for the Python prompt,
17 Tab completion
16 and for that you don't really need to read any more of this manual. But
18 ==============
17 in this section we'll try to summarize a few tips on how to make the
18 most effective use of it for everyday Python development, highlighting
19 things you might miss in the rest of the manual (which is getting long).
20 We'll give references to parts in the manual which provide more detail
21 when appropriate.
22
19
23 The following article by Jeremy Jones provides an introductory tutorial
20 Tab completion, especially for attributes, is a convenient way to explore the
24 about IPython: http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html
21 structure of any object you're dealing with. Simply type ``object_name.<TAB>``
22 to view the object's attributes (see :ref:`the readline section <readline>` for
23 more). Besides Python objects and keywords, tab completion also works on file
24 and directory names.
25
25
26 Highlights
26 Exploring your objects
27 ==========
27 ======================
28
28
29 Tab completion
29 Typing ``object_name?`` will print all sorts of details about any object,
30 --------------
30 including docstrings, function definition lines (for call arguments) and
31 constructor details for classes. To get specific information on an object, you
32 can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
31
33
32 TAB-completion, especially for attributes, is a convenient way to explore the
34 Magic functions
33 structure of any object you're dealing with. Simply type object_name.<TAB> and
35 ===============
34 a list of the object's attributes will be printed (see :ref:`the readline
35 section <readline>` for more). Tab completion also works on file and directory
36 names, which combined with IPython's alias system allows you to do from within
37 IPython many of the things you normally would need the system shell for.
38
36
39 Explore your objects
37 IPython has a set of predefined 'magic functions' that you can call with a
40 --------------------
38 command line style syntax. These include:
41
39
42 Typing object_name? will print all sorts of details about any object,
40 - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
43 including docstrings, function definition lines (for call arguments) and
41 ``%recall``, etc.
44 constructor details for classes. The magic commands %pdoc, %pdef, %psource
42 - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``, etc.
45 and %pfile will respectively print the docstring, function definition line,
43 - Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
46 full source code and the complete file for any object (when they can be
47 found). If automagic is on (it is by default), you don't need to type the '%'
48 explicitly. See :ref:`this section <dynamic_object_info>` for more.
49
44
50 The `%run` magic command
45 You can always call these using the % prefix, and if you're typing one on a line
51 ------------------------
46 by itself, you can omit even that::
47
48 run thescript.py
49
50 For more details on any magic function, call ``%somemagic?`` to read its
51 docstring. To see all the available magic functions, call ``%lsmagic``.
52
53 Running and Editing
54 -------------------
52
55
53 The %run magic command allows you to run any python script and load all of its
56 The %run magic command allows you to run any python script and load all of its
54 data directly into the interactive namespace. Since the file is re-read from
57 data directly into the interactive namespace. Since the file is re-read from
55 disk each time, changes you make to it are reflected immediately (in contrast
58 disk each time, changes you make to it are reflected immediately (unlike
56 to the behavior of import). I rarely use import for code I am testing, relying
59 imported modules, which have to be specifically reloaded). IPython also includes
57 on %run instead. See :ref:`this section <magic>` for more on this and other
60 :ref:`dreload <dreload>`, a recursive reload function.
58 magic commands, or type the name of any magic command and ? to get details on
61
59 it. See also :ref:`this section <dreload>` for a recursive reload command. %run
62 %run has special flags for timing the execution of your scripts (-t), or for
60 also has special flags for timing the execution of your scripts (-t) and for
63 running them under the control of either Python's pdb debugger (-d) or
61 executing them under the control of either Python's pdb debugger (-d) or
64 profiler (-p).
62 profiler (-p). With all of these, %run can be used as the main tool for
65
63 efficient interactive development of code which you write in your editor of
66 The %edit command gives a reasonable approximation of multiline editing,
64 choice.
67 by invoking your favorite editor on the spot. IPython will execute the
65
68 code you type in there as if it were typed interactively.
66 Debug a Python script
69
67 ---------------------
70 Debugging
68
71 ---------
69 Use the Python debugger, pdb. The %pdb command allows you to toggle on and off
72
70 the automatic invocation of an IPython-enhanced pdb debugger (with coloring,
73 After an exception occurs, you can call ``%debug`` to jump into the Python
71 tab completion and more) at any uncaught exception. The advantage of this is
74 debugger (pdb) and examine the problem. Alternatively, if you call ``%pdb``,
72 that pdb starts inside the function where the exception occurred, with all data
75 IPython will automatically start the debugger on any uncaught exception. You can
73 still available. You can print variables, see code, execute statements and even
76 print variables, see code, execute statements and even walk up and down the
74 walk up and down the call stack to track down the true source of the problem
77 call stack to track down the true source of the problem. Running programs with
75 (which often is many layers in the stack above where the exception gets
78 %run and pdb active can be an efficient way to develop and debug code, in many
76 triggered). Running programs with %run and pdb active can be an efficient to
79 cases eliminating the need for print statements or external debugging tools.
77 develop and debug code, in many cases eliminating the need for print statements
80
78 or external debugging tools. I often simply put a 1/0 in a place where I want
81 You can also step through a program from the beginning by calling
79 to take a look so that pdb gets called, quickly view whatever variables I need
82 ``%run -d theprogram.py``.
80 to or test various pieces of code and then remove the 1/0. Note also that '%run
83
81 -d' activates pdb and automatically sets initial breakpoints for you to step
84 History
82 through your code, watch variables, etc. The :ref:`output caching section
85 =======
83 <output_caching>` has more details.
86
84
87 IPython stores both the commands you enter, and the results it produces. You
85 Use the output cache
88 can easily go through previous commands with the up- and down-arrow keys, or
86 --------------------
89 access your history in more sophisticated ways.
87
90
88 All output results are automatically stored in a global dictionary named Out
91 Input and output history are kept in variables called ``In`` and ``Out``, which
89 and variables named _1, _2, etc. alias them. For example, the result of input
92 can both be indexed by the prompt number on which they occurred, e.g. ``In[4]``.
90 line 4 is available either as Out[4] or as _4. Additionally, three variables
93 The last three objects in output history are also kept in variables named ``_``,
91 named _, __ and ___ are always kept updated with the for the last three
94 ``__`` and ``___``.
92 results. This allows you to recall any previous result and further use it for
95
93 new calculations. See :ref:`the output caching section <output_caching>` for
96 You can use the ``%history`` magic function to examine past input and output.
94 more.
97 Input history from previous sessions is saved in a database, and IPython can be
95
98 configured to save output history.
96 Suppress output
99
97 ---------------
100 Several other magic functions can use your input history, including ``%edit``,
98
101 ``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a
99 Put a ';' at the end of a line to suppress the printing of output. This is
102 standard format to refer to lines::
100 useful when doing calculations which generate long output you are not
103
101 interested in seeing. The _* variables and the Out[] list do get updated with
104 %pastebin 3 18-20 ~1/1-5
102 the contents of the output, even if it is not printed. You can thus still
105
103 access the generated results this way for further processing.
106 This will take line 3 and lines 18 to 20 from the current session, and lines
104
107 1-5 from the previous session.
105 Input cache
108
106 -----------
109 System shell commands
107
110 =====================
108 A similar system exists for caching input. All input is stored in a global
111
109 list called In , so you can re-execute lines 22 through 28 plus line 34 by
112 To run any command at the system shell, simply prefix it with !, e.g.::
110 typing 'exec In[22:29]+In[34]' (using Python slicing notation). If you need
113
111 to execute the same set of lines often, you can assign them to a macro with
114 !ping www.bbc.co.uk
112 the %macro function. See :ref:`here <input_caching>` for more.
115
113
116 You can capture the output into a Python list, e.g.: ``files = !ls``. To pass
114 Use your input history
117 the values of Python variables or expressions to system commands, prefix them
115 ----------------------
118 with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section
116
119 <system_shell_access>` for more details.
117 The %hist command can show you all previous input, without line numbers if
118 desired (option -n) so you can directly copy and paste code either back in
119 IPython or in a text editor. You can also save all your history by turning on
120 logging via %logstart; these logs can later be either reloaded as IPython
121 sessions or used as code for your programs.
122
123 In particular, note taht the %rep magic function can repeat a command or get a
124 command to the input line for further editing::
125
126 $ l = ["hei", "vaan"]
127 $ "".join(l)
128 ==> heivaan
129 $ %rep
130 $ heivaan_ <== cursor blinking
131
132 For more details, type ``%rep?`` as usual.
133
120
134 Define your own system aliases
121 Define your own system aliases
135 ------------------------------
122 ------------------------------
136
123
137 Even though IPython gives you access to your system shell via the ! prefix,
124 It's convenient to have aliases to the system commands you use most often.
138 it is convenient to have aliases to the system commands you use most often.
139 This allows you to work seamlessly from inside IPython with the same commands
125 This allows you to work seamlessly from inside IPython with the same commands
140 you are used to in your system shell. IPython comes with some pre-defined
126 you are used to in your system shell. IPython comes with some pre-defined
141 aliases and a complete system for changing directories, both via a stack (see
127 aliases and a complete system for changing directories, both via a stack (see
142 %pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of
128 %pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of
143 visited directories and allows you to go to any previously visited one.
129 visited directories and allows you to go to any previously visited one.
144
130
145 Call system shell commands
146 --------------------------
147
148 Use Python to manipulate the results of system commands. The '!!' special
149 syntax, and the %sc and %sx magic commands allow you to capture system output
150 into Python variables.
151
152 Use Python variables when calling the shell
153 -------------------------------------------
154
155 Expand python variables when calling the shell (either via '!' and '!!' or via
156 aliases) by prepending a $ in front of them. You can also expand complete
157 python expressions. See :ref:`our shell section <system_shell_access>` for
158 more details.
159
160 Use profiles
161 ------------
162
163 Use profiles to maintain different configurations (modules to load, function
164 definitions, option settings) for particular tasks. You can then have
165 customized versions of IPython for specific purposes. :ref:`This section
166 <profiles>` has more details.
167
168
169 Embed IPython in your programs
170 ------------------------------
171
172 A few lines of code are enough to load a complete IPython inside your own
173 programs, giving you the ability to work with your data interactively after
174 automatic processing has been completed. See :ref:`here <embedding>` for more.
175
176 Use the Python profiler
177 -----------------------
178
179 When dealing with performance issues, the %run command with a -p option
180 allows you to run complete programs under the control of the Python profiler.
181 The %prun command does a similar job for single Python expressions (like
182 function calls).
183
184 Use IPython to present interactive demos
185 ----------------------------------------
186
187 Use the IPython.demo.Demo class to load any Python script as an interactive
188 demo. With a minimal amount of simple markup, you can control the execution of
189 the script, stopping as needed. See :ref:`here <interactive_demos>` for more.
190
191 Run doctests
192 ------------
193
194 Run your doctests from within IPython for development and debugging. The
195 special %doctest_mode command toggles a mode where the prompt, output and
196 exceptions display matches as closely as possible that of the default Python
197 interpreter. In addition, this mode allows you to directly paste in code that
198 contains leading '>>>' prompts, even if they have extra leading whitespace
199 (as is common in doctest files). This combined with the '%history -tn' call
200 to see your translated history (with these extra prompts removed and no line
201 numbers) allows for an easy doctest workflow, where you can go from doctest
202 to interactive execution to pasting into valid Python code as needed.
203
204 Source code handling tips
205 =========================
206
207 IPython is a line-oriented program, without full control of the
208 terminal. Therefore, it doesn't support true multiline editing. However,
209 it has a number of useful tools to help you in dealing effectively with
210 more complex editing.
211
212 The %edit command gives a reasonable approximation of multiline editing,
213 by invoking your favorite editor on the spot. IPython will execute the
214 code you type in there as if it were typed interactively. Type %edit?
215 for the full details on the edit command.
216
217 If you have typed various commands during a session, which you'd like to
218 reuse, IPython provides you with a number of tools. Start by using %hist
219 to see your input history, so you can see the line numbers of all input.
220 Let us say that you'd like to reuse lines 10 through 20, plus lines 24
221 and 28. All the commands below can operate on these with the syntax::
222
223 %command 10-20 24 28
224
225 where the command given can be:
226
227 * %macro <macroname>: this stores the lines into a variable which,
228 when called at the prompt, re-executes the input. Macros can be
229 edited later using '%edit macroname', and they can be stored
230 persistently across sessions with '%store macroname' (the storage
231 system is per-profile). The combination of quick macros,
232 persistent storage and editing, allows you to easily refine
233 quick-and-dirty interactive input into permanent utilities, always
234 available both in IPython and as files for general reuse.
235 * %edit: this will open a text editor with those lines pre-loaded
236 for further modification. It will then execute the resulting
237 file's contents as if you had typed it at the prompt.
238 * %save <filename>: this saves the lines directly to a named file on
239 disk.
240
241 While %macro saves input lines into memory for interactive re-execution,
242 sometimes you'd like to save your input directly to a file. The %save
243 magic does this: its input sytnax is the same as %macro, but it saves
244 your input directly to a Python file. Note that the %logstart command
245 also saves input, but it logs all input to disk (though you can
246 temporarily suspend it and reactivate it with %logoff/%logon); %save
247 allows you to select which lines of input you need to save.
248
249
250 Lightweight 'version control'
251 =============================
252
253 When you call %edit with no arguments, IPython opens an empty editor
254 with a temporary file, and it returns the contents of your editing
255 session as a string variable. Thanks to IPython's output caching
256 mechanism, this is automatically stored::
257
258 In [1]: %edit
259
260 IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
261
262 Editing... done. Executing edited code...
263
264 hello - this is a temporary file
265
266 Out[1]: "print 'hello - this is a temporary file'\n"
267
268 Now, if you call '%edit -p', IPython tries to open an editor with the
269 same data as the last time you used %edit. So if you haven't used %edit
270 in the meantime, this same contents will reopen; however, it will be
271 done in a new file. This means that if you make changes and you later
272 want to find an old version, you can always retrieve it by using its
273 output number, via '%edit _NN', where NN is the number of the output
274 prompt.
275
276 Continuing with the example above, this should illustrate this idea::
277
278 In [2]: edit -p
279
280 IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
281
282 Editing... done. Executing edited code...
283
284 hello - now I made some changes
285
286 Out[2]: "print 'hello - now I made some changes'\n"
287
288 In [3]: edit _1
289
290 IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
291
292 Editing... done. Executing edited code...
293
294 hello - this is a temporary file
295
296 IPython version control at work :)
297
298 Out[3]: "print 'hello - this is a temporary file'\nprint 'IPython version control at work :)'\n"
299
300
301 This section was written after a contribution by Alexander Belchenko on
302 the IPython user list.
303
304
305 Effective logging
306 =================
307
308 A very useful suggestion sent in by Robert Kern follows:
309
310 I recently happened on a nifty way to keep tidy per-project log files. I
311 made a profile for my project (which is called "parkfield")::
312
313 include ipythonrc
314
315 # cancel earlier logfile invocation:
316
317 logfile ''
318
319 execute import time
320
321 execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
322
323 execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
324
325 I also added a shell alias for convenience::
326
131
327 alias parkfield="ipython --pylab profile=parkfield"
132 Configuration
133 =============
328
134
329 Now I have a nice little directory with everything I ever type in,
135 Much of IPython can be tweaked through configuration. To get started, use the
330 organized by project and date.
136 command ``ipython profile create`` to produce the default config files. These
137 will be placed in :file:`~/.ipython/profile_default` or
138 :file:`~/.config/ipython/profile_default`, and contain comments explaining what
139 the various options do.
331
140
332 Contribute your own: If you have your own favorite tip on using IPython
141 Profiles allow you to use IPython for different tasks, keeping separate config
333 efficiently for a certain task (especially things which can't be done in
142 files and history for each one. More details in :ref:`the profiles section
334 the normal Python interpreter), don't hesitate to send it!
143 <profiles>`.
335
144
336
145
General Comments 0
You need to be logged in to leave comments. Login now