##// END OF EJS Templates
add whatsnew and uppercase C in load_ext...
Matthias Bussonnier -
Show More
@@ -0,0 +1,1 b''
1 * The ``%cython`` magic, is now part of the Cython module. Use `%load_ext Cython` with a version of Cython >= 0.21 to have acces to the magic now.
@@ -1,41 +1,41 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 The cython magic has been integrated into Cython itself,
3 The cython magic has been integrated into Cython itself,
4 which is now released in version 0.21.
4 which is now released in version 0.21.
5
5
6 cf github `cython` organisation, `cython` repo, under the
6 cf github `cython` organisation, `cython` repo, under the
7 file `Cython/Build/IpythonMagic.py`
7 file `Cython/Build/IpythonMagic.py`
8 """
8 """
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10 # Copyright (C) 2010-2011, IPython Development Team.
10 # Copyright (C) 2010-2011, IPython Development Team.
11 #
11 #
12 # Distributed under the terms of the Modified BSD License.
12 # Distributed under the terms of the Modified BSD License.
13 #
13 #
14 # The full license is in the file COPYING.txt, distributed with this software.
14 # The full license is in the file COPYING.txt, distributed with this software.
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import print_function
17 from __future__ import print_function
18
18
19 try:
19 try:
20 import Cython
20 import Cython
21 except:
21 except:
22 Cython = None
22 Cython = None
23
23
24 try:
24 try:
25 from Cython.Build.IpythonMagic import CythonMagics
25 from Cython.Build.IpythonMagic import CythonMagics
26 except :
26 except :
27 pass
27 pass
28
28
29
29
30 ## still load the magic in IPython 3.x, remove completely in future versions.
30 ## still load the magic in IPython 3.x, remove completely in future versions.
31 def load_ipython_extension(ip):
31 def load_ipython_extension(ip):
32 """Load the extension in IPython."""
32 """Load the extension in IPython."""
33
33
34 print("""The Cython magic has been move to the Cython package, hence """)
34 print("""The Cython magic has been move to the Cython package, hence """)
35 print("""`%load_ext cythonmagic` is deprecated; Please use `%load_ext cython` instead.""")
35 print("""`%load_ext cythonmagic` is deprecated; Please use `%load_ext Cython` instead.""")
36
36
37 if Cython is None or tuple(map(int,Cython.__version__.split('.'))) < (0,21) :
37 if Cython is None or tuple(map(int,Cython.__version__.split('.'))) < (0,21) :
38 print("You need Cython version >=0.21 to use the Cython magic")
38 print("You need Cython version >=0.21 to use the Cython magic")
39 return
39 return
40 print("""\nThough, because I am nice, I'll still try to load it for you this time.""")
40 print("""\nThough, because I am nice, I'll still try to load it for you this time.""")
41 Cython.load_ipython_extension(ip)
41 Cython.load_ipython_extension(ip)
@@ -1,104 +1,104 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
94 cythonmagic
95 storemagic
95 storemagic
96 sympyprinting
96 sympyprinting
97
97
98 * ``octavemagic`` used to be bundled, but is now part of `oct2py <http://blink1073.github.io/oct2py/docs/>`_.
98 * ``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.
99 Use ``%load_ext oct2py.ipython`` to load it.
100 * ``rmagic`` is now part of `rpy2 <http://rpy.sourceforge.net/>`_. Use
100 * ``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
101 ``%load_ext rpy2.ipython`` to load it, and see :mod:`rpy2.ipython.rmagic` for
102 details of how to use it.
102 details of how to use it.
103 * ``cythonmagic``used to be bundled, but is now part of `cython <https://github.com/cython/cython/>`_
103 * ``cythonmagic``used to be bundled, but is now part of `cython <https://github.com/cython/cython/>`_
104 Use ``%load_ext cython`` to load it.
104 Use ``%load_ext Cython`` to load it.
@@ -1,156 +1,156 b''
1 =====================================
1 =====================================
2 Introduction to IPython configuration
2 Introduction to IPython configuration
3 =====================================
3 =====================================
4
4
5 .. _setting_config:
5 .. _setting_config:
6
6
7 Setting configurable options
7 Setting configurable options
8 ============================
8 ============================
9
9
10 Many of IPython's classes have configurable attributes (see
10 Many of IPython's classes have configurable attributes (see
11 :doc:`options/index` for the list). These can be
11 :doc:`options/index` for the list). These can be
12 configured in several ways.
12 configured in several ways.
13
13
14 Python config files
14 Python config files
15 -------------------
15 -------------------
16
16
17 To create the blank config files, run::
17 To create the blank config files, run::
18
18
19 ipython profile create [profilename]
19 ipython profile create [profilename]
20
20
21 If you leave out the profile name, the files will be created for the
21 If you leave out the profile name, the files will be created for the
22 ``default`` profile (see :ref:`profiles`). These will typically be
22 ``default`` profile (see :ref:`profiles`). These will typically be
23 located in :file:`~/.ipython/profile_default/`, and will be named
23 located in :file:`~/.ipython/profile_default/`, and will be named
24 :file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc.
24 :file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc.
25 The settings in :file:`ipython_config.py` apply to all IPython commands.
25 The settings in :file:`ipython_config.py` apply to all IPython commands.
26
26
27 The files typically start by getting the root config object::
27 The files typically start by getting the root config object::
28
28
29 c = get_config()
29 c = get_config()
30
30
31 You can then configure class attributes like this::
31 You can then configure class attributes like this::
32
32
33 c.InteractiveShell.automagic = False
33 c.InteractiveShell.automagic = False
34
34
35 Be careful with spelling--incorrect names will simply be ignored, with
35 Be careful with spelling--incorrect names will simply be ignored, with
36 no error.
36 no error.
37
37
38 To add to a collection which may have already been defined elsewhere,
38 To add to a collection which may have already been defined elsewhere,
39 you can use methods like those found on lists, dicts and sets: append,
39 you can use methods like those found on lists, dicts and sets: append,
40 extend, :meth:`~IPython.config.loader.LazyConfigValue.prepend` (like
40 extend, :meth:`~IPython.config.loader.LazyConfigValue.prepend` (like
41 extend, but at the front), add and update (which works both for dicts
41 extend, but at the front), add and update (which works both for dicts
42 and sets)::
42 and sets)::
43
43
44 c.InteractiveShellApp.extensions.append('cython')
44 c.InteractiveShellApp.extensions.append('Cython')
45
45
46 .. versionadded:: 2.0
46 .. versionadded:: 2.0
47 list, dict and set methods for config values
47 list, dict and set methods for config values
48
48
49 Example config file
49 Example config file
50 ```````````````````
50 ```````````````````
51
51
52 ::
52 ::
53
53
54 # sample ipython_config.py
54 # sample ipython_config.py
55 c = get_config()
55 c = get_config()
56
56
57 c.TerminalIPythonApp.display_banner = True
57 c.TerminalIPythonApp.display_banner = True
58 c.InteractiveShellApp.log_level = 20
58 c.InteractiveShellApp.log_level = 20
59 c.InteractiveShellApp.extensions = [
59 c.InteractiveShellApp.extensions = [
60 'myextension'
60 'myextension'
61 ]
61 ]
62 c.InteractiveShellApp.exec_lines = [
62 c.InteractiveShellApp.exec_lines = [
63 'import numpy',
63 'import numpy',
64 'import scipy'
64 'import scipy'
65 ]
65 ]
66 c.InteractiveShellApp.exec_files = [
66 c.InteractiveShellApp.exec_files = [
67 'mycode.py',
67 'mycode.py',
68 'fancy.ipy'
68 'fancy.ipy'
69 ]
69 ]
70 c.InteractiveShell.autoindent = True
70 c.InteractiveShell.autoindent = True
71 c.InteractiveShell.colors = 'LightBG'
71 c.InteractiveShell.colors = 'LightBG'
72 c.InteractiveShell.confirm_exit = False
72 c.InteractiveShell.confirm_exit = False
73 c.InteractiveShell.deep_reload = True
73 c.InteractiveShell.deep_reload = True
74 c.InteractiveShell.editor = 'nano'
74 c.InteractiveShell.editor = 'nano'
75 c.InteractiveShell.xmode = 'Context'
75 c.InteractiveShell.xmode = 'Context'
76
76
77 c.PromptManager.in_template = 'In [\#]: '
77 c.PromptManager.in_template = 'In [\#]: '
78 c.PromptManager.in2_template = ' .\D.: '
78 c.PromptManager.in2_template = ' .\D.: '
79 c.PromptManager.out_template = 'Out[\#]: '
79 c.PromptManager.out_template = 'Out[\#]: '
80 c.PromptManager.justify = True
80 c.PromptManager.justify = True
81
81
82 c.PrefilterManager.multi_line_specials = True
82 c.PrefilterManager.multi_line_specials = True
83
83
84 c.AliasManager.user_aliases = [
84 c.AliasManager.user_aliases = [
85 ('la', 'ls -al')
85 ('la', 'ls -al')
86 ]
86 ]
87
87
88
88
89 Command line arguments
89 Command line arguments
90 ----------------------
90 ----------------------
91
91
92 Every configurable value can be set from the command line, using this
92 Every configurable value can be set from the command line, using this
93 syntax::
93 syntax::
94
94
95 ipython --ClassName.attribute=value
95 ipython --ClassName.attribute=value
96
96
97 Many frequently used options have short aliases and flags, such as
97 Many frequently used options have short aliases and flags, such as
98 ``--matplotlib`` (to integrate with a matplotlib GUI event loop) or
98 ``--matplotlib`` (to integrate with a matplotlib GUI event loop) or
99 ``--pdb`` (automatic post-mortem debugging of exceptions).
99 ``--pdb`` (automatic post-mortem debugging of exceptions).
100
100
101 To see all of these abbreviated options, run::
101 To see all of these abbreviated options, run::
102
102
103 ipython --help
103 ipython --help
104 ipython notebook --help
104 ipython notebook --help
105 # etc.
105 # etc.
106
106
107 Options specified at the command line, in either format, override
107 Options specified at the command line, in either format, override
108 options set in a configuration file.
108 options set in a configuration file.
109
109
110 The config magic
110 The config magic
111 ----------------
111 ----------------
112
112
113 You can also modify config from inside IPython, using a magic command::
113 You can also modify config from inside IPython, using a magic command::
114
114
115 %config IPCompleter.greedy = True
115 %config IPCompleter.greedy = True
116
116
117 At present, this only affects the current session - changes you make to
117 At present, this only affects the current session - changes you make to
118 config are not saved anywhere. Also, some options are only read when
118 config are not saved anywhere. Also, some options are only read when
119 IPython starts, so they can't be changed like this.
119 IPython starts, so they can't be changed like this.
120
120
121 .. _profiles:
121 .. _profiles:
122
122
123 Profiles
123 Profiles
124 ========
124 ========
125
125
126 IPython can use multiple profiles, with separate configuration and
126 IPython can use multiple profiles, with separate configuration and
127 history. By default, if you don't specify a profile, IPython always runs
127 history. By default, if you don't specify a profile, IPython always runs
128 in the ``default`` profile. To use a new profile::
128 in the ``default`` profile. To use a new profile::
129
129
130 ipython profile create foo # create the profile foo
130 ipython profile create foo # create the profile foo
131 ipython --profile=foo # start IPython using the new profile
131 ipython --profile=foo # start IPython using the new profile
132
132
133 Profiles are typically stored in :ref:`ipythondir`, but you can also keep
133 Profiles are typically stored in :ref:`ipythondir`, but you can also keep
134 a profile in the current working directory, for example to distribute it
134 a profile in the current working directory, for example to distribute it
135 with a project. To find a profile directory on the filesystem::
135 with a project. To find a profile directory on the filesystem::
136
136
137 ipython locate profile foo
137 ipython locate profile foo
138
138
139 .. _ipythondir:
139 .. _ipythondir:
140
140
141 The IPython directory
141 The IPython directory
142 =====================
142 =====================
143
143
144 IPython stores its files---config, command history and extensions---in
144 IPython stores its files---config, command history and extensions---in
145 the directory :file:`~/.ipython/` by default.
145 the directory :file:`~/.ipython/` by default.
146
146
147 .. envvar:: IPYTHONDIR
147 .. envvar:: IPYTHONDIR
148
148
149 If set, this environment variable should be the path to a directory,
149 If set, this environment variable should be the path to a directory,
150 which IPython will use for user data. IPython will create it if it
150 which IPython will use for user data. IPython will create it if it
151 does not exist.
151 does not exist.
152
152
153 .. option:: --ipython-dir=<path>
153 .. option:: --ipython-dir=<path>
154
154
155 This command line option can also be used to override the default
155 This command line option can also be used to override the default
156 IPython directory.
156 IPython directory.
General Comments 0
You need to be logged in to leave comments. Login now