##// END OF EJS Templates
document ipython and ipykernel global configuration
Matthias Bussonnier -
Show More
@@ -19,14 +19,16 b' To create the blank config files, run::'
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 located in
23 located in :file:`~/.ipython/profile_default/`, and will be named
23 :file:`~/.ipython/profile_default/`, and will be named
24 :file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc.
24 :file:`ipython_config.py`, for hitorical reasons you may also find fiels
25 The settings in :file:`ipython_config.py` apply to all IPython commands.
25 named with IPytho nprefix instead of Jupyter:
26 :file:`ipython_notebook_config.py`, etc. The settings in
27 :file:`ipython_config.py` apply to all IPython commands.
26
28
27 The files typically start by getting the root config object::
29 by default, configuration files are fully featured Python scripts that can
28
30 execute arbitrary code, the main usage is to set value on the config object
29 c = get_config()
31 ``c`` which exist in your configuration file.
30
32
31 You can then configure class attributes like this::
33 You can then configure class attributes like this::
32
34
@@ -35,11 +37,11 b' You can then configure class attributes like this::'
35 Be careful with spelling--incorrect names will simply be ignored, with
37 Be careful with spelling--incorrect names will simply be ignored, with
36 no error.
38 no error.
37
39
38 To add to a collection which may have already been defined elsewhere,
40 To add to a collection which may have already been defined elsewhere or have
39 you can use methods like those found on lists, dicts and sets: append,
41 default values, you can use methods like those found on lists, dicts and
40 extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
42 sets: append, extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
41 extend, but at the front), add and update (which works both for dicts
43 extend, but at the front), add and update (which works both for dicts and
42 and sets)::
44 sets)::
43
45
44 c.InteractiveShellApp.extensions.append('Cython')
46 c.InteractiveShellApp.extensions.append('Cython')
45
47
@@ -52,7 +54,6 b' Example config file'
52 ::
54 ::
53
55
54 # sample ipython_config.py
56 # sample ipython_config.py
55 c = get_config()
56
57
57 c.TerminalIPythonApp.display_banner = True
58 c.TerminalIPythonApp.display_banner = True
58 c.InteractiveShellApp.log_level = 20
59 c.InteractiveShellApp.log_level = 20
@@ -78,6 +79,38 b' Example config file'
78 ('la', 'ls -al')
79 ('la', 'ls -al')
79 ]
80 ]
80
81
82 Json Configuration files
83 ------------------------
84
85 in case where executability of configuration can be problematic, or
86 configurations need to be modified programatically, IPython also support a
87 limited set of functionalities via ``.json`` config files.
88
89 You can defined most of the configuration options via a json object which
90 hierarchy represent the value you woudl normally set on the ``c`` object of
91 ``.py`` configuration files. The following ``ipython_config.json`` file::
92
93 {
94 "InteractiveShell": {
95 "colors": "LightBG",
96 "editor": "nano"
97 },
98 "InteractiveShellApp": {
99 "extensions": [
100 "myextension"
101 ]
102 }
103 }
104
105 Is equivalent to the following ``ipython_config.py``::
106
107 c.InteractiveShellApp.extensions = [
108 'myextension'
109 ]
110
111 c.InteractiveShell.colors = 'LightBG'
112 c.InteractiveShell.editor = 'nano'
113
81
114
82 Command line arguments
115 Command line arguments
83 ----------------------
116 ----------------------
@@ -94,7 +127,7 b' Many frequently used options have short aliases and flags, such as'
94 To see all of these abbreviated options, run::
127 To see all of these abbreviated options, run::
95
128
96 ipython --help
129 ipython --help
97 ipython notebook --help
130 jupyter notebook --help
98 # etc.
131 # etc.
99
132
100 Options specified at the command line, in either format, override
133 Options specified at the command line, in either format, override
@@ -163,3 +196,38 b' the directory :file:`~/.ipython/` by default.'
163
196
164 To see where IPython is looking for the IPython directory, use the command
197 To see where IPython is looking for the IPython directory, use the command
165 ``ipython locate``, or the Python function :func:`IPython.paths.get_ipython_dir`.
198 ``ipython locate``, or the Python function :func:`IPython.paths.get_ipython_dir`.
199
200
201 Systemwide configuration
202 ========================
203
204 It can be usefull to deploy systemwide ipython or ipykernel configuration
205 when managing environment for many users. At startup time IPython and
206 IPykernel will search for configuration file in multiple systemwide
207 locations, mainly:
208
209 - ``/etc/ipython/``
210 - ``/usr/local/etc/ipython/``
211
212 When the global install is a standalone python distribution it may also
213 search in distribution specific location, for example:
214
215 - ``$ANACONDA_LOCATION/etc/ipython/``
216
217 In those locations, Terminal IPython will look for a file called
218 ``ipython_config.py`` and ``ipython_config.json``, ipykernel will look for
219 ``ipython_kernel_config.py`` and ``ipython_kernel.json``.
220
221 Configuration files are loaded in order and merged with configuration on
222 later locatoin taking precedence on earlier locations (that is to say a user
223 can overwrite a systemwide configuration option).
224
225 You can see all locations in which IPython is looking for configuration files
226 by starting ipython in debug mode::
227
228 $ ipython --debug -c 'exit()'
229
230 Identically with ipykernel though the command is currently blocking until
231 this process is killed with ``Ctrl-\``::
232
233 $ python -m ipykernel --debug No newline at end of file
General Comments 0
You need to be logged in to leave comments. Login now