##// END OF EJS Templates
Fix typos in docs
Zach Rottman -
Show More
@@ -1,99 +1,99 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.
9 and can be placed anywhere you'd normally import from.
10
10
11 Getting extensions
11 Getting extensions
12 ==================
12 ==================
13
13
14 A few important extensions are :ref:`bundled with IPython <bundled_extensions>`.
14 A few important extensions are :ref:`bundled with IPython <bundled_extensions>`.
15 Others can be found on the `extensions index
15 Others can be found on the `extensions index
16 <https://github.com/ipython/ipython/wiki/Extensions-Index>`_ on the wiki, and
16 <https://github.com/ipython/ipython/wiki/Extensions-Index>`_ on the wiki, and
17 the `Framework :: IPython tag <https://pypi.python.org/pypi?:action=browse&c=586>`_
17 the `Framework :: IPython tag <https://pypi.python.org/pypi?:action=browse&c=586>`_
18 on PyPI.
18 on PyPI.
19
19
20 Extensions on PyPI can be installed using ``pip``, like any other Python package.
20 Extensions on PyPI can be installed using ``pip``, like any other Python package.
21
21
22 Using extensions
22 Using extensions
23 ================
23 ================
24
24
25 To load an extension while IPython is running, use the ``%load_ext`` magic:
25 To load an extension while IPython is running, use the ``%load_ext`` magic:
26
26
27 .. sourcecode:: ipython
27 .. sourcecode:: ipython
28
28
29 In [1]: %load_ext myextension
29 In [1]: %load_ext myextension
30
30
31 To load it each time IPython starts, list it in your configuration file::
31 To load it each time IPython starts, list it in your configuration file::
32
32
33 c.InteractiveShellApp.extensions = [
33 c.InteractiveShellApp.extensions = [
34 'myextension'
34 'myextension'
35 ]
35 ]
36
36
37 Writing extensions
37 Writing extensions
38 ==================
38 ==================
39
39
40 An IPython extension is an importable Python module that has a couple of special
40 An IPython extension is an importable Python module that has a couple of special
41 functions to load and unload it. Here is a template::
41 functions to load and unload it. Here is a template::
42
42
43 # myextension.py
43 # myextension.py
44
44
45 def load_ipython_extension(ipython):
45 def load_ipython_extension(ipython):
46 # The `ipython` argument is the currently active `InteractiveShell`
46 # The `ipython` argument is the currently active `InteractiveShell`
47 # instance, which can be used in any way. This allows you to register
47 # instance, which can be used in any way. This allows you to register
48 # new magics or aliases, for example.
48 # new magics or aliases, for example.
49
49
50 def unload_ipython_extension(ipython):
50 def unload_ipython_extension(ipython):
51 # If you want your extension to be unloadable, put that logic here.
51 # If you want your extension to be unloadable, put that logic here.
52
52
53 This :func:`load_ipython_extension` function is called after your extension is
53 This :func:`load_ipython_extension` function is called after your extension is
54 imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell`
54 imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell`
55 instance is passed as the only argument. You can do anything you want with
55 instance is passed as the only argument. You can do anything you want with
56 IPython at that point.
56 IPython at that point.
57
57
58 :func:`load_ipython_extension` will not be called again if the user use
58 :func:`load_ipython_extension` will not be called again if the users use
59 `%load_extension`. The user have to explicitly ask the extension to be
59 `%load_extension`. The user has to explicitly ask the extension to be
60 reloaded (with `%reload_extension`). In case where the use ask the extension to
60 reloaded (with `%reload_extension`). In cases where the user asks the extension to
61 be reloaded, , the extension will be unloaded (with
61 be reloaded, the extension will be unloaded (with
62 `unload_ipython_extension`), and loaded again.
62 `unload_ipython_extension`), and loaded again.
63
63
64 Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.register_magic_function`,
64 Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.register_magic_function`,
65 :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and
65 :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and
66 :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).
66 :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading).
67
67
68 .. seealso::
68 .. seealso::
69
69
70 :ref:`defining_magics`
70 :ref:`defining_magics`
71
71
72 You can put your extension modules anywhere you want, as long as they can be
72 You can put your extension modules anywhere you want, as long as they can be
73 imported by Python's standard import mechanism.
73 imported by Python's standard import mechanism.
74
74
75 When your extension is ready for general use, please add it to the `extensions
75 When your extension is ready for general use, please add it to the `extensions
76 index <https://github.com/ipython/ipython/wiki/Extensions-Index>`_. We also
76 index <https://github.com/ipython/ipython/wiki/Extensions-Index>`_. We also
77 encourage you to upload it to PyPI and use the ``Framework :: IPython``
77 encourage you to upload it to PyPI and use the ``Framework :: IPython``
78 classifier, so that users can install it with standard packaging tools.
78 classifier, so that users can install it with standard packaging tools.
79
79
80 .. _bundled_extensions:
80 .. _bundled_extensions:
81
81
82 Extensions bundled with IPython
82 Extensions bundled with IPython
83 ===============================
83 ===============================
84
84
85 .. toctree::
85 .. toctree::
86 :maxdepth: 1
86 :maxdepth: 1
87
87
88 autoreload
88 autoreload
89 storemagic
89 storemagic
90
90
91 * ``octavemagic`` used to be bundled, but is now part of `oct2py <https://blink1073.github.io/oct2py/>`_.
91 * ``octavemagic`` used to be bundled, but is now part of `oct2py <https://blink1073.github.io/oct2py/>`_.
92 Use ``%load_ext oct2py.ipython`` to load it.
92 Use ``%load_ext oct2py.ipython`` to load it.
93 * ``rmagic`` is now part of `rpy2 <http://rpy.sourceforge.net/>`_. Use
93 * ``rmagic`` is now part of `rpy2 <http://rpy.sourceforge.net/>`_. Use
94 ``%load_ext rpy2.ipython`` to load it, and see :mod:`rpy2.ipython.rmagic` for
94 ``%load_ext rpy2.ipython`` to load it, and see :mod:`rpy2.ipython.rmagic` for
95 details of how to use it.
95 details of how to use it.
96 * ``cythonmagic`` used to be bundled, but is now part of `cython <https://github.com/cython/cython/>`_
96 * ``cythonmagic`` used to be bundled, but is now part of `cython <https://github.com/cython/cython/>`_
97 Use ``%load_ext Cython`` to load it.
97 Use ``%load_ext Cython`` to load it.
98 * ``sympyprinting`` used to be a bundled extension, but you should now use
98 * ``sympyprinting`` used to be a bundled extension, but you should now use
99 :func:`sympy.init_printing` instead.
99 :func:`sympy.init_printing` instead.
General Comments 0
You need to be logged in to leave comments. Login now