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. |
|
84 | These map to the utility functions: :func:`IPython.paths.get_ipython_dir` | |
85 |
and :func:`IPython. |
|
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