Show More
@@ -1,253 +1,255 b'' | |||
|
1 | 1 | # -*- coding: utf-8 -*- |
|
2 | 2 | # |
|
3 | 3 | # IPython documentation build configuration file. |
|
4 | 4 | |
|
5 | 5 | # NOTE: This file has been edited manually from the auto-generated one from |
|
6 | 6 | # sphinx. Do NOT delete and re-generate. If any changes from sphinx are |
|
7 | 7 | # needed, generate a scratch one and merge by hand any new fields needed. |
|
8 | 8 | |
|
9 | 9 | # |
|
10 | 10 | # This file is execfile()d with the current directory set to its containing dir. |
|
11 | 11 | # |
|
12 | 12 | # The contents of this file are pickled, so don't put values in the namespace |
|
13 | 13 | # that aren't pickleable (module imports are okay, they're removed automatically). |
|
14 | 14 | # |
|
15 | 15 | # All configuration values have a default value; values that are commented out |
|
16 | 16 | # serve to show the default value. |
|
17 | 17 | |
|
18 | 18 | import sys, os |
|
19 | 19 | |
|
20 | 20 | ON_RTD = os.environ.get('READTHEDOCS', None) == 'True' |
|
21 | 21 | |
|
22 | 22 | if ON_RTD: |
|
23 | 23 | # Mock the presence of matplotlib, which we don't have on RTD |
|
24 | 24 | # see |
|
25 | 25 | # http://read-the-docs.readthedocs.org/en/latest/faq.html |
|
26 | 26 | tags.add('rtd') |
|
27 | 27 | |
|
28 | 28 | # If your extensions are in another directory, add it here. If the directory |
|
29 | 29 | # is relative to the documentation root, use os.path.abspath to make it |
|
30 | 30 | # absolute, like shown here. |
|
31 | 31 | sys.path.insert(0, os.path.abspath('../sphinxext')) |
|
32 | 32 | |
|
33 | 33 | # We load the ipython release info into a dict by explicit execution |
|
34 | 34 | iprelease = {} |
|
35 | 35 | exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease) |
|
36 | 36 | |
|
37 | 37 | # General configuration |
|
38 | 38 | # --------------------- |
|
39 | 39 | |
|
40 | 40 | # Add any Sphinx extension module names here, as strings. They can be extensions |
|
41 | 41 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
|
42 | 42 | extensions = [ |
|
43 | 43 | 'matplotlib.sphinxext.mathmpl', |
|
44 | 44 | 'matplotlib.sphinxext.only_directives', |
|
45 | 45 | 'matplotlib.sphinxext.plot_directive', |
|
46 | 46 | 'sphinx.ext.autodoc', |
|
47 | 47 | 'sphinx.ext.autosummary', |
|
48 | 48 | 'sphinx.ext.doctest', |
|
49 | 49 | 'sphinx.ext.inheritance_diagram', |
|
50 | 50 | 'sphinx.ext.intersphinx', |
|
51 | 51 | 'IPython.sphinxext.ipython_console_highlighting', |
|
52 | 52 | 'IPython.sphinxext.ipython_directive', |
|
53 | 53 | 'numpydoc', # to preprocess docstrings |
|
54 | 54 | 'github', # for easy GitHub links |
|
55 | 55 | 'magics', |
|
56 | 56 | ] |
|
57 | 57 | |
|
58 | 58 | if ON_RTD: |
|
59 | 59 | # Remove extensions not currently supported on RTD |
|
60 | 60 | extensions.remove('matplotlib.sphinxext.only_directives') |
|
61 | 61 | extensions.remove('matplotlib.sphinxext.mathmpl') |
|
62 | 62 | extensions.remove('matplotlib.sphinxext.plot_directive') |
|
63 | 63 | extensions.remove('IPython.sphinxext.ipython_directive') |
|
64 | 64 | extensions.remove('IPython.sphinxext.ipython_console_highlighting') |
|
65 | 65 | |
|
66 | 66 | # Add any paths that contain templates here, relative to this directory. |
|
67 | 67 | templates_path = ['_templates'] |
|
68 | 68 | |
|
69 | 69 | # The suffix of source filenames. |
|
70 | 70 | source_suffix = '.rst' |
|
71 | 71 | |
|
72 | 72 | if iprelease['_version_extra'] == 'dev': |
|
73 | 73 | rst_prolog = """ |
|
74 | 74 | .. note:: |
|
75 | 75 | |
|
76 | 76 | This documentation is for a development version of IPython. There may be |
|
77 | 77 | significant differences from the latest stable release. |
|
78 | 78 | |
|
79 | 79 | """ |
|
80 | 80 | |
|
81 | 81 | # The master toctree document. |
|
82 | 82 | master_doc = 'index' |
|
83 | 83 | |
|
84 | 84 | # General substitutions. |
|
85 | 85 | project = 'IPython' |
|
86 | 86 | copyright = 'The IPython Development Team' |
|
87 | 87 | |
|
88 | 88 | # ghissue config |
|
89 | 89 | github_project_url = "https://github.com/ipython/ipython" |
|
90 | 90 | |
|
91 | 91 | # numpydoc config |
|
92 | 92 | numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings |
|
93 | 93 | numpydoc_class_members_toctree = False |
|
94 | 94 | |
|
95 | 95 | # The default replacements for |version| and |release|, also used in various |
|
96 | 96 | # other places throughout the built documents. |
|
97 | 97 | # |
|
98 | 98 | # The full version, including alpha/beta/rc tags. |
|
99 | 99 | release = "%s" % iprelease['version'] |
|
100 | 100 | # Just the X.Y.Z part, no '-dev' |
|
101 | 101 | version = iprelease['version'].split('-', 1)[0] |
|
102 | 102 | |
|
103 | 103 | |
|
104 | 104 | # There are two options for replacing |today|: either, you set today to some |
|
105 | 105 | # non-false value, then it is used: |
|
106 | 106 | #today = '' |
|
107 | 107 | # Else, today_fmt is used as the format for a strftime call. |
|
108 | 108 | today_fmt = '%B %d, %Y' |
|
109 | 109 | |
|
110 | 110 | # List of documents that shouldn't be included in the build. |
|
111 | 111 | #unused_docs = [] |
|
112 | 112 | |
|
113 | 113 | # Exclude these glob-style patterns when looking for source files. They are |
|
114 | 114 | # relative to the source/ directory. |
|
115 | 115 | exclude_patterns = ['whatsnew/pr'] |
|
116 | 116 | |
|
117 | 117 | |
|
118 | 118 | # If true, '()' will be appended to :func: etc. cross-reference text. |
|
119 | 119 | #add_function_parentheses = True |
|
120 | 120 | |
|
121 | 121 | # If true, the current module name will be prepended to all description |
|
122 | 122 | # unit titles (such as .. function::). |
|
123 | 123 | #add_module_names = True |
|
124 | 124 | |
|
125 | 125 | # If true, sectionauthor and moduleauthor directives will be shown in the |
|
126 | 126 | # output. They are ignored by default. |
|
127 | 127 | #show_authors = False |
|
128 | 128 | |
|
129 | 129 | # The name of the Pygments (syntax highlighting) style to use. |
|
130 | 130 | pygments_style = 'sphinx' |
|
131 | 131 | |
|
132 | 132 | # Set the default role so we can use `foo` instead of ``foo`` |
|
133 | 133 | default_role = 'literal' |
|
134 | 134 | |
|
135 | 135 | # Options for HTML output |
|
136 | 136 | # ----------------------- |
|
137 | 137 | |
|
138 | 138 | # The style sheet to use for HTML and HTML Help pages. A file of that name |
|
139 | 139 | # must exist either in Sphinx' static/ path, or in one of the custom paths |
|
140 | 140 | # given in html_static_path. |
|
141 | 141 | html_style = 'default.css' |
|
142 | 142 | |
|
143 | 143 | # The name for this set of Sphinx documents. If None, it defaults to |
|
144 | 144 | # "<project> v<release> documentation". |
|
145 | 145 | #html_title = None |
|
146 | 146 | |
|
147 | 147 | # The name of an image file (within the static path) to place at the top of |
|
148 | 148 | # the sidebar. |
|
149 | 149 | #html_logo = None |
|
150 | 150 | |
|
151 | 151 | # Add any paths that contain custom static files (such as style sheets) here, |
|
152 | 152 | # relative to this directory. They are copied after the builtin static files, |
|
153 | 153 | # so a file named "default.css" will overwrite the builtin "default.css". |
|
154 | 154 | html_static_path = ['_static'] |
|
155 | 155 | |
|
156 | 156 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
|
157 | 157 | # using the given strftime format. |
|
158 | 158 | html_last_updated_fmt = '%b %d, %Y' |
|
159 | 159 | |
|
160 | 160 | # If true, SmartyPants will be used to convert quotes and dashes to |
|
161 | 161 | # typographically correct entities. |
|
162 | 162 | #html_use_smartypants = True |
|
163 | 163 | |
|
164 | 164 | # Custom sidebar templates, maps document names to template names. |
|
165 | 165 | #html_sidebars = {} |
|
166 | 166 | |
|
167 | 167 | # Additional templates that should be rendered to pages, maps page names to |
|
168 | 168 | # template names. |
|
169 | 169 | html_additional_pages = { |
|
170 | 170 | 'interactive/htmlnotebook': 'notebook_redirect.html', |
|
171 | 171 | 'interactive/notebook': 'notebook_redirect.html', |
|
172 | 172 | 'interactive/nbconvert': 'notebook_redirect.html', |
|
173 | 173 | 'interactive/public_server': 'notebook_redirect.html', |
|
174 | 174 | } |
|
175 | 175 | |
|
176 | 176 | # If false, no module index is generated. |
|
177 | 177 | #html_use_modindex = True |
|
178 | 178 | |
|
179 | 179 | # If true, the reST sources are included in the HTML build as _sources/<name>. |
|
180 | 180 | #html_copy_source = True |
|
181 | 181 | |
|
182 | 182 | # If true, an OpenSearch description file will be output, and all pages will |
|
183 | 183 | # contain a <link> tag referring to it. The value of this option must be the |
|
184 | 184 | # base URL from which the finished HTML is served. |
|
185 | 185 | #html_use_opensearch = '' |
|
186 | 186 | |
|
187 | 187 | # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). |
|
188 | 188 | #html_file_suffix = '' |
|
189 | 189 | |
|
190 | 190 | # Output file base name for HTML help builder. |
|
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 | # ------------------------ |
|
198 | 200 | |
|
199 | 201 | # The paper size ('letter' or 'a4'). |
|
200 | 202 | latex_paper_size = 'letter' |
|
201 | 203 | |
|
202 | 204 | # The font size ('10pt', '11pt' or '12pt'). |
|
203 | 205 | latex_font_size = '11pt' |
|
204 | 206 | |
|
205 | 207 | # Grouping the document tree into LaTeX files. List of tuples |
|
206 | 208 | # (source start file, target name, title, author, document class [howto/manual]). |
|
207 | 209 | |
|
208 | 210 | latex_documents = [ |
|
209 | 211 | ('index', 'ipython.tex', 'IPython Documentation', |
|
210 | 212 | u"""The IPython Development Team""", 'manual', True), |
|
211 | 213 | ('parallel/winhpc_index', 'winhpc_whitepaper.tex', |
|
212 | 214 | 'Using IPython on Windows HPC Server 2008', |
|
213 | 215 | u"Brian E. Granger", 'manual', True) |
|
214 | 216 | ] |
|
215 | 217 | |
|
216 | 218 | # The name of an image file (relative to this directory) to place at the top of |
|
217 | 219 | # the title page. |
|
218 | 220 | #latex_logo = None |
|
219 | 221 | |
|
220 | 222 | # For "manual" documents, if this is true, then toplevel headings are parts, |
|
221 | 223 | # not chapters. |
|
222 | 224 | #latex_use_parts = False |
|
223 | 225 | |
|
224 | 226 | # Additional stuff for the LaTeX preamble. |
|
225 | 227 | #latex_preamble = '' |
|
226 | 228 | |
|
227 | 229 | # Documents to append as an appendix to all manuals. |
|
228 | 230 | #latex_appendices = [] |
|
229 | 231 | |
|
230 | 232 | # If false, no module index is generated. |
|
231 | 233 | latex_use_modindex = True |
|
232 | 234 | |
|
233 | 235 | |
|
234 | 236 | # Options for texinfo output |
|
235 | 237 | # -------------------------- |
|
236 | 238 | |
|
237 | 239 | texinfo_documents = [ |
|
238 | 240 | (master_doc, 'ipython', 'IPython Documentation', |
|
239 | 241 | 'The IPython Development Team', |
|
240 | 242 | 'IPython', |
|
241 | 243 | 'IPython Documentation', |
|
242 | 244 | 'Programming', |
|
243 | 245 | 1), |
|
244 | 246 | ] |
|
245 | 247 | |
|
246 | 248 | modindex_common_prefix = ['IPython.'] |
|
247 | 249 | |
|
248 | 250 | |
|
249 | 251 | # Cleanup |
|
250 | 252 | # ------- |
|
251 | 253 | # delete release info to avoid pickling errors from sphinx |
|
252 | 254 | |
|
253 | 255 | del iprelease |
@@ -1,156 +1,156 b'' | |||
|
1 | 1 | ===================================== |
|
2 | 2 | Introduction to IPython configuration |
|
3 | 3 | ===================================== |
|
4 | 4 | |
|
5 | 5 | .. _setting_config: |
|
6 | 6 | |
|
7 | 7 | Setting configurable options |
|
8 | 8 | ============================ |
|
9 | 9 | |
|
10 | 10 | Many of IPython's classes have configurable attributes (see |
|
11 | 11 | :doc:`options/index` for the list). These can be |
|
12 | 12 | configured in several ways. |
|
13 | 13 | |
|
14 | 14 | Python config files |
|
15 | 15 | ------------------- |
|
16 | 16 | |
|
17 | 17 | To create the blank config files, run:: |
|
18 | 18 | |
|
19 | 19 | ipython profile create [profilename] |
|
20 | 20 | |
|
21 | 21 | If you leave out the profile name, the files will be created for the |
|
22 | 22 | ``default`` profile (see :ref:`profiles`). These will typically be |
|
23 | 23 | located in :file:`~/.ipython/profile_default/`, and will be named |
|
24 | 24 | :file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc. |
|
25 | 25 | The settings in :file:`ipython_config.py` apply to all IPython commands. |
|
26 | 26 | |
|
27 | 27 | The files typically start by getting the root config object:: |
|
28 | 28 | |
|
29 | 29 | c = get_config() |
|
30 | 30 | |
|
31 | 31 | You can then configure class attributes like this:: |
|
32 | 32 | |
|
33 | 33 | c.InteractiveShell.automagic = False |
|
34 | 34 | |
|
35 | 35 | Be careful with spelling--incorrect names will simply be ignored, with |
|
36 | 36 | 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. |
|
|
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 | |
|
44 | 44 | c.InteractiveShellApp.extensions.append('Cython') |
|
45 | 45 | |
|
46 | 46 | .. versionadded:: 2.0 |
|
47 | 47 | list, dict and set methods for config values |
|
48 | 48 | |
|
49 | 49 | Example config file |
|
50 | 50 | ``````````````````` |
|
51 | 51 | |
|
52 | 52 | :: |
|
53 | 53 | |
|
54 | 54 | # sample ipython_config.py |
|
55 | 55 | c = get_config() |
|
56 | 56 | |
|
57 | 57 | c.TerminalIPythonApp.display_banner = True |
|
58 | 58 | c.InteractiveShellApp.log_level = 20 |
|
59 | 59 | c.InteractiveShellApp.extensions = [ |
|
60 | 60 | 'myextension' |
|
61 | 61 | ] |
|
62 | 62 | c.InteractiveShellApp.exec_lines = [ |
|
63 | 63 | 'import numpy', |
|
64 | 64 | 'import scipy' |
|
65 | 65 | ] |
|
66 | 66 | c.InteractiveShellApp.exec_files = [ |
|
67 | 67 | 'mycode.py', |
|
68 | 68 | 'fancy.ipy' |
|
69 | 69 | ] |
|
70 | 70 | c.InteractiveShell.autoindent = True |
|
71 | 71 | c.InteractiveShell.colors = 'LightBG' |
|
72 | 72 | c.InteractiveShell.confirm_exit = False |
|
73 | 73 | c.InteractiveShell.deep_reload = True |
|
74 | 74 | c.InteractiveShell.editor = 'nano' |
|
75 | 75 | c.InteractiveShell.xmode = 'Context' |
|
76 | 76 | |
|
77 | 77 | c.PromptManager.in_template = 'In [\#]: ' |
|
78 | 78 | c.PromptManager.in2_template = ' .\D.: ' |
|
79 | 79 | c.PromptManager.out_template = 'Out[\#]: ' |
|
80 | 80 | c.PromptManager.justify = True |
|
81 | 81 | |
|
82 | 82 | c.PrefilterManager.multi_line_specials = True |
|
83 | 83 | |
|
84 | 84 | c.AliasManager.user_aliases = [ |
|
85 | 85 | ('la', 'ls -al') |
|
86 | 86 | ] |
|
87 | 87 | |
|
88 | 88 | |
|
89 | 89 | Command line arguments |
|
90 | 90 | ---------------------- |
|
91 | 91 | |
|
92 | 92 | Every configurable value can be set from the command line, using this |
|
93 | 93 | syntax:: |
|
94 | 94 | |
|
95 | 95 | ipython --ClassName.attribute=value |
|
96 | 96 | |
|
97 | 97 | Many frequently used options have short aliases and flags, such as |
|
98 | 98 | ``--matplotlib`` (to integrate with a matplotlib GUI event loop) or |
|
99 | 99 | ``--pdb`` (automatic post-mortem debugging of exceptions). |
|
100 | 100 | |
|
101 | 101 | To see all of these abbreviated options, run:: |
|
102 | 102 | |
|
103 | 103 | ipython --help |
|
104 | 104 | ipython notebook --help |
|
105 | 105 | # etc. |
|
106 | 106 | |
|
107 | 107 | Options specified at the command line, in either format, override |
|
108 | 108 | options set in a configuration file. |
|
109 | 109 | |
|
110 | 110 | The config magic |
|
111 | 111 | ---------------- |
|
112 | 112 | |
|
113 | 113 | You can also modify config from inside IPython, using a magic command:: |
|
114 | 114 | |
|
115 | 115 | %config IPCompleter.greedy = True |
|
116 | 116 | |
|
117 | 117 | At present, this only affects the current session - changes you make to |
|
118 | 118 | config are not saved anywhere. Also, some options are only read when |
|
119 | 119 | IPython starts, so they can't be changed like this. |
|
120 | 120 | |
|
121 | 121 | .. _profiles: |
|
122 | 122 | |
|
123 | 123 | Profiles |
|
124 | 124 | ======== |
|
125 | 125 | |
|
126 | 126 | IPython can use multiple profiles, with separate configuration and |
|
127 | 127 | history. By default, if you don't specify a profile, IPython always runs |
|
128 | 128 | in the ``default`` profile. To use a new profile:: |
|
129 | 129 | |
|
130 | 130 | ipython profile create foo # create the profile foo |
|
131 | 131 | ipython --profile=foo # start IPython using the new profile |
|
132 | 132 | |
|
133 | 133 | Profiles are typically stored in :ref:`ipythondir`, but you can also keep |
|
134 | 134 | a profile in the current working directory, for example to distribute it |
|
135 | 135 | with a project. To find a profile directory on the filesystem:: |
|
136 | 136 | |
|
137 | 137 | ipython locate profile foo |
|
138 | 138 | |
|
139 | 139 | .. _ipythondir: |
|
140 | 140 | |
|
141 | 141 | The IPython directory |
|
142 | 142 | ===================== |
|
143 | 143 | |
|
144 | 144 | IPython stores its files---config, command history and extensions---in |
|
145 | 145 | the directory :file:`~/.ipython/` by default. |
|
146 | 146 | |
|
147 | 147 | .. envvar:: IPYTHONDIR |
|
148 | 148 | |
|
149 | 149 | If set, this environment variable should be the path to a directory, |
|
150 | 150 | which IPython will use for user data. IPython will create it if it |
|
151 | 151 | does not exist. |
|
152 | 152 | |
|
153 | 153 | .. option:: --ipython-dir=<path> |
|
154 | 154 | |
|
155 | 155 | This command line option can also be used to override the default |
|
156 | 156 | IPython directory. |
@@ -1,566 +1,148 b'' | |||
|
1 | 1 | .. _config_overview: |
|
2 | 2 | |
|
3 | 3 | ============================================ |
|
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 | =========================== |
|
300 | 13 | |
|
301 | 14 | So where should you put your configuration files? IPython uses "profiles" for |
|
302 | 15 | configuration, and by default, all profiles will be stored in the so called |
|
303 | 16 | "IPython directory". The location of this directory is determined by the |
|
304 | 17 | 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. |
|
|
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 |
|
312 | 25 | be removed in a future release. |
|
313 | 26 | |
|
314 | 27 | For most users, the configuration directory will be :file:`~/.ipython`. |
|
315 | 28 | |
|
316 | 29 | Previous versions of IPython on Linux would use the XDG config directory, |
|
317 | 30 | creating :file:`~/.config/ipython` by default. We have decided to go |
|
318 | 31 | back to :file:`~/.ipython` for consistency among systems. IPython will |
|
319 | 32 | issue a warning if it finds the XDG location, and will move it to the new |
|
320 | 33 | location if there isn't already a directory there. |
|
321 | 34 | |
|
322 | 35 | Once the location of the IPython directory has been determined, you need to know |
|
323 | 36 | which profile you are using. For users with a single configuration, this will |
|
324 | 37 | simply be 'default', and will be located in |
|
325 | 38 | :file:`<IPYTHONDIR>/profile_default`. |
|
326 | 39 | |
|
327 | 40 | The next thing you need to know is what to call your configuration file. The |
|
328 | 41 | basic idea is that each application has its own default configuration filename. |
|
329 | 42 | The default named used by the :command:`ipython` command line program is |
|
330 | 43 | :file:`ipython_config.py`, and *all* IPython applications will use this file. |
|
331 | 44 | Other applications, such as the parallel :command:`ipcluster` scripts or the |
|
332 | 45 | QtConsole will load their own config files *after* :file:`ipython_config.py`. To |
|
333 | 46 | load a particular configuration file instead of the default, the name can be |
|
334 | 47 | overridden by the ``config_file`` command line flag. |
|
335 | 48 | |
|
336 | 49 | To generate the default configuration files, do:: |
|
337 | 50 | |
|
338 | 51 | $ ipython profile create |
|
339 | 52 | |
|
340 | 53 | and you will have a default :file:`ipython_config.py` in your IPython directory |
|
341 | 54 | under :file:`profile_default`. If you want the default config files for the |
|
342 | 55 | :mod:`IPython.parallel` applications, add ``--parallel`` to the end of the |
|
343 | 56 | command-line args. |
|
344 | 57 | |
|
345 | 58 | |
|
346 | 59 | Locating these files |
|
347 | 60 | -------------------- |
|
348 | 61 | |
|
349 | 62 | From the command-line, you can quickly locate the IPYTHONDIR or a specific |
|
350 | 63 | profile with: |
|
351 | 64 | |
|
352 | 65 | .. sourcecode:: bash |
|
353 | 66 | |
|
354 | 67 | $ ipython locate |
|
355 | 68 | /home/you/.ipython |
|
356 | 69 | |
|
357 | 70 | $ ipython locate profile foo |
|
358 | 71 | /home/you/.ipython/profile_foo |
|
359 | 72 | |
|
360 | 73 | These map to the utility functions: :func:`IPython.utils.path.get_ipython_dir` |
|
361 | 74 | and :func:`IPython.utils.path.locate_profile` respectively. |
|
362 | 75 | |
|
363 | 76 | |
|
364 | 77 | .. _profiles_dev: |
|
365 | 78 | |
|
366 | 79 | Profiles |
|
367 | 80 | ======== |
|
368 | 81 | |
|
369 | 82 | A profile is a directory containing configuration and runtime files, such as |
|
370 | 83 | logs, connection info for the parallel apps, and your IPython command history. |
|
371 | 84 | |
|
372 | 85 | The idea is that users often want to maintain a set of configuration files for |
|
373 | 86 | different purposes: one for doing numerical computing with NumPy and SciPy and |
|
374 | 87 | another for doing symbolic computing with SymPy. Profiles make it easy to keep a |
|
375 | 88 | separate configuration files, logs, and histories for each of these purposes. |
|
376 | 89 | |
|
377 | 90 | Let's start by showing how a profile is used: |
|
378 | 91 | |
|
379 | 92 | .. code-block:: bash |
|
380 | 93 | |
|
381 | 94 | $ ipython --profile=sympy |
|
382 | 95 | |
|
383 | 96 | This tells the :command:`ipython` command line program to get its configuration |
|
384 | 97 | from the "sympy" profile. The file names for various profiles do not change. The |
|
385 | 98 | only difference is that profiles are named in a special way. In the case above, |
|
386 | 99 | the "sympy" profile means looking for :file:`ipython_config.py` in :file:`<IPYTHONDIR>/profile_sympy`. |
|
387 | 100 | |
|
388 | 101 | The general pattern is this: simply create a new profile with: |
|
389 | 102 | |
|
390 | 103 | .. code-block:: bash |
|
391 | 104 | |
|
392 | 105 | $ ipython profile create <name> |
|
393 | 106 | |
|
394 | 107 | which adds a directory called ``profile_<name>`` to your IPython directory. Then |
|
395 | 108 | you can load this profile by adding ``--profile=<name>`` to your command line |
|
396 | 109 | options. Profiles are supported by all IPython applications. |
|
397 | 110 | |
|
398 | 111 | IPython ships with some sample profiles in :file:`IPython/config/profile`. If |
|
399 | 112 | 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 | |
|
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: | |
|
119 | ||
|
120 | .. sourcecode:: python | |
|
121 | ||
|
122 | load_subconfig('ipython_config.py', profile='default') | |
|
123 | ||
|
403 | 124 | Security Files |
|
404 | 125 | -------------- |
|
405 | 126 | |
|
406 | 127 | If you are using the notebook, qtconsole, or parallel code, IPython stores |
|
407 | 128 | connection information in small JSON files in the active profile's security |
|
408 | 129 | directory. This directory is made private, so only you can see the files inside. If |
|
409 | 130 | you need to move connection files around to other computers, this is where they will |
|
410 | 131 | be. If you want your code to be able to open security files by name, we have a |
|
411 | 132 | convenience function :func:`IPython.utils.path.get_security_file`, which will return |
|
412 | 133 | the absolute path to a security file from its filename and [optionally] profile |
|
413 | 134 | name. |
|
414 | 135 | |
|
415 | 136 | .. _startup_files: |
|
416 | 137 | |
|
417 | 138 | Startup Files |
|
418 | 139 | ------------- |
|
419 | 140 | |
|
420 | 141 | If you want some code to be run at the beginning of every IPython session with |
|
421 | 142 | a particular profile, the easiest way is to add Python (``.py``) or |
|
422 | 143 | IPython (``.ipy``) scripts to your :file:`<profile>/startup` directory. Files |
|
423 | 144 | in this directory will always be executed as soon as the IPython shell is |
|
424 | 145 | constructed, and before any other code or scripts you have specified. If you |
|
425 | 146 | have multiple files in the startup directory, they will be run in |
|
426 | 147 | lexicographical order, so you can control the ordering by adding a '00-' |
|
427 | 148 | 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: | |
|
449 | ||
|
450 | .. sourcecode:: python | |
|
451 | ||
|
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 |
General Comments 0
You need to be logged in to leave comments.
Login now