##// END OF EJS Templates
Merge pull request #8476 from takluyver/docs-cleanup-config...
Matthias Bussonnier -
r21397:ef5e1430 merge
parent child Browse files
Show More
@@ -191,7 +191,9 b' html_additional_pages = {'
191 191 htmlhelp_basename = 'ipythondoc'
192 192
193 193 intersphinx_mapping = {'python': ('http://docs.python.org/2/', None),
194 'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None)}
194 'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None),
195 'traitlets': ('http://traitlets.readthedocs.org/en/latest/', None),
196 }
195 197
196 198 # Options for LaTeX output
197 199 # ------------------------
@@ -37,7 +37,7 b' no error.'
37 37
38 38 To add to a collection which may have already been defined elsewhere,
39 39 you can use methods like those found on lists, dicts and sets: append,
40 extend, :meth:`~traitlets.config.loader.LazyConfigValue.prepend` (like
40 extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
41 41 extend, but at the front), add and update (which works both for dicts
42 42 and sets)::
43 43
@@ -154,3 +154,6 b' the directory :file:`~/.ipython/` by default.'
154 154
155 155 This command line option can also be used to override the default
156 156 IPython directory.
157
158 To see where IPython is looking for the IPython directory, use the command
159 ``ipython locate``, or the Python function :func:`IPython.paths.get_ipython_dir`.
@@ -4,296 +4,9 b''
4 4 Overview of the IPython configuration system
5 5 ============================================
6 6
7 This section describes the IPython configuration system.
8
9 The main concepts
10 =================
11
12 There are a number of abstractions that the IPython configuration system uses.
13 Each of these abstractions is represented by a Python class.
14
15 Configuration object: :class:`~traitlets.config.loader.Config`
16 A configuration object is a simple dictionary-like class that holds
17 configuration attributes and sub-configuration objects. These classes
18 support dotted attribute style access (``cfg.Foo.bar``) in addition to the
19 regular dictionary style access (``cfg['Foo']['bar']``).
20 The Config object is a wrapper around a simple dictionary with some convenience methods,
21 such as merging and automatic section creation.
22
23 Application: :class:`~traitlets.config.application.Application`
24 An application is a process that does a specific job. The most obvious
25 application is the :command:`ipython` command line program. Each
26 application reads *one or more* configuration files and a single set of
27 command line options
28 and then produces a master configuration object for the application. This
29 configuration object is then passed to the configurable objects that the
30 application creates. These configurable objects implement the actual logic
31 of the application and know how to configure themselves given the
32 configuration object.
33
34 Applications always have a `log` attribute that is a configured Logger.
35 This allows centralized logging configuration per-application.
36
37 Configurable: :class:`~traitlets.config.configurable.Configurable`
38 A configurable is a regular Python class that serves as a base class for
39 all main classes in an application. The
40 :class:`~traitlets.config.configurable.Configurable` base class is
41 lightweight and only does one things.
42
43 This :class:`~traitlets.config.configurable.Configurable` is a subclass
44 of :class:`~traitlets.HasTraits` that knows how to configure
45 itself. Class level traits with the metadata ``config=True`` become
46 values that can be configured from the command line and configuration
47 files.
48
49 Developers create :class:`~traitlets.config.configurable.Configurable`
50 subclasses that implement all of the logic in the application. Each of
51 these subclasses has its own configuration information that controls how
52 instances are created.
53
54 Singletons: :class:`~traitlets.config.configurable.SingletonConfigurable`
55 Any object for which there is a single canonical instance. These are
56 just like Configurables, except they have a class method
57 :meth:`~traitlets.config.configurable.SingletonConfigurable.instance`,
58 that returns the current active instance (or creates one if it
59 does not exist). Examples of singletons include
60 :class:`~traitlets.config.application.Application`s and
61 :class:`~IPython.core.interactiveshell.InteractiveShell`. This lets
62 objects easily connect to the current running Application without passing
63 objects around everywhere. For instance, to get the current running
64 Application instance, simply do: ``app = Application.instance()``.
65
66
67 .. note::
68
69 Singletons are not strictly enforced - you can have many instances
70 of a given singleton class, but the :meth:`instance` method will always
71 return the same one.
72
73 Having described these main concepts, we can now state the main idea in our
74 configuration system: *"configuration" allows the default values of class
75 attributes to be controlled on a class by class basis*. Thus all instances of
76 a given class are configured in the same way. Furthermore, if two instances
77 need to be configured differently, they need to be instances of two different
78 classes. While this model may seem a bit restrictive, we have found that it
79 expresses most things that need to be configured extremely well. However, it
80 is possible to create two instances of the same class that have different
81 trait values. This is done by overriding the configuration.
82
83 Now, we show what our configuration objects and files look like.
84
85 Configuration objects and files
86 ===============================
87
88 A configuration object is little more than a wrapper around a dictionary.
89 A configuration *file* is simply a mechanism for producing that object.
90 The main IPython configuration file is a plain Python script,
91 which can perform extensive logic to populate the config object.
92 IPython 2.0 introduces a JSON configuration file,
93 which is just a direct JSON serialization of the config dictionary,
94 which is easily processed by external software.
95
96 When both Python and JSON configuration file are present, both will be loaded,
97 with JSON configuration having higher priority.
98
99 Python configuration Files
100 --------------------------
101
102 A Python configuration file is a pure Python file that populates a configuration object.
103 This configuration object is a :class:`~traitlets.config.loader.Config` instance.
104 While in a configuration file, to get a reference to this object, simply call the :func:`get_config`
105 function, which is available in the global namespace of the script.
106
107 Here is an example of a super simple configuration file that does nothing::
108
109 c = get_config()
110
111 Once you get a reference to the configuration object, you simply set
112 attributes on it. All you have to know is:
113
114 * The name of the class to configure.
115 * The name of the attribute.
116 * The type of each attribute.
117
118 The answers to these questions are provided by the various
119 :class:`~traitlets.config.configurable.Configurable` subclasses that an
120 application uses. Let's look at how this would work for a simple configurable
121 subclass::
122
123 # Sample configurable:
124 from traitlets.config.configurable import Configurable
125 from traitlets import Int, Float, Unicode, Bool
126
127 class MyClass(Configurable):
128 name = Unicode(u'defaultname', config=True)
129 ranking = Int(0, config=True)
130 value = Float(99.0)
131 # The rest of the class implementation would go here..
132
133 In this example, we see that :class:`MyClass` has three attributes, two
134 of which (``name``, ``ranking``) can be configured. All of the attributes
135 are given types and default values. If a :class:`MyClass` is instantiated,
136 but not configured, these default values will be used. But let's see how
137 to configure this class in a configuration file::
138
139 # Sample config file
140 c = get_config()
141
142 c.MyClass.name = 'coolname'
143 c.MyClass.ranking = 10
144
145 After this configuration file is loaded, the values set in it will override
146 the class defaults anytime a :class:`MyClass` is created. Furthermore,
147 these attributes will be type checked and validated anytime they are set.
148 This type checking is handled by the :mod:`traitlets` module,
149 which provides the :class:`Unicode`, :class:`Int` and :class:`Float` types.
150 In addition to these traitlets, the :mod:`traitlets` provides
151 traitlets for a number of other types.
152
153 .. note::
154
155 Underneath the hood, the :class:`Configurable` base class is a subclass of
156 :class:`traitlets.HasTraits`. The
157 :mod:`traitlets` module is a lightweight version of
158 :mod:`enthought.traits`. Our implementation is a pure Python subset
159 (mostly API compatible) of :mod:`enthought.traits` that does not have any
160 of the automatic GUI generation capabilities. Our plan is to achieve 100%
161 API compatibility to enable the actual :mod:`enthought.traits` to
162 eventually be used instead. Currently, we cannot use
163 :mod:`enthought.traits` as we are committed to the core of IPython being
164 pure Python.
165
166 It should be very clear at this point what the naming convention is for
167 configuration attributes::
168
169 c.ClassName.attribute_name = attribute_value
170
171 Here, ``ClassName`` is the name of the class whose configuration attribute you
172 want to set, ``attribute_name`` is the name of the attribute you want to set
173 and ``attribute_value`` the the value you want it to have. The ``ClassName``
174 attribute of ``c`` is not the actual class, but instead is another
175 :class:`~traitlets.config.loader.Config` instance.
176
177 .. note::
178
179 The careful reader may wonder how the ``ClassName`` (``MyClass`` in
180 the above example) attribute of the configuration object ``c`` gets
181 created. These attributes are created on the fly by the
182 :class:`~traitlets.config.loader.Config` instance, using a simple naming
183 convention. Any attribute of a :class:`~traitlets.config.loader.Config`
184 instance whose name begins with an uppercase character is assumed to be a
185 sub-configuration and a new empty :class:`~traitlets.config.loader.Config`
186 instance is dynamically created for that attribute. This allows deeply
187 hierarchical information created easily (``c.Foo.Bar.value``) on the fly.
188
189 JSON configuration Files
190 ------------------------
191
192 A JSON configuration file is simply a file that contains a
193 :class:`~traitlets.config.loader.Config` dictionary serialized to JSON.
194 A JSON configuration file has the same base name as a Python configuration file,
195 but with a .json extension.
196
197 Configuration described in previous section could be written as follows in a
198 JSON configuration file:
199
200 .. sourcecode:: json
201
202 {
203 "version": "1.0",
204 "MyClass": {
205 "name": "coolname",
206 "ranking": 10
207 }
208 }
209
210 JSON configuration files can be more easily generated or processed by programs
211 or other languages.
212
213
214 Configuration files inheritance
215 ===============================
216
217 .. note::
218
219 This section only apply to Python configuration files.
220
221 Let's say you want to have different configuration files for various purposes.
222 Our configuration system makes it easy for one configuration file to inherit
223 the information in another configuration file. The :func:`load_subconfig`
224 command can be used in a configuration file for this purpose. Here is a simple
225 example that loads all of the values from the file :file:`base_config.py`::
226
227 # base_config.py
228 c = get_config()
229 c.MyClass.name = 'coolname'
230 c.MyClass.ranking = 100
231
232 into the configuration file :file:`main_config.py`::
233
234 # main_config.py
235 c = get_config()
236
237 # Load everything from base_config.py
238 load_subconfig('base_config.py')
239
240 # Now override one of the values
241 c.MyClass.name = 'bettername'
242
243 In a situation like this the :func:`load_subconfig` makes sure that the
244 search path for sub-configuration files is inherited from that of the parent.
245 Thus, you can typically put the two in the same directory and everything will
246 just work.
247
248 You can also load configuration files by profile, for instance:
249
250 .. sourcecode:: python
251
252 load_subconfig('ipython_config.py', profile='default')
253
254 to inherit your default configuration as a starting point.
255
256
257 Class based configuration inheritance
258 =====================================
259
260 There is another aspect of configuration where inheritance comes into play.
261 Sometimes, your classes will have an inheritance hierarchy that you want
262 to be reflected in the configuration system. Here is a simple example::
263
264 from traitlets.config.configurable import Configurable
265 from traitlets import Int, Float, Unicode, Bool
266
267 class Foo(Configurable):
268 name = Unicode(u'fooname', config=True)
269 value = Float(100.0, config=True)
270
271 class Bar(Foo):
272 name = Unicode(u'barname', config=True)
273 othervalue = Int(0, config=True)
274
275 Now, we can create a configuration file to configure instances of :class:`Foo`
276 and :class:`Bar`::
277
278 # config file
279 c = get_config()
280
281 c.Foo.name = u'bestname'
282 c.Bar.othervalue = 10
283
284 This class hierarchy and configuration file accomplishes the following:
285
286 * The default value for :attr:`Foo.name` and :attr:`Bar.name` will be
287 'bestname'. Because :class:`Bar` is a :class:`Foo` subclass it also
288 picks up the configuration information for :class:`Foo`.
289 * The default value for :attr:`Foo.value` and :attr:`Bar.value` will be
290 ``100.0``, which is the value specified as the class default.
291 * The default value for :attr:`Bar.othervalue` will be 10 as set in the
292 configuration file. Because :class:`Foo` is the parent of :class:`Bar`
293 it doesn't know anything about the :attr:`othervalue` attribute.
294
295
296 .. _ipython_dir:
7 This section describes the IPython configuration system. This is based on
8 :mod:`traitlets.config`; see that documentation for more information
9 about the overall architecture.
297 10
298 11 Configuration file location
299 12 ===========================
@@ -305,7 +18,7 b' following algorithm:'
305 18
306 19 * If the ``ipython-dir`` command line flag is given, its value is used.
307 20
308 * If not, the value returned by :func:`IPython.utils.path.get_ipython_dir`
21 * If not, the value returned by :func:`IPython.paths.get_ipython_dir`
309 22 is used. This function will first look at the :envvar:`IPYTHONDIR`
310 23 environment variable and then default to :file:`~/.ipython`.
311 24 Historical support for the :envvar:`IPYTHON_DIR` environment variable will
@@ -400,167 +113,10 b' you create profiles with the name of one of our shipped profiles, these config'
400 113 files will be copied over instead of starting with the automatically generated
401 114 config files.
402 115
403 Security Files
404 --------------
405
406 If you are using the notebook, qtconsole, or parallel code, IPython stores
407 connection information in small JSON files in the active profile's security
408 directory. This directory is made private, so only you can see the files inside. If
409 you need to move connection files around to other computers, this is where they will
410 be. If you want your code to be able to open security files by name, we have a
411 convenience function :func:`IPython.utils.path.get_security_file`, which will return
412 the absolute path to a security file from its filename and [optionally] profile
413 name.
414
415 .. _startup_files:
416
417 Startup Files
418 -------------
419
420 If you want some code to be run at the beginning of every IPython session with
421 a particular profile, the easiest way is to add Python (``.py``) or
422 IPython (``.ipy``) scripts to your :file:`<profile>/startup` directory. Files
423 in this directory will always be executed as soon as the IPython shell is
424 constructed, and before any other code or scripts you have specified. If you
425 have multiple files in the startup directory, they will be run in
426 lexicographical order, so you can control the ordering by adding a '00-'
427 prefix.
428
429
430 .. _commandline:
431
432 Command-line arguments
433 ======================
434
435 IPython exposes *all* configurable options on the command-line. The command-line
436 arguments are generated from the Configurable traits of the classes associated
437 with a given Application. Configuring IPython from the command-line may look
438 very similar to an IPython config file
439
440 IPython applications use a parser called
441 :class:`~traitlets.config.loader.KeyValueLoader` to load values into a Config
442 object. Values are assigned in much the same way as in a config file:
443
444 .. code-block:: bash
445
446 $ ipython --InteractiveShell.use_readline=False --BaseIPythonApplication.profile='myprofile'
447
448 Is the same as adding:
116 IPython extends the config loader for Python files so that you can inherit
117 config from another profile. To do this, use a line like this in your Python
118 config file:
449 119
450 120 .. sourcecode:: python
451 121
452 c.InteractiveShell.use_readline=False
453 c.BaseIPythonApplication.profile='myprofile'
454
455 to your config file. Key/Value arguments *always* take a value, separated by '='
456 and no spaces.
457
458 Common Arguments
459 ----------------
460
461 Since the strictness and verbosity of the KVLoader above are not ideal for everyday
462 use, common arguments can be specified as flags_ or aliases_.
463
464 Flags and Aliases are handled by :mod:`argparse` instead, allowing for more flexible
465 parsing. In general, flags and aliases are prefixed by ``--``, except for those
466 that are single characters, in which case they can be specified with a single ``-``, e.g.:
467
468 .. code-block:: bash
469
470 $ ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg
471
472 Aliases
473 *******
474
475 For convenience, applications have a mapping of commonly used traits, so you don't have
476 to specify the whole class name:
477
478 .. code-block:: bash
479
480 $ ipython --profile myprofile
481 # and
482 $ ipython --profile='myprofile'
483 # are equivalent to
484 $ ipython --BaseIPythonApplication.profile='myprofile'
485
486 Flags
487 *****
488
489 Applications can also be passed **flags**. Flags are options that take no
490 arguments. They are simply wrappers for
491 setting one or more configurables with predefined values, often True/False.
492
493 For instance:
494
495 .. code-block:: bash
496
497 $ ipcontroller --debug
498 # is equivalent to
499 $ ipcontroller --Application.log_level=DEBUG
500 # and
501 $ ipython --matplotlib
502 # is equivalent to
503 $ ipython --matplotlib auto
504 # or
505 $ ipython --no-banner
506 # is equivalent to
507 $ ipython --TerminalIPythonApp.display_banner=False
508
509 Subcommands
510 -----------
511
512
513 Some IPython applications have **subcommands**. Subcommands are modeled after
514 :command:`git`, and are called with the form :command:`command subcommand
515 [...args]`. Currently, the QtConsole is a subcommand of terminal IPython:
516
517 .. code-block:: bash
518
519 $ ipython qtconsole --profile myprofile
520
521 and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
522 stop, engines).
523
524 .. code-block:: bash
525
526 $ ipcluster start --profile=myprofile -n 4
527
528
529 To see a list of the available aliases, flags, and subcommands for an IPython application, simply pass ``-h`` or ``--help``. And to see the full list of configurable options (*very* long), pass ``--help-all``.
530
531
532 Design requirements
533 ===================
534
535 Here are the main requirements we wanted our configuration system to have:
536
537 * Support for hierarchical configuration information.
538
539 * Full integration with command line option parsers. Often, you want to read
540 a configuration file, but then override some of the values with command line
541 options. Our configuration system automates this process and allows each
542 command line option to be linked to a particular attribute in the
543 configuration hierarchy that it will override.
544
545 * Configuration files that are themselves valid Python code. This accomplishes
546 many things. First, it becomes possible to put logic in your configuration
547 files that sets attributes based on your operating system, network setup,
548 Python version, etc. Second, Python has a super simple syntax for accessing
549 hierarchical data structures, namely regular attribute access
550 (``Foo.Bar.Bam.name``). Third, using Python makes it easy for users to
551 import configuration attributes from one configuration file to another.
552 Fourth, even though Python is dynamically typed, it does have types that can
553 be checked at runtime. Thus, a ``1`` in a config file is the integer '1',
554 while a ``'1'`` is a string.
555
556 * A fully automated method for getting the configuration information to the
557 classes that need it at runtime. Writing code that walks a configuration
558 hierarchy to extract a particular attribute is painful. When you have
559 complex configuration information with hundreds of attributes, this makes
560 you want to cry.
561
562 * Type checking and validation that doesn't require the entire configuration
563 hierarchy to be specified statically before runtime. Python is a very
564 dynamic language and you don't always know everything that needs to be
565 configured when a program starts.
566
122 load_subconfig('ipython_config.py', profile='default')
General Comments 0
You need to be logged in to leave comments. Login now