##// END OF EJS Templates
fix function references for get_ipython_dir and locate_profile
Kai Tetzlaff (moka.tetzco.de) -
Show More
@@ -1,128 +1,128 b''
1 .. _config_overview:
1 .. _config_overview:
2
2
3 ============================================
3 ============================================
4 Overview of the IPython configuration system
4 Overview of the IPython configuration system
5 ============================================
5 ============================================
6
6
7 This section describes the IPython configuration system. This is based on
7 This section describes the IPython configuration system. This is based on
8 :mod:`traitlets.config`; see that documentation for more information
8 :mod:`traitlets.config`; see that documentation for more information
9 about the overall architecture.
9 about the overall architecture.
10
10
11 Configuration file location
11 Configuration file location
12 ===========================
12 ===========================
13
13
14 So where should you put your configuration files? IPython uses "profiles" for
14 So where should you put your configuration files? IPython uses "profiles" for
15 configuration, and by default, all profiles will be stored in the so called
15 configuration, and by default, all profiles will be stored in the so called
16 "IPython directory". The location of this directory is determined by the
16 "IPython directory". The location of this directory is determined by the
17 following algorithm:
17 following algorithm:
18
18
19 * If the ``ipython-dir`` command line flag is given, its value is used.
19 * If the ``ipython-dir`` command line flag is given, its value is used.
20
20
21 * If not, the value returned by :func:`IPython.paths.get_ipython_dir`
21 * If not, the value returned by :func:`IPython.paths.get_ipython_dir`
22 is used. This function will first look at the :envvar:`IPYTHONDIR`
22 is used. This function will first look at the :envvar:`IPYTHONDIR`
23 environment variable and then default to :file:`~/.ipython`.
23 environment variable and then default to :file:`~/.ipython`.
24 Historical support for the :envvar:`IPYTHON_DIR` environment variable will
24 Historical support for the :envvar:`IPYTHON_DIR` environment variable will
25 be removed in a future release.
25 be removed in a future release.
26
26
27 For most users, the configuration directory will be :file:`~/.ipython`.
27 For most users, the configuration directory will be :file:`~/.ipython`.
28
28
29 Previous versions of IPython on Linux would use the XDG config directory,
29 Previous versions of IPython on Linux would use the XDG config directory,
30 creating :file:`~/.config/ipython` by default. We have decided to go
30 creating :file:`~/.config/ipython` by default. We have decided to go
31 back to :file:`~/.ipython` for consistency among systems. IPython will
31 back to :file:`~/.ipython` for consistency among systems. IPython will
32 issue a warning if it finds the XDG location, and will move it to the new
32 issue a warning if it finds the XDG location, and will move it to the new
33 location if there isn't already a directory there.
33 location if there isn't already a directory there.
34
34
35 Once the location of the IPython directory has been determined, you need to know
35 Once the location of the IPython directory has been determined, you need to know
36 which profile you are using. For users with a single configuration, this will
36 which profile you are using. For users with a single configuration, this will
37 simply be 'default', and will be located in
37 simply be 'default', and will be located in
38 :file:`<IPYTHONDIR>/profile_default`.
38 :file:`<IPYTHONDIR>/profile_default`.
39
39
40 The next thing you need to know is what to call your configuration file. The
40 The next thing you need to know is what to call your configuration file. The
41 basic idea is that each application has its own default configuration filename.
41 basic idea is that each application has its own default configuration filename.
42 The default named used by the :command:`ipython` command line program is
42 The default named used by the :command:`ipython` command line program is
43 :file:`ipython_config.py`, and *all* IPython applications will use this file.
43 :file:`ipython_config.py`, and *all* IPython applications will use this file.
44 The IPython kernel will load its own config file *after*
44 The IPython kernel will load its own config file *after*
45 :file:`ipython_config.py`. To load a particular configuration file instead of
45 :file:`ipython_config.py`. To load a particular configuration file instead of
46 the default, the name can be overridden by the ``config_file`` command line
46 the default, the name can be overridden by the ``config_file`` command line
47 flag.
47 flag.
48
48
49 To generate the default configuration files, do::
49 To generate the default configuration files, do::
50
50
51 $ ipython profile create
51 $ ipython profile create
52
52
53 and you will have a default :file:`ipython_config.py` in your IPython directory
53 and you will have a default :file:`ipython_config.py` in your IPython directory
54 under :file:`profile_default`.
54 under :file:`profile_default`.
55
55
56 .. note::
56 .. note::
57
57
58 IPython configuration options are case sensitive, and IPython cannot
58 IPython configuration options are case sensitive, and IPython cannot
59 catch misnamed keys or invalid values.
59 catch misnamed keys or invalid values.
60
60
61 By default IPython will also ignore any invalid configuration files.
61 By default IPython will also ignore any invalid configuration files.
62
62
63 .. versionadded:: 5.0
63 .. versionadded:: 5.0
64
64
65 IPython can be configured to abort in case of invalid configuration file.
65 IPython can be configured to abort in case of invalid configuration file.
66 To do so set the environment variable ``IPYTHON_SUPPRESS_CONFIG_ERRORS`` to
66 To do so set the environment variable ``IPYTHON_SUPPRESS_CONFIG_ERRORS`` to
67 `'1'` or `'true'`
67 `'1'` or `'true'`
68
68
69
69
70 Locating these files
70 Locating these files
71 --------------------
71 --------------------
72
72
73 From the command-line, you can quickly locate the IPYTHONDIR or a specific
73 From the command-line, you can quickly locate the IPYTHONDIR or a specific
74 profile with:
74 profile with:
75
75
76 .. sourcecode:: bash
76 .. sourcecode:: bash
77
77
78 $ ipython locate
78 $ ipython locate
79 /home/you/.ipython
79 /home/you/.ipython
80
80
81 $ ipython locate profile foo
81 $ ipython locate profile foo
82 /home/you/.ipython/profile_foo
82 /home/you/.ipython/profile_foo
83
83
84 These map to the utility functions: :func:`IPython.utils.path.get_ipython_dir`
84 These map to the utility functions: :func:`IPython.paths.get_ipython_dir`
85 and :func:`IPython.utils.path.locate_profile` respectively.
85 and :func:`IPython.paths.locate_profile` respectively.
86
86
87
87
88 .. _profiles_dev:
88 .. _profiles_dev:
89
89
90 Profiles
90 Profiles
91 ========
91 ========
92
92
93 A profile is a directory containing configuration and runtime files, such as
93 A profile is a directory containing configuration and runtime files, such as
94 logs, connection info for the parallel apps, and your IPython command history.
94 logs, connection info for the parallel apps, and your IPython command history.
95
95
96 The idea is that users often want to maintain a set of configuration files for
96 The idea is that users often want to maintain a set of configuration files for
97 different purposes: one for doing numerical computing with NumPy and SciPy and
97 different purposes: one for doing numerical computing with NumPy and SciPy and
98 another for doing symbolic computing with SymPy. Profiles make it easy to keep a
98 another for doing symbolic computing with SymPy. Profiles make it easy to keep a
99 separate configuration files, logs, and histories for each of these purposes.
99 separate configuration files, logs, and histories for each of these purposes.
100
100
101 Let's start by showing how a profile is used:
101 Let's start by showing how a profile is used:
102
102
103 .. code-block:: bash
103 .. code-block:: bash
104
104
105 $ ipython --profile=sympy
105 $ ipython --profile=sympy
106
106
107 This tells the :command:`ipython` command line program to get its configuration
107 This tells the :command:`ipython` command line program to get its configuration
108 from the "sympy" profile. The file names for various profiles do not change. The
108 from the "sympy" profile. The file names for various profiles do not change. The
109 only difference is that profiles are named in a special way. In the case above,
109 only difference is that profiles are named in a special way. In the case above,
110 the "sympy" profile means looking for :file:`ipython_config.py` in :file:`<IPYTHONDIR>/profile_sympy`.
110 the "sympy" profile means looking for :file:`ipython_config.py` in :file:`<IPYTHONDIR>/profile_sympy`.
111
111
112 The general pattern is this: simply create a new profile with:
112 The general pattern is this: simply create a new profile with:
113
113
114 .. code-block:: bash
114 .. code-block:: bash
115
115
116 $ ipython profile create <name>
116 $ ipython profile create <name>
117
117
118 which adds a directory called ``profile_<name>`` to your IPython directory. Then
118 which adds a directory called ``profile_<name>`` to your IPython directory. Then
119 you can load this profile by adding ``--profile=<name>`` to your command line
119 you can load this profile by adding ``--profile=<name>`` to your command line
120 options. Profiles are supported by all IPython applications.
120 options. Profiles are supported by all IPython applications.
121
121
122 IPython extends the config loader for Python files so that you can inherit
122 IPython extends the config loader for Python files so that you can inherit
123 config from another profile. To do this, use a line like this in your Python
123 config from another profile. To do this, use a line like this in your Python
124 config file:
124 config file:
125
125
126 .. sourcecode:: python
126 .. sourcecode:: python
127
127
128 load_subconfig('ipython_config.py', profile='default')
128 load_subconfig('ipython_config.py', profile='default')
General Comments 0
You need to be logged in to leave comments. Login now