Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# encoding: utf-8
2"""
3An application for IPython.
5All top-level applications should use the classes in this module for
6handling configuration and creating configurables.
8The job of an :class:`Application` is to create the master configuration
9object and then create the configurable objects, passing the config to them.
10"""
12# Copyright (c) IPython Development Team.
13# Distributed under the terms of the Modified BSD License.
15import atexit
16from copy import deepcopy
17import logging
18import os
19import shutil
20import sys
22from pathlib import Path
24from traitlets.config.application import Application, catch_config_error
25from traitlets.config.loader import ConfigFileNotFound, PyFileConfigLoader
26from IPython.core import release, crashhandler
27from IPython.core.profiledir import ProfileDir, ProfileDirError
28from IPython.paths import get_ipython_dir, get_ipython_package_dir
29from IPython.utils.path import ensure_dir_exists
30from traitlets import (
31 List, Unicode, Type, Bool, Set, Instance, Undefined,
32 default, observe,
33)
35if os.name == "nt":
36 programdata = os.environ.get("PROGRAMDATA", None)
37 if programdata is not None:
38 SYSTEM_CONFIG_DIRS = [str(Path(programdata) / "ipython")]
39 else: # PROGRAMDATA is not defined by default on XP.
40 SYSTEM_CONFIG_DIRS = []
41else:
42 SYSTEM_CONFIG_DIRS = [
43 "/usr/local/etc/ipython",
44 "/etc/ipython",
45 ]
48ENV_CONFIG_DIRS = []
49_env_config_dir = os.path.join(sys.prefix, 'etc', 'ipython')
50if _env_config_dir not in SYSTEM_CONFIG_DIRS:
51 # only add ENV_CONFIG if sys.prefix is not already included
52 ENV_CONFIG_DIRS.append(_env_config_dir)
55_envvar = os.environ.get('IPYTHON_SUPPRESS_CONFIG_ERRORS')
56if _envvar in {None, ''}:
57 IPYTHON_SUPPRESS_CONFIG_ERRORS = None
58else:
59 if _envvar.lower() in {'1','true'}:
60 IPYTHON_SUPPRESS_CONFIG_ERRORS = True
61 elif _envvar.lower() in {'0','false'} :
62 IPYTHON_SUPPRESS_CONFIG_ERRORS = False
63 else:
64 sys.exit("Unsupported value for environment variable: 'IPYTHON_SUPPRESS_CONFIG_ERRORS' is set to '%s' which is none of {'0', '1', 'false', 'true', ''}."% _envvar )
66# aliases and flags
68base_aliases = {}
69if isinstance(Application.aliases, dict):
70 # traitlets 5
71 base_aliases.update(Application.aliases)
72base_aliases.update(
73 {
74 "profile-dir": "ProfileDir.location",
75 "profile": "BaseIPythonApplication.profile",
76 "ipython-dir": "BaseIPythonApplication.ipython_dir",
77 "log-level": "Application.log_level",
78 "config": "BaseIPythonApplication.extra_config_file",
79 }
80)
82base_flags = dict()
83if isinstance(Application.flags, dict):
84 # traitlets 5
85 base_flags.update(Application.flags)
86base_flags.update(
87 dict(
88 debug=(
89 {"Application": {"log_level": logging.DEBUG}},
90 "set log level to logging.DEBUG (maximize logging output)",
91 ),
92 quiet=(
93 {"Application": {"log_level": logging.CRITICAL}},
94 "set log level to logging.CRITICAL (minimize logging output)",
95 ),
96 init=(
97 {
98 "BaseIPythonApplication": {
99 "copy_config_files": True,
100 "auto_create": True,
101 }
102 },
103 """Initialize profile with default config files. This is equivalent
104 to running `ipython profile create <profile>` prior to startup.
105 """,
106 ),
107 )
108)
111class ProfileAwareConfigLoader(PyFileConfigLoader):
112 """A Python file config loader that is aware of IPython profiles."""
113 def load_subconfig(self, fname, path=None, profile=None):
114 if profile is not None:
115 try:
116 profile_dir = ProfileDir.find_profile_dir_by_name(
117 get_ipython_dir(),
118 profile,
119 )
120 except ProfileDirError:
121 return
122 path = profile_dir.location
123 return super(ProfileAwareConfigLoader, self).load_subconfig(fname, path=path)
125class BaseIPythonApplication(Application):
126 name = "ipython"
127 description = "IPython: an enhanced interactive Python shell."
128 version = Unicode(release.version)
130 aliases = base_aliases
131 flags = base_flags
132 classes = List([ProfileDir])
134 # enable `load_subconfig('cfg.py', profile='name')`
135 python_config_loader_class = ProfileAwareConfigLoader
137 # Track whether the config_file has changed,
138 # because some logic happens only if we aren't using the default.
139 config_file_specified = Set()
141 config_file_name = Unicode()
142 @default('config_file_name')
143 def _config_file_name_default(self):
144 return self.name.replace('-','_') + u'_config.py'
145 @observe('config_file_name')
146 def _config_file_name_changed(self, change):
147 if change['new'] != change['old']:
148 self.config_file_specified.add(change['new'])
150 # The directory that contains IPython's builtin profiles.
151 builtin_profile_dir = Unicode(
152 os.path.join(get_ipython_package_dir(), u'config', u'profile', u'default')
153 )
155 config_file_paths = List(Unicode())
156 @default('config_file_paths')
157 def _config_file_paths_default(self):
158 return []
160 extra_config_file = Unicode(
161 help="""Path to an extra config file to load.
163 If specified, load this config file in addition to any other IPython config.
164 """).tag(config=True)
165 @observe('extra_config_file')
166 def _extra_config_file_changed(self, change):
167 old = change['old']
168 new = change['new']
169 try:
170 self.config_files.remove(old)
171 except ValueError:
172 pass
173 self.config_file_specified.add(new)
174 self.config_files.append(new)
176 profile = Unicode(u'default',
177 help="""The IPython profile to use."""
178 ).tag(config=True)
180 @observe('profile')
181 def _profile_changed(self, change):
182 self.builtin_profile_dir = os.path.join(
183 get_ipython_package_dir(), u'config', u'profile', change['new']
184 )
186 add_ipython_dir_to_sys_path = Bool(
187 False,
188 """Should the IPython profile directory be added to sys path ?
190 This option was non-existing before IPython 8.0, and ipython_dir was added to
191 sys path to allow import of extensions present there. This was historical
192 baggage from when pip did not exist. This now default to false,
193 but can be set to true for legacy reasons.
194 """,
195 ).tag(config=True)
197 ipython_dir = Unicode(
198 help="""
199 The name of the IPython directory. This directory is used for logging
200 configuration (through profiles), history storage, etc. The default
201 is usually $HOME/.ipython. This option can also be specified through
202 the environment variable IPYTHONDIR.
203 """
204 ).tag(config=True)
205 @default('ipython_dir')
206 def _ipython_dir_default(self):
207 d = get_ipython_dir()
208 self._ipython_dir_changed({
209 'name': 'ipython_dir',
210 'old': d,
211 'new': d,
212 })
213 return d
215 _in_init_profile_dir = False
217 profile_dir = Instance(ProfileDir, allow_none=True)
219 @default('profile_dir')
220 def _profile_dir_default(self):
221 # avoid recursion
222 if self._in_init_profile_dir:
223 return
224 # profile_dir requested early, force initialization
225 self.init_profile_dir()
226 return self.profile_dir
228 overwrite = Bool(False,
229 help="""Whether to overwrite existing config files when copying"""
230 ).tag(config=True)
232 auto_create = Bool(False,
233 help="""Whether to create profile dir if it doesn't exist"""
234 ).tag(config=True)
236 config_files = List(Unicode())
238 @default('config_files')
239 def _config_files_default(self):
240 return [self.config_file_name]
242 copy_config_files = Bool(False,
243 help="""Whether to install the default config files into the profile dir.
244 If a new profile is being created, and IPython contains config files for that
245 profile, then they will be staged into the new directory. Otherwise,
246 default config files will be automatically generated.
247 """).tag(config=True)
249 verbose_crash = Bool(False,
250 help="""Create a massive crash report when IPython encounters what may be an
251 internal error. The default is to append a short message to the
252 usual traceback""").tag(config=True)
254 # The class to use as the crash handler.
255 crash_handler_class = Type(crashhandler.CrashHandler)
257 @catch_config_error
258 def __init__(self, **kwargs):
259 super(BaseIPythonApplication, self).__init__(**kwargs)
260 # ensure current working directory exists
261 try:
262 os.getcwd()
263 except:
264 # exit if cwd doesn't exist
265 self.log.error("Current working directory doesn't exist.")
266 self.exit(1)
268 #-------------------------------------------------------------------------
269 # Various stages of Application creation
270 #-------------------------------------------------------------------------
272 def init_crash_handler(self):
273 """Create a crash handler, typically setting sys.excepthook to it."""
274 self.crash_handler = self.crash_handler_class(self)
275 sys.excepthook = self.excepthook
276 def unset_crashhandler():
277 sys.excepthook = sys.__excepthook__
278 atexit.register(unset_crashhandler)
280 def excepthook(self, etype, evalue, tb):
281 """this is sys.excepthook after init_crashhandler
283 set self.verbose_crash=True to use our full crashhandler, instead of
284 a regular traceback with a short message (crash_handler_lite)
285 """
287 if self.verbose_crash:
288 return self.crash_handler(etype, evalue, tb)
289 else:
290 return crashhandler.crash_handler_lite(etype, evalue, tb)
292 @observe('ipython_dir')
293 def _ipython_dir_changed(self, change):
294 old = change['old']
295 new = change['new']
296 if old is not Undefined:
297 str_old = os.path.abspath(old)
298 if str_old in sys.path:
299 sys.path.remove(str_old)
300 if self.add_ipython_dir_to_sys_path:
301 str_path = os.path.abspath(new)
302 sys.path.append(str_path)
303 ensure_dir_exists(new)
304 readme = os.path.join(new, "README")
305 readme_src = os.path.join(
306 get_ipython_package_dir(), "config", "profile", "README"
307 )
308 if not os.path.exists(readme) and os.path.exists(readme_src):
309 shutil.copy(readme_src, readme)
310 for d in ("extensions", "nbextensions"):
311 path = os.path.join(new, d)
312 try:
313 ensure_dir_exists(path)
314 except OSError as e:
315 # this will not be EEXIST
316 self.log.error("couldn't create path %s: %s", path, e)
317 self.log.debug("IPYTHONDIR set to: %s", new)
319 def load_config_file(self, suppress_errors=IPYTHON_SUPPRESS_CONFIG_ERRORS):
320 """Load the config file.
322 By default, errors in loading config are handled, and a warning
323 printed on screen. For testing, the suppress_errors option is set
324 to False, so errors will make tests fail.
326 `suppress_errors` default value is to be `None` in which case the
327 behavior default to the one of `traitlets.Application`.
329 The default value can be set :
330 - to `False` by setting 'IPYTHON_SUPPRESS_CONFIG_ERRORS' environment variable to '0', or 'false' (case insensitive).
331 - to `True` by setting 'IPYTHON_SUPPRESS_CONFIG_ERRORS' environment variable to '1' or 'true' (case insensitive).
332 - to `None` by setting 'IPYTHON_SUPPRESS_CONFIG_ERRORS' environment variable to '' (empty string) or leaving it unset.
334 Any other value are invalid, and will make IPython exit with a non-zero return code.
335 """
338 self.log.debug("Searching path %s for config files", self.config_file_paths)
339 base_config = 'ipython_config.py'
340 self.log.debug("Attempting to load config file: %s" %
341 base_config)
342 try:
343 if suppress_errors is not None:
344 old_value = Application.raise_config_file_errors
345 Application.raise_config_file_errors = not suppress_errors
346 Application.load_config_file(
347 self,
348 base_config,
349 path=self.config_file_paths
350 )
351 except ConfigFileNotFound:
352 # ignore errors loading parent
353 self.log.debug("Config file %s not found", base_config)
354 pass
355 if suppress_errors is not None:
356 Application.raise_config_file_errors = old_value
358 for config_file_name in self.config_files:
359 if not config_file_name or config_file_name == base_config:
360 continue
361 self.log.debug("Attempting to load config file: %s" %
362 self.config_file_name)
363 try:
364 Application.load_config_file(
365 self,
366 config_file_name,
367 path=self.config_file_paths
368 )
369 except ConfigFileNotFound:
370 # Only warn if the default config file was NOT being used.
371 if config_file_name in self.config_file_specified:
372 msg = self.log.warning
373 else:
374 msg = self.log.debug
375 msg("Config file not found, skipping: %s", config_file_name)
376 except Exception:
377 # For testing purposes.
378 if not suppress_errors:
379 raise
380 self.log.warning("Error loading config file: %s" %
381 self.config_file_name, exc_info=True)
383 def init_profile_dir(self):
384 """initialize the profile dir"""
385 self._in_init_profile_dir = True
386 if self.profile_dir is not None:
387 # already ran
388 return
389 if 'ProfileDir.location' not in self.config:
390 # location not specified, find by profile name
391 try:
392 p = ProfileDir.find_profile_dir_by_name(self.ipython_dir, self.profile, self.config)
393 except ProfileDirError:
394 # not found, maybe create it (always create default profile)
395 if self.auto_create or self.profile == 'default':
396 try:
397 p = ProfileDir.create_profile_dir_by_name(self.ipython_dir, self.profile, self.config)
398 except ProfileDirError:
399 self.log.fatal("Could not create profile: %r"%self.profile)
400 self.exit(1)
401 else:
402 self.log.info("Created profile dir: %r"%p.location)
403 else:
404 self.log.fatal("Profile %r not found."%self.profile)
405 self.exit(1)
406 else:
407 self.log.debug("Using existing profile dir: %r", p.location)
408 else:
409 location = self.config.ProfileDir.location
410 # location is fully specified
411 try:
412 p = ProfileDir.find_profile_dir(location, self.config)
413 except ProfileDirError:
414 # not found, maybe create it
415 if self.auto_create:
416 try:
417 p = ProfileDir.create_profile_dir(location, self.config)
418 except ProfileDirError:
419 self.log.fatal("Could not create profile directory: %r"%location)
420 self.exit(1)
421 else:
422 self.log.debug("Creating new profile dir: %r"%location)
423 else:
424 self.log.fatal("Profile directory %r not found."%location)
425 self.exit(1)
426 else:
427 self.log.debug("Using existing profile dir: %r", p.location)
428 # if profile_dir is specified explicitly, set profile name
429 dir_name = os.path.basename(p.location)
430 if dir_name.startswith('profile_'):
431 self.profile = dir_name[8:]
433 self.profile_dir = p
434 self.config_file_paths.append(p.location)
435 self._in_init_profile_dir = False
437 def init_config_files(self):
438 """[optionally] copy default config files into profile dir."""
439 self.config_file_paths.extend(ENV_CONFIG_DIRS)
440 self.config_file_paths.extend(SYSTEM_CONFIG_DIRS)
441 # copy config files
442 path = Path(self.builtin_profile_dir)
443 if self.copy_config_files:
444 src = self.profile
446 cfg = self.config_file_name
447 if path and (path / cfg).exists():
448 self.log.warning(
449 "Staging %r from %s into %r [overwrite=%s]"
450 % (cfg, src, self.profile_dir.location, self.overwrite)
451 )
452 self.profile_dir.copy_config_file(cfg, path=path, overwrite=self.overwrite)
453 else:
454 self.stage_default_config_file()
455 else:
456 # Still stage *bundled* config files, but not generated ones
457 # This is necessary for `ipython profile=sympy` to load the profile
458 # on the first go
459 files = path.glob("*.py")
460 for fullpath in files:
461 cfg = fullpath.name
462 if self.profile_dir.copy_config_file(cfg, path=path, overwrite=False):
463 # file was copied
464 self.log.warning("Staging bundled %s from %s into %r"%(
465 cfg, self.profile, self.profile_dir.location)
466 )
469 def stage_default_config_file(self):
470 """auto generate default config file, and stage it into the profile."""
471 s = self.generate_config_file()
472 config_file = Path(self.profile_dir.location) / self.config_file_name
473 if self.overwrite or not config_file.exists():
474 self.log.warning("Generating default config file: %r", (config_file))
475 config_file.write_text(s, encoding="utf-8")
477 @catch_config_error
478 def initialize(self, argv=None):
479 # don't hook up crash handler before parsing command-line
480 self.parse_command_line(argv)
481 self.init_crash_handler()
482 if self.subapp is not None:
483 # stop here if subapp is taking over
484 return
485 # save a copy of CLI config to re-load after config files
486 # so that it has highest priority
487 cl_config = deepcopy(self.config)
488 self.init_profile_dir()
489 self.init_config_files()
490 self.load_config_file()
491 # enforce cl-opts override configfile opts:
492 self.update_config(cl_config)