##// END OF EJS Templates
Update intro.rst
谭九鼎 -
Show More
@@ -1,233 +1,235 b''
1 1 =====================================
2 2 Introduction to IPython configuration
3 3 =====================================
4 4
5 5 .. _setting_config:
6 6
7 7 Setting configurable options
8 8 ============================
9 9
10 10 Many of IPython's classes have configurable attributes (see
11 11 :doc:`options/index` for the list). These can be
12 12 configured in several ways.
13 13
14 14 Python configuration files
15 15 --------------------------
16 16
17 17 To create the blank configuration files, run::
18 18
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 22 ``default`` profile (see :ref:`profiles`). These will typically be located in
23 23 :file:`~/.ipython/profile_default/`, and will be named
24 24 :file:`ipython_config.py`, for historical reasons you may also find files
25 25 named with IPython prefix instead of Jupyter:
26 26 :file:`ipython_notebook_config.py`, etc. The settings in
27 27 :file:`ipython_config.py` apply to all IPython commands.
28 28
29 29 By default, configuration files are fully featured Python scripts that can
30 30 execute arbitrary code, the main usage is to set value on the configuration
31 31 object ``c`` which exist in your configuration file.
32 32
33 33 You can then configure class attributes like this::
34 34
35 35 c.InteractiveShell.automagic = False
36 36
37 37 Be careful with spelling--incorrect names will simply be ignored, with
38 38 no error.
39 39
40 40 To add to a collection which may have already been defined elsewhere or have
41 41 default values, you can use methods like those found on lists, dicts and
42 42 sets: append, extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
43 43 extend, but at the front), add and update (which works both for dicts and
44 44 sets)::
45 45
46 46 c.InteractiveShellApp.extensions.append('Cython')
47 47
48 48 .. versionadded:: 2.0
49 49 list, dict and set methods for config values
50 50
51 51 Example configuration file
52 52 ``````````````````````````
53 53
54 54 ::
55 55
56 56 # sample ipython_config.py
57 57
58 58 c.TerminalIPythonApp.display_banner = True
59 59 c.InteractiveShellApp.log_level = 20
60 60 c.InteractiveShellApp.extensions = [
61 61 'myextension'
62 62 ]
63 63 c.InteractiveShellApp.exec_lines = [
64 64 'import numpy',
65 65 'import scipy'
66 66 ]
67 67 c.InteractiveShellApp.exec_files = [
68 68 'mycode.py',
69 69 'fancy.ipy'
70 70 ]
71 71 c.InteractiveShell.colors = 'LightBG'
72 72 c.InteractiveShell.xmode = 'Context'
73 73 c.TerminalInteractiveShell.confirm_exit = False
74 74 c.TerminalInteractiveShell.editor = 'nano'
75 75
76 76 c.PrefilterManager.multi_line_specials = True
77 77
78 78 c.AliasManager.user_aliases = [
79 79 ('la', 'ls -al')
80 80 ]
81 81
82 82 JSON Configuration files
83 83 ------------------------
84 84
85 85 In case where executability of configuration can be problematic, or
86 86 configurations need to be modified programmatically, IPython also support a
87 87 limited set of functionalities via ``.json`` configuration files.
88 88
89 89 You can defined most of the configuration options via a json object which
90 90 hierarchy represent the value you would normally set on the ``c`` object of
91 91 ``.py`` configuration files. The following ``ipython_config.json`` file::
92 92
93 93 {
94 94 "InteractiveShell": {
95 95 "colors": "LightBG",
96 "editor": "nano"
97 96 },
98 97 "InteractiveShellApp": {
99 98 "extensions": [
100 99 "myextension"
101 100 ]
101 },
102 "TerminalInteractiveShell": {
103 "editor": "nano"
102 104 }
103 105 }
104 106
105 107 Is equivalent to the following ``ipython_config.py``::
106 108
107 109 c.InteractiveShellApp.extensions = [
108 110 'myextension'
109 111 ]
110 112
111 113 c.InteractiveShell.colors = 'LightBG'
112 c.InteractiveShell.editor = 'nano'
114 c.TerminalInteractiveShell.editor = 'nano'
113 115
114 116
115 117 Command line arguments
116 118 ----------------------
117 119
118 120 Every configurable value can be set from the command line, using this
119 121 syntax::
120 122
121 123 ipython --ClassName.attribute=value
122 124
123 125 Many frequently used options have short aliases and flags, such as
124 126 ``--matplotlib`` (to integrate with a matplotlib GUI event loop) or
125 127 ``--pdb`` (automatic post-mortem debugging of exceptions).
126 128
127 129 To see all of these abbreviated options, run::
128 130
129 131 ipython --help
130 132 jupyter notebook --help
131 133 # etc.
132 134
133 135 Options specified at the command line, in either format, override
134 136 options set in a configuration file.
135 137
136 138 The config magic
137 139 ----------------
138 140
139 141 You can also modify config from inside IPython, using a magic command::
140 142
141 143 %config IPCompleter.greedy = True
142 144
143 145 At present, this only affects the current session - changes you make to
144 146 config are not saved anywhere. Also, some options are only read when
145 147 IPython starts, so they can't be changed like this.
146 148
147 149 .. _configure_start_ipython:
148 150
149 151 Running IPython from Python
150 152 ----------------------------
151 153
152 154 If you are using :ref:`embedding` to start IPython from a normal
153 155 python file, you can set configuration options the same way as in a
154 156 config file by creating a traitlets config object and passing it to
155 157 start_ipython like in the example below.
156 158
157 159 .. literalinclude:: ../../../examples/Embedding/start_ipython_config.py
158 160 :language: python
159 161
160 162 .. _profiles:
161 163
162 164 Profiles
163 165 ========
164 166
165 167 IPython can use multiple profiles, with separate configuration and
166 168 history. By default, if you don't specify a profile, IPython always runs
167 169 in the ``default`` profile. To use a new profile::
168 170
169 171 ipython profile create foo # create the profile foo
170 172 ipython --profile=foo # start IPython using the new profile
171 173
172 174 Profiles are typically stored in :ref:`ipythondir`, but you can also keep
173 175 a profile in the current working directory, for example to distribute it
174 176 with a project. To find a profile directory on the filesystem::
175 177
176 178 ipython locate profile foo
177 179
178 180 .. _ipythondir:
179 181
180 182 The IPython directory
181 183 =====================
182 184
183 185 IPython stores its files---config, command history and extensions---in
184 186 the directory :file:`~/.ipython/` by default.
185 187
186 188 .. envvar:: IPYTHONDIR
187 189
188 190 If set, this environment variable should be the path to a directory,
189 191 which IPython will use for user data. IPython will create it if it
190 192 does not exist.
191 193
192 194 .. option:: --ipython-dir=<path>
193 195
194 196 This command line option can also be used to override the default
195 197 IPython directory.
196 198
197 199 To see where IPython is looking for the IPython directory, use the command
198 200 ``ipython locate``, or the Python function :func:`IPython.paths.get_ipython_dir`.
199 201
200 202
201 203 Systemwide configuration
202 204 ========================
203 205
204 206 It can be useful to deploy systemwide ipython or ipykernel configuration
205 207 when managing environment for many users. At startup time IPython and
206 208 IPykernel will search for configuration file in multiple systemwide
207 209 locations, mainly:
208 210
209 211 - ``/etc/ipython/``
210 212 - ``/usr/local/etc/ipython/``
211 213
212 214 When the global install is a standalone python distribution it may also
213 215 search in distribution specific location, for example:
214 216
215 217 - ``$ANACONDA_LOCATION/etc/ipython/``
216 218
217 219 In those locations, Terminal IPython will look for a file called
218 220 ``ipython_config.py`` and ``ipython_config.json``, ipykernel will look for
219 221 ``ipython_kernel_config.py`` and ``ipython_kernel.json``.
220 222
221 223 Configuration files are loaded in order and merged with configuration on
222 224 later location taking precedence on earlier locations (that is to say a user
223 225 can overwrite a systemwide configuration option).
224 226
225 227 You can see all locations in which IPython is looking for configuration files
226 228 by starting ipython in debug mode::
227 229
228 230 $ ipython --debug -c 'exit()'
229 231
230 232 Identically with ipykernel though the command is currently blocking until
231 233 this process is killed with ``Ctrl-\``::
232 234
233 235 $ python -m ipykernel --debug
General Comments 0
You need to be logged in to leave comments. Login now