##// END OF EJS Templates
document ipython and ipykernel global configuration
Matthias Bussonnier -
Show More
@@ -19,27 +19,29 b' To create the blank config files, run::'
19 19 ipython profile create [profilename]
20 20
21 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
23 located in :file:`~/.ipython/profile_default/`, and will be named
24 :file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc.
25 The settings in :file:`ipython_config.py` apply to all IPython commands.
22 ``default`` profile (see :ref:`profiles`). These will typically be located in
23 :file:`~/.ipython/profile_default/`, and will be named
24 :file:`ipython_config.py`, for hitorical reasons you may also find fiels
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::
28
29 c = get_config()
29 by default, configuration files are fully featured Python scripts that can
30 execute arbitrary code, the main usage is to set value on the config object
31 ``c`` which exist in your configuration file.
30 32
31 33 You can then configure class attributes like this::
32 34
33 35 c.InteractiveShell.automagic = False
34 36
35 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,
39 you can use methods like those found on lists, dicts and sets: append,
40 extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
41 extend, but at the front), add and update (which works both for dicts
42 and sets)::
40 To add to a collection which may have already been defined elsewhere or have
41 default values, you can use methods like those found on lists, dicts and
42 sets: append, extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
43 extend, but at the front), add and update (which works both for dicts and
44 sets)::
43 45
44 46 c.InteractiveShellApp.extensions.append('Cython')
45 47
@@ -52,7 +54,6 b' Example config file'
52 54 ::
53 55
54 56 # sample ipython_config.py
55 c = get_config()
56 57
57 58 c.TerminalIPythonApp.display_banner = True
58 59 c.InteractiveShellApp.log_level = 20
@@ -78,6 +79,38 b' Example config file'
78 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 115 Command line arguments
83 116 ----------------------
@@ -94,7 +127,7 b' Many frequently used options have short aliases and flags, such as'
94 127 To see all of these abbreviated options, run::
95 128
96 129 ipython --help
97 ipython notebook --help
130 jupyter notebook --help
98 131 # etc.
99 132
100 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 197 To see where IPython is looking for the IPython directory, use the command
165 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