Show More
@@ -88,13 +88,13 b' current execution block. Cell magics can in fact make arbitrary modifications' | |||||
88 | to the input they receive, which need not even be valid Python code at all. |
|
88 | to the input they receive, which need not even be valid Python code at all. | |
89 | They receive the whole block as a single string. |
|
89 | They receive the whole block as a single string. | |
90 |
|
90 | |||
91 |
As a line magic example, the |
|
91 | As a line magic example, the :magic:`cd` magic works just like the OS command of | |
92 | the same name:: |
|
92 | the same name:: | |
93 |
|
93 | |||
94 | In [8]: %cd |
|
94 | In [8]: %cd | |
95 | /home/fperez |
|
95 | /home/fperez | |
96 |
|
96 | |||
97 |
The following uses the builtin |
|
97 | The following uses the builtin :magic:`timeit` in cell mode:: | |
98 |
|
98 | |||
99 | In [10]: %%timeit x = range(10000) |
|
99 | In [10]: %%timeit x = range(10000) | |
100 | ...: min(x) |
|
100 | ...: min(x) | |
@@ -104,7 +104,7 b' The following uses the builtin ``timeit`` in cell mode::' | |||||
104 |
|
104 | |||
105 | In this case, ``x = range(10000)`` is called as the line argument, and the |
|
105 | In this case, ``x = range(10000)`` is called as the line argument, and the | |
106 | block with ``min(x)`` and ``max(x)`` is called as the cell body. The |
|
106 | block with ``min(x)`` and ``max(x)`` is called as the cell body. The | |
107 |
|
|
107 | :magic:`timeit` magic receives both. | |
108 |
|
108 | |||
109 | If you have 'automagic' enabled (as it by default), you don't need to type in |
|
109 | If you have 'automagic' enabled (as it by default), you don't need to type in | |
110 | the single ``%`` explicitly for line magics; IPython will scan its internal |
|
110 | the single ``%`` explicitly for line magics; IPython will scan its internal | |
@@ -156,6 +156,9 b' docstrings of all currently available magic commands.' | |||||
156 |
|
156 | |||
157 | .. seealso:: |
|
157 | .. seealso:: | |
158 |
|
158 | |||
|
159 | :doc:`magics` | |||
|
160 | A list of the line and cell magics available in IPython by default | |||
|
161 | ||||
159 | :ref:`defining_magics` |
|
162 | :ref:`defining_magics` | |
160 | How to define and register additional magic functions |
|
163 | How to define and register additional magic functions | |
161 |
|
164 | |||
@@ -185,21 +188,19 b' Typing ``??word`` or ``word??`` gives access to the full information, including' | |||||
185 | the source code where possible. Long strings are not snipped. |
|
188 | the source code where possible. Long strings are not snipped. | |
186 |
|
189 | |||
187 | The following magic functions are particularly useful for gathering |
|
190 | The following magic functions are particularly useful for gathering | |
188 |
information about your working environment |
|
191 | information about your working environment: | |
189 | typing ``%magic`` or querying them individually (``%function_name?``); |
|
|||
190 | this is just a summary: |
|
|||
191 |
|
192 | |||
192 |
* |
|
193 | * :magic:`pdoc` **<object>**: Print (or run through a pager if too long) the | |
193 | docstring for an object. If the given object is a class, it will |
|
194 | docstring for an object. If the given object is a class, it will | |
194 | print both the class and the constructor docstrings. |
|
195 | print both the class and the constructor docstrings. | |
195 |
* |
|
196 | * :magic:`pdef` **<object>**: Print the call signature for any callable | |
196 | object. If the object is a class, print the constructor information. |
|
197 | object. If the object is a class, print the constructor information. | |
197 |
* |
|
198 | * :magic:`psource` **<object>**: Print (or run through a pager if too long) | |
198 | the source code for an object. |
|
199 | the source code for an object. | |
199 |
* |
|
200 | * :magic:`pfile` **<object>**: Show the entire source file where an object was | |
200 | defined via a pager, opening it at the line where the object |
|
201 | defined via a pager, opening it at the line where the object | |
201 | definition begins. |
|
202 | definition begins. | |
202 |
* |
|
203 | * :magic:`who`/:magic:`whos`: These functions give information about identifiers | |
203 | you have defined interactively (not things you loaded or defined |
|
204 | you have defined interactively (not things you loaded or defined | |
204 | in your configuration files). %who just prints a list of |
|
205 | in your configuration files). %who just prints a list of | |
205 | identifiers and %whos prints a table with some basic details about |
|
206 | identifiers and %whos prints a table with some basic details about | |
@@ -310,7 +311,7 b' Session logging and restoring' | |||||
310 |
|
311 | |||
311 | You can log all input from a session either by starting IPython with the |
|
312 | You can log all input from a session either by starting IPython with the | |
312 | command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`) |
|
313 | command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`) | |
313 |
or by activating the logging at any moment with the magic function |
|
314 | or by activating the logging at any moment with the magic function :magic:`logstart`. | |
314 |
|
315 | |||
315 | Log files can later be reloaded by running them as scripts and IPython |
|
316 | Log files can later be reloaded by running them as scripts and IPython | |
316 | will attempt to 'replay' the log by executing all the lines in it, thus |
|
317 | will attempt to 'replay' the log by executing all the lines in it, thus | |
@@ -322,7 +323,7 b' any code you wrote while experimenting. Log files are regular text files' | |||||
322 | which you can later open in your favorite text editor to extract code or |
|
323 | which you can later open in your favorite text editor to extract code or | |
323 | to 'clean them up' before using them to replay a session. |
|
324 | to 'clean them up' before using them to replay a session. | |
324 |
|
325 | |||
325 |
The ` |
|
326 | The :magic:`logstart` function for activating logging in mid-session is used as | |
326 | follows:: |
|
327 | follows:: | |
327 |
|
328 | |||
328 | %logstart [log_name [log_mode]] |
|
329 | %logstart [log_name [log_mode]] | |
@@ -341,7 +342,7 b' one of (note that the modes are given unquoted):' | |||||
341 | * [append:] well, that says it. |
|
342 | * [append:] well, that says it. | |
342 | * [rotate:] create rotating logs log_name.1~, log_name.2~, etc. |
|
343 | * [rotate:] create rotating logs log_name.1~, log_name.2~, etc. | |
343 |
|
344 | |||
344 |
The |
|
345 | The :magic:`logoff` and :magic:`logon` functions allow you to temporarily stop and | |
345 | resume logging to a file which had previously been started with |
|
346 | resume logging to a file which had previously been started with | |
346 | %logstart. They will fail (with an explanation) if you try to use them |
|
347 | %logstart. They will fail (with an explanation) if you try to use them | |
347 | before logging has been started. |
|
348 | before logging has been started. | |
@@ -362,7 +363,7 b' You can assign the result of a system command to a Python variable with the' | |||||
362 | syntax ``myfiles = !ls``. This gets machine readable output from stdout |
|
363 | syntax ``myfiles = !ls``. This gets machine readable output from stdout | |
363 | (e.g. without colours), and splits on newlines. To explicitly get this sort of |
|
364 | (e.g. without colours), and splits on newlines. To explicitly get this sort of | |
364 | output without assigning to a variable, use two exclamation marks (``!!ls``) or |
|
365 | output without assigning to a variable, use two exclamation marks (``!!ls``) or | |
365 |
the |
|
366 | the :magic:`sx` magic command. | |
366 |
|
367 | |||
367 | The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s`` |
|
368 | The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s`` | |
368 | returns a string delimited by newlines or spaces, respectively. ``myfiles.p`` |
|
369 | returns a string delimited by newlines or spaces, respectively. ``myfiles.p`` | |
@@ -392,7 +393,7 b' Note that `$$` is used to represent a literal `$`.' | |||||
392 | System command aliases |
|
393 | System command aliases | |
393 | ---------------------- |
|
394 | ---------------------- | |
394 |
|
395 | |||
395 |
The |
|
396 | The :magic:`alias` magic function allows you to define magic functions which are in fact | |
396 | system shell commands. These aliases can have parameters. |
|
397 | system shell commands. These aliases can have parameters. | |
397 |
|
398 | |||
398 | ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd' |
|
399 | ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd' | |
@@ -411,10 +412,10 b' replaced by a positional parameter to the call to %parts::' | |||||
411 | In [3]: parts A |
|
412 | In [3]: parts A | |
412 | ERROR: Alias <parts> requires 2 arguments, 1 given. |
|
413 | ERROR: Alias <parts> requires 2 arguments, 1 given. | |
413 |
|
414 | |||
414 |
If called with no parameters, |
|
415 | If called with no parameters, :magic:`alias` prints the table of currently | |
415 | defined aliases. |
|
416 | defined aliases. | |
416 |
|
417 | |||
417 |
The |
|
418 | The :magic:`rehashx` magic allows you to load your entire $PATH as | |
418 | ipython aliases. See its docstring for further details. |
|
419 | ipython aliases. See its docstring for further details. | |
419 |
|
420 | |||
420 |
|
421 | |||
@@ -440,7 +441,7 b' detailed tracebacks. Furthermore, both normal and verbose tracebacks can' | |||||
440 | be colored (if your terminal supports it) which makes them much easier |
|
441 | be colored (if your terminal supports it) which makes them much easier | |
441 | to parse visually. |
|
442 | to parse visually. | |
442 |
|
443 | |||
443 | See the magic xmode and colors functions for details. |
|
444 | See the magic :magic:`xmode` and :magic:`colors` functions for details. | |
444 |
|
445 | |||
445 | These features are basically a terminal version of Ka-Ping Yee's cgitb |
|
446 | These features are basically a terminal version of Ka-Ping Yee's cgitb | |
446 | module, now part of the standard Python library. |
|
447 | module, now part of the standard Python library. | |
@@ -454,8 +455,8 b' Input caching system' | |||||
454 | IPython offers numbered prompts (In/Out) with input and output caching |
|
455 | IPython offers numbered prompts (In/Out) with input and output caching | |
455 | (also referred to as 'input history'). All input is saved and can be |
|
456 | (also referred to as 'input history'). All input is saved and can be | |
456 | retrieved as variables (besides the usual arrow key recall), in |
|
457 | retrieved as variables (besides the usual arrow key recall), in | |
457 |
addition to the |
|
458 | addition to the :magic:`rep` magic command that brings a history entry | |
458 |
up for editing on the next |
|
459 | up for editing on the next command line. | |
459 |
|
460 | |||
460 | The following variables always exist: |
|
461 | The following variables always exist: | |
461 |
|
462 | |||
@@ -476,17 +477,17 b' characters. You can also manipulate them like regular variables (they' | |||||
476 | are strings), modify or exec them. |
|
477 | are strings), modify or exec them. | |
477 |
|
478 | |||
478 | You can also re-execute multiple lines of input easily by using the |
|
479 | You can also re-execute multiple lines of input easily by using the | |
479 |
magic |
|
480 | magic :magic:`rerun` or :magic:`macro` functions. The macro system also allows you to re-execute | |
480 | previous lines which include magic function calls (which require special |
|
481 | previous lines which include magic function calls (which require special | |
481 | processing). Type %macro? for more details on the macro system. |
|
482 | processing). Type %macro? for more details on the macro system. | |
482 |
|
483 | |||
483 |
A history function |
|
484 | A history function :magic:`history` allows you to see any part of your input | |
484 | history by printing a range of the _i variables. |
|
485 | history by printing a range of the _i variables. | |
485 |
|
486 | |||
486 | You can also search ('grep') through your history by typing |
|
487 | You can also search ('grep') through your history by typing | |
487 | ``%hist -g somestring``. This is handy for searching for URLs, IP addresses, |
|
488 | ``%hist -g somestring``. This is handy for searching for URLs, IP addresses, | |
488 | etc. You can bring history entries listed by '%hist -g' up for editing |
|
489 | etc. You can bring history entries listed by '%hist -g' up for editing | |
489 |
with the %recall command, or run them immediately with |
|
490 | with the %recall command, or run them immediately with :magic:`rerun`. | |
490 |
|
491 | |||
491 | .. _output_caching: |
|
492 | .. _output_caching: | |
492 |
|
493 | |||
@@ -522,15 +523,15 b' This system obviously can potentially put heavy memory demands on your' | |||||
522 | system, since it prevents Python's garbage collector from removing any |
|
523 | system, since it prevents Python's garbage collector from removing any | |
523 | previously computed results. You can control how many results are kept |
|
524 | previously computed results. You can control how many results are kept | |
524 | in memory with the configuration option ``InteractiveShell.cache_size``. |
|
525 | in memory with the configuration option ``InteractiveShell.cache_size``. | |
525 |
If you set it to 0, output caching is disabled. You can also use the |
|
526 | If you set it to 0, output caching is disabled. You can also use the :magic:`reset` | |
526 |
and |
|
527 | and :magic:`xdel` magics to clear large items from memory. | |
527 |
|
528 | |||
528 | Directory history |
|
529 | Directory history | |
529 | ----------------- |
|
530 | ----------------- | |
530 |
|
531 | |||
531 | Your history of visited directories is kept in the global list _dh, and |
|
532 | Your history of visited directories is kept in the global list _dh, and | |
532 |
the magic |
|
533 | the magic :magic:`cd` command can be used to go to any entry in that list. The | |
533 |
|
|
534 | :magic:`dhist` command allows you to view this history. Do ``cd -<TAB>`` to | |
534 | conveniently view the directory history. |
|
535 | conveniently view the directory history. | |
535 |
|
536 | |||
536 |
|
537 | |||
@@ -707,7 +708,7 b' allows you to step through code, set breakpoints, watch variables,' | |||||
707 | etc. IPython makes it very easy to start any script under the control |
|
708 | etc. IPython makes it very easy to start any script under the control | |
708 | of pdb, regardless of whether you have wrapped it into a 'main()' |
|
709 | of pdb, regardless of whether you have wrapped it into a 'main()' | |
709 | function or not. For this, simply type ``%run -d myscript`` at an |
|
710 | function or not. For this, simply type ``%run -d myscript`` at an | |
710 |
IPython prompt. See the |
|
711 | IPython prompt. See the :magic:`run` command's documentation for more details, including | |
711 | how to control where pdb will stop execution first. |
|
712 | how to control where pdb will stop execution first. | |
712 |
|
713 | |||
713 | For more information on the use of the pdb debugger, see :ref:`debugger-commands` |
|
714 | For more information on the use of the pdb debugger, see :ref:`debugger-commands` | |
@@ -724,9 +725,9 b" while your program is at this point 'dead', all the data is still" | |||||
724 | available and you can walk up and down the stack frame and understand |
|
725 | available and you can walk up and down the stack frame and understand | |
725 | the origin of the problem. |
|
726 | the origin of the problem. | |
726 |
|
727 | |||
727 |
You can use the |
|
728 | You can use the :magic:`debug` magic after an exception has occurred to start | |
728 | post-mortem debugging. IPython can also call debugger every time your code |
|
729 | post-mortem debugging. IPython can also call debugger every time your code | |
729 |
triggers an uncaught exception. This feature can be toggled with the |
|
730 | triggers an uncaught exception. This feature can be toggled with the :magic:`pdb` magic | |
730 | command, or you can start IPython with the ``--pdb`` option. |
|
731 | command, or you can start IPython with the ``--pdb`` option. | |
731 |
|
732 | |||
732 | For a post-mortem debugger in your programs outside IPython, |
|
733 | For a post-mortem debugger in your programs outside IPython, | |
@@ -805,7 +806,7 b' advantages of this are:' | |||||
805 | all of these things. |
|
806 | all of these things. | |
806 |
|
807 | |||
807 | For users, enabling GUI event loop integration is simple. You simple use the |
|
808 | For users, enabling GUI event loop integration is simple. You simple use the | |
808 |
|
|
809 | :magic:`gui` magic as follows:: | |
809 |
|
810 | |||
810 | %gui [GUINAME] |
|
811 | %gui [GUINAME] | |
811 |
|
812 | |||
@@ -904,7 +905,7 b' scientific computing, all with a syntax compatible with that of the popular' | |||||
904 | Matlab program. |
|
905 | Matlab program. | |
905 |
|
906 | |||
906 | To start IPython with matplotlib support, use the ``--matplotlib`` switch. If |
|
907 | To start IPython with matplotlib support, use the ``--matplotlib`` switch. If | |
907 |
IPython is already running, you can run the |
|
908 | IPython is already running, you can run the :magic:`matplotlib` magic. If no | |
908 | arguments are given, IPython will automatically detect your choice of |
|
909 | arguments are given, IPython will automatically detect your choice of | |
909 | matplotlib backend. You can also request a specific backend with |
|
910 | matplotlib backend. You can also request a specific backend with | |
910 | ``%matplotlib backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', |
|
911 | ``%matplotlib backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', |
@@ -60,7 +60,7 b' 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 |
|
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) | |
@@ -73,19 +73,19 b' line and cell mode::' | |||||
73 |
|
73 | |||
74 | The builtin magics include: |
|
74 | The builtin magics include: | |
75 |
|
75 | |||
76 |
- Functions that work with code: |
|
76 | - Functions that work with code: :magic`run`, :magic:`edit`, :magic:`save`, :magic:`macro`, | |
77 |
|
|
77 | :magic:`recall`, etc. | |
78 |
- Functions which affect the shell: |
|
78 | - Functions which affect the shell: :magic:`colors`, :magic:`xmode`, :magic:`autoindent`, | |
79 |
|
|
79 | :magic:`automagic`, etc. | |
80 |
- Other functions such as |
|
80 | - Other functions such as :magic:`reset`, :magic:`timeit`, :cellmagic:`writefile`, :magic:`load`, or | |
81 |
|
|
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 |
|
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 | |
@@ -95,12 +95,14 b' read its docstring. To see all the available magic functions, call' | |||||
95 |
|
95 | |||
96 | .. seealso:: |
|
96 | .. seealso:: | |
97 |
|
97 | |||
|
98 | :doc:`magics` | |||
|
99 | ||||
98 | `Cell magics`_ example notebook |
|
100 | `Cell magics`_ example notebook | |
99 |
|
101 | |||
100 | Running and Editing |
|
102 | Running and Editing | |
101 | ------------------- |
|
103 | ------------------- | |
102 |
|
104 | |||
103 |
The |
|
105 | The :magic:`run` magic command allows you to run any python script and load all of | |
104 | 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 | |
105 | 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 | |
106 | imported modules, which have to be specifically reloaded). IPython also |
|
108 | imported modules, which have to be specifically reloaded). IPython also | |
@@ -110,15 +112,15 b' includes :ref:`dreload <dreload>`, a recursive reload function.' | |||||
110 | 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 | |
111 | profiler (-p). |
|
113 | profiler (-p). | |
112 |
|
114 | |||
113 |
The |
|
115 | The :magic:`edit` command gives a reasonable approximation of multiline editing, | |
114 | 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 | |
115 | code you type in there as if it were typed interactively. |
|
117 | code you type in there as if it were typed interactively. | |
116 |
|
118 | |||
117 | Debugging |
|
119 | Debugging | |
118 | --------- |
|
120 | --------- | |
119 |
|
121 | |||
120 |
After an exception occurs, you can call |
|
122 | After an exception occurs, you can call :magic:`debug` to jump into the Python | |
121 |
debugger (pdb) and examine the problem. Alternatively, if you call |
|
123 | debugger (pdb) and examine the problem. Alternatively, if you call :magic:`pdb`, | |
122 | 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 | |
123 | 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 | |
124 | 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 | |
@@ -163,7 +165,7 b' You can capture the output into a Python list, e.g.: ``files = !ls``. To pass' | |||||
163 | 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 | |
164 | with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section |
|
166 | with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section | |
165 | <system_shell_access>` for more details. |
|
167 | <system_shell_access>` for more details. | |
166 |
|
168 | |||
167 | Define your own system aliases |
|
169 | Define your own system aliases | |
168 | ------------------------------ |
|
170 | ------------------------------ | |
169 |
|
171 | |||
@@ -171,7 +173,7 b" It's convenient to have aliases to the system commands you use most often." | |||||
171 | 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 | |
172 | 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 | |
173 | 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 | |
174 |
|
|
176 | :magic:`pushd`, :magic:`popd` and :magic:`dhist`) and via direct :magic:`cd`. The latter keeps a history of | |
175 | 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. | |
176 |
|
178 | |||
177 |
|
179 |
General Comments 0
You need to be logged in to leave comments.
Login now