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