|
@@
-26,19
+26,6
b' files for each profile, and the files look like :file:`ipython_config.py` or'
|
|
26
|
which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
|
|
26
|
which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
|
|
27
|
resolves to :file:`C:\\Users\\{YourUserName}` in most instances.
|
|
27
|
resolves to :file:`C:\\Users\\{YourUserName}` in most instances.
|
|
28
|
|
|
28
|
|
|
29
|
|
|
|
|
|
30
|
Eventloop integration
|
|
|
|
|
31
|
---------------------
|
|
|
|
|
32
|
|
|
|
|
|
33
|
Previously IPython had command line options for controlling GUI event loop
|
|
|
|
|
34
|
integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
|
|
|
|
|
35
|
version 0.11, these have been removed. Please see the new ``%gui``
|
|
|
|
|
36
|
magic command or :ref:`this section <gui_support>` for details on the new
|
|
|
|
|
37
|
interface, or specify the gui at the commandline::
|
|
|
|
|
38
|
|
|
|
|
|
39
|
$ ipython --gui=qt
|
|
|
|
|
40
|
|
|
|
|
|
41
|
|
|
|
|
|
42
|
Command-line Options
|
|
29
|
Command-line Options
|
|
43
|
--------------------
|
|
30
|
--------------------
|
|
44
|
|
|
31
|
|
|
@@
-131,11
+118,9
b' Note that cell magics *always* require an explicit ``%%`` prefix, automagic'
|
|
131
|
calling only works for line magics.
|
|
118
|
calling only works for line magics.
|
|
132
|
|
|
119
|
|
|
133
|
The automagic system has the lowest possible precedence in name searches, so
|
|
120
|
The automagic system has the lowest possible precedence in name searches, so
|
|
134
|
defining an identifier with the same name as an existing magic function will
|
|
121
|
you can freely use variables with the same names as magic commands. If a magic
|
|
135
|
shadow it for automagic use. You can still access the shadowed magic function
|
|
122
|
command is 'shadowed' by a variable, you will need the explicit ``%`` prefix to
|
|
136
|
by explicitly using the ``%`` character at the beginning of the line.
|
|
123
|
use it:
|
|
137
|
|
|
|
|
|
138
|
An example (with automagic on) should clarify all this:
|
|
|
|
|
139
|
|
|
124
|
|
|
140
|
.. sourcecode:: ipython
|
|
125
|
.. sourcecode:: ipython
|
|
141
|
|
|
126
|
|
|
@@
-378,25
+363,16
b' Search command history'
|
|
378
|
IPython provides two ways for searching through previous input and thus
|
|
363
|
IPython provides two ways for searching through previous input and thus
|
|
379
|
reduce the need for repetitive typing:
|
|
364
|
reduce the need for repetitive typing:
|
|
380
|
|
|
365
|
|
|
381
|
1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
|
|
366
|
1. Start typing, and then use the up and down arrow keys (or :kbd:`Ctrl-p`
|
|
382
|
(next,down) to search through only the history items that match
|
|
367
|
and :kbd:`Ctrl-n`) to search through only the history items that match
|
|
383
|
what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
|
|
368
|
what you've typed so far.
|
|
384
|
prompt, they just behave like normal arrow keys.
|
|
369
|
2. Hit :kbd:`Ctrl-r`: to open a search prompt. Begin typing and the system
|
|
385
|
2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
|
|
|
|
|
386
|
searches your history for lines that contain what you've typed so
|
|
370
|
searches your history for lines that contain what you've typed so
|
|
387
|
far, completing as much as it can.
|
|
371
|
far, completing as much as it can.
|
|
388
|
|
|
372
|
|
|
389
|
|
|
|
|
|
390
|
Persistent command history across sessions
|
|
|
|
|
391
|
++++++++++++++++++++++++++++++++++++++++++
|
|
|
|
|
392
|
|
|
|
|
|
393
|
IPython will save your input history when it leaves and reload it next
|
|
373
|
IPython will save your input history when it leaves and reload it next
|
|
394
|
time you restart it. By default, the history file is named
|
|
374
|
time you restart it. By default, the history file is named
|
|
395
|
$IPYTHONDIR/profile_<name>/history.sqlite. This allows you to keep
|
|
375
|
:file:`.ipython/profile_{name}/history.sqlite`.
|
|
396
|
separate histories related to various tasks: commands related to
|
|
|
|
|
397
|
numerical work will not be clobbered by a system shell history, for
|
|
|
|
|
398
|
example.
|
|
|
|
|
399
|
|
|
|
|
|
400
|
|
|
376
|
|
|
401
|
Autoindent
|
|
377
|
Autoindent
|
|
402
|
++++++++++
|
|
378
|
++++++++++
|
|
@@
-405,7
+381,7
b" IPython can recognize lines ending in ':' and indent the next line,"
|
|
405
|
while also un-indenting automatically after 'raise' or 'return'.
|
|
381
|
while also un-indenting automatically after 'raise' or 'return'.
|
|
406
|
|
|
382
|
|
|
407
|
This feature uses the readline library, so it will honor your
|
|
383
|
This feature uses the readline library, so it will honor your
|
|
408
|
:file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
|
|
384
|
:file:`~/.inputrc` configuration (or whatever file your :envvar:`INPUTRC` environment variable points
|
|
409
|
to). Adding the following lines to your :file:`.inputrc` file can make
|
|
385
|
to). Adding the following lines to your :file:`.inputrc` file can make
|
|
410
|
indenting/unindenting more convenient (M-i indents, M-u unindents)::
|
|
386
|
indenting/unindenting more convenient (M-i indents, M-u unindents)::
|
|
411
|
|
|
387
|
|
|
@@
-441,20
+417,15
b' Customizing readline behavior'
|
|
441
|
|
|
417
|
|
|
442
|
All these features are based on the GNU readline library, which has an
|
|
418
|
All these features are based on the GNU readline library, which has an
|
|
443
|
extremely customizable interface. Normally, readline is configured via a
|
|
419
|
extremely customizable interface. Normally, readline is configured via a
|
|
444
|
file which defines the behavior of the library; the details of the
|
|
420
|
:file:`.inputrc` file. IPython respects this, and you can also customise readline
|
|
445
|
syntax for this can be found in the readline documentation available
|
|
421
|
by setting the following :doc:`configuration </config/intro>` options:
|
|
446
|
with your system or on the Internet. IPython doesn't read this file (if
|
|
422
|
|
|
447
|
it exists) directly, but it does support passing to readline valid
|
|
423
|
* ``InteractiveShell.readline_parse_and_bind``: this holds a list of strings to be executed
|
|
448
|
options via a simple interface. In brief, you can customize readline by
|
|
|
|
|
449
|
setting the following options in your configuration file (note
|
|
|
|
|
450
|
that these options can not be specified at the command line):
|
|
|
|
|
451
|
|
|
|
|
|
452
|
* **readline_parse_and_bind**: this holds a list of strings to be executed
|
|
|
|
|
453
|
via a readline.parse_and_bind() command. The syntax for valid commands
|
|
424
|
via a readline.parse_and_bind() command. The syntax for valid commands
|
|
454
|
of this kind can be found by reading the documentation for the GNU
|
|
425
|
of this kind can be found by reading the documentation for the GNU
|
|
455
|
readline library, as these commands are of the kind which readline
|
|
426
|
readline library, as these commands are of the kind which readline
|
|
456
|
accepts in its configuration file.
|
|
427
|
accepts in its configuration file.
|
|
457
|
* **readline_remove_delims**: a string of characters to be removed
|
|
428
|
* ``InteractiveShell.readline_remove_delims``: a string of characters to be removed
|
|
458
|
from the default word-delimiters list used by readline, so that
|
|
429
|
from the default word-delimiters list used by readline, so that
|
|
459
|
completions may be performed on strings which contain them. Do not
|
|
430
|
completions may be performed on strings which contain them. Do not
|
|
460
|
change the default value unless you know what you're doing.
|
|
431
|
change the default value unless you know what you're doing.
|
|
@@
-595,7
+566,7
b' detailed tracebacks. Furthermore, both normal and verbose tracebacks can'
|
|
595
|
be colored (if your terminal supports it) which makes them much easier
|
|
566
|
be colored (if your terminal supports it) which makes them much easier
|
|
596
|
to parse visually.
|
|
567
|
to parse visually.
|
|
597
|
|
|
568
|
|
|
598
|
See the magic xmode and colors functions for details (just type %magic).
|
|
569
|
See the magic xmode and colors functions for details.
|
|
599
|
|
|
570
|
|
|
600
|
These features are basically a terminal version of Ka-Ping Yee's cgitb
|
|
571
|
These features are basically a terminal version of Ka-Ping Yee's cgitb
|
|
601
|
module, now part of the standard Python library.
|
|
572
|
module, now part of the standard Python library.
|
|
@@
-612,7
+583,7
b' retrieved as variables (besides the usual arrow key recall), in'
|
|
612
|
addition to the %rep magic command that brings a history entry
|
|
583
|
addition to the %rep magic command that brings a history entry
|
|
613
|
up for editing on the next command line.
|
|
584
|
up for editing on the next command line.
|
|
614
|
|
|
585
|
|
|
615
|
The following GLOBAL variables always exist (so don't overwrite them!):
|
|
586
|
The following variables always exist:
|
|
616
|
|
|
587
|
|
|
617
|
* _i, _ii, _iii: store previous, next previous and next-next previous inputs.
|
|
588
|
* _i, _ii, _iii: store previous, next previous and next-next previous inputs.
|
|
618
|
* In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
|
|
589
|
* In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
|
|
@@
-622,14
+593,13
b" The following GLOBAL variables always exist (so don't overwrite them!):"
|
|
622
|
Additionally, global variables named _i<n> are dynamically created (<n>
|
|
593
|
Additionally, global variables named _i<n> are dynamically created (<n>
|
|
623
|
being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
|
|
594
|
being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
|
|
624
|
|
|
595
|
|
|
625
|
For example, what you typed at prompt 14 is available as _i14, _ih[14]
|
|
596
|
For example, what you typed at prompt 14 is available as ``_i14``, ``_ih[14]``
|
|
626
|
and In[14].
|
|
597
|
and ``In[14]``.
|
|
627
|
|
|
598
|
|
|
628
|
This allows you to easily cut and paste multi line interactive prompts
|
|
599
|
This allows you to easily cut and paste multi line interactive prompts
|
|
629
|
by printing them out: they print like a clean string, without prompt
|
|
600
|
by printing them out: they print like a clean string, without prompt
|
|
630
|
characters. You can also manipulate them like regular variables (they
|
|
601
|
characters. You can also manipulate them like regular variables (they
|
|
631
|
are strings), modify or exec them (typing ``exec _i9`` will re-execute the
|
|
602
|
are strings), modify or exec them.
|
|
632
|
contents of input prompt 9.
|
|
|
|
|
633
|
|
|
603
|
|
|
634
|
You can also re-execute multiple lines of input easily by using the
|
|
604
|
You can also re-execute multiple lines of input easily by using the
|
|
635
|
magic %rerun or %macro functions. The macro system also allows you to re-execute
|
|
605
|
magic %rerun or %macro functions. The macro system also allows you to re-execute
|
|
@@
-655,9
+625,9
b' result (NOT assignments, for example) are cached. If you are familiar'
|
|
655
|
with Mathematica, IPython's _ variables behave exactly like
|
|
625
|
with Mathematica, IPython's _ variables behave exactly like
|
|
656
|
Mathematica's % variables.
|
|
626
|
Mathematica's % variables.
|
|
657
|
|
|
627
|
|
|
658
|
The following GLOBAL variables always exist (so don't overwrite them!):
|
|
628
|
The following variables always exist:
|
|
659
|
|
|
629
|
|
|
660
|
* [_] (a single underscore) : stores previous output, like Python's
|
|
630
|
* [_] (a single underscore): stores previous output, like Python's
|
|
661
|
default interpreter.
|
|
631
|
default interpreter.
|
|
662
|
* [__] (two underscores): next previous.
|
|
632
|
* [__] (two underscores): next previous.
|
|
663
|
* [___] (three underscores): next-next previous.
|
|
633
|
* [___] (three underscores): next-next previous.
|
|
@@
-665,22
+635,21
b" The following GLOBAL variables always exist (so don't overwrite them!):"
|
|
665
|
Additionally, global variables named _<n> are dynamically created (<n>
|
|
635
|
Additionally, global variables named _<n> are dynamically created (<n>
|
|
666
|
being the prompt counter), such that the result of output <n> is always
|
|
636
|
being the prompt counter), such that the result of output <n> is always
|
|
667
|
available as _<n> (don't use the angle brackets, just the number, e.g.
|
|
637
|
available as _<n> (don't use the angle brackets, just the number, e.g.
|
|
668
|
_21).
|
|
638
|
``_21``).
|
|
669
|
|
|
639
|
|
|
670
|
These variables are also stored in a global dictionary (not a
|
|
640
|
These variables are also stored in a global dictionary (not a
|
|
671
|
list, since it only has entries for lines which returned a result)
|
|
641
|
list, since it only has entries for lines which returned a result)
|
|
672
|
available under the names _oh and Out (similar to _ih and In). So the
|
|
642
|
available under the names _oh and Out (similar to _ih and In). So the
|
|
673
|
output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
|
|
643
|
output from line 12 can be obtained as ``_12``, ``Out[12]`` or ``_oh[12]``. If you
|
|
674
|
accidentally overwrite the Out variable you can recover it by typing
|
|
644
|
accidentally overwrite the Out variable you can recover it by typing
|
|
675
|
'Out=_oh' at the prompt.
|
|
645
|
``Out=_oh`` at the prompt.
|
|
676
|
|
|
646
|
|
|
677
|
This system obviously can potentially put heavy memory demands on your
|
|
647
|
This system obviously can potentially put heavy memory demands on your
|
|
678
|
system, since it prevents Python's garbage collector from removing any
|
|
648
|
system, since it prevents Python's garbage collector from removing any
|
|
679
|
previously computed results. You can control how many results are kept
|
|
649
|
previously computed results. You can control how many results are kept
|
|
680
|
in memory with the option (at the command line or in your configuration
|
|
650
|
in memory with the configuration option ``InteractiveShell.cache_size``.
|
|
681
|
file) cache_size. If you set it to 0, the whole system is completely
|
|
651
|
If you set it to 0, output caching is disabled. You can also use the ``%reset``
|
|
682
|
disabled and the prompts revert to the classic '>>>' of normal Python.
|
|
652
|
and ``%xdel`` magics to clear large items from memory.
|
|
683
|
|
|
|
|
|
684
|
|
|
653
|
|
|
685
|
Directory history
|
|
654
|
Directory history
|
|
686
|
-----------------
|
|
655
|
-----------------
|
|
@@
-697,16
+666,17
b' Automatic parentheses and quotes'
|
|
697
|
These features were adapted from Nathan Gray's LazyPython. They are
|
|
666
|
These features were adapted from Nathan Gray's LazyPython. They are
|
|
698
|
meant to allow less typing for common situations.
|
|
667
|
meant to allow less typing for common situations.
|
|
699
|
|
|
668
|
|
|
700
|
|
|
|
|
|
701
|
Automatic parentheses
|
|
|
|
|
702
|
+++++++++++++++++++++
|
|
|
|
|
703
|
|
|
|
|
|
704
|
Callable objects (i.e. functions, methods, etc) can be invoked like this
|
|
669
|
Callable objects (i.e. functions, methods, etc) can be invoked like this
|
|
705
|
(notice the commas between the arguments)::
|
|
670
|
(notice the commas between the arguments)::
|
|
706
|
|
|
671
|
|
|
707
|
In [1]: callable_ob arg1, arg2, arg3
|
|
672
|
In [1]: callable_ob arg1, arg2, arg3
|
|
708
|
------> callable_ob(arg1, arg2, arg3)
|
|
673
|
------> callable_ob(arg1, arg2, arg3)
|
|
709
|
|
|
674
|
|
|
|
|
|
675
|
.. note::
|
|
|
|
|
676
|
This feature is disabled by default. To enable it, use the ``%autocall``
|
|
|
|
|
677
|
magic command. The commands below with special prefixes will always work,
|
|
|
|
|
678
|
however.
|
|
|
|
|
679
|
|
|
710
|
You can force automatic parentheses by using '/' as the first character
|
|
680
|
You can force automatic parentheses by using '/' as the first character
|
|
711
|
of a line. For example::
|
|
681
|
of a line. For example::
|
|
712
|
|
|
682
|
|
|
@@
-730,17
+700,10
b' but this will work::'
|
|
730
|
Out[5]: [(1, 4), (2, 5), (3, 6)]
|
|
700
|
Out[5]: [(1, 4), (2, 5), (3, 6)]
|
|
731
|
|
|
701
|
|
|
732
|
IPython tells you that it has altered your command line by displaying
|
|
702
|
IPython tells you that it has altered your command line by displaying
|
|
733
|
the new command line preceded by ->. e.g.::
|
|
703
|
the new command line preceded by ``--->``.
|
|
734
|
|
|
|
|
|
735
|
In [6]: callable list
|
|
|
|
|
736
|
------> callable(list)
|
|
|
|
|
737
|
|
|
704
|
|
|
738
|
|
|
705
|
You can force automatic quoting of a function's arguments by using ``,``
|
|
739
|
Automatic quoting
|
|
706
|
or ``;`` as the first character of a line. For example::
|
|
740
|
+++++++++++++++++
|
|
|
|
|
741
|
|
|
|
|
|
742
|
You can force automatic quoting of a function's arguments by using ','
|
|
|
|
|
743
|
or ';' as the first character of a line. For example::
|
|
|
|
|
744
|
|
|
707
|
|
|
745
|
In [1]: ,my_function /home/me # becomes my_function("/home/me")
|
|
708
|
In [1]: ,my_function /home/me # becomes my_function("/home/me")
|
|
746
|
|
|
709
|
|
|
@@
-770,7
+733,7
b' environment anytime you start Python::'
|
|
770
|
raise SystemExit
|
|
733
|
raise SystemExit
|
|
771
|
|
|
734
|
|
|
772
|
The ``raise SystemExit`` is needed to exit Python when
|
|
735
|
The ``raise SystemExit`` is needed to exit Python when
|
|
773
|
it finishes, otherwise you'll be back at the normal Python '>>>'
|
|
736
|
it finishes, otherwise you'll be back at the normal Python ``>>>``
|
|
774
|
prompt.
|
|
737
|
prompt.
|
|
775
|
|
|
738
|
|
|
776
|
This is probably useful to developers who manage multiple Python
|
|
739
|
This is probably useful to developers who manage multiple Python
|
|
@@
-788,12
+751,12
b' You can start a regular IPython session with'
|
|
788
|
.. sourcecode:: python
|
|
751
|
.. sourcecode:: python
|
|
789
|
|
|
752
|
|
|
790
|
import IPython
|
|
753
|
import IPython
|
|
791
|
IPython.start_ipython()
|
|
754
|
IPython.start_ipython(argv=[])
|
|
792
|
|
|
755
|
|
|
793
|
at any point in your program. This will load IPython configuration,
|
|
756
|
at any point in your program. This will load IPython configuration,
|
|
794
|
startup files, and everything, just as if it were a normal IPython session.
|
|
757
|
startup files, and everything, just as if it were a normal IPython session.
|
|
795
|
In addition to this,
|
|
758
|
|
|
796
|
it is possible to embed an IPython instance inside your own Python programs.
|
|
759
|
It is also possible to embed an IPython shell in a namespace in your Python code.
|
|
797
|
This allows you to evaluate dynamically the state of your code,
|
|
760
|
This allows you to evaluate dynamically the state of your code,
|
|
798
|
operate with your variables, analyze them, etc. Note however that
|
|
761
|
operate with your variables, analyze them, etc. Note however that
|
|
799
|
any changes you make to values while in the shell do not propagate back
|
|
762
|
any changes you make to values while in the shell do not propagate back
|
|
@@
-826,13
+789,10
b' your Python programs for this to work (detailed examples follow later)::'
|
|
826
|
|
|
789
|
|
|
827
|
embed() # this call anywhere in your program will start IPython
|
|
790
|
embed() # this call anywhere in your program will start IPython
|
|
828
|
|
|
791
|
|
|
829
|
.. note::
|
|
792
|
You can also embed an IPython *kernel*, for use with qtconsole, etc. via
|
|
830
|
|
|
793
|
``IPython.embed_kernel()``. This should function work the same way, but you can
|
|
831
|
As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
|
|
794
|
connect an external frontend (``ipython qtconsole`` or ``ipython console``),
|
|
832
|
etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
|
|
795
|
rather than interacting with it in the terminal.
|
|
833
|
It should function just the same as regular embed, but you connect
|
|
|
|
|
834
|
an external frontend rather than IPython starting up in the local
|
|
|
|
|
835
|
terminal.
|
|
|
|
|
836
|
|
|
796
|
|
|
837
|
You can run embedded instances even in code which is itself being run at
|
|
797
|
You can run embedded instances even in code which is itself being run at
|
|
838
|
the IPython interactive prompt with '%run <filename>'. Since it's easy
|
|
798
|
the IPython interactive prompt with '%run <filename>'. Since it's easy
|
|
@@
-872,45
+832,31
b' pdb, the Python debugger, is a powerful interactive debugger which'
|
|
872
|
allows you to step through code, set breakpoints, watch variables,
|
|
832
|
allows you to step through code, set breakpoints, watch variables,
|
|
873
|
etc. IPython makes it very easy to start any script under the control
|
|
833
|
etc. IPython makes it very easy to start any script under the control
|
|
874
|
of pdb, regardless of whether you have wrapped it into a 'main()'
|
|
834
|
of pdb, regardless of whether you have wrapped it into a 'main()'
|
|
875
|
function or not. For this, simply type '%run -d myscript' at an
|
|
835
|
function or not. For this, simply type ``%run -d myscript`` at an
|
|
876
|
IPython prompt. See the %run command's documentation (via '%run?' or
|
|
836
|
IPython prompt. See the %run command's documentation for more details, including
|
|
877
|
in Sec. magic_ for more details, including how to control where pdb
|
|
837
|
how to control where pdb will stop execution first.
|
|
878
|
will stop execution first.
|
|
|
|
|
879
|
|
|
|
|
|
880
|
For more information on the use of the pdb debugger, read the included
|
|
|
|
|
881
|
pdb.doc file (part of the standard Python distribution). On a stock
|
|
|
|
|
882
|
Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
|
|
|
|
|
883
|
easiest way to read it is by using the help() function of the pdb module
|
|
|
|
|
884
|
as follows (in an IPython prompt)::
|
|
|
|
|
885
|
|
|
838
|
|
|
886
|
In [1]: import pdb
|
|
839
|
For more information on the use of the pdb debugger, see :ref:`debugger-commands`
|
|
887
|
In [2]: pdb.help()
|
|
840
|
in the Python documentation.
|
|
888
|
|
|
841
|
|
|
889
|
This will load the pdb.doc document in a file viewer for you automatically.
|
|
|
|
|
890
|
|
|
842
|
|
|
|
|
|
843
|
Post-mortem debugging
|
|
|
|
|
844
|
---------------------
|
|
891
|
|
|
845
|
|
|
892
|
Automatic invocation of pdb on exceptions
|
|
846
|
Going into a debugger when an exception occurs can be
|
|
893
|
-----------------------------------------
|
|
|
|
|
894
|
|
|
|
|
|
895
|
IPython, if started with the ``--pdb`` option (or if the option is set in
|
|
|
|
|
896
|
your config file) can call the Python pdb debugger every time your code
|
|
|
|
|
897
|
triggers an uncaught exception. This feature
|
|
|
|
|
898
|
can also be toggled at any time with the %pdb magic command. This can be
|
|
|
|
|
899
|
extremely useful in order to find the origin of subtle bugs, because pdb
|
|
847
|
extremely useful in order to find the origin of subtle bugs, because pdb
|
|
900
|
opens up at the point in your code which triggered the exception, and
|
|
848
|
opens up at the point in your code which triggered the exception, and
|
|
901
|
while your program is at this point 'dead', all the data is still
|
|
849
|
while your program is at this point 'dead', all the data is still
|
|
902
|
available and you can walk up and down the stack frame and understand
|
|
850
|
available and you can walk up and down the stack frame and understand
|
|
903
|
the origin of the problem.
|
|
851
|
the origin of the problem.
|
|
904
|
|
|
852
|
|
|
905
|
Furthermore, you can use these debugging facilities both with the
|
|
853
|
You can use the ``%debug`` magic after an exception has occurred to start
|
|
906
|
embedded IPython mode and without IPython at all. For an embedded shell
|
|
854
|
post-mortem debugging. IPython can also call debugger every time your code
|
|
907
|
(see sec. Embedding_), simply call the constructor with
|
|
855
|
triggers an uncaught exception. This feature can be toggled with the %pdb magic
|
|
908
|
``--pdb`` in the argument string and pdb will automatically be called if an
|
|
856
|
command, or you can start IPython with the ``--pdb`` option.
|
|
909
|
uncaught exception is triggered by your code.
|
|
|
|
|
910
|
|
|
857
|
|
|
911
|
For stand-alone use of the feature in your programs which do not use
|
|
858
|
For a post-mortem debugger in your programs outside IPython,
|
|
912
|
IPython at all, put the following lines toward the top of your 'main'
|
|
859
|
put the following lines toward the top of your 'main' routine::
|
|
913
|
routine::
|
|
|
|
|
914
|
|
|
860
|
|
|
915
|
import sys
|
|
861
|
import sys
|
|
916
|
from IPython.core import ultratb
|
|
862
|
from IPython.core import ultratb
|
|
@@
-925,25
+871,10
b' options which can be set in IPython with ``--colors`` and ``--xmode``.'
|
|
925
|
This will give any of your programs detailed, colored tracebacks with
|
|
871
|
This will give any of your programs detailed, colored tracebacks with
|
|
926
|
automatic invocation of pdb.
|
|
872
|
automatic invocation of pdb.
|
|
927
|
|
|
873
|
|
|
928
|
|
|
|
|
|
929
|
Extensions for syntax processing
|
|
|
|
|
930
|
================================
|
|
|
|
|
931
|
|
|
|
|
|
932
|
This isn't for the faint of heart, because the potential for breaking
|
|
|
|
|
933
|
things is quite high. But it can be a very powerful and useful feature.
|
|
|
|
|
934
|
In a nutshell, you can redefine the way IPython processes the user input
|
|
|
|
|
935
|
line to accept new, special extensions to the syntax without needing to
|
|
|
|
|
936
|
change any of IPython's own code.
|
|
|
|
|
937
|
|
|
|
|
|
938
|
In the IPython/extensions directory you will find some examples
|
|
|
|
|
939
|
supplied, which we will briefly describe now. These can be used 'as is'
|
|
|
|
|
940
|
(and both provide very useful functionality), or you can use them as a
|
|
|
|
|
941
|
starting point for writing your own extensions.
|
|
|
|
|
942
|
|
|
|
|
|
943
|
.. _pasting_with_prompts:
|
|
874
|
.. _pasting_with_prompts:
|
|
944
|
|
|
875
|
|
|
945
|
Pasting of code starting with Python or IPython prompts
|
|
876
|
Pasting of code starting with Python or IPython prompts
|
|
946
|
-------------------------------------------------------
|
|
877
|
=======================================================
|
|
947
|
|
|
878
|
|
|
948
|
IPython is smart enough to filter out input prompts, be they plain Python ones
|
|
879
|
IPython is smart enough to filter out input prompts, be they plain Python ones
|
|
949
|
(``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``). You can
|
|
880
|
(``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``). You can
|
|
@@
-1012,6
+943,11
b' object, do::'
|
|
1012
|
|
|
943
|
|
|
1013
|
%gui wx
|
|
944
|
%gui wx
|
|
1014
|
|
|
945
|
|
|
|
|
|
946
|
You can also start IPython with an event loop set up using the :option:`--gui`
|
|
|
|
|
947
|
flag::
|
|
|
|
|
948
|
|
|
|
|
|
949
|
$ ipython --gui=qt
|
|
|
|
|
950
|
|
|
1015
|
For information on IPython's matplotlib_ integration (and the ``matplotlib``
|
|
951
|
For information on IPython's matplotlib_ integration (and the ``matplotlib``
|
|
1016
|
mode) see :ref:`this section <matplotlib_support>`.
|
|
952
|
mode) see :ref:`this section <matplotlib_support>`.
|
|
1017
|
|
|
953
|
|
|
@@
-1135,29
+1071,23
b' demo::'
|
|
1135
|
mydemo = Demo('myscript.py')
|
|
1071
|
mydemo = Demo('myscript.py')
|
|
1136
|
|
|
1072
|
|
|
1137
|
This creates the mydemo object, whose blocks you run one at a time by
|
|
1073
|
This creates the mydemo object, whose blocks you run one at a time by
|
|
1138
|
simply calling the object with no arguments. If you have autocall active
|
|
1074
|
simply calling the object with no arguments. Then call it to run each step
|
|
1139
|
in IPython (the default), all you need to do is type::
|
|
1075
|
of the demo::
|
|
1140
|
|
|
1076
|
|
|
1141
|
mydemo
|
|
1077
|
mydemo()
|
|
1142
|
|
|
1078
|
|
|
1143
|
and IPython will call it, executing each block. Demo objects can be
|
|
1079
|
Demo objects can be
|
|
1144
|
restarted, you can move forward or back skipping blocks, re-execute the
|
|
1080
|
restarted, you can move forward or back skipping blocks, re-execute the
|
|
1145
|
last block, etc. Simply use the Tab key on a demo object to see its
|
|
1081
|
last block, etc. See the :mod:`IPython.lib.demo` module and the
|
|
1146
|
methods, and call '?' on them to see their docstrings for more usage
|
|
1082
|
:class:`~IPython.lib.demo.Demo` class for details.
|
|
1147
|
details. In addition, the demo module itself contains a comprehensive
|
|
|
|
|
1148
|
docstring, which you can access via::
|
|
|
|
|
1149
|
|
|
|
|
|
1150
|
from IPython.lib import demo
|
|
|
|
|
1151
|
|
|
|
|
|
1152
|
demo?
|
|
|
|
|
1153
|
|
|
1083
|
|
|
1154
|
Limitations: It is important to note that these demos are limited to
|
|
1084
|
Limitations: These demos are limited to
|
|
1155
|
fairly simple uses. In particular, you cannot break up sections within
|
|
1085
|
fairly simple uses. In particular, you cannot break up sections within
|
|
1156
|
indented code (loops, if statements, function definitions, etc.)
|
|
1086
|
indented code (loops, if statements, function definitions, etc.)
|
|
1157
|
Supporting something like this would basically require tracking the
|
|
1087
|
Supporting something like this would basically require tracking the
|
|
1158
|
internal execution state of the Python interpreter, so only top-level
|
|
1088
|
internal execution state of the Python interpreter, so only top-level
|
|
1159
|
divisions are allowed. If you want to be able to open an IPython
|
|
1089
|
divisions are allowed. If you want to be able to open an IPython
|
|
1160
|
instance at an arbitrary point in a program, you can use IPython's
|
|
1090
|
instance at an arbitrary point in a program, you can use IPython's
|
|
1161
|
embedding facilities, see :func:`IPython.embed` for details.
|
|
1091
|
:ref:`embedding facilities <Embedding>`.
|
|
1162
|
|
|
1092
|
|
|
1163
|
.. include:: ../links.txt
|
|
1093
|
.. include:: ../links.txt
|