##// END OF EJS Templates
update config docs with recent changes...
MinRK -
Show More
@@ -46,7 +46,7 b' There are two ways you can tell IPython to use your extension:'
46 To load an extension called :file:`myextension.py` add the following logic
46 To load an extension called :file:`myextension.py` add the following logic
47 to your configuration file::
47 to your configuration file::
48
48
49 c.Global.extensions = [
49 c.InteractiveShellApp.extensions = [
50 'myextension'
50 'myextension'
51 ]
51 ]
52
52
@@ -15,63 +15,74 b' can configure the application. A sample is provided in'
15 :mod:`IPython.config.default.ipython_config`. Simply copy this file to your
15 :mod:`IPython.config.default.ipython_config`. Simply copy this file to your
16 :ref:`IPython directory <ipython_dir>` to start using it.
16 :ref:`IPython directory <ipython_dir>` to start using it.
17
17
18 Most configuration attributes that this file accepts are associated with
18 Most configuration attributes that this file accepts are associated with classes
19 classes that are subclasses of :class:`~IPython.core.component.Component`.
19 that are subclasses of :class:`~IPython.config.configurable.Configurable`.
20
20
21 A few configuration attributes are not associated with a particular
21 Applications themselves are Configurable as well, so we will start with some
22 :class:`~IPython.core.component.Component` subclass. These are application
22 application-level config.
23 wide configuration attributes and are stored in the ``Global``
24 sub-configuration section. We begin with a description of these
25 attributes.
26
23
27 Global configuration
24 Application-level configuration
28 ====================
25 ===============================
29
26
30 Assuming that your configuration file has the following at the top::
27 Assuming that your configuration file has the following at the top::
31
28
32 c = get_config()
29 c = get_config()
33
30
34 the following attributes can be set in the ``Global`` section.
31 the following attributes are set application-wide:
35
32
36 :attr:`c.IPythonApp.display_banner`
33 terminal IPython-only flags:
34
35 :attr:`c.TerminalIPythonApp.display_banner`
37 A boolean that determined if the banner is printer when :command:`ipython`
36 A boolean that determined if the banner is printer when :command:`ipython`
38 is started.
37 is started.
39
38
40 :attr:`c.IPythonApp.classic`
39 :attr:`c.TerminalIPythonApp.classic`
41 A boolean that determines if IPython starts in "classic" mode. In this
40 A boolean that determines if IPython starts in "classic" mode. In this
42 mode, the prompts and everything mimic that of the normal :command:`python`
41 mode, the prompts and everything mimic that of the normal :command:`python`
43 shell
42 shell
44
43
45 :attr:`c.IPythonApp.nosep`
44 :attr:`c.TerminalIPythonApp.nosep`
46 A boolean that determines if there should be no blank lines between
45 A boolean that determines if there should be no blank lines between
47 prompts.
46 prompts.
48
47
49 :attr:`c.IPythonApp.log_level`
48 :attr:`c.Application.log_level`
50 An integer that sets the detail of the logging level during the startup
49 An integer that sets the detail of the logging level during the startup
51 of :command:`ipython`. The default is 30 and the possible values are
50 of :command:`ipython`. The default is 30 and the possible values are
52 (0, 10, 20, 30, 40, 50). Higher is quieter and lower is more verbose.
51 (0, 10, 20, 30, 40, 50). Higher is quieter and lower is more verbose.
52 This can also be set by the name of the logging level, e.g. INFO=20,
53 WARN=30.
54
55 Some options, such as extensions and startup code, can be set for any
56 application that starts an
57 :class:`~IPython.core.interactiveshell.InteractiveShell`. These apps are
58 subclasses of :class:`~IPython.core.shellapp.InteractiveShellApp`. Since
59 subclasses inherit configuration, setting a trait of
60 :attr:`c.InteractiveShellApp` will affect all IPython applications, but if you
61 want terminal IPython and the QtConsole to have different values, you can set
62 them via :attr:`c.TerminalIPythonApp` and :attr:`c.IPKernelApp` respectively.
63
53
64
54 :attr:`c.IPythonApp.extensions`
65 :attr:`c.InteractiveShellApp.extensions`
55 A list of strings, each of which is an importable IPython extension. An
66 A list of strings, each of which is an importable IPython extension. An
56 IPython extension is a regular Python module or package that has a
67 IPython extension is a regular Python module or package that has a
57 :func:`load_ipython_extension(ip)` method. This method gets called when
68 :func:`load_ipython_extension(ip)` method. This method gets called when
58 the extension is loaded with the currently running
69 the extension is loaded with the currently running
59 :class:`~IPython.core.iplib.InteractiveShell` as its only argument. You
70 :class:`~IPython.core.interactiveshell.InteractiveShell` as its only
60 can put your extensions anywhere they can be imported but we add the
71 argument. You can put your extensions anywhere they can be imported but we
61 :file:`extensions` subdirectory of the ipython directory to ``sys.path``
72 add the :file:`extensions` subdirectory of the ipython directory to
62 during extension loading, so you can put them there as well. Extensions
73 ``sys.path`` during extension loading, so you can put them there as well.
63 are not executed in the user's interactive namespace and they must be pure
74 Extensions are not executed in the user's interactive namespace and they
64 Python code. Extensions are the recommended way of customizing
75 must be pure Python code. Extensions are the recommended way of customizing
65 :command:`ipython`. Extensions can provide an
76 :command:`ipython`. Extensions can provide an
66 :func:`unload_ipython_extension` that will be called when the extension is
77 :func:`unload_ipython_extension` that will be called when the extension is
67 unloaded.
78 unloaded.
68
79
69 :attr:`c.IPythonApp.exec_lines`
80 :attr:`c.InteractiveShellApp.exec_lines`
70 A list of strings, each of which is Python code that is run in the user's
81 A list of strings, each of which is Python code that is run in the user's
71 namespace after IPython start. These lines can contain full IPython syntax
82 namespace after IPython start. These lines can contain full IPython syntax
72 with magics, etc.
83 with magics, etc.
73
84
74 :attr:`c.IPythonApp.exec_files`
85 :attr:`c.InteractiveShellApp.exec_files`
75 A list of strings, each of which is the full pathname of a ``.py`` or
86 A list of strings, each of which is the full pathname of a ``.py`` or
76 ``.ipy`` file that will be executed as IPython starts. These files are run
87 ``.ipy`` file that will be executed as IPython starts. These files are run
77 in IPython in the user's namespace. Files with a ``.py`` extension need to
88 in IPython in the user's namespace. Files with a ``.py`` extension need to
@@ -85,7 +96,7 b' Classes that can be configured'
85 The following classes can also be configured in the configuration file for
96 The following classes can also be configured in the configuration file for
86 :command:`ipython`:
97 :command:`ipython`:
87
98
88 * :class:`~IPython.core.iplib.InteractiveShell`
99 * :class:`~IPython.core.interactiveshell.InteractiveShell`
89
100
90 * :class:`~IPython.core.prefilter.PrefilterManager`
101 * :class:`~IPython.core.prefilter.PrefilterManager`
91
102
@@ -105,16 +116,16 b' attributes::'
105 # sample ipython_config.py
116 # sample ipython_config.py
106 c = get_config()
117 c = get_config()
107
118
108 c.IPythonApp.display_banner = True
119 c.IPythonTerminalApp.display_banner = True
109 c.IPythonApp.log_level = 20
120 c.InteractiveShellApp.log_level = 20
110 c.IPythonApp.extensions = [
121 c.InteractiveShellApp.extensions = [
111 'myextension'
122 'myextension'
112 ]
123 ]
113 c.IPythonApp.exec_lines = [
124 c.InteractiveShellApp.exec_lines = [
114 'import numpy',
125 'import numpy',
115 'import scipy'
126 'import scipy'
116 ]
127 ]
117 c.IPythonApp.exec_files = [
128 c.InteractiveShellApp.exec_files = [
118 'mycode.py',
129 'mycode.py',
119 'fancy.ipy'
130 'fancy.ipy'
120 ]
131 ]
@@ -18,8 +18,8 b' met our requirements.'
18 your old :file:`ipythonrc` or :file:`ipy_user_conf.py` configuration files
18 your old :file:`ipythonrc` or :file:`ipy_user_conf.py` configuration files
19 to the new system. Read on for information on how to do this.
19 to the new system. Read on for information on how to do this.
20
20
21 The discussion that follows is focused on teaching user's how to configure
21 The discussion that follows is focused on teaching users how to configure
22 IPython to their liking. Developer's who want to know more about how they
22 IPython to their liking. Developers who want to know more about how they
23 can enable their objects to take advantage of the configuration system
23 can enable their objects to take advantage of the configuration system
24 should consult our :ref:`developer guide <developer_guide>`
24 should consult our :ref:`developer guide <developer_guide>`
25
25
@@ -37,16 +37,20 b' Configuration object: :class:`~IPython.config.loader.Config`'
37 are smart. They know how to merge themselves with other configuration
37 are smart. They know how to merge themselves with other configuration
38 objects and they automatically create sub-configuration objects.
38 objects and they automatically create sub-configuration objects.
39
39
40 Application: :class:`~IPython.core.application.Application`
40 Application: :class:`~IPython.config.application.Application`
41 An application is a process that does a specific job. The most obvious
41 An application is a process that does a specific job. The most obvious
42 application is the :command:`ipython` command line program. Each
42 application is the :command:`ipython` command line program. Each
43 application reads a *single* configuration file and command line options
43 application reads *one or more* configuration files and a single set of
44 command line options
44 and then produces a master configuration object for the application. This
45 and then produces a master configuration object for the application. This
45 configuration object is then passed to the configurable objects that the
46 configuration object is then passed to the configurable objects that the
46 application creates. These configurable objects implement the actual logic
47 application creates. These configurable objects implement the actual logic
47 of the application and know how to configure themselves given the
48 of the application and know how to configure themselves given the
48 configuration object.
49 configuration object.
49
50
51 Applications always have a `log` attribute that is a configured Logger.
52 This allows centralized logging configuration per-application.
53
50 Component: :class:`~IPython.config.configurable.Configurable`
54 Component: :class:`~IPython.config.configurable.Configurable`
51 A configurable is a regular Python class that serves as a base class for
55 A configurable is a regular Python class that serves as a base class for
52 all main classes in an application. The
56 all main classes in an application. The
@@ -64,6 +68,25 b' Component: :class:`~IPython.config.configurable.Configurable`'
64 these subclasses has its own configuration information that controls how
68 these subclasses has its own configuration information that controls how
65 instances are created.
69 instances are created.
66
70
71 Singletons: :class:`~IPython.config.configurable.SingletonConfigurable`
72 Any object for which there is a single canonical instance. These are
73 just like Configurables, except they have a class method
74 :meth:`~IPython.config.configurable.SingletonConfigurable.instance`,
75 that returns the current active instance (or creates one if it
76 does not exist). Examples of singletons include
77 :class:`~IPython.config.application.Application`s and
78 :class:`~IPython.core.interactiveshell.InteractiveShell`. This lets
79 objects easily connect to the current running Application without passing
80 objects around everywhere. For instance, to get the current running
81 Application instance, simply do: ``app = Application.instance()``.
82
83
84 .. note::
85
86 Singletons are not strictly enforced - you can have many instances
87 of a given singleton class, but the :meth:`instance` method will always
88 return the same one.
89
67 Having described these main concepts, we can now state the main idea in our
90 Having described these main concepts, we can now state the main idea in our
68 configuration system: *"configuration" allows the default values of class
91 configuration system: *"configuration" allows the default values of class
69 attributes to be controlled on a class by class basis*. Thus all instances of
92 attributes to be controlled on a class by class basis*. Thus all instances of
@@ -106,7 +129,7 b' subclass::'
106 from IPython.utils.traitlets import Int, Float, Str, Bool
129 from IPython.utils.traitlets import Int, Float, Str, Bool
107
130
108 class MyClass(Configurable):
131 class MyClass(Configurable):
109 name = Str('defaultname', config=True)
132 name = Unicode(u'defaultname', config=True)
110 ranking = Int(0, config=True)
133 ranking = Int(0, config=True)
111 value = Float(99.0)
134 value = Float(99.0)
112 # The rest of the class implementation would go here..
135 # The rest of the class implementation would go here..
@@ -197,6 +220,15 b' search path for sub-configuration files is inherited from that of the parent.'
197 Thus, you can typically put the two in the same directory and everything will
220 Thus, you can typically put the two in the same directory and everything will
198 just work.
221 just work.
199
222
223 You can also load configuration files by profile, for instance:
224
225 .. sourcecode:: python
226
227 load_subconfig('ipython_config.py', profile='default')
228
229 to inherit your default configuration as a starting point.
230
231
200 Class based configuration inheritance
232 Class based configuration inheritance
201 =====================================
233 =====================================
202
234
@@ -241,9 +273,10 b' This class hierarchy and configuration file accomplishes the following:'
241 Configuration file location
273 Configuration file location
242 ===========================
274 ===========================
243
275
244 So where should you put your configuration files? By default, all IPython
276 So where should you put your configuration files? IPython uses "profiles" for
245 applications look in the so called "IPython directory". The location of
277 configuration, and by default, all profiles will be stored in the so called
246 this directory is determined by the following algorithm:
278 "IPython directory". The location of this directory is determined by the
279 following algorithm:
247
280
248 * If the ``ipython_dir`` command line flag is given, its value is used.
281 * If the ``ipython_dir`` command line flag is given, its value is used.
249
282
@@ -263,26 +296,41 b' For most users, the default value will simply be something like'
263 :file:`$HOME/.config/ipython` on Linux, or :file:`$HOME/.ipython`
296 :file:`$HOME/.config/ipython` on Linux, or :file:`$HOME/.ipython`
264 elsewhere.
297 elsewhere.
265
298
266 Once the location of the IPython directory has been determined, you need to
299 Once the location of the IPython directory has been determined, you need to know
267 know what filename to use for the configuration file. The basic idea is that
300 which profile you are using. For users with a single configuration, this will
268 each application has its own default configuration filename. The default named
301 simply be 'default', and will be located in
269 used by the :command:`ipython` command line program is
302 :file:`<IPYTHON_DIR>/profile_default`.
270 :file:`ipython_config.py`. This value can be overriden by the ``config_file``
303
271 command line flag. A sample :file:`ipython_config.py` file can be found
304 The next thing you need to know is what to call your configuration file. The
272 in :mod:`IPython.config.default.ipython_config.py`. Simple copy it to your
305 basic idea is that each application has its own default configuration filename.
273 IPython directory to begin using it.
306 The default named used by the :command:`ipython` command line program is
307 :file:`ipython_config.py`, and *all* IPython applications will use this file.
308 Other applications, such as the parallel :command:`ipcluster` scripts or the
309 QtConsole will load their own config files *after* :file:`ipython_config.py`. To
310 load a particular configuration file instead of the default, the name can be
311 overridden by the ``config_file`` command line flag.
312
313 To generate the default configuration files, do::
314
315 $> ipython profile create
316
317 and you will have a default :file:`ipython_config.py` in your IPython directory
318 under :file:`profile_default`. If you want the default config files for the
319 :mod:`IPython.parallel` applications, add ``--parallel`` to the end of the
320 command-line args.
274
321
275 .. _Profiles:
322 .. _Profiles:
276
323
277 Profiles
324 Profiles
278 ========
325 ========
279
326
280 A profile is simply a configuration file that follows a simple naming
327 A profile is a directory containing configuration and runtime files, such as
281 convention and can be loaded using a simplified syntax. The idea is
328 logs, connection info for the parallel apps, and your IPython command history.
282 that users often want to maintain a set of configuration files for different
329
283 purposes: one for doing numerical computing with NumPy and SciPy and
330 The idea is that users often want to maintain a set of configuration files for
284 another for doing symbolic computing with SymPy. Profiles make it easy
331 different purposes: one for doing numerical computing with NumPy and SciPy and
285 to keep a separate configuration file for each of these purposes.
332 another for doing symbolic computing with SymPy. Profiles make it easy to keep a
333 separate configuration files, logs, and histories for each of these purposes.
286
334
287 Let's start by showing how a profile is used:
335 Let's start by showing how a profile is used:
288
336
@@ -290,18 +338,107 b" Let's start by showing how a profile is used:"
290
338
291 $ ipython profile=sympy
339 $ ipython profile=sympy
292
340
293 This tells the :command:`ipython` command line program to get its
341 This tells the :command:`ipython` command line program to get its configuration
294 configuration from the "sympy" profile. The search path for profiles is the
342 from the "sympy" profile. The file names for various profiles do not change. The
295 same as that of regular configuration files. The only difference is that
343 only difference is that profiles are named in a special way. In the case above,
296 profiles are named in a special way. In the case above, the "sympy" profile
344 the "sympy" profile means looking for :file:`ipython_config.py` in :file:`<IPYTHON_DIR>/profile_sympy`.
297 would need to have the name :file:`ipython_config_sympy.py`.
345
346 The general pattern is this: simply create a new profile with:
347
348 .. code-block:: bash
349
350 ipython profile create <name>
351
352 which adds a directory called ``profile_<name>`` to your IPython directory. Then
353 you can load this profile by adding ``profile=<name>`` to your command line
354 options. Profiles are supported by all IPython applications.
355
356 IPython ships with some sample profiles in :file:`IPython/config/profile`. If
357 you create profiles with the name of one of our shipped profiles, these config
358 files will be copied over instead of starting with the automatically generated
359 config files.
360
361 .. _commandline:
362
363 Command-line arguments
364 ======================
365
366 IPython exposes *all* configurable options on the command-line. The command-line
367 arguments are generated from the Configurable traits of the classes associated
368 with a given Application. Configuring IPython from the command-line may look
369 very similar to an IPython config file
370
371 IPython applications use a parser called
372 :class:`~IPython.config.loader.KeyValueLoader` to load values into a Config
373 object. Values are assigned in much the same way as in a config file:
374
375 .. code-block:: bash
376
377 $> ipython InteractiveShell.use_readline=False BaseIPythonApplication.profile='myprofile'
378
379 Is the same as adding:
380
381 .. sourcecode:: python
382
383 c.InteractiveShell.use_readline=False
384 c.BaseIPythonApplication.profile='myprofile'
385
386 to your config file. Key/Value arguments *always* take a value, separated by '='
387 and no spaces.
388
389 Aliases
390 -------
391
392 For convenience, applications have a mapping of commonly
393 used traits, so you don't have to specify the whole class name. For these **aliases**, the class need not be specified:
394
395 .. code-block:: bash
396
397 $> ipython profile='myprofile'
398 # is equivalent to
399 $> ipython BaseIPythonApplication.profile='myprofile'
400
401 Flags
402 -----
403
404 Applications can also be passed **flags**. Flags are options that take no
405 arguments, and are always prefixed with ``--``. They are simply wrappers for
406 setting one or more configurables with predefined values, often True/False.
407
408 For instance:
409
410 .. code-block:: bash
411
412 $> ipcontroller --debug
413 # is equivalent to
414 $> ipcontroller Application.log_level=DEBUG
415 # and
416 $> ipython --pylab
417 # is equivalent to
418 $> ipython pylab=auto
419
420 Subcommands
421 -----------
422
423
424 Some IPython applications have **subcommands**. Subcommands are modeled after
425 :command:`git`, and are called with the form :command:`command subcommand
426 [...args]`. Currently, the QtConsole is a subcommand of terminal IPython:
427
428 .. code-block:: bash
429
430 $> ipython qtconsole profile=myprofile
431
432 and :command:`ipcluster` is simply a wrapper for its various subcommands (start,
433 stop, engines).
434
435 .. code-block:: bash
436
437 $> ipcluster start profile=myprofile n=4
438
298
439
299 The general pattern is this: simply add ``<profilename>`` to the end of the
440 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``.
300 normal configuration file name. Then load the profile by adding
301 ``profile=<profilename>`` to your command line options.
302
441
303 IPython ships with some sample profiles in :mod:`IPython.config.profile`.
304 Simply copy these to your IPython directory to begin using them.
305
442
306 Design requirements
443 Design requirements
307 ===================
444 ===================
@@ -23,4 +23,3 b" IPython developer's guide"
23 ipgraph.txt
23 ipgraph.txt
24 ipython_qt.txt
24 ipython_qt.txt
25 ipythonzmq.txt
25 ipythonzmq.txt
26 parallelzmq.txt
General Comments 0
You need to be logged in to leave comments. Login now