Show More
@@ -1,203 +1,203 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've never used Python before, you might want to look at `the official |
|
13 | If you've never used Python before, you might want to look at `the official | |
14 | tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into |
|
14 | tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into | |
15 | Python <http://diveintopython.net/toc/index.html>`_. |
|
15 | Python <http://diveintopython.net/toc/index.html>`_. | |
16 |
|
16 | |||
17 | The four most helpful commands |
|
17 | The four most helpful commands | |
18 | =============================== |
|
18 | =============================== | |
19 |
|
19 | |||
20 | The four most helpful commands, as well as their brief description, is shown |
|
20 | The four most helpful commands, as well as their brief description, is shown | |
21 | to you in a banner, every time you start IPython: |
|
21 | to you in a banner, every time you start IPython: | |
22 |
|
22 | |||
23 | ========== ========================================================= |
|
23 | ========== ========================================================= | |
24 | command description |
|
24 | command description | |
25 | ========== ========================================================= |
|
25 | ========== ========================================================= | |
26 | ? Introduction and overview of IPython's features. |
|
26 | ? Introduction and overview of IPython's features. | |
27 | %quickref Quick reference. |
|
27 | %quickref Quick reference. | |
28 | help Python's own help system. |
|
28 | help Python's own help system. | |
29 | object? Details about 'object', use 'object??' for extra details. |
|
29 | object? Details about 'object', use 'object??' for extra details. | |
30 | ========== ========================================================= |
|
30 | ========== ========================================================= | |
31 |
|
31 | |||
32 | Tab completion |
|
32 | Tab completion | |
33 | ============== |
|
33 | ============== | |
34 |
|
34 | |||
35 | Tab completion, especially for attributes, is a convenient way to explore the |
|
35 | Tab completion, especially for attributes, is a convenient way to explore the | |
36 | structure of any object you're dealing with. Simply type ``object_name.<TAB>`` |
|
36 | structure of any object you're dealing with. Simply type ``object_name.<TAB>`` | |
37 | to view the object's attributes (see :ref:`the readline section <readline>` for |
|
37 | to view the object's attributes (see :ref:`the readline section <readline>` for | |
38 | more). Besides Python objects and keywords, tab completion also works on file |
|
38 | more). Besides Python objects and keywords, tab completion also works on file | |
39 | and directory names. |
|
39 | and directory names. | |
40 |
|
40 | |||
41 | Exploring your objects |
|
41 | Exploring your objects | |
42 | ====================== |
|
42 | ====================== | |
43 |
|
43 | |||
44 | Typing ``object_name?`` will print all sorts of details about any object, |
|
44 | Typing ``object_name?`` will print all sorts of details about any object, | |
45 | including docstrings, function definition lines (for call arguments) and |
|
45 | including docstrings, function definition lines (for call arguments) and | |
46 | constructor details for classes. To get specific information on an object, you |
|
46 | constructor details for classes. To get specific information on an object, you | |
47 | can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile`` |
|
47 | can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile`` | |
48 |
|
48 | |||
49 | .. _magics_explained: |
|
49 | .. _magics_explained: | |
50 |
|
50 | |||
51 | Magic functions |
|
51 | Magic functions | |
52 | =============== |
|
52 | =============== | |
53 |
|
53 | |||
54 | IPython has a set of predefined 'magic functions' that you can call with a |
|
54 | IPython has a set of predefined 'magic functions' that you can call with a | |
55 | command line style syntax. There are two kinds of magics, line-oriented and |
|
55 | command line style syntax. There are two kinds of magics, line-oriented and | |
56 | cell-oriented. **Line magics** are prefixed with the ``%`` character and work much |
|
56 | cell-oriented. **Line magics** are prefixed with the ``%`` character and work much | |
57 | like OS command-line calls: they get as an argument the rest of the line, where |
|
57 | like OS command-line calls: they get as an argument the rest of the line, where | |
58 | arguments are passed without parentheses or quotes. **Cell magics** are |
|
58 | arguments are passed without parentheses or quotes. **Cell magics** are | |
59 | prefixed with a double ``%%``, and they are functions that get as an argument |
|
59 | prefixed with a double ``%%``, and they are functions that get as an argument | |
60 | not only the rest of the line, but also the lines below it in a separate |
|
60 | not only the rest of the line, but also the lines below it in a separate | |
61 | argument. |
|
61 | argument. | |
62 |
|
62 | |||
63 | The following examples show how to call the builtin :magic:`timeit` magic, both in |
|
63 | The following examples show how to call the builtin :magic:`timeit` magic, both in | |
64 | line and cell mode:: |
|
64 | line and cell mode:: | |
65 |
|
65 | |||
66 | In [1]: %timeit range(1000) |
|
66 | In [1]: %timeit range(1000) | |
67 | 100000 loops, best of 3: 7.76 us per loop |
|
67 | 100000 loops, best of 3: 7.76 us per loop | |
68 |
|
68 | |||
69 | In [2]: %%timeit x = range(10000) |
|
69 | In [2]: %%timeit x = range(10000) | |
70 | ...: max(x) |
|
70 | ...: max(x) | |
71 | ...: |
|
71 | ...: | |
72 | 1000 loops, best of 3: 223 us per loop |
|
72 | 1000 loops, best of 3: 223 us per loop | |
73 |
|
73 | |||
74 | The builtin magics include: |
|
74 | The builtin magics include: | |
75 |
|
75 | |||
76 | - Functions that work with code: :magic`run`, :magic:`edit`, :magic:`save`, :magic:`macro`, |
|
76 | - Functions that work with code: :magic:`run`, :magic:`edit`, :magic:`save`, :magic:`macro`, | |
77 | :magic:`recall`, etc. |
|
77 | :magic:`recall`, etc. | |
78 | - Functions which affect the shell: :magic:`colors`, :magic:`xmode`, :magic:`autoindent`, |
|
78 | - Functions which affect the shell: :magic:`colors`, :magic:`xmode`, :magic:`autoindent`, | |
79 | :magic:`automagic`, etc. |
|
79 | :magic:`automagic`, etc. | |
80 | - Other functions such as :magic:`reset`, :magic:`timeit`, :cellmagic:`writefile`, :magic:`load`, or |
|
80 | - Other functions such as :magic:`reset`, :magic:`timeit`, :cellmagic:`writefile`, :magic:`load`, or | |
81 | :magic:`paste`. |
|
81 | :magic:`paste`. | |
82 |
|
82 | |||
83 | You can always call them using the ``%`` prefix, and if you're calling a line |
|
83 | You can always call them using the ``%`` prefix, and if you're calling a line | |
84 | magic on a line by itself, you can omit even that:: |
|
84 | magic on a line by itself, you can omit even that:: | |
85 |
|
85 | |||
86 | run thescript.py |
|
86 | run thescript.py | |
87 |
|
87 | |||
88 | You can toggle this behavior by running the :magic:`automagic` magic. Cell magics |
|
88 | You can toggle this behavior by running the :magic:`automagic` magic. Cell magics | |
89 | must always have the ``%%`` prefix. |
|
89 | must always have the ``%%`` prefix. | |
90 |
|
90 | |||
91 | A more detailed explanation of the magic system can be obtained by calling |
|
91 | A more detailed explanation of the magic system can be obtained by calling | |
92 | ``%magic``, and for more details on any magic function, call ``%somemagic?`` to |
|
92 | ``%magic``, and for more details on any magic function, call ``%somemagic?`` to | |
93 | read its docstring. To see all the available magic functions, call |
|
93 | read its docstring. To see all the available magic functions, call | |
94 | ``%lsmagic``. |
|
94 | ``%lsmagic``. | |
95 |
|
95 | |||
96 | .. seealso:: |
|
96 | .. seealso:: | |
97 |
|
97 | |||
98 | :doc:`magics` |
|
98 | :doc:`magics` | |
99 |
|
99 | |||
100 | `Cell magics`_ example notebook |
|
100 | `Cell magics`_ example notebook | |
101 |
|
101 | |||
102 | Running and Editing |
|
102 | Running and Editing | |
103 | ------------------- |
|
103 | ------------------- | |
104 |
|
104 | |||
105 | The :magic:`run` magic command allows you to run any python script and load all of |
|
105 | The :magic:`run` magic command allows you to run any python script and load all of | |
106 | its data directly into the interactive namespace. Since the file is re-read |
|
106 | its data directly into the interactive namespace. Since the file is re-read | |
107 | from disk each time, changes you make to it are reflected immediately (unlike |
|
107 | from disk each time, changes you make to it are reflected immediately (unlike | |
108 | imported modules, which have to be specifically reloaded). IPython also |
|
108 | imported modules, which have to be specifically reloaded). IPython also | |
109 | includes :ref:`dreload <dreload>`, a recursive reload function. |
|
109 | includes :ref:`dreload <dreload>`, a recursive reload function. | |
110 |
|
110 | |||
111 | ``%run`` has special flags for timing the execution of your scripts (-t), or |
|
111 | ``%run`` has special flags for timing the execution of your scripts (-t), or | |
112 | for running them under the control of either Python's pdb debugger (-d) or |
|
112 | for running them under the control of either Python's pdb debugger (-d) or | |
113 | profiler (-p). |
|
113 | profiler (-p). | |
114 |
|
114 | |||
115 | The :magic:`edit` command gives a reasonable approximation of multiline editing, |
|
115 | The :magic:`edit` command gives a reasonable approximation of multiline editing, | |
116 | by invoking your favorite editor on the spot. IPython will execute the |
|
116 | by invoking your favorite editor on the spot. IPython will execute the | |
117 | code you type in there as if it were typed interactively. |
|
117 | code you type in there as if it were typed interactively. | |
118 |
|
118 | |||
119 | Debugging |
|
119 | Debugging | |
120 | --------- |
|
120 | --------- | |
121 |
|
121 | |||
122 | After an exception occurs, you can call :magic:`debug` to jump into the Python |
|
122 | After an exception occurs, you can call :magic:`debug` to jump into the Python | |
123 | debugger (pdb) and examine the problem. Alternatively, if you call :magic:`pdb`, |
|
123 | debugger (pdb) and examine the problem. Alternatively, if you call :magic:`pdb`, | |
124 | IPython will automatically start the debugger on any uncaught exception. You can |
|
124 | IPython will automatically start the debugger on any uncaught exception. You can | |
125 | print variables, see code, execute statements and even walk up and down the |
|
125 | print variables, see code, execute statements and even walk up and down the | |
126 | call stack to track down the true source of the problem. This can be an efficient |
|
126 | call stack to track down the true source of the problem. This can be an efficient | |
127 | way to develop and debug code, in many cases eliminating the need for print |
|
127 | way to develop and debug code, in many cases eliminating the need for print | |
128 | statements or external debugging tools. |
|
128 | statements or external debugging tools. | |
129 |
|
129 | |||
130 | You can also step through a program from the beginning by calling |
|
130 | You can also step through a program from the beginning by calling | |
131 | ``%run -d theprogram.py``. |
|
131 | ``%run -d theprogram.py``. | |
132 |
|
132 | |||
133 | History |
|
133 | History | |
134 | ======= |
|
134 | ======= | |
135 |
|
135 | |||
136 | IPython stores both the commands you enter, and the results it produces. You |
|
136 | IPython stores both the commands you enter, and the results it produces. You | |
137 | can easily go through previous commands with the up- and down-arrow keys, or |
|
137 | can easily go through previous commands with the up- and down-arrow keys, or | |
138 | access your history in more sophisticated ways. |
|
138 | access your history in more sophisticated ways. | |
139 |
|
139 | |||
140 | Input and output history are kept in variables called ``In`` and ``Out``, keyed |
|
140 | Input and output history are kept in variables called ``In`` and ``Out``, keyed | |
141 | by the prompt numbers, e.g. ``In[4]``. The last three objects in output history |
|
141 | by the prompt numbers, e.g. ``In[4]``. The last three objects in output history | |
142 | are also kept in variables named ``_``, ``__`` and ``___``. |
|
142 | are also kept in variables named ``_``, ``__`` and ``___``. | |
143 |
|
143 | |||
144 | You can use the ``%history`` magic function to examine past input and output. |
|
144 | You can use the ``%history`` magic function to examine past input and output. | |
145 | Input history from previous sessions is saved in a database, and IPython can be |
|
145 | Input history from previous sessions is saved in a database, and IPython can be | |
146 | configured to save output history. |
|
146 | configured to save output history. | |
147 |
|
147 | |||
148 | Several other magic functions can use your input history, including ``%edit``, |
|
148 | Several other magic functions can use your input history, including ``%edit``, | |
149 | ``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a |
|
149 | ``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a | |
150 | standard format to refer to lines:: |
|
150 | standard format to refer to lines:: | |
151 |
|
151 | |||
152 | %pastebin 3 18-20 ~1/1-5 |
|
152 | %pastebin 3 18-20 ~1/1-5 | |
153 |
|
153 | |||
154 | This will take line 3 and lines 18 to 20 from the current session, and lines |
|
154 | This will take line 3 and lines 18 to 20 from the current session, and lines | |
155 | 1-5 from the previous session. |
|
155 | 1-5 from the previous session. | |
156 |
|
156 | |||
157 | System shell commands |
|
157 | System shell commands | |
158 | ===================== |
|
158 | ===================== | |
159 |
|
159 | |||
160 | To run any command at the system shell, simply prefix it with !, e.g.:: |
|
160 | To run any command at the system shell, simply prefix it with !, e.g.:: | |
161 |
|
161 | |||
162 | !ping www.bbc.co.uk |
|
162 | !ping www.bbc.co.uk | |
163 |
|
163 | |||
164 | You can capture the output into a Python list, e.g.: ``files = !ls``. To pass |
|
164 | You can capture the output into a Python list, e.g.: ``files = !ls``. To pass | |
165 | the values of Python variables or expressions to system commands, prefix them |
|
165 | the values of Python variables or expressions to system commands, prefix them | |
166 | with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section |
|
166 | with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section | |
167 | <system_shell_access>` for more details. |
|
167 | <system_shell_access>` for more details. | |
168 |
|
168 | |||
169 | Define your own system aliases |
|
169 | Define your own system aliases | |
170 | ------------------------------ |
|
170 | ------------------------------ | |
171 |
|
171 | |||
172 | It's convenient to have aliases to the system commands you use most often. |
|
172 | It's convenient to have aliases to the system commands you use most often. | |
173 | This allows you to work seamlessly from inside IPython with the same commands |
|
173 | This allows you to work seamlessly from inside IPython with the same commands | |
174 | you are used to in your system shell. IPython comes with some pre-defined |
|
174 | you are used to in your system shell. IPython comes with some pre-defined | |
175 | aliases and a complete system for changing directories, both via a stack (see |
|
175 | aliases and a complete system for changing directories, both via a stack (see | |
176 | :magic:`pushd`, :magic:`popd` and :magic:`dhist`) and via direct :magic:`cd`. The latter keeps a history of |
|
176 | :magic:`pushd`, :magic:`popd` and :magic:`dhist`) and via direct :magic:`cd`. The latter keeps a history of | |
177 | visited directories and allows you to go to any previously visited one. |
|
177 | visited directories and allows you to go to any previously visited one. | |
178 |
|
178 | |||
179 |
|
179 | |||
180 | Configuration |
|
180 | Configuration | |
181 | ============= |
|
181 | ============= | |
182 |
|
182 | |||
183 | Much of IPython can be tweaked through :doc:`configuration </config/intro>`. |
|
183 | Much of IPython can be tweaked through :doc:`configuration </config/intro>`. | |
184 | To get started, use the command ``ipython profile create`` to produce the |
|
184 | To get started, use the command ``ipython profile create`` to produce the | |
185 | default config files. These will be placed in |
|
185 | default config files. These will be placed in | |
186 | :file:`~/.ipython/profile_default`, and contain comments explaining |
|
186 | :file:`~/.ipython/profile_default`, and contain comments explaining | |
187 | what the various options do. |
|
187 | what the various options do. | |
188 |
|
188 | |||
189 | Profiles allow you to use IPython for different tasks, keeping separate config |
|
189 | Profiles allow you to use IPython for different tasks, keeping separate config | |
190 | files and history for each one. More details in :ref:`the profiles section |
|
190 | files and history for each one. More details in :ref:`the profiles section | |
191 | <profiles>`. |
|
191 | <profiles>`. | |
192 |
|
192 | |||
193 | Startup Files |
|
193 | Startup Files | |
194 | ------------- |
|
194 | ------------- | |
195 |
|
195 | |||
196 | If you want some code to be run at the beginning of every IPython session, the |
|
196 | If you want some code to be run at the beginning of every IPython session, the | |
197 | easiest way is to add Python (.py) or IPython (.ipy) scripts to your |
|
197 | easiest way is to add Python (.py) or IPython (.ipy) scripts to your | |
198 | :file:`profile_default/startup/` directory. Files here will be executed as soon |
|
198 | :file:`profile_default/startup/` directory. Files here will be executed as soon | |
199 | as the IPython shell is constructed, before any other code or scripts you have |
|
199 | as the IPython shell is constructed, before any other code or scripts you have | |
200 | specified. The files will be run in order of their names, so you can control the |
|
200 | specified. The files will be run in order of their names, so you can control the | |
201 | ordering with prefixes, like ``10-myimports.py``. |
|
201 | ordering with prefixes, like ``10-myimports.py``. | |
202 |
|
202 | |||
203 | .. include:: ../links.txt |
|
203 | .. include:: ../links.txt |
General Comments 0
You need to be logged in to leave comments.
Login now