##// END OF EJS Templates
Merge pull request #3208 from benjaminfjones/patch-1...
Min RK -
r10259:4d090de0 merge
parent child Browse files
Show More
@@ -1,86 +1,86 b''
1 .. _extensions_overview:
1 .. _extensions_overview:
2
2
3 ==================
3 ==================
4 IPython extensions
4 IPython extensions
5 ==================
5 ==================
6
6
7 A level above configuration are IPython extensions, Python modules which modify
7 A level above configuration are IPython extensions, Python modules which modify
8 the behaviour of the shell. They are referred to by an importable module name,
8 the behaviour of the shell. They are referred to by an importable module name,
9 and can be placed anywhere you'd normally import from, or in
9 and can be placed anywhere you'd normally import from, or in
10 ``$IPYTHONDIR/extensions/``.
10 ``$IPYTHONDIR/extensions/``.
11
11
12 Getting extensions
12 Getting extensions
13 ==================
13 ==================
14
14
15 A few important extensions are :ref:`bundled with IPython <bundled_extensions>`.
15 A few important extensions are :ref:`bundled with IPython <bundled_extensions>`.
16 Others can be found on the `extensions index
16 Others can be found on the `extensions index
17 <http://wiki.ipython.org/Extensions_Index>`_ on the wiki, and installed with
17 <https://github.com/ipython/ipython/wiki/Extensions-Index>`_ on the wiki, and installed with
18 the ``%install_ext`` magic function.
18 the ``%install_ext`` magic function.
19
19
20 Using extensions
20 Using extensions
21 ================
21 ================
22
22
23 To load an extension while IPython is running, use the ``%load_ext`` magic:
23 To load an extension while IPython is running, use the ``%load_ext`` magic:
24
24
25 .. sourcecode:: ipython
25 .. sourcecode:: ipython
26
26
27 In [1]: %load_ext myextension
27 In [1]: %load_ext myextension
28
28
29 To load it each time IPython starts, list it in your configuration file::
29 To load it each time IPython starts, list it in your configuration file::
30
30
31 c.InteractiveShellApp.extensions = [
31 c.InteractiveShellApp.extensions = [
32 'myextension'
32 'myextension'
33 ]
33 ]
34
34
35 Writing extensions
35 Writing extensions
36 ==================
36 ==================
37
37
38 An IPython extension is an importable Python module that has a couple of special
38 An IPython extension is an importable Python module that has a couple of special
39 functions to load and unload it. Here is a template::
39 functions to load and unload it. Here is a template::
40
40
41 # myextension.py
41 # myextension.py
42
42
43 def load_ipython_extension(ipython):
43 def load_ipython_extension(ipython):
44 # The `ipython` argument is the currently active `InteractiveShell`
44 # The `ipython` argument is the currently active `InteractiveShell`
45 # instance, which can be used in any way. This allows you to register
45 # instance, which can be used in any way. This allows you to register
46 # new magics or aliases, for example.
46 # new magics or aliases, for example.
47
47
48 def unload_ipython_extension(ipython):
48 def unload_ipython_extension(ipython):
49 # If you want your extension to be unloadable, put that logic here.
49 # If you want your extension to be unloadable, put that logic here.
50
50
51 This :func:`load_ipython_extension` function is called after your extension is
51 This :func:`load_ipython_extension` function is called after your extension is
52 imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell`
52 imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell`
53 instance is passed as the only argument. You can do anything you want with
53 instance is passed as the only argument. You can do anything you want with
54 IPython at that point.
54 IPython at that point.
55
55
56 :func:`load_ipython_extension` will be called again if you load or reload
56 :func:`load_ipython_extension` will be called again if you load or reload
57 the extension again. It is up to the extension author to add code to manage
57 the extension again. It is up to the extension author to add code to manage
58 that.
58 that.
59
59
60 Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.define_magic`,
60 Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.define_magic`,
61 :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and
61 :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and
62 :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).
62 :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).
63
63
64 You can put your extension modules anywhere you want, as long as they can be
64 You can put your extension modules anywhere you want, as long as they can be
65 imported by Python's standard import mechanism. However, to make it easy to
65 imported by Python's standard import mechanism. However, to make it easy to
66 write extensions, you can also put your extensions in
66 write extensions, you can also put your extensions in
67 ``os.path.join(ip.ipython_dir, 'extensions')``. This directory is added to
67 ``os.path.join(ip.ipython_dir, 'extensions')``. This directory is added to
68 ``sys.path`` automatically.
68 ``sys.path`` automatically.
69
69
70 When your extension is ready for general use, please add it to the `extensions
70 When your extension is ready for general use, please add it to the `extensions
71 index <http://wiki.ipython.org/Extensions_Index>`_.
71 index <https://github.com/ipython/ipython/wiki/Extensions-Index>`_.
72
72
73 .. _bundled_extensions:
73 .. _bundled_extensions:
74
74
75 Extensions bundled with IPython
75 Extensions bundled with IPython
76 ===============================
76 ===============================
77
77
78 .. toctree::
78 .. toctree::
79 :maxdepth: 1
79 :maxdepth: 1
80
80
81 autoreload
81 autoreload
82 cythonmagic
82 cythonmagic
83 octavemagic
83 octavemagic
84 rmagic
84 rmagic
85 storemagic
85 storemagic
86 sympyprinting
86 sympyprinting
General Comments 0
You need to be logged in to leave comments. Login now