##// END OF EJS Templates
Merge pull request #11825 from sysadmin75/docs-broken-install-links...
Matthias Bussonnier -
r25144:db8e4b86 merge
parent child Browse files
Show More
@@ -1,282 +1,282 b''
1 .. _tutorial:
1 .. _tutorial:
2
2
3 ======================
3 ======================
4 Introducing IPython
4 Introducing IPython
5 ======================
5 ======================
6
6
7 You don't need to know anything beyond Python to start using IPython – just type
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
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
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
10 information, check the :ref:`tips page <tips>`, or look at examples in the
11 `IPython cookbook <https://github.com/ipython/ipython/wiki/Cookbook%3A-Index>`_.
11 `IPython cookbook <https://github.com/ipython/ipython/wiki/Cookbook%3A-Index>`_.
12
12
13 If you haven't done that yet see `how to install ipython <install>`_ .
13 If you haven't done that yet see `how to install ipython <https://ipython.readthedocs.io/en/stable/install/index.html>`_ .
14
14
15 If you've never used Python before, you might want to look at `the official
15 If you've never used Python before, you might want to look at `the official
16 tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
16 tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
17 Python <http://diveintopython.net/toc/index.html>`_.
17 Python <https://www.diveinto.org/python3/table-of-contents.html>`_.
18
18
19 Start IPython by issuing the ``ipython`` command from your shell, you should be
19 Start IPython by issuing the ``ipython`` command from your shell, you should be
20 greeted by the following::
20 greeted by the following::
21
21
22 Python 3.6.0
22 Python 3.6.0
23 Type 'copyright', 'credits' or 'license' for more information
23 Type 'copyright', 'credits' or 'license' for more information
24 IPython 6.0.0.dev -- An enhanced Interactive Python. Type '?' for help.
24 IPython 6.0.0.dev -- An enhanced Interactive Python. Type '?' for help.
25
25
26 In [1]:
26 In [1]:
27
27
28
28
29 Unlike the Python REPL, you will see that the input prompt is ``In [N]:``
29 Unlike the Python REPL, you will see that the input prompt is ``In [N]:``
30 instead of ``>>>``. The number ``N`` in the prompt will be used later in this
30 instead of ``>>>``. The number ``N`` in the prompt will be used later in this
31 tutorial but should usually not impact the computation.
31 tutorial but should usually not impact the computation.
32
32
33 You should be able to type single line expressions and press enter to evaluate
33 You should be able to type single line expressions and press enter to evaluate
34 them. If an expression is incomplete, IPython will automatically detect this and
34 them. If an expression is incomplete, IPython will automatically detect this and
35 add a new line when you press :kbd:`Enter` instead of executing right away.
35 add a new line when you press :kbd:`Enter` instead of executing right away.
36
36
37 Feel free to explore multi-line text input. Unlike many other REPLs, with
37 Feel free to explore multi-line text input. Unlike many other REPLs, with
38 IPython you can use the up and down arrow keys when editing multi-line
38 IPython you can use the up and down arrow keys when editing multi-line
39 code blocks.
39 code blocks.
40
40
41 Here is an example of a longer interaction with the IPython REPL,
41 Here is an example of a longer interaction with the IPython REPL,
42 which we often refer to as an IPython *session* ::
42 which we often refer to as an IPython *session* ::
43
43
44 In [1]: print('Hello IPython')
44 In [1]: print('Hello IPython')
45 Hello IPython
45 Hello IPython
46
46
47 In [2]: 21 * 2
47 In [2]: 21 * 2
48 Out[2]: 42
48 Out[2]: 42
49
49
50 In [3]: def say_hello(name):
50 In [3]: def say_hello(name):
51 ...: print('Hello {name}'.format(name=name))
51 ...: print('Hello {name}'.format(name=name))
52 ...:
52 ...:
53
53
54 We won't get into details right now, but you may notice a few differences to
54 We won't get into details right now, but you may notice a few differences to
55 the standard Python REPL. First, your code should be syntax-highlighted as you
55 the standard Python REPL. First, your code should be syntax-highlighted as you
56 type. Second, you will see that some results will have an ``Out[N]:`` prompt,
56 type. Second, you will see that some results will have an ``Out[N]:`` prompt,
57 while some other do not. We'll come to this later.
57 while some other do not. We'll come to this later.
58
58
59 Depending on the exact command you are typing you might realize that sometimes
59 Depending on the exact command you are typing you might realize that sometimes
60 :kbd:`Enter` will add a new line, and sometimes it will execute the current
60 :kbd:`Enter` will add a new line, and sometimes it will execute the current
61 statement. IPython tries to guess what you are doing, so most of the time you
61 statement. IPython tries to guess what you are doing, so most of the time you
62 should not have to care. Though if by any chance IPython does not the right
62 should not have to care. Though if by any chance IPython does not the right
63 thing you can force execution of the current code block by pressing in sequence
63 thing you can force execution of the current code block by pressing in sequence
64 :kbd:`Esc` and :kbd:`Enter`. You can also force the insertion of a new line at
64 :kbd:`Esc` and :kbd:`Enter`. You can also force the insertion of a new line at
65 the position of the cursor by using :kbd:`Ctrl-o`.
65 the position of the cursor by using :kbd:`Ctrl-o`.
66
66
67 The four most helpful commands
67 The four most helpful commands
68 ==============================
68 ==============================
69
69
70 The four most helpful commands, as well as their brief description, is shown
70 The four most helpful commands, as well as their brief description, is shown
71 to you in a banner, every time you start IPython:
71 to you in a banner, every time you start IPython:
72
72
73 ========== =========================================================
73 ========== =========================================================
74 command description
74 command description
75 ========== =========================================================
75 ========== =========================================================
76 ? Introduction and overview of IPython's features.
76 ? Introduction and overview of IPython's features.
77 %quickref Quick reference.
77 %quickref Quick reference.
78 help Python's own help system.
78 help Python's own help system.
79 object? Details about 'object', use 'object??' for extra details.
79 object? Details about 'object', use 'object??' for extra details.
80 ========== =========================================================
80 ========== =========================================================
81
81
82 Tab completion
82 Tab completion
83 ==============
83 ==============
84
84
85 Tab completion, especially for attributes, is a convenient way to explore the
85 Tab completion, especially for attributes, is a convenient way to explore the
86 structure of any object you're dealing with. Simply type ``object_name.<TAB>``
86 structure of any object you're dealing with. Simply type ``object_name.<TAB>``
87 to view the object's attributes. Besides Python objects and keywords, tab
87 to view the object's attributes. Besides Python objects and keywords, tab
88 completion also works on file and directory names.
88 completion also works on file and directory names.
89
89
90 Starting with IPython 6.0, if ``jedi`` is installed, IPython will try to pull
90 Starting with IPython 6.0, if ``jedi`` is installed, IPython will try to pull
91 completions from Jedi as well. This allows to not only inspect currently
91 completions from Jedi as well. This allows to not only inspect currently
92 existing objects, but also to infer completion statically without executing
92 existing objects, but also to infer completion statically without executing
93 code. There is nothing particular need to get this to work, simply use tab
93 code. There is nothing particular need to get this to work, simply use tab
94 completion on more complex expressions like the following::
94 completion on more complex expressions like the following::
95
95
96 >>> data = ['Number of users', 123456]
96 >>> data = ['Number of users', 123456]
97 ... data[0].<tab>
97 ... data[0].<tab>
98
98
99 IPython and Jedi will be able to infer that ``data[0]`` is actually a string
99 IPython and Jedi will be able to infer that ``data[0]`` is actually a string
100 and should show relevant completions like ``upper()``, ``lower()`` and other
100 and should show relevant completions like ``upper()``, ``lower()`` and other
101 string methods. You can use the :kbd:`Tab` key to cycle through completions,
101 string methods. You can use the :kbd:`Tab` key to cycle through completions,
102 and while a completion is highlighted, its type will be shown as well.
102 and while a completion is highlighted, its type will be shown as well.
103 When the type of the completion is a function, the completer will also show the
103 When the type of the completion is a function, the completer will also show the
104 signature of the function when highlighted.
104 signature of the function when highlighted.
105
105
106 Exploring your objects
106 Exploring your objects
107 ======================
107 ======================
108
108
109 Typing ``object_name?`` will print all sorts of details about any object,
109 Typing ``object_name?`` will print all sorts of details about any object,
110 including docstrings, function definition lines (for call arguments) and
110 including docstrings, function definition lines (for call arguments) and
111 constructor details for classes. To get specific information on an object, you
111 constructor details for classes. To get specific information on an object, you
112 can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
112 can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
113
113
114 .. _magics_explained:
114 .. _magics_explained:
115
115
116 Magic functions
116 Magic functions
117 ===============
117 ===============
118
118
119 IPython has a set of predefined 'magic functions' that you can call with a
119 IPython has a set of predefined 'magic functions' that you can call with a
120 command line style syntax. There are two kinds of magics, line-oriented and
120 command line style syntax. There are two kinds of magics, line-oriented and
121 cell-oriented. **Line magics** are prefixed with the ``%`` character and work
121 cell-oriented. **Line magics** are prefixed with the ``%`` character and work
122 much like OS command-line calls: they get as an argument the rest of the line,
122 much like OS command-line calls: they get as an argument the rest of the line,
123 where arguments are passed without parentheses or quotes. **Lines magics** can
123 where arguments are passed without parentheses or quotes. **Lines magics** can
124 return results and can be used in the right hand side of an assignment. **Cell
124 return results and can be used in the right hand side of an assignment. **Cell
125 magics** are prefixed with a double ``%%``, and they are functions that get as
125 magics** are prefixed with a double ``%%``, and they are functions that get as
126 an argument not only the rest of the line, but also the lines below it in a
126 an argument not only the rest of the line, but also the lines below it in a
127 separate argument.
127 separate argument.
128
128
129 Magics are useful as convenient functions where Python syntax is not the most
129 Magics are useful as convenient functions where Python syntax is not the most
130 natural one, or when one want to embed invalid python syntax in their work flow.
130 natural one, or when one want to embed invalid python syntax in their work flow.
131
131
132 The following examples show how to call the built-in :magic:`timeit` magic, both
132 The following examples show how to call the built-in :magic:`timeit` magic, both
133 in line and cell mode::
133 in line and cell mode::
134
134
135 In [1]: %timeit range(1000)
135 In [1]: %timeit range(1000)
136 100000 loops, best of 3: 7.76 us per loop
136 100000 loops, best of 3: 7.76 us per loop
137
137
138 In [2]: %%timeit x = range(10000)
138 In [2]: %%timeit x = range(10000)
139 ...: max(x)
139 ...: max(x)
140 ...:
140 ...:
141 1000 loops, best of 3: 223 us per loop
141 1000 loops, best of 3: 223 us per loop
142
142
143 The built-in magics include:
143 The built-in magics include:
144
144
145 - Functions that work with code: :magic:`run`, :magic:`edit`, :magic:`save`,
145 - Functions that work with code: :magic:`run`, :magic:`edit`, :magic:`save`,
146 :magic:`macro`, :magic:`recall`, etc.
146 :magic:`macro`, :magic:`recall`, etc.
147
147
148 - Functions which affect the shell: :magic:`colors`, :magic:`xmode`,
148 - Functions which affect the shell: :magic:`colors`, :magic:`xmode`,
149 :magic:`automagic`, etc.
149 :magic:`automagic`, etc.
150
150
151 - Other functions such as :magic:`reset`, :magic:`timeit`,
151 - Other functions such as :magic:`reset`, :magic:`timeit`,
152 :cellmagic:`writefile`, :magic:`load`, or :magic:`paste`.
152 :cellmagic:`writefile`, :magic:`load`, or :magic:`paste`.
153
153
154 You can always call magics using the ``%`` prefix, and if you're calling a line
154 You can always call magics using the ``%`` prefix, and if you're calling a line
155 magic on a line by itself, as long as the identifier is not defined in your
155 magic on a line by itself, as long as the identifier is not defined in your
156 namespace, you can omit even that::
156 namespace, you can omit even that::
157
157
158 run thescript.py
158 run thescript.py
159
159
160 You can toggle this behavior by running the :magic:`automagic` magic. Cell
160 You can toggle this behavior by running the :magic:`automagic` magic. Cell
161 magics must always have the ``%%`` prefix.
161 magics must always have the ``%%`` prefix.
162
162
163 A more detailed explanation of the magic system can be obtained by calling
163 A more detailed explanation of the magic system can be obtained by calling
164 ``%magic``, and for more details on any magic function, call ``%somemagic?`` to
164 ``%magic``, and for more details on any magic function, call ``%somemagic?`` to
165 read its docstring. To see all the available magic functions, call
165 read its docstring. To see all the available magic functions, call
166 ``%lsmagic``.
166 ``%lsmagic``.
167
167
168 .. seealso::
168 .. seealso::
169
169
170 The :ref:`magic` section of the documentation goes more in depth into how
170 The :ref:`magic` section of the documentation goes more in depth into how
171 the magics works and how to define your own, and :doc:`magics` for a list of
171 the magics works and how to define your own, and :doc:`magics` for a list of
172 built-in magics.
172 built-in magics.
173
173
174 `Cell magics`_ example notebook
174 `Cell magics`_ example notebook
175
175
176 Running and Editing
176 Running and Editing
177 -------------------
177 -------------------
178
178
179 The :magic:`run` magic command allows you to run any python script and load all
179 The :magic:`run` magic command allows you to run any python script and load all
180 of its data directly into the interactive namespace. Since the file is re-read
180 of its data directly into the interactive namespace. Since the file is re-read
181 from disk each time, changes you make to it are reflected immediately (unlike
181 from disk each time, changes you make to it are reflected immediately (unlike
182 imported modules, which have to be specifically reloaded). IPython also includes
182 imported modules, which have to be specifically reloaded). IPython also includes
183 :ref:`dreload <dreload>`, a recursive reload function.
183 :ref:`dreload <dreload>`, a recursive reload function.
184
184
185 ``%run`` has special flags for timing the execution of your scripts (-t), or
185 ``%run`` has special flags for timing the execution of your scripts (-t), or
186 for running them under the control of either Python's pdb debugger (-d) or
186 for running them under the control of either Python's pdb debugger (-d) or
187 profiler (-p).
187 profiler (-p).
188
188
189 The :magic:`edit` command gives a reasonable approximation of multi-line editing,
189 The :magic:`edit` command gives a reasonable approximation of multi-line editing,
190 by invoking your favorite editor on the spot. IPython will execute the
190 by invoking your favorite editor on the spot. IPython will execute the
191 code you type in there as if it were typed interactively. Note that for
191 code you type in there as if it were typed interactively. Note that for
192 :magic:`edit` to work, the call to startup your editor has to be a blocking
192 :magic:`edit` to work, the call to startup your editor has to be a blocking
193 call. In a GUI environment, your editor likely will have such an option.
193 call. In a GUI environment, your editor likely will have such an option.
194
194
195 Debugging
195 Debugging
196 ---------
196 ---------
197
197
198 After an exception occurs, you can call :magic:`debug` to jump into the Python
198 After an exception occurs, you can call :magic:`debug` to jump into the Python
199 debugger (pdb) and examine the problem. Alternatively, if you call :magic:`pdb`,
199 debugger (pdb) and examine the problem. Alternatively, if you call :magic:`pdb`,
200 IPython will automatically start the debugger on any uncaught exception. You can
200 IPython will automatically start the debugger on any uncaught exception. You can
201 print variables, see code, execute statements and even walk up and down the call
201 print variables, see code, execute statements and even walk up and down the call
202 stack to track down the true source of the problem. This can be an efficient way
202 stack to track down the true source of the problem. This can be an efficient way
203 to develop and debug code, in many cases eliminating the need for print
203 to develop and debug code, in many cases eliminating the need for print
204 statements or external debugging tools.
204 statements or external debugging tools.
205
205
206 You can also step through a program from the beginning by calling
206 You can also step through a program from the beginning by calling
207 ``%run -d theprogram.py``.
207 ``%run -d theprogram.py``.
208
208
209 History
209 History
210 =======
210 =======
211
211
212 IPython stores both the commands you enter, and the results it produces. You
212 IPython stores both the commands you enter, and the results it produces. You
213 can easily go through previous commands with the up- and down-arrow keys, or
213 can easily go through previous commands with the up- and down-arrow keys, or
214 access your history in more sophisticated ways.
214 access your history in more sophisticated ways.
215
215
216 Input and output history are kept in variables called ``In`` and ``Out``, keyed
216 Input and output history are kept in variables called ``In`` and ``Out``, keyed
217 by the prompt numbers, e.g. ``In[4]``. The last three objects in output history
217 by the prompt numbers, e.g. ``In[4]``. The last three objects in output history
218 are also kept in variables named ``_``, ``__`` and ``___``.
218 are also kept in variables named ``_``, ``__`` and ``___``.
219
219
220 You can use the ``%history`` magic function to examine past input and output.
220 You can use the ``%history`` magic function to examine past input and output.
221 Input history from previous sessions is saved in a database, and IPython can be
221 Input history from previous sessions is saved in a database, and IPython can be
222 configured to save output history.
222 configured to save output history.
223
223
224 Several other magic functions can use your input history, including ``%edit``,
224 Several other magic functions can use your input history, including ``%edit``,
225 ``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a
225 ``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a
226 standard format to refer to lines::
226 standard format to refer to lines::
227
227
228 %pastebin 3 18-20 ~1/1-5
228 %pastebin 3 18-20 ~1/1-5
229
229
230 This will take line 3 and lines 18 to 20 from the current session, and lines
230 This will take line 3 and lines 18 to 20 from the current session, and lines
231 1-5 from the previous session.
231 1-5 from the previous session.
232
232
233 System shell commands
233 System shell commands
234 =====================
234 =====================
235
235
236 To run any command at the system shell, simply prefix it with ``!``, e.g.::
236 To run any command at the system shell, simply prefix it with ``!``, e.g.::
237
237
238 !ping www.bbc.co.uk
238 !ping www.bbc.co.uk
239
239
240 You can capture the output into a Python list, e.g.: ``files = !ls``. To pass
240 You can capture the output into a Python list, e.g.: ``files = !ls``. To pass
241 the values of Python variables or expressions to system commands, prefix them
241 the values of Python variables or expressions to system commands, prefix them
242 with $: ``!grep -rF $pattern ipython/*`` or wrap in `{braces}`. See :ref:`our
242 with $: ``!grep -rF $pattern ipython/*`` or wrap in `{braces}`. See :ref:`our
243 shell section <system_shell_access>` for more details.
243 shell section <system_shell_access>` for more details.
244
244
245 Define your own system aliases
245 Define your own system aliases
246 ------------------------------
246 ------------------------------
247
247
248 It's convenient to have aliases to the system commands you use most often. This
248 It's convenient to have aliases to the system commands you use most often. This
249 allows you to work seamlessly from inside IPython with the same commands you are
249 allows you to work seamlessly from inside IPython with the same commands you are
250 used to in your system shell. IPython comes with some pre-defined aliases and a
250 used to in your system shell. IPython comes with some pre-defined aliases and a
251 complete system for changing directories, both via a stack (see :magic:`pushd`,
251 complete system for changing directories, both via a stack (see :magic:`pushd`,
252 :magic:`popd` and :magic:`dhist`) and via direct :magic:`cd`. The latter keeps a
252 :magic:`popd` and :magic:`dhist`) and via direct :magic:`cd`. The latter keeps a
253 history of visited directories and allows you to go to any previously visited
253 history of visited directories and allows you to go to any previously visited
254 one.
254 one.
255
255
256
256
257 Configuration
257 Configuration
258 =============
258 =============
259
259
260 Much of IPython can be tweaked through :doc:`configuration </config/intro>`.
260 Much of IPython can be tweaked through :doc:`configuration </config/intro>`.
261 To get started, use the command ``ipython profile create`` to produce the
261 To get started, use the command ``ipython profile create`` to produce the
262 default config files. These will be placed in
262 default config files. These will be placed in
263 :file:`~/.ipython/profile_default`, and contain comments explaining
263 :file:`~/.ipython/profile_default`, and contain comments explaining
264 what the various options do.
264 what the various options do.
265
265
266 Profiles allow you to use IPython for different tasks, keeping separate config
266 Profiles allow you to use IPython for different tasks, keeping separate config
267 files and history for each one. More details in :ref:`the profiles section
267 files and history for each one. More details in :ref:`the profiles section
268 <profiles>`.
268 <profiles>`.
269
269
270 .. _startup_files:
270 .. _startup_files:
271
271
272 Startup Files
272 Startup Files
273 -------------
273 -------------
274
274
275 If you want some code to be run at the beginning of every IPython session, the
275 If you want some code to be run at the beginning of every IPython session, the
276 easiest way is to add Python (.py) or IPython (.ipy) scripts to your
276 easiest way is to add Python (.py) or IPython (.ipy) scripts to your
277 :file:`profile_default/startup/` directory. Files here will be executed as soon
277 :file:`profile_default/startup/` directory. Files here will be executed as soon
278 as the IPython shell is constructed, before any other code or scripts you have
278 as the IPython shell is constructed, before any other code or scripts you have
279 specified. The files will be run in order of their names, so you can control the
279 specified. The files will be run in order of their names, so you can control the
280 ordering with prefixes, like ``10-myimports.py``.
280 ordering with prefixes, like ``10-myimports.py``.
281
281
282 .. include:: ../links.txt
282 .. include:: ../links.txt
General Comments 0
You need to be logged in to leave comments. Login now