##// END OF EJS Templates
fix IPython.embed...
Paul Ivanov -
Show More
@@ -1,603 +1,605 b''
1 1 # encoding: utf-8
2 2 """
3 3 A base class for a configurable application.
4 4
5 5 Authors:
6 6
7 7 * Brian Granger
8 8 * Min RK
9 9 """
10 10 from __future__ import print_function
11 11
12 12 #-----------------------------------------------------------------------------
13 13 # Copyright (C) 2008-2011 The IPython Development Team
14 14 #
15 15 # Distributed under the terms of the BSD License. The full license is in
16 16 # the file COPYING, distributed as part of this software.
17 17 #-----------------------------------------------------------------------------
18 18
19 19 #-----------------------------------------------------------------------------
20 20 # Imports
21 21 #-----------------------------------------------------------------------------
22 22
23 23 import logging
24 24 import os
25 25 import re
26 26 import sys
27 27 from copy import deepcopy
28 28 from collections import defaultdict
29 29
30 30 from IPython.external.decorator import decorator
31 31
32 32 from IPython.config.configurable import SingletonConfigurable
33 33 from IPython.config.loader import (
34 34 KVArgParseConfigLoader, PyFileConfigLoader, Config, ArgumentError, ConfigFileNotFound, JSONFileConfigLoader
35 35 )
36 36
37 37 from IPython.utils.traitlets import (
38 38 Unicode, List, Enum, Dict, Instance, TraitError
39 39 )
40 40 from IPython.utils.importstring import import_item
41 41 from IPython.utils.text import indent, wrap_paragraphs, dedent
42 42 from IPython.utils import py3compat
43 43 from IPython.utils.py3compat import string_types, iteritems
44 44
45 45 #-----------------------------------------------------------------------------
46 46 # function for re-wrapping a helpstring
47 47 #-----------------------------------------------------------------------------
48 48
49 49 #-----------------------------------------------------------------------------
50 50 # Descriptions for the various sections
51 51 #-----------------------------------------------------------------------------
52 52
53 53 # merge flags&aliases into options
54 54 option_description = """
55 55 Arguments that take values are actually convenience aliases to full
56 56 Configurables, whose aliases are listed on the help line. For more information
57 57 on full configurables, see '--help-all'.
58 58 """.strip() # trim newlines of front and back
59 59
60 60 keyvalue_description = """
61 61 Parameters are set from command-line arguments of the form:
62 62 `--Class.trait=value`.
63 63 This line is evaluated in Python, so simple expressions are allowed, e.g.::
64 64 `--C.a='range(3)'` For setting C.a=[0,1,2].
65 65 """.strip() # trim newlines of front and back
66 66
67 67 # sys.argv can be missing, for example when python is embedded. See the docs
68 68 # for details: http://docs.python.org/2/c-api/intro.html#embedding-python
69 69 if not hasattr(sys, "argv"):
70 70 sys.argv = [""]
71 71
72 72 subcommand_description = """
73 73 Subcommands are launched as `{app} cmd [args]`. For information on using
74 74 subcommand 'cmd', do: `{app} cmd -h`.
75 75 """.strip().format(app=os.path.basename(sys.argv[0]))
76 76 # get running program name
77 77
78 78 #-----------------------------------------------------------------------------
79 79 # Application class
80 80 #-----------------------------------------------------------------------------
81 81
82 82 @decorator
83 83 def catch_config_error(method, app, *args, **kwargs):
84 84 """Method decorator for catching invalid config (Trait/ArgumentErrors) during init.
85 85
86 86 On a TraitError (generally caused by bad config), this will print the trait's
87 87 message, and exit the app.
88 88
89 89 For use on init methods, to prevent invoking excepthook on invalid input.
90 90 """
91 91 try:
92 92 return method(app, *args, **kwargs)
93 93 except (TraitError, ArgumentError) as e:
94 94 app.print_help()
95 95 app.log.fatal("Bad config encountered during initialization:")
96 96 app.log.fatal(str(e))
97 97 app.log.debug("Config at the time: %s", app.config)
98 98 app.exit(1)
99 99
100 100
101 101 class ApplicationError(Exception):
102 102 pass
103 103
104 104 class LevelFormatter(logging.Formatter):
105 105 """Formatter with additional `highlevel` record
106 106
107 107 This field is empty if log level is less than highlevel_limit,
108 108 otherwise it is formatted with self.highlevel_format.
109 109
110 110 Useful for adding 'WARNING' to warning messages,
111 111 without adding 'INFO' to info, etc.
112 112 """
113 113 highlevel_limit = logging.WARN
114 114 highlevel_format = " %(levelname)s |"
115 115
116 116 def format(self, record):
117 117 if record.levelno >= self.highlevel_limit:
118 118 record.highlevel = self.highlevel_format % record.__dict__
119 119 else:
120 120 record.highlevel = ""
121 121 return super(LevelFormatter, self).format(record)
122 122
123 123
124 124 class Application(SingletonConfigurable):
125 125 """A singleton application with full configuration support."""
126 126
127 127 # The name of the application, will usually match the name of the command
128 128 # line application
129 129 name = Unicode(u'application')
130 130
131 131 # The description of the application that is printed at the beginning
132 132 # of the help.
133 133 description = Unicode(u'This is an application.')
134 134 # default section descriptions
135 135 option_description = Unicode(option_description)
136 136 keyvalue_description = Unicode(keyvalue_description)
137 137 subcommand_description = Unicode(subcommand_description)
138 138
139 139 # The usage and example string that goes at the end of the help string.
140 140 examples = Unicode()
141 141
142 142 # A sequence of Configurable subclasses whose config=True attributes will
143 143 # be exposed at the command line.
144 144 classes = List([])
145 145
146 146 # The version string of this application.
147 147 version = Unicode(u'0.0')
148 148
149 149 # the argv used to initialize the application
150 150 argv = List()
151 151
152 152 # The log level for the application
153 153 log_level = Enum((0,10,20,30,40,50,'DEBUG','INFO','WARN','ERROR','CRITICAL'),
154 154 default_value=logging.WARN,
155 155 config=True,
156 156 help="Set the log level by value or name.")
157 157 def _log_level_changed(self, name, old, new):
158 158 """Adjust the log level when log_level is set."""
159 159 if isinstance(new, string_types):
160 160 new = getattr(logging, new)
161 161 self.log_level = new
162 162 self.log.setLevel(new)
163 163
164 164 log_datefmt = Unicode("%Y-%m-%d %H:%M:%S", config=True,
165 165 help="The date format used by logging formatters for %(asctime)s"
166 166 )
167 167 def _log_datefmt_changed(self, name, old, new):
168 168 self._log_format_changed()
169 169
170 170 log_format = Unicode("[%(name)s]%(highlevel)s %(message)s", config=True,
171 171 help="The Logging format template",
172 172 )
173 173 def _log_format_changed(self, name, old, new):
174 174 """Change the log formatter when log_format is set."""
175 175 _log_handler = self.log.handlers[0]
176 176 _log_formatter = LevelFormatter(new, datefmt=self.log_datefmt)
177 177 _log_handler.setFormatter(_log_formatter)
178 178
179 179 log = Instance(logging.Logger)
180 180 def _log_default(self):
181 181 """Start logging for this application.
182 182
183 183 The default is to log to stderr using a StreamHandler, if no default
184 184 handler already exists. The log level starts at logging.WARN, but this
185 185 can be adjusted by setting the ``log_level`` attribute.
186 186 """
187 187 log = logging.getLogger(self.__class__.__name__)
188 188 log.setLevel(self.log_level)
189 189 log.propagate = False
190 190 _log = log # copied from Logger.hasHandlers() (new in Python 3.2)
191 191 while _log:
192 192 if _log.handlers:
193 193 return log
194 194 if not _log.propagate:
195 195 break
196 196 else:
197 197 _log = _log.parent
198 198 if sys.executable.endswith('pythonw.exe'):
199 199 # this should really go to a file, but file-logging is only
200 200 # hooked up in parallel applications
201 201 _log_handler = logging.StreamHandler(open(os.devnull, 'w'))
202 202 else:
203 203 _log_handler = logging.StreamHandler()
204 204 _log_formatter = LevelFormatter(self.log_format, datefmt=self.log_datefmt)
205 205 _log_handler.setFormatter(_log_formatter)
206 206 log.addHandler(_log_handler)
207 207 return log
208 208
209 209 # the alias map for configurables
210 210 aliases = Dict({'log-level' : 'Application.log_level'})
211 211
212 212 # flags for loading Configurables or store_const style flags
213 213 # flags are loaded from this dict by '--key' flags
214 214 # this must be a dict of two-tuples, the first element being the Config/dict
215 215 # and the second being the help string for the flag
216 216 flags = Dict()
217 217 def _flags_changed(self, name, old, new):
218 218 """ensure flags dict is valid"""
219 219 for key,value in iteritems(new):
220 220 assert len(value) == 2, "Bad flag: %r:%s"%(key,value)
221 221 assert isinstance(value[0], (dict, Config)), "Bad flag: %r:%s"%(key,value)
222 222 assert isinstance(value[1], string_types), "Bad flag: %r:%s"%(key,value)
223 223
224 224
225 225 # subcommands for launching other applications
226 226 # if this is not empty, this will be a parent Application
227 227 # this must be a dict of two-tuples,
228 228 # the first element being the application class/import string
229 229 # and the second being the help string for the subcommand
230 230 subcommands = Dict()
231 231 # parse_command_line will initialize a subapp, if requested
232 232 subapp = Instance('IPython.config.application.Application', allow_none=True)
233 233
234 234 # extra command-line arguments that don't set config values
235 235 extra_args = List(Unicode)
236 236
237 237
238 238 def __init__(self, **kwargs):
239 239 SingletonConfigurable.__init__(self, **kwargs)
240 240 # Ensure my class is in self.classes, so my attributes appear in command line
241 241 # options and config files.
242 242 if self.__class__ not in self.classes:
243 243 self.classes.insert(0, self.__class__)
244 244
245 245 def _config_changed(self, name, old, new):
246 246 SingletonConfigurable._config_changed(self, name, old, new)
247 247 self.log.debug('Config changed:')
248 248 self.log.debug(repr(new))
249 249
250 250 @catch_config_error
251 251 def initialize(self, argv=None):
252 252 """Do the basic steps to configure me.
253 253
254 254 Override in subclasses.
255 255 """
256 256 self.parse_command_line(argv)
257 257
258 258
259 259 def start(self):
260 260 """Start the app mainloop.
261 261
262 262 Override in subclasses.
263 263 """
264 264 if self.subapp is not None:
265 265 return self.subapp.start()
266 266
267 267 def print_alias_help(self):
268 268 """Print the alias part of the help."""
269 269 if not self.aliases:
270 270 return
271 271
272 272 lines = []
273 273 classdict = {}
274 274 for cls in self.classes:
275 275 # include all parents (up to, but excluding Configurable) in available names
276 276 for c in cls.mro()[:-3]:
277 277 classdict[c.__name__] = c
278 278
279 279 for alias, longname in iteritems(self.aliases):
280 280 classname, traitname = longname.split('.',1)
281 281 cls = classdict[classname]
282 282
283 283 trait = cls.class_traits(config=True)[traitname]
284 284 help = cls.class_get_trait_help(trait).splitlines()
285 285 # reformat first line
286 286 help[0] = help[0].replace(longname, alias) + ' (%s)'%longname
287 287 if len(alias) == 1:
288 288 help[0] = help[0].replace('--%s='%alias, '-%s '%alias)
289 289 lines.extend(help)
290 290 # lines.append('')
291 291 print(os.linesep.join(lines))
292 292
293 293 def print_flag_help(self):
294 294 """Print the flag part of the help."""
295 295 if not self.flags:
296 296 return
297 297
298 298 lines = []
299 299 for m, (cfg,help) in iteritems(self.flags):
300 300 prefix = '--' if len(m) > 1 else '-'
301 301 lines.append(prefix+m)
302 302 lines.append(indent(dedent(help.strip())))
303 303 # lines.append('')
304 304 print(os.linesep.join(lines))
305 305
306 306 def print_options(self):
307 307 if not self.flags and not self.aliases:
308 308 return
309 309 lines = ['Options']
310 310 lines.append('-'*len(lines[0]))
311 311 lines.append('')
312 312 for p in wrap_paragraphs(self.option_description):
313 313 lines.append(p)
314 314 lines.append('')
315 315 print(os.linesep.join(lines))
316 316 self.print_flag_help()
317 317 self.print_alias_help()
318 318 print()
319 319
320 320 def print_subcommands(self):
321 321 """Print the subcommand part of the help."""
322 322 if not self.subcommands:
323 323 return
324 324
325 325 lines = ["Subcommands"]
326 326 lines.append('-'*len(lines[0]))
327 327 lines.append('')
328 328 for p in wrap_paragraphs(self.subcommand_description):
329 329 lines.append(p)
330 330 lines.append('')
331 331 for subc, (cls, help) in iteritems(self.subcommands):
332 332 lines.append(subc)
333 333 if help:
334 334 lines.append(indent(dedent(help.strip())))
335 335 lines.append('')
336 336 print(os.linesep.join(lines))
337 337
338 338 def print_help(self, classes=False):
339 339 """Print the help for each Configurable class in self.classes.
340 340
341 341 If classes=False (the default), only flags and aliases are printed.
342 342 """
343 343 self.print_description()
344 344 self.print_subcommands()
345 345 self.print_options()
346 346
347 347 if classes:
348 348 if self.classes:
349 349 print("Class parameters")
350 350 print("----------------")
351 351 print()
352 352 for p in wrap_paragraphs(self.keyvalue_description):
353 353 print(p)
354 354 print()
355 355
356 356 for cls in self.classes:
357 357 cls.class_print_help()
358 358 print()
359 359 else:
360 360 print("To see all available configurables, use `--help-all`")
361 361 print()
362 362
363 363 self.print_examples()
364 364
365 365
366 366 def print_description(self):
367 367 """Print the application description."""
368 368 for p in wrap_paragraphs(self.description):
369 369 print(p)
370 370 print()
371 371
372 372 def print_examples(self):
373 373 """Print usage and examples.
374 374
375 375 This usage string goes at the end of the command line help string
376 376 and should contain examples of the application's usage.
377 377 """
378 378 if self.examples:
379 379 print("Examples")
380 380 print("--------")
381 381 print()
382 382 print(indent(dedent(self.examples.strip())))
383 383 print()
384 384
385 385 def print_version(self):
386 386 """Print the version string."""
387 387 print(self.version)
388 388
389 389 def update_config(self, config):
390 390 """Fire the traits events when the config is updated."""
391 391 # Save a copy of the current config.
392 392 newconfig = deepcopy(self.config)
393 393 # Merge the new config into the current one.
394 394 newconfig.merge(config)
395 395 # Save the combined config as self.config, which triggers the traits
396 396 # events.
397 397 self.config = newconfig
398 398
399 399 @catch_config_error
400 400 def initialize_subcommand(self, subc, argv=None):
401 401 """Initialize a subcommand with argv."""
402 402 subapp,help = self.subcommands.get(subc)
403 403
404 404 if isinstance(subapp, string_types):
405 405 subapp = import_item(subapp)
406 406
407 407 # clear existing instances
408 408 self.__class__.clear_instance()
409 409 # instantiate
410 410 self.subapp = subapp.instance(config=self.config)
411 411 # and initialize subapp
412 412 self.subapp.initialize(argv)
413 413
414 414 def flatten_flags(self):
415 415 """flatten flags and aliases, so cl-args override as expected.
416 416
417 417 This prevents issues such as an alias pointing to InteractiveShell,
418 418 but a config file setting the same trait in TerminalInteraciveShell
419 419 getting inappropriate priority over the command-line arg.
420 420
421 421 Only aliases with exactly one descendent in the class list
422 422 will be promoted.
423 423
424 424 """
425 425 # build a tree of classes in our list that inherit from a particular
426 426 # it will be a dict by parent classname of classes in our list
427 427 # that are descendents
428 428 mro_tree = defaultdict(list)
429 429 for cls in self.classes:
430 430 clsname = cls.__name__
431 431 for parent in cls.mro()[1:-3]:
432 432 # exclude cls itself and Configurable,HasTraits,object
433 433 mro_tree[parent.__name__].append(clsname)
434 434 # flatten aliases, which have the form:
435 435 # { 'alias' : 'Class.trait' }
436 436 aliases = {}
437 437 for alias, cls_trait in iteritems(self.aliases):
438 438 cls,trait = cls_trait.split('.',1)
439 439 children = mro_tree[cls]
440 440 if len(children) == 1:
441 441 # exactly one descendent, promote alias
442 442 cls = children[0]
443 443 aliases[alias] = '.'.join([cls,trait])
444 444
445 445 # flatten flags, which are of the form:
446 446 # { 'key' : ({'Cls' : {'trait' : value}}, 'help')}
447 447 flags = {}
448 448 for key, (flagdict, help) in iteritems(self.flags):
449 449 newflag = {}
450 450 for cls, subdict in iteritems(flagdict):
451 451 children = mro_tree[cls]
452 452 # exactly one descendent, promote flag section
453 453 if len(children) == 1:
454 454 cls = children[0]
455 455 newflag[cls] = subdict
456 456 flags[key] = (newflag, help)
457 457 return flags, aliases
458 458
459 459 @catch_config_error
460 460 def parse_command_line(self, argv=None):
461 461 """Parse the command line arguments."""
462 462 argv = sys.argv[1:] if argv is None else argv
463 463 self.argv = [ py3compat.cast_unicode(arg) for arg in argv ]
464 464
465 465 if argv and argv[0] == 'help':
466 466 # turn `ipython help notebook` into `ipython notebook -h`
467 467 argv = argv[1:] + ['-h']
468 468
469 469 if self.subcommands and len(argv) > 0:
470 470 # we have subcommands, and one may have been specified
471 471 subc, subargv = argv[0], argv[1:]
472 472 if re.match(r'^\w(\-?\w)*$', subc) and subc in self.subcommands:
473 473 # it's a subcommand, and *not* a flag or class parameter
474 474 return self.initialize_subcommand(subc, subargv)
475 475
476 476 # Arguments after a '--' argument are for the script IPython may be
477 477 # about to run, not IPython iteslf. For arguments parsed here (help and
478 478 # version), we want to only search the arguments up to the first
479 479 # occurrence of '--', which we're calling interpreted_argv.
480 480 try:
481 481 interpreted_argv = argv[:argv.index('--')]
482 482 except ValueError:
483 483 interpreted_argv = argv
484 484
485 485 if any(x in interpreted_argv for x in ('-h', '--help-all', '--help')):
486 486 self.print_help('--help-all' in interpreted_argv)
487 487 self.exit(0)
488 488
489 489 if '--version' in interpreted_argv or '-V' in interpreted_argv:
490 490 self.print_version()
491 491 self.exit(0)
492 492
493 493 # flatten flags&aliases, so cl-args get appropriate priority:
494 494 flags,aliases = self.flatten_flags()
495 495 loader = KVArgParseConfigLoader(argv=argv, aliases=aliases,
496 496 flags=flags, log=self.log)
497 497 config = loader.load_config()
498 498 self.update_config(config)
499 499 # store unparsed args in extra_args
500 500 self.extra_args = loader.extra_args
501 501
502 502 @classmethod
503 503 def _load_config_files(cls, basefilename, path=None, log=None):
504 504 """Load config files (py,json) by filename and path.
505 505
506 506 yield each config object in turn.
507 507 """
508 508
509 509 pyloader = PyFileConfigLoader(basefilename+'.py', path=path, log=log)
510 510 jsonloader = JSONFileConfigLoader(basefilename+'.json', path=path, log=log)
511 511 config_found = False
512 512 config = None
513 513 for loader in [pyloader, jsonloader]:
514 514 try:
515 515 config = loader.load_config()
516 516 config_found = True
517 517 except ConfigFileNotFound:
518 518 pass
519 519 except Exception:
520 520 # try to get the full filename, but it will be empty in the
521 521 # unlikely event that the error raised before filefind finished
522 522 filename = loader.full_filename or filename
523 523 # problem while running the file
524 log.error("Exception while loading config file %s",
525 filename, exc_info=True)
524 if log:
525 log.error("Exception while loading config file %s",
526 filename, exc_info=True)
526 527 else:
527 log.debug("Loaded config file: %s", loader.full_filename)
528 if log:
529 log.debug("Loaded config file: %s", loader.full_filename)
528 530 if config:
529 531 yield config
530 532
531 533 if not config_found:
532 534 raise ConfigFileNotFound('Neither .json, nor .py config file found.')
533 535 raise StopIteration
534 536
535 537
536 538 @catch_config_error
537 539 def load_config_file(self, filename, path=None):
538 540 """Load config files by filename and path."""
539 541 filename, ext = os.path.splitext(filename)
540 542 for config in self._load_config_files(filename, path=path, log=self.log):
541 543 self.update_config(config)
542 544
543 545
544 546 def generate_config_file(self):
545 547 """generate default config file from Configurables"""
546 548 lines = ["# Configuration file for %s."%self.name]
547 549 lines.append('')
548 550 lines.append('c = get_config()')
549 551 lines.append('')
550 552 for cls in self.classes:
551 553 lines.append(cls.class_config_section())
552 554 return '\n'.join(lines)
553 555
554 556 def exit(self, exit_status=0):
555 557 self.log.debug("Exiting application: %s" % self.name)
556 558 sys.exit(exit_status)
557 559
558 560 @classmethod
559 561 def launch_instance(cls, argv=None, **kwargs):
560 562 """Launch a global instance of this Application
561 563
562 564 If a global instance already exists, this reinitializes and starts it
563 565 """
564 566 app = cls.instance(**kwargs)
565 567 app.initialize(argv)
566 568 app.start()
567 569
568 570 #-----------------------------------------------------------------------------
569 571 # utility functions, for convenience
570 572 #-----------------------------------------------------------------------------
571 573
572 574 def boolean_flag(name, configurable, set_help='', unset_help=''):
573 575 """Helper for building basic --trait, --no-trait flags.
574 576
575 577 Parameters
576 578 ----------
577 579
578 580 name : str
579 581 The name of the flag.
580 582 configurable : str
581 583 The 'Class.trait' string of the trait to be set/unset with the flag
582 584 set_help : unicode
583 585 help string for --name flag
584 586 unset_help : unicode
585 587 help string for --no-name flag
586 588
587 589 Returns
588 590 -------
589 591
590 592 cfg : dict
591 593 A dict with two keys: 'name', and 'no-name', for setting and unsetting
592 594 the trait, respectively.
593 595 """
594 596 # default helpstrings
595 597 set_help = set_help or "set %s=True"%configurable
596 598 unset_help = unset_help or "set %s=False"%configurable
597 599
598 600 cls,trait = configurable.split('.')
599 601
600 602 setter = {cls : {trait : True}}
601 603 unsetter = {cls : {trait : False}}
602 604 return {name : (setter, set_help), 'no-'+name : (unsetter, unset_help)}
603 605
General Comments 0
You need to be logged in to leave comments. Login now