##// END OF EJS Templates
Update index.rst...
Doug Blank -
Show More
@@ -1,104 +1,103 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 ``.ipython/extensions/``.
10 ``.ipython/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 <https://github.com/ipython/ipython/wiki/Extensions-Index>`_ on the wiki, and
17 <https://github.com/ipython/ipython/wiki/Extensions-Index>`_ on the wiki, and
18 the `Framework :: IPython tag <https://pypi.python.org/pypi?:action=browse&c=586>`_
18 the `Framework :: IPython tag <https://pypi.python.org/pypi?:action=browse&c=586>`_
19 on PyPI.
19 on PyPI.
20
20
21 Extensions on PyPI can be installed using ``pip``, like any other Python package.
21 Extensions on PyPI can be installed using ``pip``, like any other Python package.
22 Other simple extensions can be installed with the ``%install_ext`` magic. The
22 Other simple extensions can be installed with the ``%install_ext`` magic. The
23 latter does no validation, so be careful using it on untrusted networks like
23 latter does no validation, so be careful using it on untrusted networks like
24 public wifi.
24 public wifi.
25
25
26 Using extensions
26 Using extensions
27 ================
27 ================
28
28
29 To load an extension while IPython is running, use the ``%load_ext`` magic:
29 To load an extension while IPython is running, use the ``%load_ext`` magic:
30
30
31 .. sourcecode:: ipython
31 .. sourcecode:: ipython
32
32
33 In [1]: %load_ext myextension
33 In [1]: %load_ext myextension
34
34
35 To load it each time IPython starts, list it in your configuration file::
35 To load it each time IPython starts, list it in your configuration file::
36
36
37 c.InteractiveShellApp.extensions = [
37 c.InteractiveShellApp.extensions = [
38 'myextension'
38 'myextension'
39 ]
39 ]
40
40
41 Writing extensions
41 Writing extensions
42 ==================
42 ==================
43
43
44 An IPython extension is an importable Python module that has a couple of special
44 An IPython extension is an importable Python module that has a couple of special
45 functions to load and unload it. Here is a template::
45 functions to load and unload it. Here is a template::
46
46
47 # myextension.py
47 # myextension.py
48
48
49 def load_ipython_extension(ipython):
49 def load_ipython_extension(ipython):
50 # The `ipython` argument is the currently active `InteractiveShell`
50 # The `ipython` argument is the currently active `InteractiveShell`
51 # instance, which can be used in any way. This allows you to register
51 # instance, which can be used in any way. This allows you to register
52 # new magics or aliases, for example.
52 # new magics or aliases, for example.
53
53
54 def unload_ipython_extension(ipython):
54 def unload_ipython_extension(ipython):
55 # If you want your extension to be unloadable, put that logic here.
55 # If you want your extension to be unloadable, put that logic here.
56
56
57 This :func:`load_ipython_extension` function is called after your extension is
57 This :func:`load_ipython_extension` function is called after your extension is
58 imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell`
58 imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell`
59 instance is passed as the only argument. You can do anything you want with
59 instance is passed as the only argument. You can do anything you want with
60 IPython at that point.
60 IPython at that point.
61
61
62 :func:`load_ipython_extension` will be called again if you load or reload
62 :func:`load_ipython_extension` will be called again if you load or reload
63 the extension again. It is up to the extension author to add code to manage
63 the extension again. It is up to the extension author to add code to manage
64 that.
64 that.
65
65
66 Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.register_magic_function`,
66 Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.register_magic_function`,
67 :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and
67 :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and
68 :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).
68 :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).
69
69
70 .. seealso::
70 .. seealso::
71
71
72 :ref:`defining_magics`
72 :ref:`defining_magics`
73
73
74 You can put your extension modules anywhere you want, as long as they can be
74 You can put your extension modules anywhere you want, as long as they can be
75 imported by Python's standard import mechanism. However, to make it easy to
75 imported by Python's standard import mechanism. However, to make it easy to
76 write extensions, you can also put your extensions in :file:`extensions/`
76 write extensions, you can also put your extensions in :file:`extensions/`
77 within the :ref:`IPython directory <ipythondir>`. This directory is
77 within the :ref:`IPython directory <ipythondir>`. This directory is
78 added to :data:`sys.path` automatically.
78 added to :data:`sys.path` automatically.
79
79
80 When your extension is ready for general use, please add it to the `extensions
80 When your extension is ready for general use, please add it to the `extensions
81 index <https://github.com/ipython/ipython/wiki/Extensions-Index>`_. We also
81 index <https://github.com/ipython/ipython/wiki/Extensions-Index>`_. We also
82 encourage you to upload it to PyPI and use the ``Framework :: IPython``
82 encourage you to upload it to PyPI and use the ``Framework :: IPython``
83 classifier, so that users can install it with standard packaging tools.
83 classifier, so that users can install it with standard packaging tools.
84
84
85 .. _bundled_extensions:
85 .. _bundled_extensions:
86
86
87 Extensions bundled with IPython
87 Extensions bundled with IPython
88 ===============================
88 ===============================
89
89
90 .. toctree::
90 .. toctree::
91 :maxdepth: 1
91 :maxdepth: 1
92
92
93 autoreload
93 autoreload
94 cythonmagic
95 storemagic
94 storemagic
96 sympyprinting
95 sympyprinting
97
96
98 * ``octavemagic`` used to be bundled, but is now part of `oct2py <http://blink1073.github.io/oct2py/docs/>`_.
97 * ``octavemagic`` used to be bundled, but is now part of `oct2py <http://blink1073.github.io/oct2py/docs/>`_.
99 Use ``%load_ext oct2py.ipython`` to load it.
98 Use ``%load_ext oct2py.ipython`` to load it.
100 * ``rmagic`` is now part of `rpy2 <http://rpy.sourceforge.net/>`_. Use
99 * ``rmagic`` is now part of `rpy2 <http://rpy.sourceforge.net/>`_. Use
101 ``%load_ext rpy2.ipython`` to load it, and see :mod:`rpy2.ipython.rmagic` for
100 ``%load_ext rpy2.ipython`` to load it, and see :mod:`rpy2.ipython.rmagic` for
102 details of how to use it.
101 details of how to use it.
103 * ``cythonmagic``used to be bundled, but is now part of `cython <https://github.com/cython/cython/>`_
102 * ``cythonmagic`` used to be bundled, but is now part of `cython <https://github.com/cython/cython/>`_
104 Use ``%load_ext Cython`` to load it.
103 Use ``%load_ext Cython`` to load it.
General Comments 0
You need to be logged in to leave comments. Login now