Show More
@@ -2,16 +2,28 b'' | |||
|
2 | 2 | Using IPython for interactive work |
|
3 | 3 | ================================== |
|
4 | 4 | |
|
5 | This section of IPython documentation walk you through most of the IPython | |
|
6 | functionality. You do not need to have any deep knowledge of Python to read this | |
|
7 | tutorial, though some section might make slightly more sens if you have already | |
|
8 | done some work in the REPL. | |
|
9 | ||
|
10 | .. note:: | |
|
11 | ||
|
12 | Some part of this documentation are more than a decade old so might be out | |
|
13 | of date, we welcome any report of inacuracy, and Pull Requests that make | |
|
14 | that up to date. | |
|
15 | ||
|
5 | 16 | .. toctree:: |
|
6 | 17 | :maxdepth: 2 |
|
18 | :hidden: | |
|
7 | 19 | |
|
8 | 20 | tutorial |
|
9 | magics | |
|
10 | 21 | plotting |
|
11 | 22 | reference |
|
12 | 23 | shell |
|
13 | 24 | tips |
|
14 | 25 | python-ipython-diff |
|
26 | magics | |
|
15 | 27 | |
|
16 | 28 | .. seealso:: |
|
17 | 29 |
@@ -2,4 +2,21 b'' | |||
|
2 | 2 | Built-in magic commands |
|
3 | 3 | ======================= |
|
4 | 4 | |
|
5 | .. note:: | |
|
6 | ||
|
7 | To Jupyter users: Magics are specifit to the IPython kernel. Other kernels | |
|
8 | may be implementing magics but this decision is a per-kernel one. To be able | |
|
9 | to work, Magics need to use a syntax which is not valid in the language they | |
|
10 | are implemented. IPython choosed the `%` as it is not a valid unary operator | |
|
11 | in Python. It is in other languages. | |
|
12 | ||
|
13 | ||
|
14 | Here is the help auto generated from the docstrings of all the available magics | |
|
15 | function that IPython ships with. | |
|
16 | ||
|
17 | You can create an register your own magics with IPython. You can find many user | |
|
18 | defined magics on `PyPI <https://pypi.io>`_. Feel free to publish your own and | |
|
19 | use the ``Framework :: IPython`` trove classifier. | |
|
20 | ||
|
21 | ||
|
5 | 22 | .. include:: magics-generated.txt |
@@ -6,11 +6,11 b' One major feature of the IPython kernel is the ability to display plots that' | |||
|
6 | 6 | are the output of running code cells. The IPython kernel is designed to work |
|
7 | 7 | seamlessly with the matplotlib_ plotting library to provide this functionality. |
|
8 | 8 | |
|
9 |
To set this up, before any plotting is performed you |
|
|
10 |
``%matplotlib`` :ref:`magic command <magics_explained>`. This |
|
|
11 |
necessary behind-the-scenes setup for IPython to work correctly |
|
|
12 |
with ``matplotlib``; it does *not*, however, actually execute any |
|
|
13 | ``import`` commands, that is, no names are added to the namespace. | |
|
9 | To set this up, before any plotting or import of matplotlib is performed you | |
|
10 | must execute the ``%matplotlib`` :ref:`magic command <magics_explained>`. This | |
|
11 | performs the necessary behind-the-scenes setup for IPython to work correctly | |
|
12 | hand in hand with ``matplotlib``; it does *not*, however, actually execute any | |
|
13 | Python ``import`` commands, that is, no names are added to the namespace. | |
|
14 | 14 | |
|
15 | 15 | If the ``%matplotlib`` magic is called without an argument, the |
|
16 | 16 | output of a plotting command is displayed using the default ``matplotlib`` |
@@ -25,12 +25,18 b' Jupyter QtConsole. It can be invoked as follows::' | |||
|
25 | 25 | |
|
26 | 26 | %matplotlib inline |
|
27 | 27 | |
|
28 | With this backend, the output of plotting commands is displayed *inline* | |
|
29 |
|
|
|
30 | resulting plots will then also be stored in the notebook document. | |
|
28 | With this backend, the output of plotting commands is displayed *inline* within | |
|
29 | frontends like the Jupyter notebook, directly below the code cell that produced | |
|
30 | it. The resulting plots will then also be stored in the notebook document. | |
|
31 | 31 | |
|
32 | 32 | .. seealso:: |
|
33 | 33 | |
|
34 | 34 | `Plotting with Matplotlib`_ example notebook |
|
35 | 35 | |
|
36 | ||
|
37 | The matplotlib_ library also ships with ``%matplotlib notebook`` command that | |
|
38 | allows interactive figures if your environment allows it. | |
|
39 | ||
|
40 | See the matplotlib_ documentation for more information. | |
|
41 | ||
|
36 | 42 | .. include:: ../links.txt |
@@ -11,20 +11,21 b' You start IPython with the command::' | |||
|
11 | 11 | |
|
12 | 12 | $ ipython [options] files |
|
13 | 13 | |
|
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 | |
|
16 |
you may have set in your ipython_config.py. This |
|
|
17 |
standard Python, which when called as python |
|
|
18 | file and ignore your configuration setup. | |
|
19 | ||
|
20 | Please note that some of the configuration options are not available at | |
|
21 |
|
|
|
22 |
|
|
|
23 |
|
|
|
14 | If invoked with no options, it executes all the files listed in sequence and | |
|
15 | exit. If you add the ``-i`` flag, it drops you into the interpreter while still | |
|
16 | acknowledging any options you may have set in your ``ipython_config.py``. This | |
|
17 | behavior is different from standard Python, which when called as python ``-i`` | |
|
18 | will only execute one file and ignore your configuration setup. | |
|
19 | ||
|
20 | Please note that some of the configuration options are not available at the | |
|
21 | command line, simply because they are not practical here. Look into your | |
|
22 | configuration files for details on those. There are separate configuration files | |
|
23 | for each profile, and the files look like :file:`ipython_config.py` or | |
|
24 | 24 | :file:`ipython_config_{frontendname}.py`. Profile directories look like |
|
25 |
:file:`profile_{profilename}` and are typically installed in the |
|
|
26 | which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME` | |
|
27 |
resolves to :file:`C:\\Users\\{YourUserName}` in |
|
|
25 | :file:`profile_{profilename}` and are typically installed in the | |
|
26 | :envvar:`IPYTHONDIR` directory, which defaults to :file:`$HOME/.ipython`. For | |
|
27 | Windows users, :envvar:`HOME` resolves to :file:`C:\\Users\\{YourUserName}` in | |
|
28 | most instances. | |
|
28 | 29 | |
|
29 | 30 | Command-line Options |
|
30 | 31 | -------------------- |
@@ -36,6 +37,20 b' alias to control them, but IPython lets you configure all of its objects from' | |||
|
36 | 37 | the command-line by passing the full class name and a corresponding value; type |
|
37 | 38 | ``ipython --help-all`` to see this full list. For example:: |
|
38 | 39 | |
|
40 | :: | |
|
41 | $ ipython --help-all | |
|
42 | <...snip...> | |
|
43 | --matplotlib=<CaselessStrEnum> (InteractiveShellApp.matplotlib) | |
|
44 | Default: None | |
|
45 | Choices: ['auto', 'gtk', 'gtk3', 'inline', 'nbagg', 'notebook', 'osx', 'qt', 'qt4', 'qt5', 'tk', 'wx'] | |
|
46 | Configure matplotlib for interactive use with the default matplotlib | |
|
47 | backend. | |
|
48 | <...snip...> | |
|
49 | ||
|
50 | ||
|
51 | Indicate that the following:: | |
|
52 | ||
|
53 | ||
|
39 | 54 | ipython --matplotlib qt |
|
40 | 55 | |
|
41 | 56 | is equivalent to:: |
@@ -145,9 +160,9 b' use it:' | |||
|
145 | 160 | |
|
146 | 161 | /home/fperez/ipython |
|
147 | 162 | |
|
148 |
Line magics, if they return a value, can be assigned to a variable using the |
|
|
149 |
``l = %sx ls`` (which in this particular case returns the result of `ls` |
|
|
150 | See :ref:`below <manual_capture>` for more information. | |
|
163 | Line magics, if they return a value, can be assigned to a variable using the | |
|
164 | syntax ``l = %sx ls`` (which in this particular case returns the result of `ls` | |
|
165 | as a python list). See :ref:`below <manual_capture>` for more information. | |
|
151 | 166 | |
|
152 | 167 | Type ``%magic`` for more information, including a list of all available magic |
|
153 | 168 | functions at any time and their docstrings. You can also type |
@@ -215,15 +230,6 b' The dynamic object information functions (?/??, ``%pdoc``,' | |||
|
215 | 230 | directly on variables. For example, after doing ``import os``, you can use |
|
216 | 231 | ``os.path.abspath??``. |
|
217 | 232 | |
|
218 | .. _readline: | |
|
219 | ||
|
220 | Readline-based features | |
|
221 | ----------------------- | |
|
222 | ||
|
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 | |
|
225 | behavior IPython uses, and then how to change it to suit your preferences. | |
|
226 | ||
|
227 | 233 | |
|
228 | 234 | Command line completion |
|
229 | 235 | +++++++++++++++++++++++ |
@@ -313,8 +319,8 b' before logging has been started.' | |||
|
313 | 319 | System shell access |
|
314 | 320 | ------------------- |
|
315 | 321 | |
|
316 | Any input line beginning with a ! character is passed verbatim (minus | |
|
317 | the !, of course) to the underlying operating system. For example, | |
|
322 | Any input line beginning with a ``!`` character is passed verbatim (minus | |
|
323 | the ``!``, of course) to the underlying operating system. For example, | |
|
318 | 324 | typing ``!ls`` will run 'ls' in the current directory. |
|
319 | 325 | |
|
320 | 326 | .. _manual_capture: |
@@ -368,9 +374,9 b' system shell commands. These aliases can have parameters.' | |||
|
368 | 374 | Then, typing ``alias_name params`` will execute the system command 'cmd |
|
369 | 375 | params' (from your underlying operating system). |
|
370 | 376 | |
|
371 | You can also define aliases with parameters using %s specifiers (one per | |
|
377 | You can also define aliases with parameters using ``%s`` specifiers (one per | |
|
372 | 378 | parameter). The following example defines the parts function as an |
|
373 |
alias to the command |
|
|
379 | alias to the command ``echo first %s second %s`` where each ``%s`` will be | |
|
374 | 380 | replaced by a positional parameter to the call to %parts:: |
|
375 | 381 | |
|
376 | 382 | In [1]: %alias parts echo first %s second %s |
@@ -427,12 +433,14 b' up for editing on the next command line.' | |||
|
427 | 433 | |
|
428 | 434 | The following variables always exist: |
|
429 | 435 | |
|
430 |
* _i, _ii, _iii: store previous, next previous and next-next |
|
|
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 | |
|
433 | internal list with a simple ``In=_ih``. | |
|
436 | * ``_i``, ``_ii``, ``_iii``: store previous, next previous and next-next | |
|
437 | previous inputs. | |
|
438 | ||
|
439 | * ``In``, ``_ih`` : a list of all inputs; ``_ih[n]`` is the input from line | |
|
440 | ``n``. If you overwrite In with a variable of your own, you can remake the | |
|
441 | assignment to the internal list with a simple ``In=_ih``. | |
|
434 | 442 | |
|
435 | Additionally, global variables named _i<n> are dynamically created (<n> | |
|
443 | Additionally, global variables named ``_i<n>`` are dynamically created (``<n>`` | |
|
436 | 444 | being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``. |
|
437 | 445 | |
|
438 | 446 | For example, what you typed at prompt 14 is available as ``_i14``, ``_ih[14]`` |
@@ -443,10 +451,10 b' by printing them out: they print like a clean string, without prompt' | |||
|
443 | 451 | characters. You can also manipulate them like regular variables (they |
|
444 | 452 | are strings), modify or exec them. |
|
445 | 453 | |
|
446 | You can also re-execute multiple lines of input easily by using the | |
|
447 |
|
|
|
448 |
previous lines which include magic function calls (which require |
|
|
449 | processing). Type %macro? for more details on the macro system. | |
|
454 | You can also re-execute multiple lines of input easily by using the magic | |
|
455 | :magic:`rerun` or :magic:`macro` functions. The macro system also allows you to | |
|
456 | re-execute previous lines which include magic function calls (which require | |
|
457 | special processing). Type %macro? for more details on the macro system. | |
|
450 | 458 | |
|
451 | 459 | A history function :magic:`history` allows you to see any part of your input |
|
452 | 460 | history by printing a range of the _i variables. |
@@ -34,9 +34,8 b' Tab completion' | |||
|
34 | 34 | |
|
35 | 35 | Tab completion, especially for attributes, is a convenient way to explore the |
|
36 | 36 | structure of any object you're dealing with. Simply type ``object_name.<TAB>`` |
|
37 |
to view the object's attributes |
|
|
38 | more). Besides Python objects and keywords, tab completion also works on file | |
|
39 | and directory names. | |
|
37 | to view the object's attributes. Besides Python objects and keywords, tab | |
|
38 | completion also works on file and directory names. | |
|
40 | 39 | |
|
41 | 40 | Exploring your objects |
|
42 | 41 | ====================== |
@@ -53,15 +52,19 b' Magic functions' | |||
|
53 | 52 | |
|
54 | 53 | IPython has a set of predefined 'magic functions' that you can call with a |
|
55 | 54 | 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 |
|
|
57 |
like OS command-line calls: they get as an argument the rest of the line, |
|
|
58 |
arguments are passed without parentheses or quotes. |
|
|
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 | |
|
61 | argument. | |
|
55 | cell-oriented. **Line magics** are prefixed with the ``%`` character and work | |
|
56 | much like OS command-line calls: they get as an argument the rest of the line, | |
|
57 | where arguments are passed without parentheses or quotes. **Lines magics** can | |
|
58 | return results and can be use in the right and side of an assignment. **Cell | |
|
59 | magics** are prefixed with a double ``%%``, and they are functions that get as | |
|
60 | an argument not only the rest of the line, but also the lines below it in a | |
|
61 | separate argument. | |
|
62 | 62 | |
|
63 | The following examples show how to call the builtin :magic:`timeit` magic, both in | |
|
64 | line and cell mode:: | |
|
63 | Magics are useful as convenient functions where Python syntax is not the most | |
|
64 | natural one, or when one want to embed invalid python syntax in their work flow. | |
|
65 | ||
|
66 | The following examples show how to call the builtin :magic:`timeit` magic, both | |
|
67 | in line and cell mode:: | |
|
65 | 68 | |
|
66 | 69 | In [1]: %timeit range(1000) |
|
67 | 70 | 100000 loops, best of 3: 7.76 us per loop |
@@ -73,20 +76,23 b' line and cell mode::' | |||
|
73 | 76 | |
|
74 | 77 | The builtin magics include: |
|
75 | 78 | |
|
76 |
- Functions that work with code: :magic:`run`, :magic:`edit`, :magic:`save` |
|
|
77 | :magic:`recall`, etc. | |
|
78 | - Functions which affect the shell: :magic:`colors`, :magic:`xmode`, :magic:`autoindent`, | |
|
79 | :magic:`automagic`, etc. | |
|
80 | - Other functions such as :magic:`reset`, :magic:`timeit`, :cellmagic:`writefile`, :magic:`load`, or | |
|
81 | :magic:`paste`. | |
|
79 | - Functions that work with code: :magic:`run`, :magic:`edit`, :magic:`save`, | |
|
80 | :magic:`macro`, :magic:`recall`, etc. | |
|
81 | ||
|
82 | - Functions which affect the shell: :magic:`colors`, :magic:`xmode`, | |
|
83 | :magic:`autoindent`, :magic:`automagic`, etc. | |
|
84 | ||
|
85 | - Other functions such as :magic:`reset`, :magic:`timeit`, | |
|
86 | :cellmagic:`writefile`, :magic:`load`, or :magic:`paste`. | |
|
82 | 87 | |
|
83 |
You can always call |
|
|
84 | magic on a line by itself, you can omit even that:: | |
|
88 | You can always call magics using the ``%`` prefix, and if you're calling a line | |
|
89 | magic on a line by itself, as long as the identifier is not defined in your | |
|
90 | namespace, you can omit even that:: | |
|
85 | 91 | |
|
86 | 92 | run thescript.py |
|
87 | 93 | |
|
88 |
You can toggle this behavior by running the :magic:`automagic` magic. Cell |
|
|
89 | must always have the ``%%`` prefix. | |
|
94 | You can toggle this behavior by running the :magic:`automagic` magic. Cell | |
|
95 | magics must always have the ``%%`` prefix. | |
|
90 | 96 | |
|
91 | 97 | A more detailed explanation of the magic system can be obtained by calling |
|
92 | 98 | ``%magic``, and for more details on any magic function, call ``%somemagic?`` to |
@@ -95,18 +101,20 b' read its docstring. To see all the available magic functions, call' | |||
|
95 | 101 | |
|
96 | 102 | .. seealso:: |
|
97 | 103 | |
|
98 | :doc:`magics` | |
|
104 | The :ref:`magic` section of the documentation goes more in depth into how | |
|
105 | the magics works and how to define your own, and :doc:`magics` for a list of | |
|
106 | built-in magics. | |
|
99 | 107 | |
|
100 | 108 | `Cell magics`_ example notebook |
|
101 | 109 | |
|
102 | 110 | Running and Editing |
|
103 | 111 | ------------------- |
|
104 | 112 | |
|
105 |
The :magic:`run` magic command allows you to run any python script and load all |
|
|
106 | its data directly into the interactive namespace. Since the file is re-read | |
|
113 | The :magic:`run` magic command allows you to run any python script and load all | |
|
114 | of its data directly into the interactive namespace. Since the file is re-read | |
|
107 | 115 | from disk each time, changes you make to it are reflected immediately (unlike |
|
108 | imported modules, which have to be specifically reloaded). IPython also | |
|
109 |
|
|
|
116 | imported modules, which have to be specifically reloaded). IPython also includes | |
|
117 | :ref:`dreload <dreload>`, a recursive reload function. | |
|
110 | 118 | |
|
111 | 119 | ``%run`` has special flags for timing the execution of your scripts (-t), or |
|
112 | 120 | for running them under the control of either Python's pdb debugger (-d) or |
@@ -114,7 +122,9 b' profiler (-p).' | |||
|
114 | 122 | |
|
115 | 123 | The :magic:`edit` command gives a reasonable approximation of multiline editing, |
|
116 | 124 | by invoking your favorite editor on the spot. IPython will execute the |
|
117 | code you type in there as if it were typed interactively. | |
|
125 | code you type in there as if it were typed interactively. Note that for | |
|
126 | :magic:`edit` to work, the call to startup your editor have to be a blocking | |
|
127 | call. In a GUI environment, your editor likely have such an option. | |
|
118 | 128 | |
|
119 | 129 | Debugging |
|
120 | 130 | --------- |
@@ -122,9 +132,9 b' Debugging' | |||
|
122 | 132 | After an exception occurs, you can call :magic:`debug` to jump into the Python |
|
123 | 133 | debugger (pdb) and examine the problem. Alternatively, if you call :magic:`pdb`, |
|
124 | 134 | 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 | |
|
126 |
|
|
|
127 |
|
|
|
135 | print variables, see code, execute statements and even walk up and down the call | |
|
136 | stack to track down the true source of the problem. This can be an efficient way | |
|
137 | to develop and debug code, in many cases eliminating the need for print | |
|
128 | 138 | statements or external debugging tools. |
|
129 | 139 | |
|
130 | 140 | You can also step through a program from the beginning by calling |
@@ -157,7 +167,7 b' This will take line 3 and lines 18 to 20 from the current session, and lines' | |||
|
157 | 167 | System shell commands |
|
158 | 168 | ===================== |
|
159 | 169 | |
|
160 | To run any command at the system shell, simply prefix it with !, e.g.:: | |
|
170 | To run any command at the system shell, simply prefix it with ``!``, e.g.:: | |
|
161 | 171 | |
|
162 | 172 | !ping www.bbc.co.uk |
|
163 | 173 | |
@@ -169,12 +179,13 b' with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section' | |||
|
169 | 179 | Define your own system aliases |
|
170 | 180 | ------------------------------ |
|
171 | 181 | |
|
172 | It's convenient to have aliases to the system commands you use most often. | |
|
173 |
|
|
|
174 |
|
|
|
175 |
|
|
|
176 |
|
|
|
177 |
visited directories and allows you to go to any previously visited |
|
|
182 | It's convenient to have aliases to the system commands you use most often. This | |
|
183 | allows you to work seamlessly from inside IPython with the same commands you are | |
|
184 | used to in your system shell. IPython comes with some pre-defined aliases and a | |
|
185 | complete system for changing directories, both via a stack (see :magic:`pushd`, | |
|
186 | :magic:`popd` and :magic:`dhist`) and via direct :magic:`cd`. The latter keeps a | |
|
187 | history of visited directories and allows you to go to any previously visited | |
|
188 | one. | |
|
178 | 189 | |
|
179 | 190 | |
|
180 | 191 | Configuration |
General Comments 0
You need to be logged in to leave comments.
Login now