Fix rpmlint: non-executable-script

"""
This text file contains a shebang or is located in a path dedicated for
executables, but lacks the executable bits and cannot thus be executed.  If
the file is meant to be an executable script, add the executable bits,
otherwise remove the shebang or move the file elsewhere.
"""

Mostly deleting the shebang, but some files contain a __main__ function,
so make them executable.

This is the last commit of this series and:
Closes gh-647.

IPython/config/configurable.py

@@ -1,328 +1,327 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 A base class for objects that are configurable.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 * Min RK
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import datetime
 from copy import deepcopy
 
 from loader import Config
 from IPython.utils.traitlets import HasTraits, Instance
 from IPython.utils.text import indent, wrap_paragraphs
 
 
 #-----------------------------------------------------------------------------
 # Helper classes for Configurables
 #-----------------------------------------------------------------------------
 
 
 class ConfigurableError(Exception):
     pass
 
 
 class MultipleInstanceError(ConfigurableError):
     pass
 
 #-----------------------------------------------------------------------------
 # Configurable implementation
 #-----------------------------------------------------------------------------
 
 class Configurable(HasTraits):
 
     config = Instance(Config,(),{})
     created = None
 
     def __init__(self, **kwargs):
         """Create a configurable given a config config.
 
         Parameters
         ----------
         config : Config
             If this is empty, default values are used. If config is a 
             :class:`Config` instance, it will be used to configure the
             instance.
         
         Notes
         -----
         Subclasses of Configurable must call the :meth:`__init__` method of
         :class:`Configurable` *before* doing anything else and using 
         :func:`super`::
         
             class MyConfigurable(Configurable):
                 def __init__(self, config=None):
                     super(MyConfigurable, self).__init__(config)
                     # Then any other code you need to finish initialization.
 
         This ensures that instances will be configured properly.
         """
         config = kwargs.pop('config', None)
         if config is not None:
             # We used to deepcopy, but for now we are trying to just save
             # by reference.  This *could* have side effects as all components
             # will share config. In fact, I did find such a side effect in
             # _config_changed below. If a config attribute value was a mutable type
             # all instances of a component were getting the same copy, effectively
             # making that a class attribute.
             # self.config = deepcopy(config)
             self.config = config
         # This should go second so individual keyword arguments override 
         # the values in config.
         super(Configurable, self).__init__(**kwargs)
         self.created = datetime.datetime.now()
 
     #-------------------------------------------------------------------------
     # Static trait notifiations
     #-------------------------------------------------------------------------
 
     def _config_changed(self, name, old, new):
         """Update all the class traits having ``config=True`` as metadata.
 
         For any class trait with a ``config`` metadata attribute that is
         ``True``, we update the trait with the value of the corresponding
         config entry.
         """
         # Get all traits with a config metadata entry that is True
         traits = self.traits(config=True)
 
         # We auto-load config section for this class as well as any parent
         # classes that are Configurable subclasses.  This starts with Configurable
         # and works down the mro loading the config for each section.
         section_names = [cls.__name__ for cls in \
             reversed(self.__class__.__mro__) if 
             issubclass(cls, Configurable) and issubclass(self.__class__, cls)]
 
         for sname in section_names:
             # Don't do a blind getattr as that would cause the config to 
             # dynamically create the section with name self.__class__.__name__.
             if new._has_section(sname):
                 my_config = new[sname]
                 for k, v in traits.iteritems():
                     # Don't allow traitlets with config=True to start with
                     # uppercase.  Otherwise, they are confused with Config
                     # subsections.  But, developers shouldn't have uppercase
                     # attributes anyways! (PEP 6)
                     if k[0].upper()==k[0] and not k.startswith('_'):
                         raise ConfigurableError('Configurable traitlets with '
                         'config=True must start with a lowercase so they are '
                         'not confused with Config subsections: %s.%s' % \
                         (self.__class__.__name__, k))
                     try:
                         # Here we grab the value from the config
                         # If k has the naming convention of a config
                         # section, it will be auto created.
                         config_value = my_config[k]
                     except KeyError:
                         pass
                     else:
                         # print "Setting %s.%s from %s.%s=%r" % \
                         #     (self.__class__.__name__,k,sname,k,config_value)
                         # We have to do a deepcopy here if we don't deepcopy the entire
                         # config object. If we don't, a mutable config_value will be
                         # shared by all instances, effectively making it a class attribute.
                         setattr(self, k, deepcopy(config_value))
 
     @classmethod
     def class_get_help(cls):
         """Get the help string for this class in ReST format."""
         cls_traits = cls.class_traits(config=True)
         final_help = []
         final_help.append(u'%s options' % cls.__name__)
         final_help.append(len(final_help[0])*u'-')
         for k,v in cls.class_traits(config=True).iteritems():
             help = cls.class_get_trait_help(v)
             final_help.append(help)
         return '\n'.join(final_help)
     
     @classmethod
     def class_get_trait_help(cls, trait):
         """Get the help string for a single trait."""
         lines = []
         header = "--%s.%s=<%s>" % (cls.__name__, trait.name, trait.__class__.__name__)
         lines.append(header)
         try:
             dvr = repr(trait.get_default_value())
         except Exception:
             dvr = None # ignore defaults we can't construct
         if dvr is not None:
             if len(dvr) > 64:
                 dvr = dvr[:61]+'...'
             lines.append(indent('Default: %s'%dvr, 4))
         if 'Enum' in trait.__class__.__name__:
             # include Enum choices
             lines.append(indent('Choices: %r'%(trait.values,)))
         
         help = trait.get_metadata('help')
         if help is not None:
             help = '\n'.join(wrap_paragraphs(help, 76))
             lines.append(indent(help, 4))
         return '\n'.join(lines)
 
     @classmethod
     def class_print_help(cls):
         """Get the help string for a single trait and print it."""
         print cls.class_get_help()
 
     @classmethod
     def class_config_section(cls):
         """Get the config class config section"""
         def c(s):
             """return a commented, wrapped block."""
             s = '\n\n'.join(wrap_paragraphs(s, 78))
             
             return '# ' + s.replace('\n', '\n# ')
         
         # section header
         breaker = '#' + '-'*78
         s = "# %s configuration"%cls.__name__
         lines = [breaker, s, breaker, '']
         # get the description trait
         desc = cls.class_traits().get('description')
         if desc:
             desc = desc.default_value
         else:
             # no description trait, use __doc__
             desc = getattr(cls, '__doc__', '')
         if desc:
             lines.append(c(desc))
             lines.append('')
         
         parents = []
         for parent in cls.mro():
             # only include parents that are not base classes
             # and are not the class itself
             if issubclass(parent, Configurable) and \
                     not parent in (Configurable, SingletonConfigurable, cls):
                 parents.append(parent)
         
         if parents:
             pstr = ', '.join([ p.__name__ for p in parents ])
             lines.append(c('%s will inherit config from: %s'%(cls.__name__, pstr)))
             lines.append('')
         
         for name,trait in cls.class_traits(config=True).iteritems():
             help = trait.get_metadata('help') or ''
             lines.append(c(help))
             lines.append('# c.%s.%s = %r'%(cls.__name__, name, trait.get_default_value()))
             lines.append('')
         return '\n'.join(lines)
     
     
 
 class SingletonConfigurable(Configurable):
     """A configurable that only allows one instance.
 
     This class is for classes that should only have one instance of itself
     or *any* subclass. To create and retrieve such a class use the
     :meth:`SingletonConfigurable.instance` method.
     """
 
     _instance = None
     
     @classmethod
     def _walk_mro(cls):
         """Walk the cls.mro() for parent classes that are also singletons
         
         For use in instance()
         """
         
         for subclass in cls.mro():
             if issubclass(cls, subclass) and \
                     issubclass(subclass, SingletonConfigurable) and \
                     subclass != SingletonConfigurable:
                 yield subclass
     
     @classmethod
     def clear_instance(cls):
         """unset _instance for this class and singleton parents.
         """
         if not cls.initialized():
             return
         for subclass in cls._walk_mro():
             if isinstance(subclass._instance, cls):
                 # only clear instances that are instances
                 # of the calling class
                 subclass._instance = None
             
     @classmethod
     def instance(cls, *args, **kwargs):
         """Returns a global instance of this class.
 
         This method create a new instance if none have previously been created
         and returns a previously created instance is one already exists.
 
         The arguments and keyword arguments passed to this method are passed
         on to the :meth:`__init__` method of the class upon instantiation.
 
         Examples
         --------
 
         Create a singleton class using instance, and retrieve it::
 
             >>> from IPython.config.configurable import SingletonConfigurable
             >>> class Foo(SingletonConfigurable): pass
             >>> foo = Foo.instance()
             >>> foo == Foo.instance()
             True
 
         Create a subclass that is retrived using the base class instance::
 
             >>> class Bar(SingletonConfigurable): pass
             >>> class Bam(Bar): pass
             >>> bam = Bam.instance()
             >>> bam == Bar.instance()
             True
         """
         # Create and save the instance
         if cls._instance is None:
             inst = cls(*args, **kwargs)
             # Now make sure that the instance will also be returned by
             # parent classes' _instance attribute.
             for subclass in cls._walk_mro():
                 subclass._instance = inst
         
         if isinstance(cls._instance, cls):
             return cls._instance
         else:
             raise MultipleInstanceError(
                 'Multiple incompatible subclass instances of '
                 '%s are being created.' % cls.__name__
             )
 
     @classmethod
     def initialized(cls):
         """Has an instance been created?"""
         return hasattr(cls, "_instance") and cls._instance is not None
 
 
 class LoggingConfigurable(Configurable):
     """A parent class for Configurables that log.
     
     Subclasses have a log trait, and the default behavior
     is to get the logger from the currently running Application
     via Application.instance().log.
     """
     
     log = Instance('logging.Logger')
     def _log_default(self):
         from IPython.config.application import Application
         return Application.instance().log
         
         

IPython/config/tests/test_configurable.py

@@ -1,166 +1,165 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Tests for IPython.config.configurable
 
 Authors:
 
 * Brian Granger
 * Fernando Perez (design help)
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from unittest import TestCase
 
 from IPython.config.configurable import (
     Configurable, 
     SingletonConfigurable
 )
 
 from IPython.utils.traitlets import (
     Int, Float, Unicode
 )
 
 from IPython.config.loader import Config
 
 
 #-----------------------------------------------------------------------------
 # Test cases
 #-----------------------------------------------------------------------------
 
 
 class MyConfigurable(Configurable):
     a = Int(1, config=True, help="The integer a.")
     b = Float(1.0, config=True, help="The integer b.")
     c = Unicode('no config')
 
 
 mc_help=u"""MyConfigurable options
 ----------------------
 --MyConfigurable.a=<Int>
     Default: 1
     The integer a.
 --MyConfigurable.b=<Float>
     Default: 1.0
     The integer b."""
 
 class Foo(Configurable):
     a = Int(0, config=True, help="The integer a.")
     b = Unicode('nope', config=True)
 
 
 class Bar(Foo):
     b = Unicode('gotit', config=False, help="The string b.")
     c = Float(config=True, help="The string c.")
 
 
 class TestConfigurable(TestCase):
 
     def test_default(self):
         c1 = Configurable()
         c2 = Configurable(config=c1.config)
         c3 = Configurable(config=c2.config)
         self.assertEquals(c1.config, c2.config)
         self.assertEquals(c2.config, c3.config)
 
     def test_custom(self):
         config = Config()
         config.foo = 'foo'
         config.bar = 'bar'
         c1 = Configurable(config=config)
         c2 = Configurable(config=c1.config)
         c3 = Configurable(config=c2.config)
         self.assertEquals(c1.config, config)
         self.assertEquals(c2.config, config)
         self.assertEquals(c3.config, config)
         # Test that copies are not made
         self.assert_(c1.config is config)
         self.assert_(c2.config is config)
         self.assert_(c3.config is config)
         self.assert_(c1.config is c2.config)
         self.assert_(c2.config is c3.config)
         
     def test_inheritance(self):
         config = Config()
         config.MyConfigurable.a = 2
         config.MyConfigurable.b = 2.0
         c1 = MyConfigurable(config=config)
         c2 = MyConfigurable(config=c1.config)
         self.assertEquals(c1.a, config.MyConfigurable.a)
         self.assertEquals(c1.b, config.MyConfigurable.b)
         self.assertEquals(c2.a, config.MyConfigurable.a)
         self.assertEquals(c2.b, config.MyConfigurable.b)
 
     def test_parent(self):
         config = Config()
         config.Foo.a = 10
         config.Foo.b = "wow"
         config.Bar.b = 'later'
         config.Bar.c = 100.0
         f = Foo(config=config)
         b = Bar(config=f.config)
         self.assertEquals(f.a, 10)
         self.assertEquals(f.b, 'wow')
         self.assertEquals(b.b, 'gotit')
         self.assertEquals(b.c, 100.0)
 
     def test_override1(self):
         config = Config()
         config.MyConfigurable.a = 2
         config.MyConfigurable.b = 2.0
         c = MyConfigurable(a=3, config=config)
         self.assertEquals(c.a, 3)
         self.assertEquals(c.b, config.MyConfigurable.b)
         self.assertEquals(c.c, 'no config')
 
     def test_override2(self):
         config = Config()
         config.Foo.a = 1
         config.Bar.b = 'or'  # Up above b is config=False, so this won't do it.
         config.Bar.c = 10.0
         c = Bar(config=config)
         self.assertEquals(c.a, config.Foo.a)
         self.assertEquals(c.b, 'gotit')
         self.assertEquals(c.c, config.Bar.c)
         c = Bar(a=2, b='and', c=20.0, config=config)
         self.assertEquals(c.a, 2)
         self.assertEquals(c.b, 'and')
         self.assertEquals(c.c, 20.0)
 
     def test_help(self):
         self.assertEquals(MyConfigurable.class_get_help(), mc_help)
 
 
 class TestSingletonConfigurable(TestCase):
 
     def test_instance(self):
         from IPython.config.configurable import SingletonConfigurable
         class Foo(SingletonConfigurable): pass
         self.assertEquals(Foo.initialized(), False)
         foo = Foo.instance()
         self.assertEquals(Foo.initialized(), True)
         self.assertEquals(foo, Foo.instance())
         self.assertEquals(SingletonConfigurable._instance, None)
 
     def test_inheritance(self):
         class Bar(SingletonConfigurable): pass
         class Bam(Bar): pass
         self.assertEquals(Bar.initialized(), False)
         self.assertEquals(Bam.initialized(), False)
         bam = Bam.instance()
         bam == Bar.instance()
         self.assertEquals(Bar.initialized(), True)
         self.assertEquals(Bam.initialized(), True)
         self.assertEquals(bam, Bam._instance)
         self.assertEquals(bam, Bar._instance)
         self.assertEquals(SingletonConfigurable._instance, None)

IPython/config/tests/test_loader.py

@@ -1,226 +1,225 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Tests for IPython.config.loader
 
 Authors:
 
 * Brian Granger
 * Fernando Perez (design help)
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import sys
 from tempfile import mkstemp
 from unittest import TestCase
 
 from nose import SkipTest
 
 from IPython.testing.tools import mute_warn
 
 from IPython.utils.traitlets import Int, Unicode
 from IPython.config.configurable import Configurable
 from IPython.config.loader import (
     Config,
     PyFileConfigLoader,
     KeyValueConfigLoader,
     ArgParseConfigLoader,
     ConfigError
 )
 
 #-----------------------------------------------------------------------------
 # Actual tests
 #-----------------------------------------------------------------------------
 
 
 pyfile = """
 c = get_config()
 c.a=10
 c.b=20
 c.Foo.Bar.value=10
 c.Foo.Bam.value=range(10)
 c.D.C.value='hi there'
 """
 
 class TestPyFileCL(TestCase):
 
     def test_basic(self):
         fd, fname = mkstemp('.py')
         f = os.fdopen(fd, 'w')
         f.write(pyfile)
         f.close()
         # Unlink the file
         cl = PyFileConfigLoader(fname)
         config = cl.load_config()
         self.assertEquals(config.a, 10)
         self.assertEquals(config.b, 20)
         self.assertEquals(config.Foo.Bar.value, 10)
         self.assertEquals(config.Foo.Bam.value, range(10))
         self.assertEquals(config.D.C.value, 'hi there')
 
 class MyLoader1(ArgParseConfigLoader):
     def _add_arguments(self):
         p = self.parser
         p.add_argument('-f', '--foo', dest='Global.foo', type=str)
         p.add_argument('-b', dest='MyClass.bar', type=int)
         p.add_argument('-n', dest='n', action='store_true')
         p.add_argument('Global.bam', type=str)
 
 class MyLoader2(ArgParseConfigLoader):
     def _add_arguments(self):
         subparsers = self.parser.add_subparsers(dest='subparser_name')
         subparser1 = subparsers.add_parser('1')
         subparser1.add_argument('-x',dest='Global.x')
         subparser2 = subparsers.add_parser('2')
         subparser2.add_argument('y')
 
 class TestArgParseCL(TestCase):
 
     def test_basic(self):
         cl = MyLoader1()
         config = cl.load_config('-f hi -b 10 -n wow'.split())
         self.assertEquals(config.Global.foo, 'hi')
         self.assertEquals(config.MyClass.bar, 10)
         self.assertEquals(config.n, True)
         self.assertEquals(config.Global.bam, 'wow')
         config = cl.load_config(['wow'])
         self.assertEquals(config.keys(), ['Global'])
         self.assertEquals(config.Global.keys(), ['bam'])
         self.assertEquals(config.Global.bam, 'wow')
 
     def test_add_arguments(self):
         cl = MyLoader2()
         config = cl.load_config('2 frobble'.split())
         self.assertEquals(config.subparser_name, '2')
         self.assertEquals(config.y, 'frobble')
         config = cl.load_config('1 -x frobble'.split())
         self.assertEquals(config.subparser_name, '1')
         self.assertEquals(config.Global.x, 'frobble')
 
     def test_argv(self):
         cl = MyLoader1(argv='-f hi -b 10 -n wow'.split())
         config = cl.load_config()
         self.assertEquals(config.Global.foo, 'hi')
         self.assertEquals(config.MyClass.bar, 10)
         self.assertEquals(config.n, True)
         self.assertEquals(config.Global.bam, 'wow')
 
 
 class TestKeyValueCL(TestCase):
 
     def test_basic(self):
         cl = KeyValueConfigLoader()
         argv = ['--'+s.strip('c.') for s in pyfile.split('\n')[2:-1]]
         with mute_warn():
             config = cl.load_config(argv)
         self.assertEquals(config.a, 10)
         self.assertEquals(config.b, 20)
         self.assertEquals(config.Foo.Bar.value, 10)
         self.assertEquals(config.Foo.Bam.value, range(10))
         self.assertEquals(config.D.C.value, 'hi there')
     
     def test_extra_args(self):
         cl = KeyValueConfigLoader()
         with mute_warn():
             config = cl.load_config(['--a=5', 'b', '--c=10', 'd'])
         self.assertEquals(cl.extra_args, ['b', 'd'])
         self.assertEquals(config.a, 5)
         self.assertEquals(config.c, 10)
         with mute_warn():
             config = cl.load_config(['--', '--a=5', '--c=10'])
         self.assertEquals(cl.extra_args, ['--a=5', '--c=10'])
     
     def test_unicode_args(self):
         cl = KeyValueConfigLoader()
         argv = [u'--a=épsîlön']
         with mute_warn():
             config = cl.load_config(argv)
         self.assertEquals(config.a, u'épsîlön')
     
     def test_unicode_bytes_args(self):
         uarg = u'--a=é'
         try:
             barg = uarg.encode(sys.stdin.encoding)
         except (TypeError, UnicodeEncodeError):
             raise SkipTest("sys.stdin.encoding can't handle 'é'")
         
         cl = KeyValueConfigLoader()
         with mute_warn():
             config = cl.load_config([barg])
         self.assertEquals(config.a, u'é')
 
 
 class TestConfig(TestCase):
 
     def test_setget(self):
         c = Config()
         c.a = 10
         self.assertEquals(c.a, 10)
         self.assertEquals(c.has_key('b'), False)
 
     def test_auto_section(self):
         c = Config()
         self.assertEquals(c.has_key('A'), True)
         self.assertEquals(c._has_section('A'), False)
         A = c.A
         A.foo = 'hi there'
         self.assertEquals(c._has_section('A'), True)
         self.assertEquals(c.A.foo, 'hi there')
         del c.A
         self.assertEquals(len(c.A.keys()),0)
 
     def test_merge_doesnt_exist(self):
         c1 = Config()
         c2 = Config()
         c2.bar = 10
         c2.Foo.bar = 10
         c1._merge(c2)
         self.assertEquals(c1.Foo.bar, 10)
         self.assertEquals(c1.bar, 10)
         c2.Bar.bar = 10
         c1._merge(c2)
         self.assertEquals(c1.Bar.bar, 10)
 
     def test_merge_exists(self):
         c1 = Config()
         c2 = Config()
         c1.Foo.bar = 10
         c1.Foo.bam = 30
         c2.Foo.bar = 20
         c2.Foo.wow = 40
         c1._merge(c2)
         self.assertEquals(c1.Foo.bam, 30)
         self.assertEquals(c1.Foo.bar, 20)
         self.assertEquals(c1.Foo.wow, 40)
         c2.Foo.Bam.bam = 10
         c1._merge(c2)
         self.assertEquals(c1.Foo.Bam.bam, 10)
 
     def test_deepcopy(self):
         c1 = Config()
         c1.Foo.bar = 10
         c1.Foo.bam = 30
         c1.a = 'asdf'
         c1.b = range(10)
         import copy
         c2 = copy.deepcopy(c1)
         self.assertEquals(c1, c2)
         self.assert_(c1 is not c2)
         self.assert_(c1.Foo is not c2.Foo)
 
     def test_builtin(self):
         c1 = Config()
         exec 'foo = True' in c1
         self.assertEquals(c1.foo, True)
         self.assertRaises(ConfigError, setattr, c1, 'ValueError', 10)

IPython/core/alias.py

@@ -1,264 +1,263 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 System command aliases.
 
 Authors:
 
 * Fernando Perez
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import __builtin__
 import keyword
 import os
 import re
 import sys
 
 from IPython.config.configurable import Configurable
 from IPython.core.splitinput import split_user_input
 
 from IPython.utils.traitlets import List, Instance
 from IPython.utils.autoattr import auto_attr
 from IPython.utils.warn import warn, error
 
 #-----------------------------------------------------------------------------
 # Utilities
 #-----------------------------------------------------------------------------
 
 # This is used as the pattern for calls to split_user_input.
 shell_line_split = re.compile(r'^(\s*)(\S*\s*)(.*$)')
 
 def default_aliases():
     """Return list of shell aliases to auto-define.
     """
     # Note: the aliases defined here should be safe to use on a kernel
     # regardless of what frontend it is attached to.  Frontends that use a
     # kernel in-process can define additional aliases that will only work in
     # their case.  For example, things like 'less' or 'clear' that manipulate
     # the terminal should NOT be declared here, as they will only work if the
     # kernel is running inside a true terminal, and not over the network.
     
     if os.name == 'posix':
         default_aliases = [('mkdir', 'mkdir'), ('rmdir', 'rmdir'),
                            ('mv', 'mv -i'), ('rm', 'rm -i'), ('cp', 'cp -i'),
                            ('cat', 'cat'),
                            ]
         # Useful set of ls aliases.  The GNU and BSD options are a little
         # different, so we make aliases that provide as similar as possible
         # behavior in ipython, by passing the right flags for each platform
         if sys.platform.startswith('linux'):
             ls_aliases = [('ls', 'ls -F --color'),
                           # long ls
                           ('ll', 'ls -F -o --color'),
                           # ls normal files only
                           ('lf', 'ls -F -o --color %l | grep ^-'),
                           # ls symbolic links
                           ('lk', 'ls -F -o --color %l | grep ^l'),
                           # directories or links to directories,
                           ('ldir', 'ls -F -o --color %l | grep /$'),
                           # things which are executable
                           ('lx', 'ls -F -o --color %l | grep ^-..x'),
                           ]
         else:
             # BSD, OSX, etc.
             ls_aliases = [('ls', 'ls -F'),
                           # long ls
                           ('ll', 'ls -F -l'),
                           # ls normal files only
                           ('lf', 'ls -F -l %l | grep ^-'),
                           # ls symbolic links
                           ('lk', 'ls -F -l %l | grep ^l'),
                           # directories or links to directories,
                           ('ldir', 'ls -F -l %l | grep /$'),
                           # things which are executable
                           ('lx', 'ls -F -l %l | grep ^-..x'),
                           ]
         default_aliases = default_aliases + ls_aliases
     elif os.name in ['nt', 'dos']:
         default_aliases = [('ls', 'dir /on'),
                            ('ddir', 'dir /ad /on'), ('ldir', 'dir /ad /on'),
                            ('mkdir', 'mkdir'), ('rmdir', 'rmdir'),
                            ('echo', 'echo'), ('ren', 'ren'), ('copy', 'copy'),
                            ]
     else:
         default_aliases = []
         
     return default_aliases
 
 
 class AliasError(Exception):
     pass
 
 
 class InvalidAliasError(AliasError):
     pass
 
 #-----------------------------------------------------------------------------
 # Main AliasManager class
 #-----------------------------------------------------------------------------
 
 class AliasManager(Configurable):
 
     default_aliases = List(default_aliases(), config=True)
     user_aliases = List(default_value=[], config=True)
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
 
     def __init__(self, shell=None, config=None):
         super(AliasManager, self).__init__(shell=shell, config=config)
         self.alias_table = {}
         self.exclude_aliases()
         self.init_aliases()
 
     def __contains__(self, name):
         return name in self.alias_table
 
     @property
     def aliases(self):
         return [(item[0], item[1][1]) for item in self.alias_table.iteritems()]
 
     def exclude_aliases(self):
         # set of things NOT to alias (keywords, builtins and some magics)
         no_alias = set(['cd','popd','pushd','dhist','alias','unalias'])
         no_alias.update(set(keyword.kwlist))
         no_alias.update(set(__builtin__.__dict__.keys()))
         self.no_alias = no_alias
 
     def init_aliases(self):
         # Load default aliases
         for name, cmd in self.default_aliases:
             self.soft_define_alias(name, cmd)
 
         # Load user aliases
         for name, cmd in self.user_aliases:
             self.soft_define_alias(name, cmd)
 
     def clear_aliases(self):
         self.alias_table.clear()
 
     def soft_define_alias(self, name, cmd):
         """Define an alias, but don't raise on an AliasError."""
         try:
             self.define_alias(name, cmd)
         except AliasError, e:
             error("Invalid alias: %s" % e)
 
     def define_alias(self, name, cmd):
         """Define a new alias after validating it.
 
         This will raise an :exc:`AliasError` if there are validation
         problems.
         """
         nargs = self.validate_alias(name, cmd)
         self.alias_table[name] = (nargs, cmd)
 
     def undefine_alias(self, name):
         if self.alias_table.has_key(name):
             del self.alias_table[name]
 
     def validate_alias(self, name, cmd):
         """Validate an alias and return the its number of arguments."""
         if name in self.no_alias:
             raise InvalidAliasError("The name %s can't be aliased "
                                     "because it is a keyword or builtin." % name)
         if not (isinstance(cmd, basestring)):
             raise InvalidAliasError("An alias command must be a string, "
                                     "got: %r" % name)
         nargs = cmd.count('%s')
         if nargs>0 and cmd.find('%l')>=0:
             raise InvalidAliasError('The %s and %l specifiers are mutually '
                                     'exclusive in alias definitions.')
         return nargs
 
     def call_alias(self, alias, rest=''):
         """Call an alias given its name and the rest of the line."""
         cmd = self.transform_alias(alias, rest)
         try:
             self.shell.system(cmd)
         except:
             self.shell.showtraceback()
 
     def transform_alias(self, alias,rest=''):
         """Transform alias to system command string."""
         nargs, cmd = self.alias_table[alias]
 
         if ' ' in cmd and os.path.isfile(cmd):
             cmd = '"%s"' % cmd
 
         # Expand the %l special to be the user's input line
         if cmd.find('%l') >= 0:
             cmd = cmd.replace('%l', rest)
             rest = ''
         if nargs==0:
             # Simple, argument-less aliases
             cmd = '%s %s' % (cmd, rest)
         else:
             # Handle aliases with positional arguments
             args = rest.split(None, nargs)
             if len(args) < nargs:
                 raise AliasError('Alias <%s> requires %s arguments, %s given.' %
                       (alias, nargs, len(args)))
             cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
         return cmd
 
     def expand_alias(self, line):
         """ Expand an alias in the command line 
         
         Returns the provided command line, possibly with the first word 
         (command) translated according to alias expansion rules.
         
         [ipython]|16> _ip.expand_aliases("np myfile.txt")
                  <16> 'q:/opt/np/notepad++.exe myfile.txt'
         """
         
         pre,fn,rest = split_user_input(line)
         res = pre + self.expand_aliases(fn, rest)
         return res
 
     def expand_aliases(self, fn, rest):
         """Expand multiple levels of aliases:
         
         if:
         
         alias foo bar /tmp
         alias baz foo
         
         then:
         
         baz huhhahhei -> bar /tmp huhhahhei
         """
         line = fn + " " + rest
         
         done = set()
         while 1:
             pre,fn,rest = split_user_input(line, shell_line_split)
             if fn in self.alias_table:
                 if fn in done:
                     warn("Cyclic alias definition, repeated '%s'" % fn)
                     return ""
                 done.add(fn)
 
                 l2 = self.transform_alias(fn, rest)
                 if l2 == line:
                     break
                 # ls -> ls -F should not recurse forever
                 if l2.split(None,1)[0] == line.split(None,1)[0]:
                     line = l2
                     break
                 line=l2
             else:
                 break
                 
         return line

IPython/core/autocall.py

@@ -1,71 +1,70 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Autocall capabilities for IPython.core.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 * Thomas Kluyver
 
 Notes
 -----
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 class IPyAutocall(object):
     """ Instances of this class are always autocalled
     
     This happens regardless of 'autocall' variable state. Use this to
     develop macro-like mechanisms.
     """
     _ip = None
     rewrite = True
     def __init__(self, ip=None):
         self._ip = ip
     
     def set_ip(self, ip):
         """ Will be used to set _ip point to current ipython instance b/f call
         
         Override this method if you don't want this to happen.
         
         """
         self._ip = ip
 
 
 class ExitAutocall(IPyAutocall):
     """An autocallable object which will be added to the user namespace so that
     exit, exit(), quit or quit() are all valid ways to close the shell."""
     rewrite = False
     
     def __call__(self):
         self._ip.ask_exit()
         
 class ZMQExitAutocall(ExitAutocall):
     """Exit IPython. Autocallable, so it needn't be explicitly called.
     
     Parameters
     ----------
     keep_kernel : bool
       If True, leave the kernel alive. Otherwise, tell the kernel to exit too
       (default).
     """
     def __call__(self, keep_kernel=False):
         self._ip.keepkernel_on_exit = keep_kernel
         self._ip.ask_exit()

IPython/core/display_trap.py

@@ -1,71 +1,70 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 A context manager for handling sys.displayhook.
 
 Authors:
 
 * Robert Kern
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import sys
 
 from IPython.config.configurable import Configurable
 from IPython.utils.traitlets import Any
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 
 class DisplayTrap(Configurable):
     """Object to manage sys.displayhook.
 
     This came from IPython.core.kernel.display_hook, but is simplified
     (no callbacks or formatters) until more of the core is refactored.
     """
 
     hook = Any
 
     def __init__(self, hook=None):
         super(DisplayTrap, self).__init__(hook=hook, config=None)
         self.old_hook = None
         # We define this to track if a single BuiltinTrap is nested.
         # Only turn off the trap when the outermost call to __exit__ is made.
         self._nested_level = 0
 
     def __enter__(self):
         if self._nested_level == 0:
             self.set()
         self._nested_level += 1
         return self
 
     def __exit__(self, type, value, traceback):
         if self._nested_level == 1:
             self.unset()
         self._nested_level -= 1
         # Returning False will cause exceptions to propagate
         return False
 
     def set(self):
         """Set the hook."""
         if sys.displayhook is not self.hook:
             self.old_hook = sys.displayhook
             sys.displayhook = self.hook
 
     def unset(self):
         """Unset the hook."""
         sys.displayhook = self.old_hook
 

IPython/core/error.py

@@ -1,52 +1,51 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Global exception classes for IPython.core.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 
 Notes
 -----
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Exception classes
 #-----------------------------------------------------------------------------
 
 class IPythonCoreError(Exception):
     pass
 
 
 class TryNext(IPythonCoreError):
     """Try next hook exception.
      
     Raise this in your hook function to indicate that the next hook handler
     should be used to handle the operation.  If you pass arguments to the
     constructor those arguments will be used by the next hook instead of the
     original ones.
     """
 
     def __init__(self, *args, **kwargs):
         self.args = args
         self.kwargs = kwargs
 
 class UsageError(IPythonCoreError):
     """Error in magic function arguments, etc.
     
     Something that probably won't warrant a full traceback, but should
     nevertheless interrupt a macro / batch file.   
     """

IPython/core/ipapi.py

@@ -1,30 +1,29 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 This module is *completely* deprecated and should no longer be used for
 any purpose.  Currently, we have a few parts of the core that have
 not been componentized and thus, still rely on this module.  When everything
 has been made into a component, this module will be sent to deathrow.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 
 def get():
     """Get the global InteractiveShell instance."""
     from IPython.core.interactiveshell import InteractiveShell
     return InteractiveShell.instance()
 

IPython/core/page.py

@@ -1,327 +1,326 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Paging capabilities for IPython.core
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 
 Notes
 -----
 
 For now this uses ipapi, so it can't be in IPython.utils.  If we can get
 rid of that dependency, we could move it there.
 -----
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import re
 import sys
 import tempfile
 
 from IPython.core import ipapi
 from IPython.core.error import TryNext
 from IPython.utils.cursesimport import use_curses
 from IPython.utils.data import chop
 from IPython.utils import io
 from IPython.utils.process import system
 from IPython.utils.terminal import get_terminal_size
 
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 esc_re = re.compile(r"(\x1b[^m]+m)")
 
 def page_dumb(strng, start=0, screen_lines=25):
     """Very dumb 'pager' in Python, for when nothing else works.
 
     Only moves forward, same interface as page(), except for pager_cmd and
     mode."""
 
     out_ln  = strng.splitlines()[start:]
     screens = chop(out_ln,screen_lines-1)
     if len(screens) == 1:
         print >>io.stdout, os.linesep.join(screens[0])
     else:
         last_escape = ""
         for scr in screens[0:-1]:
             hunk = os.linesep.join(scr)
             print >>io.stdout, last_escape + hunk
             if not page_more():
                 return
             esc_list = esc_re.findall(hunk)
             if len(esc_list) > 0:
                 last_escape = esc_list[-1]
         print >>io.stdout, last_escape + os.linesep.join(screens[-1])
 
 
 def page(strng, start=0, screen_lines=0, pager_cmd=None):
     """Print a string, piping through a pager after a certain length.
 
     The screen_lines parameter specifies the number of *usable* lines of your
     terminal screen (total lines minus lines you need to reserve to show other
     information).
 
     If you set screen_lines to a number <=0, page() will try to auto-determine
     your screen size and will only use up to (screen_size+screen_lines) for
     printing, paging after that. That is, if you want auto-detection but need
     to reserve the bottom 3 lines of the screen, use screen_lines = -3, and for
     auto-detection without any lines reserved simply use screen_lines = 0.
 
     If a string won't fit in the allowed lines, it is sent through the
     specified pager command. If none given, look for PAGER in the environment,
     and ultimately default to less.
 
     If no system pager works, the string is sent through a 'dumb pager'
     written in python, very simplistic.
     """
 
     # Some routines may auto-compute start offsets incorrectly and pass a
     # negative value.  Offset to 0 for robustness.
     start = max(0, start)
 
     # first, try the hook
     ip = ipapi.get()
     if ip:
         try:
             ip.hooks.show_in_pager(strng)
             return
         except TryNext:
             pass
 
     # Ugly kludge, but calling curses.initscr() flat out crashes in emacs
     TERM = os.environ.get('TERM','dumb')
     if TERM in ['dumb','emacs'] and os.name != 'nt':
         print strng
         return
     # chop off the topmost part of the string we don't want to see
     str_lines = strng.splitlines()[start:]
     str_toprint = os.linesep.join(str_lines)
     num_newlines = len(str_lines)
     len_str = len(str_toprint)
 
     # Dumb heuristics to guesstimate number of on-screen lines the string
     # takes.  Very basic, but good enough for docstrings in reasonable
     # terminals. If someone later feels like refining it, it's not hard.
     numlines = max(num_newlines,int(len_str/80)+1)
 
     screen_lines_def = get_terminal_size()[1]
 
     # auto-determine screen size
     if screen_lines <= 0:
         if (TERM=='xterm' or TERM=='xterm-color') and sys.platform != 'sunos5':
             local_use_curses = use_curses
         else:
             # curses causes problems on many terminals other than xterm, and
             # some termios calls lock up on Sun OS5.
             local_use_curses = False
         if local_use_curses:
             import termios
             import curses
             # There is a bug in curses, where *sometimes* it fails to properly
             # initialize, and then after the endwin() call is made, the
             # terminal is left in an unusable state.  Rather than trying to
             # check everytime for this (by requesting and comparing termios
             # flags each time), we just save the initial terminal state and
             # unconditionally reset it every time.  It's cheaper than making
             # the checks.
             term_flags = termios.tcgetattr(sys.stdout)
 
             # Curses modifies the stdout buffer size by default, which messes
             # up Python's normal stdout buffering.  This would manifest itself
             # to IPython users as delayed printing on stdout after having used
             # the pager.
             #
             # We can prevent this by manually setting the NCURSES_NO_SETBUF
             # environment variable.  For more details, see:
             # http://bugs.python.org/issue10144
             NCURSES_NO_SETBUF = os.environ.get('NCURSES_NO_SETBUF', None)
             os.environ['NCURSES_NO_SETBUF'] = ''
             
             # Proceed with curses initialization
             scr = curses.initscr()
             screen_lines_real,screen_cols = scr.getmaxyx()
             curses.endwin()
 
             # Restore environment
             if NCURSES_NO_SETBUF is None:
                 del os.environ['NCURSES_NO_SETBUF']
             else:
                 os.environ['NCURSES_NO_SETBUF'] = NCURSES_NO_SETBUF
                 
             # Restore terminal state in case endwin() didn't.
             termios.tcsetattr(sys.stdout,termios.TCSANOW,term_flags)
             # Now we have what we needed: the screen size in rows/columns
             screen_lines += screen_lines_real
             #print '***Screen size:',screen_lines_real,'lines x',\
             #screen_cols,'columns.' # dbg
         else:
             screen_lines += screen_lines_def
 
     #print 'numlines',numlines,'screenlines',screen_lines  # dbg
     if numlines <= screen_lines :
         #print '*** normal print'  # dbg
         print >>io.stdout, str_toprint
     else:
         # Try to open pager and default to internal one if that fails.
         # All failure modes are tagged as 'retval=1', to match the return
         # value of a failed system command.  If any intermediate attempt
         # sets retval to 1, at the end we resort to our own page_dumb() pager.
         pager_cmd = get_pager_cmd(pager_cmd)
         pager_cmd += ' ' + get_pager_start(pager_cmd,start)
         if os.name == 'nt':
             if pager_cmd.startswith('type'):
                 # The default WinXP 'type' command is failing on complex strings.
                 retval = 1
             else:
                 tmpname = tempfile.mktemp('.txt')
                 tmpfile = file(tmpname,'wt')
                 tmpfile.write(strng)
                 tmpfile.close()
                 cmd = "%s < %s" % (pager_cmd,tmpname)
                 if os.system(cmd):
                   retval = 1
                 else:
                   retval = None
                 os.remove(tmpname)
         else:
             try:
                 retval = None
                 # if I use popen4, things hang. No idea why.
                 #pager,shell_out = os.popen4(pager_cmd)
                 pager = os.popen(pager_cmd,'w')
                 pager.write(strng)
                 pager.close()
                 retval = pager.close()  # success returns None
             except IOError,msg:  # broken pipe when user quits
                 if msg.args == (32,'Broken pipe'):
                     retval = None
                 else:
                     retval = 1
             except OSError:
                 # Other strange problems, sometimes seen in Win2k/cygwin
                 retval = 1
         if retval is not None:
             page_dumb(strng,screen_lines=screen_lines)
 
 
 def page_file(fname, start=0, pager_cmd=None):
     """Page a file, using an optional pager command and starting line.
     """
 
     pager_cmd = get_pager_cmd(pager_cmd)
     pager_cmd += ' ' + get_pager_start(pager_cmd,start)
 
     try:
         if os.environ['TERM'] in ['emacs','dumb']:
             raise EnvironmentError
         system(pager_cmd + ' ' + fname)
     except:
         try:
             if start > 0:
                 start -= 1
             page(open(fname).read(),start)
         except:
             print 'Unable to show file',`fname`
 
 
 def get_pager_cmd(pager_cmd=None):
     """Return a pager command.
 
     Makes some attempts at finding an OS-correct one.
     """
     if os.name == 'posix':
         default_pager_cmd = 'less -r'  # -r for color control sequences
     elif os.name in ['nt','dos']:
         default_pager_cmd = 'type'
 
     if pager_cmd is None:
         try:
             pager_cmd = os.environ['PAGER']
         except:
             pager_cmd = default_pager_cmd
     return pager_cmd
 
 
 def get_pager_start(pager, start):
     """Return the string for paging files with an offset.
 
     This is the '+N' argument which less and more (under Unix) accept.
     """
 
     if pager in ['less','more']:
         if start:
             start_string = '+' + str(start)
         else:
             start_string = ''
     else:
         start_string = ''
     return start_string
 
 
 # (X)emacs on win32 doesn't like to be bypassed with msvcrt.getch()
 if os.name == 'nt' and os.environ.get('TERM','dumb') != 'emacs':
     import msvcrt
     def page_more():
         """ Smart pausing between pages
 
         @return:    True if need print more lines, False if quit
         """
         io.stdout.write('---Return to continue, q to quit--- ')
         ans = msvcrt.getch()
         if ans in ("q", "Q"):
             result = False
         else:
             result = True
         io.stdout.write("\b"*37 + " "*37 + "\b"*37)
         return result
 else:
     def page_more():
         ans = raw_input('---Return to continue, q to quit--- ')
         if ans.lower().startswith('q'):
             return False
         else:
             return True
 
 
 def snip_print(str,width = 75,print_full = 0,header = ''):
     """Print a string snipping the midsection to fit in width.
 
     print_full: mode control:
       - 0: only snip long strings
       - 1: send to page() directly.
       - 2: snip long strings and ask for full length viewing with page()
     Return 1 if snipping was necessary, 0 otherwise."""
 
     if print_full == 1:
         page(header+str)
         return 0
 
     print header,
     if len(str) < width:
         print str
         snip = 0
     else:
         whalf = int((width -5)/2)
         print str[:whalf] + ' <...> ' + str[-whalf:]
         snip = 1
     if snip and print_full == 2:
         if raw_input(header+' Snipped. View (y/n)? [N]').lower() == 'y':
             page(str)
     return snip
 

IPython/core/payloadpage.py

@@ -1,97 +1,96 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 A payload based version of page.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Third-party
 try:
     from docutils.core import publish_string
 except ImportError:
     # html paging won't be available, but we don't raise any errors.  It's a
     # purely optional feature.
     pass
 
 # Our own
 from IPython.core.interactiveshell import InteractiveShell
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 def page(strng, start=0, screen_lines=0, pager_cmd=None,
          html=None, auto_html=False):
     """Print a string, piping through a pager.
 
     This version ignores the screen_lines and pager_cmd arguments and uses
     IPython's payload system instead.
 
     Parameters
     ----------
     strng : str
       Text to page.
 
     start : int
       Starting line at which to place the display.
     
     html : str, optional
       If given, an html string to send as well.
 
     auto_html : bool, optional
       If true, the input string is assumed to be valid reStructuredText and is
       converted to HTML with docutils.  Note that if docutils is not found,
       this option is silently ignored.
 
     Note
     ----
 
     Only one of the ``html`` and ``auto_html`` options can be given, not
     both.
     """
 
     # Some routines may auto-compute start offsets incorrectly and pass a
     # negative value.  Offset to 0 for robustness.
     start = max(0, start)
     shell = InteractiveShell.instance()
 
     if auto_html:
         try:
             # These defaults ensure user configuration variables for docutils
             # are not loaded, only our config is used here.
             defaults = {'file_insertion_enabled': 0,
                         'raw_enabled': 0,
                         '_disable_config': 1}
             html = publish_string(strng, writer_name='html',
                                   settings_overrides=defaults)
         except:
             pass
         
     payload = dict(
         source='IPython.zmq.page.page',
         text=strng,
         html=html,
         start_line_number=start
         )
     shell.payload_manager.write_payload(payload)
 
 
 def install_payload_page():
     """Install this version of page as IPython.core.page.page."""
     from IPython.core import page as corepage
     corepage.page = page

IPython/core/prefilter.py

@@ -1,1013 +1,1012 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Prefiltering components.
 
 Prefilters transform user input before it is exec'd by Python.  These
 transforms are used to implement additional syntax such as !ls and %magic.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 * Dan Milstein
 * Ville Vainio
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import __builtin__
 import codeop
 import re
 
 from IPython.core.alias import AliasManager
 from IPython.core.autocall import IPyAutocall
 from IPython.config.configurable import Configurable
 from IPython.core.macro import Macro
 from IPython.core.splitinput import split_user_input
 from IPython.core import page
 
 from IPython.utils.traitlets import List, Int, Any, Unicode, CBool, Bool, Instance
 from IPython.utils.text import make_quoted_expr
 from IPython.utils.autoattr import auto_attr
 
 #-----------------------------------------------------------------------------
 # Global utilities, errors and constants
 #-----------------------------------------------------------------------------
 
 # Warning, these cannot be changed unless various regular expressions
 # are updated in a number of places.  Not great, but at least we told you.
 ESC_SHELL  = '!'
 ESC_SH_CAP = '!!'
 ESC_HELP   = '?'
 ESC_MAGIC  = '%'
 ESC_QUOTE  = ','
 ESC_QUOTE2 = ';'
 ESC_PAREN  = '/'
 
 
 class PrefilterError(Exception):
     pass
 
 
 # RegExp to identify potential function names
 re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
 
 # RegExp to exclude strings with this start from autocalling.  In
 # particular, all binary operators should be excluded, so that if foo is
 # callable, foo OP bar doesn't become foo(OP bar), which is invalid.  The
 # characters '!=()' don't need to be checked for, as the checkPythonChars
 # routine explicitely does so, to catch direct calls and rebindings of
 # existing names.
 
 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
 # it affects the rest of the group in square brackets.
 re_exclude_auto = re.compile(r'^[,&^\|\*/\+-]'
                              r'|^is |^not |^in |^and |^or ')
 
 # try to catch also methods for stuff in lists/tuples/dicts: off
 # (experimental). For this to work, the line_split regexp would need
 # to be modified so it wouldn't break things at '['. That line is
 # nasty enough that I shouldn't change it until I can test it _well_.
 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
 
 
 # Handler Check Utilities
 def is_shadowed(identifier, ip):
     """Is the given identifier defined in one of the namespaces which shadow
     the alias and magic namespaces?  Note that an identifier is different
     than ifun, because it can not contain a '.' character."""
     # This is much safer than calling ofind, which can change state
     return (identifier in ip.user_ns \
             or identifier in ip.internal_ns \
             or identifier in ip.ns_table['builtin'])
 
 
 #-----------------------------------------------------------------------------
 # The LineInfo class used throughout
 #-----------------------------------------------------------------------------
 
 
 class LineInfo(object):
     """A single line of input and associated info.
 
     Includes the following as properties: 
 
     line
       The original, raw line
     
     continue_prompt
       Is this line a continuation in a sequence of multiline input?
     
     pre
       The initial esc character or whitespace.
     
     pre_char
       The escape character(s) in pre or the empty string if there isn't one.
       Note that '!!' is a possible value for pre_char.  Otherwise it will
       always be a single character.
     
     pre_whitespace
       The leading whitespace from pre if it exists.  If there is a pre_char,
       this is just ''.
     
     ifun
       The 'function part', which is basically the maximal initial sequence
       of valid python identifiers and the '.' character.  This is what is
       checked for alias and magic transformations, used for auto-calling,
       etc.
     
     the_rest
       Everything else on the line.
     """
     def __init__(self, line, continue_prompt):
         self.line            = line
         self.continue_prompt = continue_prompt
         self.pre, self.ifun, self.the_rest = split_user_input(line)
 
         self.pre_char       = self.pre.strip()
         if self.pre_char:
             self.pre_whitespace = '' # No whitespace allowd before esc chars
         else: 
             self.pre_whitespace = self.pre
 
         self._oinfo = None
 
     def ofind(self, ip):
         """Do a full, attribute-walking lookup of the ifun in the various
         namespaces for the given IPython InteractiveShell instance.
 
         Return a dict with keys: found,obj,ospace,ismagic
 
         Note: can cause state changes because of calling getattr, but should
         only be run if autocall is on and if the line hasn't matched any
         other, less dangerous handlers.
 
         Does cache the results of the call, so can be called multiple times
         without worrying about *further* damaging state.
         """
         if not self._oinfo:
             # ip.shell._ofind is actually on the Magic class!
             self._oinfo = ip.shell._ofind(self.ifun)
         return self._oinfo
 
     def __str__(self):                                                         
         return "Lineinfo [%s|%s|%s]" %(self.pre, self.ifun, self.the_rest) 
 
 
 #-----------------------------------------------------------------------------
 # Main Prefilter manager
 #-----------------------------------------------------------------------------
 
 
 class PrefilterManager(Configurable):
     """Main prefilter component.
 
     The IPython prefilter is run on all user input before it is run.  The
     prefilter consumes lines of input and produces transformed lines of 
     input.
 
     The iplementation consists of two phases:
 
     1. Transformers
     2. Checkers and handlers
 
     Over time, we plan on deprecating the checkers and handlers and doing
     everything in the transformers.
 
     The transformers are instances of :class:`PrefilterTransformer` and have
     a single method :meth:`transform` that takes a line and returns a
     transformed line.  The transformation can be accomplished using any
     tool, but our current ones use regular expressions for speed.  We also
     ship :mod:`pyparsing` in :mod:`IPython.external` for use in transformers.
 
     After all the transformers have been run, the line is fed to the checkers,
     which are instances of :class:`PrefilterChecker`.  The line is passed to
     the :meth:`check` method, which either returns `None` or a 
     :class:`PrefilterHandler` instance.  If `None` is returned, the other
     checkers are tried.  If an :class:`PrefilterHandler` instance is returned,
     the line is passed to the :meth:`handle` method of the returned
     handler and no further checkers are tried.
     
     Both transformers and checkers have a `priority` attribute, that determines
     the order in which they are called.  Smaller priorities are tried first.
 
     Both transformers and checkers also have `enabled` attribute, which is
     a boolean that determines if the instance is used.
 
     Users or developers can change the priority or enabled attribute of
     transformers or checkers, but they must call the :meth:`sort_checkers`
     or :meth:`sort_transformers` method after changing the priority.
     """
 
     multi_line_specials = CBool(True, config=True)
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
 
     def __init__(self, shell=None, config=None):
         super(PrefilterManager, self).__init__(shell=shell, config=config)
         self.shell = shell
         self.init_transformers()
         self.init_handlers()
         self.init_checkers()
 
     #-------------------------------------------------------------------------
     # API for managing transformers
     #-------------------------------------------------------------------------
 
     def init_transformers(self):
         """Create the default transformers."""
         self._transformers = []
         for transformer_cls in _default_transformers:
             transformer_cls(
                 shell=self.shell, prefilter_manager=self, config=self.config
             )
 
     def sort_transformers(self):
         """Sort the transformers by priority.
 
         This must be called after the priority of a transformer is changed.
         The :meth:`register_transformer` method calls this automatically.
         """
         self._transformers.sort(key=lambda x: x.priority)
 
     @property
     def transformers(self):
         """Return a list of checkers, sorted by priority."""
         return self._transformers
 
     def register_transformer(self, transformer):
         """Register a transformer instance."""
         if transformer not in self._transformers:
             self._transformers.append(transformer)
             self.sort_transformers()
 
     def unregister_transformer(self, transformer):
         """Unregister a transformer instance."""
         if transformer in self._transformers:
             self._transformers.remove(transformer)
 
     #-------------------------------------------------------------------------
     # API for managing checkers
     #-------------------------------------------------------------------------
 
     def init_checkers(self):
         """Create the default checkers."""
         self._checkers = []
         for checker in _default_checkers:
             checker(
                 shell=self.shell, prefilter_manager=self, config=self.config
             )
 
     def sort_checkers(self):
         """Sort the checkers by priority.
 
         This must be called after the priority of a checker is changed.
         The :meth:`register_checker` method calls this automatically.
         """
         self._checkers.sort(key=lambda x: x.priority)
 
     @property
     def checkers(self):
         """Return a list of checkers, sorted by priority."""
         return self._checkers
 
     def register_checker(self, checker):
         """Register a checker instance."""
         if checker not in self._checkers:
             self._checkers.append(checker)
             self.sort_checkers()
 
     def unregister_checker(self, checker):
         """Unregister a checker instance."""
         if checker in self._checkers:
             self._checkers.remove(checker)
 
     #-------------------------------------------------------------------------
     # API for managing checkers
     #-------------------------------------------------------------------------
 
     def init_handlers(self):
         """Create the default handlers."""
         self._handlers = {}
         self._esc_handlers = {}
         for handler in _default_handlers:
             handler(
                 shell=self.shell, prefilter_manager=self, config=self.config
             )
 
     @property
     def handlers(self):
         """Return a dict of all the handlers."""
         return self._handlers
 
     def register_handler(self, name, handler, esc_strings):
         """Register a handler instance by name with esc_strings."""
         self._handlers[name] = handler
         for esc_str in esc_strings:
             self._esc_handlers[esc_str] = handler
 
     def unregister_handler(self, name, handler, esc_strings):
         """Unregister a handler instance by name with esc_strings."""
         try:
             del self._handlers[name]
         except KeyError:
             pass
         for esc_str in esc_strings:
             h = self._esc_handlers.get(esc_str)
             if h is handler:
                 del self._esc_handlers[esc_str]
 
     def get_handler_by_name(self, name):
         """Get a handler by its name."""
         return self._handlers.get(name)
 
     def get_handler_by_esc(self, esc_str):
         """Get a handler by its escape string."""
         return self._esc_handlers.get(esc_str)
 
     #-------------------------------------------------------------------------
     # Main prefiltering API
     #-------------------------------------------------------------------------
 
     def prefilter_line_info(self, line_info):
         """Prefilter a line that has been converted to a LineInfo object.
 
         This implements the checker/handler part of the prefilter pipe.
         """
         # print "prefilter_line_info: ", line_info
         handler = self.find_handler(line_info)
         return handler.handle(line_info)
 
     def find_handler(self, line_info):
         """Find a handler for the line_info by trying checkers."""
         for checker in self.checkers:
             if checker.enabled:
                 handler = checker.check(line_info)
                 if handler:
                     return handler
         return self.get_handler_by_name('normal')
 
     def transform_line(self, line, continue_prompt):
         """Calls the enabled transformers in order of increasing priority."""
         for transformer in self.transformers:
             if transformer.enabled:
                 line = transformer.transform(line, continue_prompt)
         return line
 
     def prefilter_line(self, line, continue_prompt=False):
         """Prefilter a single input line as text.
 
         This method prefilters a single line of text by calling the
         transformers and then the checkers/handlers.
         """
 
         # print "prefilter_line: ", line, continue_prompt
         # All handlers *must* return a value, even if it's blank ('').
 
         # save the line away in case we crash, so the post-mortem handler can
         # record it
         self.shell._last_input_line = line
 
         if not line:
             # Return immediately on purely empty lines, so that if the user
             # previously typed some whitespace that started a continuation
             # prompt, he can break out of that loop with just an empty line.
             # This is how the default python prompt works.
             return ''
 
         # At this point, we invoke our transformers.
         if not continue_prompt or (continue_prompt and self.multi_line_specials):
             line = self.transform_line(line, continue_prompt)
 
         # Now we compute line_info for the checkers and handlers
         line_info = LineInfo(line, continue_prompt)
         
         # the input history needs to track even empty lines
         stripped = line.strip()
 
         normal_handler = self.get_handler_by_name('normal')
         if not stripped:
             if not continue_prompt:
                 self.shell.displayhook.prompt_count -= 1
 
             return normal_handler.handle(line_info)
 
         # special handlers are only allowed for single line statements
         if continue_prompt and not self.multi_line_specials:
             return normal_handler.handle(line_info)
 
         prefiltered = self.prefilter_line_info(line_info)
         # print "prefiltered line: %r" % prefiltered
         return prefiltered
 
     def prefilter_lines(self, lines, continue_prompt=False):
         """Prefilter multiple input lines of text.
 
         This is the main entry point for prefiltering multiple lines of
         input.  This simply calls :meth:`prefilter_line` for each line of
         input.
 
         This covers cases where there are multiple lines in the user entry,
         which is the case when the user goes back to a multiline history
         entry and presses enter.
         """
         llines = lines.rstrip('\n').split('\n')
         # We can get multiple lines in one shot, where multiline input 'blends'
         # into one line, in cases like recalling from the readline history
         # buffer.  We need to make sure that in such cases, we correctly
         # communicate downstream which line is first and which are continuation
         # ones.
         if len(llines) > 1:
             out = '\n'.join([self.prefilter_line(line, lnum>0)
                              for lnum, line in enumerate(llines) ])
         else:
             out = self.prefilter_line(llines[0], continue_prompt)
             
         return out
 
 #-----------------------------------------------------------------------------
 # Prefilter transformers
 #-----------------------------------------------------------------------------
 
 
 class PrefilterTransformer(Configurable):
     """Transform a line of user input."""
 
     priority = Int(100, config=True)
     # Transformers don't currently use shell or prefilter_manager, but as we
     # move away from checkers and handlers, they will need them.
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
     prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
     enabled = Bool(True, config=True)
 
     def __init__(self, shell=None, prefilter_manager=None, config=None):
         super(PrefilterTransformer, self).__init__(
             shell=shell, prefilter_manager=prefilter_manager, config=config
         )
         self.prefilter_manager.register_transformer(self)
 
     def transform(self, line, continue_prompt):
         """Transform a line, returning the new one."""
         return None
 
     def __repr__(self):
         return "<%s(priority=%r, enabled=%r)>" % (
             self.__class__.__name__, self.priority, self.enabled)
 
 
 _assign_system_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
                                r'\s*=\s*!(?P<cmd>.*)')
 
 
 class AssignSystemTransformer(PrefilterTransformer):
     """Handle the `files = !ls` syntax."""
 
     priority = Int(100, config=True)
 
     def transform(self, line, continue_prompt):
         m = _assign_system_re.match(line)
         if m is not None:
             cmd = m.group('cmd')
             lhs = m.group('lhs')
             expr = make_quoted_expr("sc =%s" % cmd)
             new_line = '%s = get_ipython().magic(%s)' % (lhs, expr)
             return new_line
         return line
 
 
 _assign_magic_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
                                r'\s*=\s*%(?P<cmd>.*)')
 
 class AssignMagicTransformer(PrefilterTransformer):
     """Handle the `a = %who` syntax."""
 
     priority = Int(200, config=True)
 
     def transform(self, line, continue_prompt):
         m = _assign_magic_re.match(line)
         if m is not None:
             cmd = m.group('cmd')
             lhs = m.group('lhs')
             expr = make_quoted_expr(cmd)
             new_line = '%s = get_ipython().magic(%s)' % (lhs, expr)
             return new_line
         return line
 
 
 _classic_prompt_re = re.compile(r'(^[ \t]*>>> |^[ \t]*\.\.\. )')
 
 class PyPromptTransformer(PrefilterTransformer):
     """Handle inputs that start with '>>> ' syntax."""
 
     priority = Int(50, config=True)
 
     def transform(self, line, continue_prompt):
 
         if not line or line.isspace() or line.strip() == '...':
             # This allows us to recognize multiple input prompts separated by
             # blank lines and pasted in a single chunk, very common when
             # pasting doctests or long tutorial passages.
             return ''
         m = _classic_prompt_re.match(line)
         if m:
             return line[len(m.group(0)):]
         else:
             return line
 
 
 _ipy_prompt_re = re.compile(r'(^[ \t]*In \[\d+\]: |^[ \t]*\ \ \ \.\.\.+: )')
 
 class IPyPromptTransformer(PrefilterTransformer):
     """Handle inputs that start classic IPython prompt syntax."""
 
     priority = Int(50, config=True)
 
     def transform(self, line, continue_prompt):
 
         if not line or line.isspace() or line.strip() == '...':
             # This allows us to recognize multiple input prompts separated by
             # blank lines and pasted in a single chunk, very common when
             # pasting doctests or long tutorial passages.
             return ''
         m = _ipy_prompt_re.match(line)
         if m:
             return line[len(m.group(0)):]
         else:
             return line
 
 #-----------------------------------------------------------------------------
 # Prefilter checkers
 #-----------------------------------------------------------------------------
 
 
 class PrefilterChecker(Configurable):
     """Inspect an input line and return a handler for that line."""
 
     priority = Int(100, config=True)
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
     prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
     enabled = Bool(True, config=True)
 
     def __init__(self, shell=None, prefilter_manager=None, config=None):
         super(PrefilterChecker, self).__init__(
             shell=shell, prefilter_manager=prefilter_manager, config=config
         )
         self.prefilter_manager.register_checker(self)
 
     def check(self, line_info):
         """Inspect line_info and return a handler instance or None."""
         return None
 
     def __repr__(self):
         return "<%s(priority=%r, enabled=%r)>" % (
             self.__class__.__name__, self.priority, self.enabled)
 
 
 class EmacsChecker(PrefilterChecker):
 
     priority = Int(100, config=True)
     enabled = Bool(False, config=True)
 
     def check(self, line_info):
         "Emacs ipython-mode tags certain input lines."
         if line_info.line.endswith('# PYTHON-MODE'):
             return self.prefilter_manager.get_handler_by_name('emacs')
         else:
             return None
 
 
 class ShellEscapeChecker(PrefilterChecker):
 
     priority = Int(200, config=True)
 
     def check(self, line_info):
         if line_info.line.lstrip().startswith(ESC_SHELL):
             return self.prefilter_manager.get_handler_by_name('shell')
 
 
 class MacroChecker(PrefilterChecker):
     
     priority = Int(250, config=True)
     
     def check(self, line_info):
         obj = self.shell.user_ns.get(line_info.ifun)
         if isinstance(obj, Macro):
             return self.prefilter_manager.get_handler_by_name('macro')
         else:
             return None
 
 
 class IPyAutocallChecker(PrefilterChecker):
 
     priority = Int(300, config=True)
 
     def check(self, line_info):
         "Instances of IPyAutocall in user_ns get autocalled immediately"
         obj = self.shell.user_ns.get(line_info.ifun, None)
         if isinstance(obj, IPyAutocall):
             obj.set_ip(self.shell)
             return self.prefilter_manager.get_handler_by_name('auto')
         else:
             return None
 
 
 class MultiLineMagicChecker(PrefilterChecker):
 
     priority = Int(400, config=True)
 
     def check(self, line_info):
         "Allow ! and !! in multi-line statements if multi_line_specials is on"
         # Note that this one of the only places we check the first character of
         # ifun and *not* the pre_char.  Also note that the below test matches
         # both ! and !!.    
         if line_info.continue_prompt \
             and self.prefilter_manager.multi_line_specials:
                 if line_info.ifun.startswith(ESC_MAGIC):
                     return self.prefilter_manager.get_handler_by_name('magic')
         else:
             return None
 
 
 class EscCharsChecker(PrefilterChecker):
 
     priority = Int(500, config=True)
 
     def check(self, line_info):
         """Check for escape character and return either a handler to handle it,
         or None if there is no escape char."""
         if line_info.line[-1] == ESC_HELP \
                and line_info.pre_char != ESC_SHELL \
                and line_info.pre_char != ESC_SH_CAP:
             # the ? can be at the end, but *not* for either kind of shell escape,
             # because a ? can be a vaild final char in a shell cmd
             return self.prefilter_manager.get_handler_by_name('help')
         else:
             # This returns None like it should if no handler exists
             return self.prefilter_manager.get_handler_by_esc(line_info.pre_char)
 
 
 class AssignmentChecker(PrefilterChecker):
 
     priority = Int(600, config=True)
 
     def check(self, line_info):
         """Check to see if user is assigning to a var for the first time, in
         which case we want to avoid any sort of automagic / autocall games.
     
         This allows users to assign to either alias or magic names true python
         variables (the magic/alias systems always take second seat to true
         python code).  E.g. ls='hi', or ls,that=1,2"""
         if line_info.the_rest:
             if line_info.the_rest[0] in '=,':
                 return self.prefilter_manager.get_handler_by_name('normal')
         else:
             return None
 
 
 class AutoMagicChecker(PrefilterChecker):
 
     priority = Int(700, config=True)
 
     def check(self, line_info):
         """If the ifun is magic, and automagic is on, run it.  Note: normal,
         non-auto magic would already have been triggered via '%' in
         check_esc_chars. This just checks for automagic.  Also, before
         triggering the magic handler, make sure that there is nothing in the
         user namespace which could shadow it."""
         if not self.shell.automagic or not hasattr(self.shell,'magic_'+line_info.ifun):
             return None
 
         # We have a likely magic method.  Make sure we should actually call it.
         if line_info.continue_prompt and not self.prefilter_manager.multi_line_specials:
             return None
 
         head = line_info.ifun.split('.',1)[0]
         if is_shadowed(head, self.shell):
             return None
 
         return self.prefilter_manager.get_handler_by_name('magic')
 
 
 class AliasChecker(PrefilterChecker):
 
     priority = Int(800, config=True)
 
     def check(self, line_info):
         "Check if the initital identifier on the line is an alias."
         # Note: aliases can not contain '.'
         head = line_info.ifun.split('.',1)[0]
         if line_info.ifun not in self.shell.alias_manager \
                or head not in self.shell.alias_manager \
                or is_shadowed(head, self.shell):
             return None
 
         return self.prefilter_manager.get_handler_by_name('alias')
 
 
 class PythonOpsChecker(PrefilterChecker):
 
     priority = Int(900, config=True)
 
     def check(self, line_info):
         """If the 'rest' of the line begins with a function call or pretty much
         any python operator, we should simply execute the line (regardless of
         whether or not there's a possible autocall expansion).  This avoids
         spurious (and very confusing) geattr() accesses."""
         if line_info.the_rest and line_info.the_rest[0] in '!=()<>,+*/%^&|':
             return self.prefilter_manager.get_handler_by_name('normal')
         else:
             return None
 
 
 class AutocallChecker(PrefilterChecker):
 
     priority = Int(1000, config=True)
 
     def check(self, line_info):
         "Check if the initial word/function is callable and autocall is on."
         if not self.shell.autocall:
             return None
 
         oinfo = line_info.ofind(self.shell) # This can mutate state via getattr
         if not oinfo['found']:
             return None
         
         if callable(oinfo['obj']) \
                and (not re_exclude_auto.match(line_info.the_rest)) \
                and re_fun_name.match(line_info.ifun):
             return self.prefilter_manager.get_handler_by_name('auto')
         else:
             return None
 
 
 #-----------------------------------------------------------------------------
 # Prefilter handlers
 #-----------------------------------------------------------------------------
 
 
 class PrefilterHandler(Configurable):
 
     handler_name = Unicode('normal')
     esc_strings = List([])
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
     prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
 
     def __init__(self, shell=None, prefilter_manager=None, config=None):
         super(PrefilterHandler, self).__init__(
             shell=shell, prefilter_manager=prefilter_manager, config=config
         )
         self.prefilter_manager.register_handler(
             self.handler_name,
             self,
             self.esc_strings
         )
 
     def handle(self, line_info):
         # print "normal: ", line_info
         """Handle normal input lines. Use as a template for handlers."""
 
         # With autoindent on, we need some way to exit the input loop, and I
         # don't want to force the user to have to backspace all the way to
         # clear the line.  The rule will be in this case, that either two
         # lines of pure whitespace in a row, or a line of pure whitespace but
         # of a size different to the indent level, will exit the input loop.
         line = line_info.line
         continue_prompt = line_info.continue_prompt
 
         if (continue_prompt and
             self.shell.autoindent and
             line.isspace() and
             0 < abs(len(line) - self.shell.indent_current_nsp) <= 2):
             line = ''
 
         return line
 
     def __str__(self):
         return "<%s(name=%s)>" % (self.__class__.__name__, self.handler_name)
 
 
 class AliasHandler(PrefilterHandler):
 
     handler_name = Unicode('alias')
 
     def handle(self, line_info):
         """Handle alias input lines. """
         transformed = self.shell.alias_manager.expand_aliases(line_info.ifun,line_info.the_rest)
         # pre is needed, because it carries the leading whitespace.  Otherwise
         # aliases won't work in indented sections.
         line_out = '%sget_ipython().system(%s)' % (line_info.pre_whitespace,
                                          make_quoted_expr(transformed))
         
         return line_out
 
 
 class ShellEscapeHandler(PrefilterHandler):
 
     handler_name = Unicode('shell')
     esc_strings = List([ESC_SHELL, ESC_SH_CAP])
 
     def handle(self, line_info):
         """Execute the line in a shell, empty return value"""
         magic_handler = self.prefilter_manager.get_handler_by_name('magic')
 
         line = line_info.line
         if line.lstrip().startswith(ESC_SH_CAP):
             # rewrite LineInfo's line, ifun and the_rest to properly hold the
             # call to %sx and the actual command to be executed, so
             # handle_magic can work correctly.  Note that this works even if
             # the line is indented, so it handles multi_line_specials
             # properly.
             new_rest = line.lstrip()[2:]
             line_info.line = '%ssx %s' % (ESC_MAGIC, new_rest)
             line_info.ifun = 'sx'
             line_info.the_rest = new_rest
             return magic_handler.handle(line_info)
         else:
             cmd = line.lstrip().lstrip(ESC_SHELL)
             line_out = '%sget_ipython().system(%s)' % (line_info.pre_whitespace,
                                              make_quoted_expr(cmd))
         return line_out
 
 
 class MacroHandler(PrefilterHandler):
     handler_name = Unicode("macro")
     
     def handle(self, line_info):
         obj = self.shell.user_ns.get(line_info.ifun)
         pre_space = line_info.pre_whitespace
         line_sep = "\n" + pre_space
         return pre_space + line_sep.join(obj.value.splitlines())
 
 
 class MagicHandler(PrefilterHandler):
 
     handler_name = Unicode('magic')
     esc_strings = List([ESC_MAGIC])
 
     def handle(self, line_info):
         """Execute magic functions."""
         ifun    = line_info.ifun
         the_rest = line_info.the_rest
         cmd = '%sget_ipython().magic(%s)' % (line_info.pre_whitespace,
                                    make_quoted_expr(ifun + " " + the_rest))
         return cmd
 
 
 class AutoHandler(PrefilterHandler):
 
     handler_name = Unicode('auto')
     esc_strings = List([ESC_PAREN, ESC_QUOTE, ESC_QUOTE2])
 
     def handle(self, line_info):
         """Handle lines which can be auto-executed, quoting if requested."""
         line    = line_info.line
         ifun    = line_info.ifun
         the_rest = line_info.the_rest
         pre     = line_info.pre
         continue_prompt = line_info.continue_prompt
         obj = line_info.ofind(self)['obj']
         #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun,the_rest)  # dbg
 
         # This should only be active for single-line input!
         if continue_prompt:
             return line
 
         force_auto = isinstance(obj, IPyAutocall)
         auto_rewrite = getattr(obj, 'rewrite', True)
         
         if pre == ESC_QUOTE:
             # Auto-quote splitting on whitespace
             newcmd = '%s("%s")' % (ifun,'", "'.join(the_rest.split()) )
         elif pre == ESC_QUOTE2:
             # Auto-quote whole string
             newcmd = '%s("%s")' % (ifun,the_rest)
         elif pre == ESC_PAREN:
             newcmd = '%s(%s)' % (ifun,",".join(the_rest.split()))
         else:
             # Auto-paren.
             # We only apply it to argument-less calls if the autocall
             # parameter is set to 2.  We only need to check that autocall is <
             # 2, since this function isn't called unless it's at least 1.
             if not the_rest and (self.shell.autocall < 2) and not force_auto:
                 newcmd = '%s %s' % (ifun,the_rest)
                 auto_rewrite = False
             else:
                 if not force_auto and the_rest.startswith('['):
                     if hasattr(obj,'__getitem__'):
                         # Don't autocall in this case: item access for an object
                         # which is BOTH callable and implements __getitem__.
                         newcmd = '%s %s' % (ifun,the_rest)
                         auto_rewrite = False
                     else:
                         # if the object doesn't support [] access, go ahead and
                         # autocall
                         newcmd = '%s(%s)' % (ifun.rstrip(),the_rest)
                 elif the_rest.endswith(';'):
                     newcmd = '%s(%s);' % (ifun.rstrip(),the_rest[:-1])
                 else:
                     newcmd = '%s(%s)' % (ifun.rstrip(), the_rest)
 
         if auto_rewrite:
             self.shell.auto_rewrite_input(newcmd)
             
         return newcmd
 
 
 class HelpHandler(PrefilterHandler):
 
     handler_name = Unicode('help')
     esc_strings = List([ESC_HELP])
 
     def handle(self, line_info):
         """Try to get some help for the object.
 
         obj? or ?obj   -> basic information.
         obj?? or ??obj -> more details.
         """
         normal_handler = self.prefilter_manager.get_handler_by_name('normal')
         line = line_info.line
         # We need to make sure that we don't process lines which would be
         # otherwise valid python, such as "x=1 # what?"
         try:
             codeop.compile_command(line)
         except SyntaxError:
             # We should only handle as help stuff which is NOT valid syntax
             if line[0]==ESC_HELP:
                 line = line[1:]
             elif line[-1]==ESC_HELP:
                 line = line[:-1]
             if line:
                 #print 'line:<%r>' % line  # dbg
                 self.shell.magic_pinfo(line)
             else:
                 self.shell.show_usage()
             return '' # Empty string is needed here!
         except:
             raise
             # Pass any other exceptions through to the normal handler
             return normal_handler.handle(line_info)
         else:
             # If the code compiles ok, we should handle it normally
             return normal_handler.handle(line_info)
 
 
 class EmacsHandler(PrefilterHandler):
 
     handler_name = Unicode('emacs')
     esc_strings = List([])
 
     def handle(self, line_info):
         """Handle input lines marked by python-mode."""
 
         # Currently, nothing is done.  Later more functionality can be added
         # here if needed.
 
         # The input cache shouldn't be updated
         return line_info.line
 
 
 #-----------------------------------------------------------------------------
 # Defaults
 #-----------------------------------------------------------------------------
 
 
 _default_transformers = [
     AssignSystemTransformer,
     AssignMagicTransformer,
     PyPromptTransformer,
     IPyPromptTransformer,
 ]
 
 _default_checkers = [
     EmacsChecker,
     ShellEscapeChecker,
     MacroChecker,
     IPyAutocallChecker,
     MultiLineMagicChecker,
     EscCharsChecker,
     AssignmentChecker,
     AutoMagicChecker,
     AliasChecker,
     PythonOpsChecker,
     AutocallChecker
 ]
 
 _default_handlers = [
     PrefilterHandler,
     AliasHandler,
     ShellEscapeHandler,
     MacroHandler,
     MagicHandler,
     AutoHandler,
     HelpHandler,
     EmacsHandler
 ]

IPython/core/shellapp.py

@@ -1,253 +1,252 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 A mixin for :class:`~IPython.core.application.Application` classes that
 launch InteractiveShell instances, load extensions, etc.
 
 Authors
 -------
 
 * Min Ragan-Kelley
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from __future__ import absolute_import
 
 import os
 import sys
 
 from IPython.config.application import boolean_flag
 from IPython.config.configurable import Configurable
 from IPython.config.loader import Config
 from IPython.utils.path import filefind
 from IPython.utils.traitlets import Unicode, Instance, List
 
 #-----------------------------------------------------------------------------
 # Aliases and Flags
 #-----------------------------------------------------------------------------
 
 shell_flags = {}
 
 addflag = lambda *args: shell_flags.update(boolean_flag(*args))
 addflag('autoindent', 'InteractiveShell.autoindent',
         'Turn on autoindenting.', 'Turn off autoindenting.'
 )
 addflag('automagic', 'InteractiveShell.automagic',
         """Turn on the auto calling of magic commands. Type %%magic at the
         IPython  prompt  for  more information.""",
         'Turn off the auto calling of magic commands.'
 )
 addflag('pdb', 'InteractiveShell.pdb',
     "Enable auto calling the pdb debugger after every exception.",
     "Disable auto calling the pdb debugger after every exception."
 )
 addflag('pprint', 'PlainTextFormatter.pprint',
     "Enable auto pretty printing of results.",
     "Disable auto auto pretty printing of results."
 )
 addflag('color-info', 'InteractiveShell.color_info',
     """IPython can display information about objects via a set of func-
     tions, and optionally can use colors for this, syntax highlighting
     source code and various other elements.  However, because this
     information is passed through a pager (like 'less') and many pagers get
     confused with color codes, this option is off by default.  You can test
     it and turn it on permanently in your ipython_config.py file if it
     works for you.  Test it and turn it on permanently if it works with
     your system.  The magic function %%color_info allows you to toggle this
     interactively for testing.""",
     "Disable using colors for info related things."
 )
 addflag('deep-reload', 'InteractiveShell.deep_reload',
     """Enable deep (recursive) reloading by default. IPython can use the
     deep_reload module which reloads changes in modules recursively (it
     replaces the reload() function, so you don't need to change anything to
     use it). deep_reload() forces a full reload of modules whose code may
     have changed, which the default reload() function does not.  When
     deep_reload is off, IPython will use the normal reload(), but
     deep_reload will still be available as dreload(). This feature is off
     by default [which means that you have both normal reload() and
     dreload()].""",
     "Disable deep (recursive) reloading by default."
 )
 nosep_config = Config()
 nosep_config.InteractiveShell.separate_in = ''
 nosep_config.InteractiveShell.separate_out = ''
 nosep_config.InteractiveShell.separate_out2 = ''
 
 shell_flags['nosep']=(nosep_config, "Eliminate all spacing between prompts.")
 
 
 # it's possible we don't want short aliases for *all* of these:
 shell_aliases = dict(
     autocall='InteractiveShell.autocall',
     colors='InteractiveShell.colors',
     logfile='InteractiveShell.logfile',
     logappend='InteractiveShell.logappend',
     c='InteractiveShellApp.code_to_run',
     ext='InteractiveShellApp.extra_extension',
 )
 shell_aliases['cache-size'] = 'InteractiveShell.cache_size'
 
 #-----------------------------------------------------------------------------
 # Main classes and functions
 #-----------------------------------------------------------------------------
 
 class InteractiveShellApp(Configurable):
     """A Mixin for applications that start InteractiveShell instances.
     
     Provides configurables for loading extensions and executing files
     as part of configuring a Shell environment.
     
     Provides init_extensions() and init_code() methods, to be called
     after init_shell(), which must be implemented by subclasses.
     """
     extensions = List(Unicode, config=True,
         help="A list of dotted module names of IPython extensions to load."
     )
     extra_extension = Unicode('', config=True,
         help="dotted module name of an IPython extension to load."
     )
     def _extra_extension_changed(self, name, old, new):
         if new:
             # add to self.extensions
             self.extensions.append(new)
 
     exec_files = List(Unicode, config=True,
         help="""List of files to run at IPython startup."""
     )
     file_to_run = Unicode('', config=True,
         help="""A file to be run""")
 
     exec_lines = List(Unicode, config=True,
         help="""lines of code to run at IPython startup."""
     )
     code_to_run = Unicode('', config=True,
         help="Execute the given command string."
     )
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
 
     def init_shell(self):
         raise NotImplementedError("Override in subclasses")
     
     def init_extensions(self):
         """Load all IPython extensions in IPythonApp.extensions.
 
         This uses the :meth:`ExtensionManager.load_extensions` to load all
         the extensions listed in ``self.extensions``.
         """
         if not self.extensions:
             return
         try:
             self.log.debug("Loading IPython extensions...")
             extensions = self.extensions
             for ext in extensions:
                 try:
                     self.log.info("Loading IPython extension: %s" % ext)
                     self.shell.extension_manager.load_extension(ext)
                 except:
                     self.log.warn("Error in loading extension: %s" % ext)
                     self.shell.showtraceback()
         except:
             self.log.warn("Unknown error in loading extensions:")
             self.shell.showtraceback()
 
     def init_code(self):
         """run the pre-flight code, specified via exec_lines"""
         self._run_exec_lines()
         self._run_exec_files()
         self._run_cmd_line_code()
 
     def _run_exec_lines(self):
         """Run lines of code in IPythonApp.exec_lines in the user's namespace."""
         if not self.exec_lines:
             return
         try:
             self.log.debug("Running code from IPythonApp.exec_lines...")
             for line in self.exec_lines:
                 try:
                     self.log.info("Running code in user namespace: %s" %
                                   line)
                     self.shell.run_cell(line, store_history=False)
                 except:
                     self.log.warn("Error in executing line in user "
                                   "namespace: %s" % line)
                     self.shell.showtraceback()
         except:
             self.log.warn("Unknown error in handling IPythonApp.exec_lines:")
             self.shell.showtraceback()
 
     def _exec_file(self, fname):
         try:
             full_filename = filefind(fname, [u'.', self.ipython_dir])
         except IOError as e:
             self.log.warn("File not found: %r"%fname)
             return
         # Make sure that the running script gets a proper sys.argv as if it
         # were run from a system shell.
         save_argv = sys.argv
         sys.argv = [full_filename] + self.extra_args[1:]
         try:
             if os.path.isfile(full_filename):
                 if full_filename.endswith('.ipy'):
                     self.log.info("Running file in user namespace: %s" %
                                   full_filename)
                     self.shell.safe_execfile_ipy(full_filename)
                 else:
                     # default to python, even without extension
                     self.log.info("Running file in user namespace: %s" %
                                   full_filename)
                     # Ensure that __file__ is always defined to match Python behavior
                     self.shell.user_ns['__file__'] = fname
                     try:
                         self.shell.safe_execfile(full_filename, self.shell.user_ns)
                     finally:
                         del self.shell.user_ns['__file__']
         finally:
             sys.argv = save_argv
 
     def _run_exec_files(self):
         """Run files from IPythonApp.exec_files"""
         if not self.exec_files:
             return
 
         self.log.debug("Running files in IPythonApp.exec_files...")
         try:
             for fname in self.exec_files:
                 self._exec_file(fname)
         except:
             self.log.warn("Unknown error in handling IPythonApp.exec_files:")
             self.shell.showtraceback()
 
     def _run_cmd_line_code(self):
         """Run code or file specified at the command-line"""
         if self.code_to_run:
             line = self.code_to_run
             try:
                 self.log.info("Running code given at command line (c=): %s" %
                               line)
                 self.shell.run_cell(line, store_history=False)
             except:
                 self.log.warn("Error in executing line in user namespace: %s" %
                               line)
                 self.shell.showtraceback()
 
         # Like Python itself, ignore the second if the first of these is present
         elif self.file_to_run:
             fname = self.file_to_run
             try:
                 self._exec_file(fname)
             except:
                 self.log.warn("Error in executing file in user namespace: %s" %
                               fname)
                 self.shell.showtraceback()
 

IPython/core/splitinput.py

@@ -1,91 +1,90 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Simple utility for splitting user input.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import re
 import sys
 
 #-----------------------------------------------------------------------------
 # Main function
 #-----------------------------------------------------------------------------
 
 
 # RegExp for splitting line contents into pre-char//first word-method//rest.
 # For clarity, each group in on one line.
 
 # WARNING: update the regexp if the escapes in interactiveshell are changed, as they
 # are hardwired in.
 
 # Although it's not solely driven by the regex, note that:
 # ,;/% only trigger if they are the first character on the line
 # ! and !! trigger if they are first char(s) *or* follow an indent 
 # ? triggers as first or last char.
 
 # The three parts of the regex are:
 #  1) pre:     pre_char *or* initial whitespace 
 #  2) ifun:    first word/method (mix of \w and '.')
 #  3) the_rest: rest of line (separated from ifun by space if non-empty)
 line_split = re.compile(r'^([,;/%?]|!!?|\s*)'
                         r'\s*([\w\.]+)'
                         r'(\s+.*$|$)')
 
 # r'[\w\.]+'
 # r'\s*=\s*%.*'
 
 def split_user_input(line, pattern=None):
     """Split user input into pre-char/whitespace, function part and rest.
 
     This is currently handles lines with '=' in them in a very inconsistent
     manner.
     """
     # We need to ensure that the rest of this routine deals only with unicode
     if type(line)==str:
         codec = sys.stdin.encoding
         if codec is None:
             codec = 'utf-8'
         line = line.decode(codec)
         
     if pattern is None:
         pattern = line_split
     match = pattern.match(line)
     if not match:
         # print "match failed for line '%s'" % line
         try:
             ifun, the_rest = line.split(None,1)
         except ValueError:
             # print "split failed for line '%s'" % line
             ifun, the_rest = line, u''
         pre = re.match('^(\s*)(.*)',line).groups()[0]
     else:
         pre,ifun,the_rest = match.groups()
 
     # ifun has to be a valid python identifier, so it better encode into
     # ascii.  We do still make it a unicode string so that we consistently
     # return unicode, but it will be one that is guaranteed to be pure ascii
     try:
         ifun = unicode(ifun.encode('ascii'))
     except UnicodeEncodeError:
         the_rest = ifun + u' ' + the_rest
         ifun = u''
 
     #print 'line:<%s>' % line # dbg
     #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun.strip(),the_rest) # dbg
     return pre, ifun.strip(), the_rest.lstrip()

IPython/core/tests/test_imports.py

@@ -1,59 +1,58 b''
-#!/usr/bin/env python
 # encoding: utf-8
 
 def test_import_completer():
     from IPython.core import completer
 
 def test_import_crashhandler():
     from IPython.core import crashhandler
 
 def test_import_debugger():
     from IPython.core import debugger
 
 def test_import_fakemodule():
     from IPython.core import fakemodule
 
 def test_import_excolors():
     from IPython.core import excolors
 
 def test_import_history():
     from IPython.core import history
 
 def test_import_hooks():
     from IPython.core import hooks
 
 def test_import_ipapi():
     from IPython.core import ipapi
 
 def test_import_interactiveshell():
     from IPython.core import interactiveshell
 
 def test_import_logger():
     from IPython.core import logger
 
 def test_import_macro():
     from IPython.core import macro
 
 def test_import_magic():
     from IPython.core import magic
 
 def test_import_oinspect():
     from IPython.core import oinspect
 
 def test_import_prefilter():
     from IPython.core import prefilter
 
 def test_import_prompts():
     from IPython.core import prompts
 
 def test_import_release():
     from IPython.core import release
 
 def test_import_shadowns():
     from IPython.core import shadowns
 
 def test_import_ultratb():
     from IPython.core import ultratb
 
 def test_import_usage():
     from IPython.core import usage

IPython/extensions/parallelmagic.py

@@ -1,300 +1,299 b''
-#!/usr/bin/env python
 # encoding: utf-8
 
 """Magic command interface for interactive parallel work."""
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import ast
 import re
 
 from IPython.core.plugin import Plugin
 from IPython.utils.traitlets import Bool, Any, Instance
 from IPython.testing.skipdoctest import skip_doctest
 
 #-----------------------------------------------------------------------------
 # Definitions of magic functions for use with IPython
 #-----------------------------------------------------------------------------
 
 
 NO_ACTIVE_VIEW = """
 Use activate() on a DirectView object to activate it for magics.
 """
 
 
 class ParalleMagic(Plugin):
     """A component to manage the %result, %px and %autopx magics."""
 
     active_view = Instance('IPython.parallel.client.view.DirectView')
     verbose = Bool(False, config=True)
     shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
 
     def __init__(self, shell=None, config=None):
         super(ParalleMagic, self).__init__(shell=shell, config=config)
         self._define_magics()
         # A flag showing if autopx is activated or not
         self.autopx = False
 
     def _define_magics(self):
         """Define the magic functions."""
         self.shell.define_magic('result', self.magic_result)
         self.shell.define_magic('px', self.magic_px)
         self.shell.define_magic('autopx', self.magic_autopx)
 
     @skip_doctest
     def magic_result(self, ipself, parameter_s=''):
         """Print the result of command i on all engines..
 
         To use this a :class:`DirectView` instance must be created 
         and then activated by calling its :meth:`activate` method.
 
         Then you can do the following::
 
             In [23]: %result
             Out[23]: 
             <Results List>
             [0] In [6]: a = 10
             [1] In [6]: a = 10
     
             In [22]: %result 6
             Out[22]: 
             <Results List>
             [0] In [6]: a = 10
             [1] In [6]: a = 10
         """
         if self.active_view is None:
             print NO_ACTIVE_VIEW
             return
 
         try:
             index = int(parameter_s)
         except:
             index = None
         result = self.active_view.get_result(index)
         return result
 
     @skip_doctest
     def magic_px(self, ipself, parameter_s=''):
         """Executes the given python command in parallel.
 
         To use this a :class:`DirectView` instance must be created 
         and then activated by calling its :meth:`activate` method.
         
         Then you can do the following::
 
             In [24]: %px a = 5
             Parallel execution on engine(s): all
             Out[24]: 
             <Results List>
             [0] In [7]: a = 5
             [1] In [7]: a = 5
         """
 
         if self.active_view is None:
             print NO_ACTIVE_VIEW
             return
         print "Parallel execution on engine(s): %s" % self.active_view.targets
         result = self.active_view.execute(parameter_s, block=False)
         if self.active_view.block:
             result.get()
             self._maybe_display_output(result)
 
     @skip_doctest
     def magic_autopx(self, ipself, parameter_s=''):
         """Toggles auto parallel mode.
 
         To use this a :class:`DirectView` instance must be created 
         and then activated by calling its :meth:`activate` method. Once this
         is called, all commands typed at the command line are send to
         the engines to be executed in parallel. To control which engine
         are used, set the ``targets`` attributed of the multiengine client
         before entering ``%autopx`` mode.
 
         Then you can do the following::
 
             In [25]: %autopx
             %autopx to enabled
 
             In [26]: a = 10
             Parallel execution on engine(s): [0,1,2,3]
             In [27]: print a
             Parallel execution on engine(s): [0,1,2,3]
             [stdout:0] 10
             [stdout:1] 10
             [stdout:2] 10
             [stdout:3] 10
 
 
             In [27]: %autopx
             %autopx disabled
         """
         if self.autopx:
             self._disable_autopx()
         else:
             self._enable_autopx()
 
     def _enable_autopx(self):
         """Enable %autopx mode by saving the original run_cell and installing 
         pxrun_cell.
         """
         if self.active_view is None:
             print NO_ACTIVE_VIEW
             return
 
         # override run_cell and run_code
         self._original_run_cell = self.shell.run_cell
         self.shell.run_cell = self.pxrun_cell
         self._original_run_code = self.shell.run_code
         self.shell.run_code = self.pxrun_code
 
         self.autopx = True
         print "%autopx enabled"
     
     def _disable_autopx(self):
         """Disable %autopx by restoring the original InteractiveShell.run_cell.
         """
         if self.autopx:
             self.shell.run_cell = self._original_run_cell
             self.shell.run_code = self._original_run_code
             self.autopx = False
             print "%autopx disabled"
 
     def _maybe_display_output(self, result):
         """Maybe display the output of a parallel result.
 
         If self.active_view.block is True, wait for the result
         and display the result.  Otherwise, this is a noop.
         """
         if isinstance(result.stdout, basestring):
             # single result
             stdouts = [result.stdout.rstrip()]
         else:
             stdouts = [s.rstrip() for s in result.stdout]
         
         targets = self.active_view.targets
         if isinstance(targets, int):
             targets = [targets]
         elif targets == 'all':
             targets = self.active_view.client.ids
 
         if any(stdouts):
             for eid,stdout in zip(targets, stdouts):
                 print '[stdout:%i]'%eid, stdout
 
 
     def pxrun_cell(self, raw_cell, store_history=True):
         """drop-in replacement for InteractiveShell.run_cell.
         
         This executes code remotely, instead of in the local namespace.
 
         See InteractiveShell.run_cell for details.
         """
         
         if (not raw_cell) or raw_cell.isspace():
             return
         
         ipself = self.shell
         
         with ipself.builtin_trap:
             cell = ipself.prefilter_manager.prefilter_lines(raw_cell)
         
             # Store raw and processed history
             if store_history:
                 ipself.history_manager.store_inputs(ipself.execution_count, 
                                                   cell, raw_cell)
 
             # ipself.logger.log(cell, raw_cell)
         
             cell_name = ipself.compile.cache(cell, ipself.execution_count)
         
             try:
                 code_ast = ast.parse(cell, filename=cell_name)
             except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
                 # Case 1
                 ipself.showsyntaxerror()
                 ipself.execution_count += 1
                 return None
             except NameError:
                 # ignore name errors, because we don't know the remote keys
                 pass
 
         if store_history:
             # Write output to the database. Does nothing unless
             # history output logging is enabled.
             ipself.history_manager.store_output(ipself.execution_count)
             # Each cell is a *single* input, regardless of how many lines it has
             ipself.execution_count += 1
         
         if re.search(r'get_ipython\(\)\.magic\(u?"%?autopx', cell):
             self._disable_autopx()
             return False
         else:
             try:
                 result = self.active_view.execute(cell, block=False)
             except:
                 ipself.showtraceback()
                 return True
             else:
                 if self.active_view.block:
                     try:
                         result.get()
                     except:
                         self.shell.showtraceback()
                         return True
                     else:
                         self._maybe_display_output(result)
                 return False
 
     def pxrun_code(self, code_obj):
         """drop-in replacement for InteractiveShell.run_code.
 
         This executes code remotely, instead of in the local namespace.
 
         See InteractiveShell.run_code for details.
         """
         ipself = self.shell
         # check code object for the autopx magic
         if 'get_ipython' in code_obj.co_names and 'magic' in code_obj.co_names and \
             any( [ isinstance(c, basestring) and 'autopx' in c for c in code_obj.co_consts ]):
             self._disable_autopx()
             return False
         else:
             try:
                 result = self.active_view.execute(code_obj, block=False)
             except:
                 ipself.showtraceback()
                 return True
             else:
                 if self.active_view.block:
                     try:
                         result.get()
                     except:
                         self.shell.showtraceback()
                         return True
                     else:
                         self._maybe_display_output(result)
                 return False
 
 
 
 
 _loaded = False
 
 
 def load_ipython_extension(ip):
     """Load the extension in IPython."""
     global _loaded
     if not _loaded:
         plugin = ParalleMagic(shell=ip, config=ip.config)
         ip.plugin_manager.register_plugin('parallelmagic', plugin)
         _loaded = True
 

IPython/external/guid/_guid.py

@@ -1,170 +1,169 b''
-#!/usr/bin/env python
 # encoding: utf-8
 
 # GUID.py
 # Version 2.6
 #
 # Copyright (c) 2006 Conan C. Albrecht
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy 
 # of this software and associated documentation files (the "Software"), to deal 
 # in the Software without restriction, including without limitation the rights 
 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
 # copies of the Software, and to permit persons to whom the Software is furnished 
 # to do so, subject to the following conditions:
 #
 # The above copyright notice and this permission notice shall be included in all 
 # copies or substantial portions of the Software.
 #
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
 # INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
 # PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
 # FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 
 # OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
 # DEALINGS IN THE SOFTWARE.
 
 
 
 ##################################################################################################
 ###   A globally-unique identifier made up of time and ip and 8 digits for a counter: 
 ###   each GUID is 40 characters wide
 ###
 ###   A globally unique identifier that combines ip, time, and a counter.  Since the 
 ###   time is listed first, you can sort records by guid.  You can also extract the time 
 ###   and ip if needed.  
 ###
 ###   Since the counter has eight hex characters, you can create up to 
 ###   0xffffffff (4294967295) GUIDs every millisecond.  If your processor
 ###   is somehow fast enough to create more than that in a millisecond (looking
 ###   toward the future, of course), the function will wait until the next
 ###   millisecond to return.
 ###     
 ###   GUIDs make wonderful database keys.  They require no access to the 
 ###   database (to get the max index number), they are extremely unique, and they sort 
 ###   automatically by time.   GUIDs prevent key clashes when merging
 ###   two databases together, combining data, or generating keys in distributed
 ###   systems.
 ###
 ###   There is an Internet Draft for UUIDs, but this module does not implement it.
 ###   If the draft catches on, perhaps I'll conform the module to it.
 ###
 
 
 # Changelog
 # Sometime, 1997     Created the Java version of GUID
 #                    Went through many versions in Java
 # Sometime, 2002     Created the Python version of GUID, mirroring the Java version
 # November 24, 2003  Changed Python version to be more pythonic, took out object and made just a module
 # December 2, 2003   Fixed duplicating GUIDs.  Sometimes they duplicate if multiples are created
 #                    in the same millisecond (it checks the last 100 GUIDs now and has a larger random part)
 # December 9, 2003   Fixed MAX_RANDOM, which was going over sys.maxint
 # June 12, 2004      Allowed a custom IP address to be sent in rather than always using the 
 #                    local IP address.  
 # November 4, 2005   Changed the random part to a counter variable.  Now GUIDs are totally 
 #                    unique and more efficient, as long as they are created by only
 #                    on runtime on a given machine.  The counter part is after the time
 #                    part so it sorts correctly.
 # November 8, 2005   The counter variable now starts at a random long now and cycles
 #                    around.  This is in case two guids are created on the same
 #                    machine at the same millisecond (by different processes).  Even though
 #                    it is possible the GUID can be created, this makes it highly unlikely
 #                    since the counter will likely be different.
 # November 11, 2005  Fixed a bug in the new IP getting algorithm.  Also, use IPv6 range
 #                    for IP when we make it up (when it's no accessible)
 # November 21, 2005  Added better IP-finding code.  It finds IP address better now.
 # January 5, 2006    Fixed a small bug caused in old versions of python (random module use)
 
 import math
 import socket
 import random
 import sys
 import time
 import threading
 
 
 
 #############################
 ###   global module variables
 
 #Makes a hex IP from a decimal dot-separated ip (eg: 127.0.0.1)
 make_hexip = lambda ip: ''.join(["%04x" % long(i) for i in ip.split('.')]) # leave space for ip v6 (65K in each sub)
   
 MAX_COUNTER = 0xfffffffe
 counter = 0L
 firstcounter = MAX_COUNTER
 lasttime = 0
 ip = ''
 lock = threading.RLock()
 try:  # only need to get the IP addresss once
   ip = socket.getaddrinfo(socket.gethostname(),0)[-1][-1][0]
   hexip = make_hexip(ip)
 except: # if we don't have an ip, default to someting in the 10.x.x.x private range
   ip = '10'
   rand = random.Random()
   for i in range(3):
     ip += '.' + str(rand.randrange(1, 0xffff))  # might as well use IPv6 range if we're making it up
   hexip = make_hexip(ip)
 
   
 #################################
 ###   Public module functions
 
 def generate(ip=None):
   '''Generates a new guid.  A guid is unique in space and time because it combines
      the machine IP with the current time in milliseconds.  Be careful about sending in
      a specified IP address because the ip makes it unique in space.  You could send in
      the same IP address that is created on another machine.
   '''
   global counter, firstcounter, lasttime
   lock.acquire() # can't generate two guids at the same time
   try:
     parts = []
 
     # do we need to wait for the next millisecond (are we out of counters?)
     now = long(time.time() * 1000)
     while lasttime == now and counter == firstcounter: 
       time.sleep(.01)
       now = long(time.time() * 1000)
 
     # time part
     parts.append("%016x" % now)
 
     # counter part
     if lasttime != now:  # time to start counter over since we have a different millisecond
       firstcounter = long(random.uniform(1, MAX_COUNTER))  # start at random position
       counter = firstcounter
     counter += 1
     if counter > MAX_COUNTER:
       counter = 0
     lasttime = now
     parts.append("%08x" % (counter)) 
 
     # ip part
     parts.append(hexip)
 
     # put them all together
     return ''.join(parts)
   finally:
     lock.release()
     
 
 def extract_time(guid):
   '''Extracts the time portion out of the guid and returns the 
      number of seconds since the epoch as a float'''
   return float(long(guid[0:16], 16)) / 1000.0
 
 
 def extract_counter(guid):
   '''Extracts the counter from the guid (returns the bits in decimal)'''
   return int(guid[16:24], 16)
 
 
 def extract_ip(guid):
   '''Extracts the ip portion out of the guid and returns it
      as a string like 10.10.10.10'''
   # there's probably a more elegant way to do this
   thisip = []
   for index in range(24, 40, 4):
     thisip.append(str(int(guid[index: index + 4], 16)))
   return '.'.join(thisip)
 

IPython/external/ssh/forward.py

@@ -1,90 +1,88 b''
-#!/usr/bin/env python
-
 #
 # This file is adapted from a paramiko demo, and thus licensed under LGPL 2.1.
 # Original Copyright (C) 2003-2007  Robey Pointer <[e-mail]>
 # Edits Copyright (C) 2010 The IPython Team
 #
 # Paramiko is free software; you can redistribute it and/or modify it under the
 # terms of the GNU Lesser General Public License as published by the Free
 # Software Foundation; either version 2.1 of the License, or (at your option)
 # any later version.
 #
 # Paramiko is distrubuted in the hope that it will be useful, but WITHOUT ANY
 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 # A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
 # details.
 #
 # You should have received a copy of the GNU Lesser General Public License
 # along with Paramiko; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA.
 
 """
 Sample script showing how to do local port forwarding over paramiko.
 
 This script connects to the requested SSH server and sets up local port
 forwarding (the openssh -L option) from a local port through a tunneled
 connection to a destination reachable from the SSH server machine.
 """
 
 from __future__ import print_function
 
 import logging
 import select
 import SocketServer
 
 logger = logging.getLogger('ssh')
 
 class ForwardServer (SocketServer.ThreadingTCPServer):
     daemon_threads = True
     allow_reuse_address = True
     
 
 class Handler (SocketServer.BaseRequestHandler):
 
     def handle(self):
         try:
             chan = self.ssh_transport.open_channel('direct-tcpip',
                                                    (self.chain_host, self.chain_port),
                                                    self.request.getpeername())
         except Exception, e:
             logger.debug('Incoming request to %s:%d failed: %s' % (self.chain_host,
                                                               self.chain_port,
                                                               repr(e)))
             return
         if chan is None:
             logger.debug('Incoming request to %s:%d was rejected by the SSH server.' %
                     (self.chain_host, self.chain_port))
             return
 
         logger.debug('Connected!  Tunnel open %r -> %r -> %r' % (self.request.getpeername(),
                                                             chan.getpeername(), (self.chain_host, self.chain_port)))
         while True:
             r, w, x = select.select([self.request, chan], [], [])
             if self.request in r:
                 data = self.request.recv(1024)
                 if len(data) == 0:
                     break
                 chan.send(data)
             if chan in r:
                 data = chan.recv(1024)
                 if len(data) == 0:
                     break
                 self.request.send(data)
         chan.close()
         self.request.close()
         logger.debug('Tunnel closed ')
 
 
 def forward_tunnel(local_port, remote_host, remote_port, transport):
     # this is a little convoluted, but lets me configure things for the Handler
     # object.  (SocketServer doesn't give Handlers any way to access the outer
     # server normally.)
     class SubHander (Handler):
         chain_host = remote_host
         chain_port = remote_port
         ssh_transport = transport
     ForwardServer(('127.0.0.1', local_port), SubHander).serve_forever()
 
 
 __all__ = ['forward_tunnel']

IPython/lib/__init__.py

@@ -1,29 +1,28 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Extra capabilities for IPython
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from IPython.lib.inputhook import (
     enable_wx, disable_wx,
     enable_gtk, disable_gtk,
     enable_qt4, disable_qt4,
     enable_tk, disable_tk,
     set_inputhook, clear_inputhook,
     current_gui
 )
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------

IPython/lib/guisupport.py

@@ -1,147 +1,146 b''
-#!/usr/bin/env python
 # coding: utf-8
 """
 Support for creating GUI apps and starting event loops.
 
 IPython's GUI integration allows interative plotting and GUI usage in IPython
 session. IPython has two different types of GUI integration:
 
 1. The terminal based IPython supports GUI event loops through Python's
    PyOS_InputHook. PyOS_InputHook is a hook that Python calls periodically
    whenever raw_input is waiting for a user to type code. We implement GUI
    support in the terminal by setting PyOS_InputHook to a function that 
    iterates the event loop for a short while. It is important to note that
    in this situation, the real GUI event loop is NOT run in the normal
    manner, so you can't use the normal means to detect that it is running.
 2. In the two process IPython kernel/frontend, the GUI event loop is run in 
    the kernel. In this case, the event loop is run in the normal manner by
    calling the function or method of the GUI toolkit that starts the event
    loop.
 
 In addition to starting the GUI event loops in one of these two ways, IPython
 will *always* create an appropriate GUI application object when GUi
 integration is enabled.
 
 If you want your GUI apps to run in IPython you need to do two things:
 
 1. Test to see if there is already an existing main application object. If
    there is, you should use it. If there is not an existing application object
    you should create one.
 2. Test to see if the GUI event loop is running. If it is, you should not
    start it. If the event loop is not running you may start it.
 
 This module contains functions for each toolkit that perform these things
 in a consistent manner. Because of how PyOS_InputHook runs the event loop
 you cannot detect if the event loop is running using the traditional calls
 (such as ``wx.GetApp.IsMainLoopRunning()`` in wxPython). If PyOS_InputHook is
 set These methods will return a false negative. That is, they will say the
 event loop is not running, when is actually is. To work around this limitation
 we proposed the following informal protocol:
 
 * Whenever someone starts the event loop, they *must* set the ``_in_event_loop``
   attribute of the main application object to ``True``. This should be done
   regardless of how the event loop is actually run.
 * Whenever someone stops the event loop, they *must* set the ``_in_event_loop``
   attribute of the main application object to ``False``.
 * If you want to see if the event loop is running, you *must* use ``hasattr``
   to see if ``_in_event_loop`` attribute has been set. If it is set, you
   *must* use its value. If it has not been set, you can query the toolkit
   in the normal manner.
 * If you want GUI support and no one else has created an application or
   started the event loop you *must* do this. We don't want projects to 
   attempt to defer these things to someone else if they themselves need it.
 
 The functions below implement this logic for each GUI toolkit. If you need
 to create custom application subclasses, you will likely have to modify this
 code for your own purposes. This code can be copied into your own project
 so you don't have to depend on IPython.
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # wx
 #-----------------------------------------------------------------------------
 
 def get_app_wx(*args, **kwargs):
     """Create a new wx app or return an exiting one."""
     import wx
     app = wx.GetApp()
     if app is None:
         if not kwargs.has_key('redirect'):
             kwargs['redirect'] = False
         app = wx.PySimpleApp(*args, **kwargs)
     return app
 
 def is_event_loop_running_wx(app=None):
     """Is the wx event loop running."""
     if app is None:
         app = get_app_wx()
     if hasattr(app, '_in_event_loop'):
         return app._in_event_loop
     else:
         return app.IsMainLoopRunning()
 
 def start_event_loop_wx(app=None):
     """Start the wx event loop in a consistent manner."""
     if app is None:
         app = get_app_wx()
     if not is_event_loop_running_wx(app):
         app._in_event_loop = True
         app.MainLoop()
         app._in_event_loop = False
     else:
         app._in_event_loop = True
 
 #-----------------------------------------------------------------------------
 # qt4
 #-----------------------------------------------------------------------------
 
 def get_app_qt4(*args, **kwargs):
     """Create a new qt4 app or return an existing one."""
     from IPython.external.qt_for_kernel import QtGui
     app = QtGui.QApplication.instance()
     if app is None:
         if not args:
             args = ([''],)
         app = QtGui.QApplication(*args, **kwargs)
     return app
 
 def is_event_loop_running_qt4(app=None):
     """Is the qt4 event loop running."""
     if app is None:
         app = get_app_qt4([''])
     if hasattr(app, '_in_event_loop'):
         return app._in_event_loop
     else:
         # Does qt4 provide a other way to detect this?
         return False
 
 def start_event_loop_qt4(app=None):
     """Start the qt4 event loop in a consistent manner."""
     if app is None:
         app = get_app_qt4([''])
     if not is_event_loop_running_qt4(app):
         app._in_event_loop = True
         app.exec_()
         app._in_event_loop = False
     else:
         app._in_event_loop = True
 
 #-----------------------------------------------------------------------------
 # Tk
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # gtk
 #-----------------------------------------------------------------------------

IPython/lib/inputhook.py

@@ -1,345 +1,344 b''
-#!/usr/bin/env python
 # coding: utf-8
 """
 Inputhook management for GUI event loop integration.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import ctypes
 import sys
 import warnings
 
 #-----------------------------------------------------------------------------
 # Constants
 #-----------------------------------------------------------------------------
 
 # Constants for identifying the GUI toolkits.
 GUI_WX = 'wx'
 GUI_QT = 'qt'
 GUI_QT4 = 'qt4'
 GUI_GTK = 'gtk'
 GUI_TK = 'tk'
 GUI_OSX = 'osx'
 
 #-----------------------------------------------------------------------------
 # Utility classes
 #-----------------------------------------------------------------------------
 
 
 #-----------------------------------------------------------------------------
 # Main InputHookManager class
 #-----------------------------------------------------------------------------
 
 
 class InputHookManager(object):
     """Manage PyOS_InputHook for different GUI toolkits.
 
     This class installs various hooks under ``PyOSInputHook`` to handle
     GUI event loop integration.
     """
     
     def __init__(self):
         self.PYFUNC = ctypes.PYFUNCTYPE(ctypes.c_int)
         self._apps = {}
         self._reset()
 
     def _reset(self):
         self._callback_pyfunctype = None
         self._callback = None
         self._installed = False
         self._current_gui = None
 
     def get_pyos_inputhook(self):
         """Return the current PyOS_InputHook as a ctypes.c_void_p."""
         return ctypes.c_void_p.in_dll(ctypes.pythonapi,"PyOS_InputHook")
 
     def get_pyos_inputhook_as_func(self):
         """Return the current PyOS_InputHook as a ctypes.PYFUNCYPE."""
         return self.PYFUNC.in_dll(ctypes.pythonapi,"PyOS_InputHook")
 
     def set_inputhook(self, callback):
         """Set PyOS_InputHook to callback and return the previous one."""
         self._callback = callback
         self._callback_pyfunctype = self.PYFUNC(callback)
         pyos_inputhook_ptr = self.get_pyos_inputhook()
         original = self.get_pyos_inputhook_as_func()
         pyos_inputhook_ptr.value = \
             ctypes.cast(self._callback_pyfunctype, ctypes.c_void_p).value
         self._installed = True
         return original
 
     def clear_inputhook(self, app=None):
         """Set PyOS_InputHook to NULL and return the previous one.
 
         Parameters
         ----------
         app : optional, ignored
           This parameter is allowed only so that clear_inputhook() can be
           called with a similar interface as all the ``enable_*`` methods.  But
           the actual value of the parameter is ignored.  This uniform interface
           makes it easier to have user-level entry points in the main IPython
           app like :meth:`enable_gui`."""
         pyos_inputhook_ptr = self.get_pyos_inputhook()
         original = self.get_pyos_inputhook_as_func()
         pyos_inputhook_ptr.value = ctypes.c_void_p(None).value
         self._reset()
         return original
 
     def clear_app_refs(self, gui=None):
         """Clear IPython's internal reference to an application instance.
 
         Whenever we create an app for a user on qt4 or wx, we hold a
         reference to the app.  This is needed because in some cases bad things
         can happen if a user doesn't hold a reference themselves.  This
         method is provided to clear the references we are holding.
 
         Parameters
         ----------
         gui : None or str
             If None, clear all app references.  If ('wx', 'qt4') clear
             the app for that toolkit.  References are not held for gtk or tk
             as those toolkits don't have the notion of an app.
         """
         if gui is None:
             self._apps = {}
         elif self._apps.has_key(gui):
             del self._apps[gui]
 
     def enable_wx(self, app=None):
         """Enable event loop integration with wxPython.
 
         Parameters
         ----------
         app : WX Application, optional.
             Running application to use.  If not given, we probe WX for an
             existing application object, and create a new one if none is found.
 
         Notes
         -----
         This methods sets the ``PyOS_InputHook`` for wxPython, which allows
         the wxPython to integrate with terminal based applications like
         IPython.
 
         If ``app`` is not given we probe for an existing one, and return it if
         found.  If no existing app is found, we create an :class:`wx.App` as
         follows::
 
             import wx
             app = wx.App(redirect=False, clearSigInt=False)
         """
         from IPython.lib.inputhookwx import inputhook_wx
         self.set_inputhook(inputhook_wx)
         self._current_gui = GUI_WX
         import wx
         if app is None:
             app = wx.GetApp()
         if app is None:
             app = wx.App(redirect=False, clearSigInt=False)
         app._in_event_loop = True
         self._apps[GUI_WX] = app
         return app
 
     def disable_wx(self):
         """Disable event loop integration with wxPython.
 
         This merely sets PyOS_InputHook to NULL.
         """
         if self._apps.has_key(GUI_WX):
             self._apps[GUI_WX]._in_event_loop = False
         self.clear_inputhook()
 
     def enable_qt4(self, app=None):
         """Enable event loop integration with PyQt4.
         
         Parameters
         ----------
         app : Qt Application, optional.
             Running application to use.  If not given, we probe Qt for an
             existing application object, and create a new one if none is found.
 
         Notes
         -----
         This methods sets the PyOS_InputHook for PyQt4, which allows
         the PyQt4 to integrate with terminal based applications like
         IPython.
 
         If ``app`` is not given we probe for an existing one, and return it if
         found.  If no existing app is found, we create an :class:`QApplication`
         as follows::
 
             from PyQt4 import QtCore
             app = QtGui.QApplication(sys.argv)
         """
         from IPython.external.qt_for_kernel import QtCore, QtGui
 
         if 'pyreadline' in sys.modules:
             # see IPython GitHub Issue #281 for more info on this issue
             # Similar intermittent behavior has been reported on OSX,
             # but not consistently reproducible
             warnings.warn("""PyReadline's inputhook can conflict with Qt, causing delays
             in interactive input. If you do see this issue, we recommend using another GUI
             toolkit if you can, or disable readline with the configuration option
             'TerminalInteractiveShell.readline_use=False', specified in a config file or
             at the command-line""",
             RuntimeWarning)
         
         # PyQt4 has had this since 4.3.1.  In version 4.2, PyOS_InputHook
         # was set when QtCore was imported, but if it ever got removed,
         # you couldn't reset it.  For earlier versions we can
         # probably implement a ctypes version.
         try:
             QtCore.pyqtRestoreInputHook()
         except AttributeError:
             pass
 
         self._current_gui = GUI_QT4
         if app is None:
             app = QtCore.QCoreApplication.instance()
         if app is None:
             app = QtGui.QApplication([" "])
         app._in_event_loop = True
         self._apps[GUI_QT4] = app
         return app
 
     def disable_qt4(self):
         """Disable event loop integration with PyQt4.
 
         This merely sets PyOS_InputHook to NULL.
         """
         if self._apps.has_key(GUI_QT4):
             self._apps[GUI_QT4]._in_event_loop = False
         self.clear_inputhook()
 
     def enable_gtk(self, app=None):
         """Enable event loop integration with PyGTK.
 
         Parameters
         ----------
         app : ignored
            Ignored, it's only a placeholder to keep the call signature of all
            gui activation methods consistent, which simplifies the logic of
            supporting magics.
 
         Notes
         -----
         This methods sets the PyOS_InputHook for PyGTK, which allows
         the PyGTK to integrate with terminal based applications like
         IPython.
         """
         import gtk
         try:
             gtk.set_interactive(True)
             self._current_gui = GUI_GTK
         except AttributeError:
             # For older versions of gtk, use our own ctypes version
             from IPython.lib.inputhookgtk import inputhook_gtk
             self.set_inputhook(inputhook_gtk)
             self._current_gui = GUI_GTK
 
     def disable_gtk(self):
         """Disable event loop integration with PyGTK.
         
         This merely sets PyOS_InputHook to NULL.
         """
         self.clear_inputhook()
 
     def enable_tk(self, app=None):
         """Enable event loop integration with Tk.
 
         Parameters
         ----------
         app : toplevel :class:`Tkinter.Tk` widget, optional.
             Running toplevel widget to use.  If not given, we probe Tk for an
             existing one, and create a new one if none is found.
 
         Notes
         -----
         If you have already created a :class:`Tkinter.Tk` object, the only
         thing done by this method is to register with the
         :class:`InputHookManager`, since creating that object automatically
         sets ``PyOS_InputHook``.
         """
         self._current_gui = GUI_TK
         if app is None:
             import Tkinter
             app = Tkinter.Tk()
             app.withdraw()
             self._apps[GUI_TK] = app
             return app
 
     def disable_tk(self):
         """Disable event loop integration with Tkinter.
         
         This merely sets PyOS_InputHook to NULL.
         """
         self.clear_inputhook()
 
     def current_gui(self):
         """Return a string indicating the currently active GUI or None."""
         return self._current_gui
 
 inputhook_manager = InputHookManager()
 
 enable_wx = inputhook_manager.enable_wx
 disable_wx = inputhook_manager.disable_wx
 enable_qt4 = inputhook_manager.enable_qt4
 disable_qt4 = inputhook_manager.disable_qt4
 enable_gtk = inputhook_manager.enable_gtk
 disable_gtk = inputhook_manager.disable_gtk
 enable_tk = inputhook_manager.enable_tk
 disable_tk = inputhook_manager.disable_tk
 clear_inputhook = inputhook_manager.clear_inputhook
 set_inputhook = inputhook_manager.set_inputhook
 current_gui = inputhook_manager.current_gui
 clear_app_refs = inputhook_manager.clear_app_refs
 
 
 # Convenience function to switch amongst them
 def enable_gui(gui=None, app=None):
     """Switch amongst GUI input hooks by name.
 
     This is just a utility wrapper around the methods of the InputHookManager
     object.
 
     Parameters
     ----------
     gui : optional, string or None
       If None, clears input hook, otherwise it must be one of the recognized
       GUI names (see ``GUI_*`` constants in module).
 
     app : optional, existing application object.
       For toolkits that have the concept of a global app, you can supply an
       existing one.  If not given, the toolkit will be probed for one, and if
       none is found, a new one will be created.  Note that GTK does not have
       this concept, and passing an app if `gui`=="GTK" will raise an error.
 
     Returns
     -------
     The output of the underlying gui switch routine, typically the actual
     PyOS_InputHook wrapper object or the GUI toolkit app created, if there was
     one.
     """
     guis = {None: clear_inputhook,
             GUI_OSX: lambda app=False: None,
             GUI_TK: enable_tk,
             GUI_GTK: enable_gtk,
             GUI_WX: enable_wx,
             GUI_QT: enable_qt4, # qt3 not supported
             GUI_QT4: enable_qt4 }
     try:
         gui_hook = guis[gui]
     except KeyError:
         e = "Invalid GUI request %r, valid ones are:%s" % (gui, guis.keys())
         raise ValueError(e)
     return gui_hook(app)
 

IPython/lib/inputhookgtk.py

@@ -1,36 +1,35 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Enable pygtk to be used interacive by setting PyOS_InputHook.
 
 Authors: Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import sys
 import gtk, gobject
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 
 def _main_quit(*args, **kwargs):
     gtk.main_quit()
     return False
 
 def inputhook_gtk():
     gobject.io_add_watch(sys.stdin, gobject.IO_IN, _main_quit)
     gtk.main()
     return 0
 

IPython/lib/inputhookwx.py

@@ -1,179 +1,178 b''
-#!/usr/bin/env python
 # encoding: utf-8
 
 """
 Enable wxPython to be used interacive by setting PyOS_InputHook.
 
 Authors:  Robin Dunn, Brian Granger, Ondrej Certik
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import signal
 import sys
 import time
 from timeit import default_timer as clock
 import wx
 
 if os.name == 'posix':
     import select
 elif sys.platform == 'win32':
     import msvcrt
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 def stdin_ready():
     if os.name == 'posix':
         infds, outfds, erfds = select.select([sys.stdin],[],[],0)
         if infds:
             return True
         else:
             return False
     elif sys.platform == 'win32':
         return msvcrt.kbhit()
 
 
 def inputhook_wx1():
     """Run the wx event loop by processing pending events only.
     
     This approach seems to work, but its performance is not great as it 
     relies on having PyOS_InputHook called regularly.
     """
     try:
         app = wx.GetApp()
         if app is not None:
             assert wx.Thread_IsMain()
 
             # Make a temporary event loop and process system events until
             # there are no more waiting, then allow idle events (which
             # will also deal with pending or posted wx events.)
             evtloop = wx.EventLoop()
             ea = wx.EventLoopActivator(evtloop)
             while evtloop.Pending():
                 evtloop.Dispatch()
             app.ProcessIdle()
             del ea
     except KeyboardInterrupt:
         pass
     return 0
 
 class EventLoopTimer(wx.Timer):
 
     def __init__(self, func):
         self.func = func
         wx.Timer.__init__(self)
 
     def Notify(self):
         self.func()
 
 class EventLoopRunner(object):
 
     def Run(self, time):
         self.evtloop = wx.EventLoop()
         self.timer = EventLoopTimer(self.check_stdin)
         self.timer.Start(time)
         self.evtloop.Run()
 
     def check_stdin(self):
         if stdin_ready():
             self.timer.Stop()
             self.evtloop.Exit()
 
 def inputhook_wx2():
     """Run the wx event loop, polling for stdin.
     
     This version runs the wx eventloop for an undetermined amount of time,
     during which it periodically checks to see if anything is ready on
     stdin.  If anything is ready on stdin, the event loop exits.
     
     The argument to elr.Run controls how often the event loop looks at stdin.
     This determines the responsiveness at the keyboard.  A setting of 1000
     enables a user to type at most 1 char per second.  I have found that a
     setting of 10 gives good keyboard response.  We can shorten it further, 
     but eventually performance would suffer from calling select/kbhit too 
     often.
     """
     try:
         app = wx.GetApp()
         if app is not None:
             assert wx.Thread_IsMain()
             elr = EventLoopRunner()
             # As this time is made shorter, keyboard response improves, but idle
             # CPU load goes up.  10 ms seems like a good compromise.
             elr.Run(time=10)  # CHANGE time here to control polling interval
     except KeyboardInterrupt:
         pass
     return 0
 
 def inputhook_wx3():
     """Run the wx event loop by processing pending events only.
     
     This is like inputhook_wx1, but it keeps processing pending events
     until stdin is ready.  After processing all pending events, a call to 
     time.sleep is inserted.  This is needed, otherwise, CPU usage is at 100%.
     This sleep time should be tuned though for best performance.
     """
     # We need to protect against a user pressing Control-C when IPython is
     # idle and this is running. We trap KeyboardInterrupt and pass.
     try:
         app = wx.GetApp()
         if app is not None:
             assert wx.Thread_IsMain()
 
             # The import of wx on Linux sets the handler for signal.SIGINT
             # to 0.  This is a bug in wx or gtk.  We fix by just setting it
             # back to the Python default.
             if not callable(signal.getsignal(signal.SIGINT)):
                 signal.signal(signal.SIGINT, signal.default_int_handler)
 
             evtloop = wx.EventLoop()
             ea = wx.EventLoopActivator(evtloop)
             t = clock()
             while not stdin_ready():
                 while evtloop.Pending():
                     t = clock()
                     evtloop.Dispatch()
                 app.ProcessIdle()
                 # We need to sleep at this point to keep the idle CPU load
                 # low.  However, if sleep to long, GUI response is poor.  As 
                 # a compromise, we watch how often GUI events are being processed
                 # and switch between a short and long sleep time.  Here are some
                 # stats useful in helping to tune this.
                 # time    CPU load
                 # 0.001   13%
                 # 0.005   3%
                 # 0.01    1.5%
                 # 0.05    0.5%
                 used_time = clock() - t
                 if used_time > 5*60.0:
                     # print 'Sleep for 5 s'  # dbg
                     time.sleep(5.0)
                 elif used_time > 10.0:
                     # print 'Sleep for 1 s'  # dbg
                     time.sleep(1.0)
                 elif used_time > 0.1:
                     # Few GUI events coming in, so we can sleep longer
                     # print 'Sleep for 0.05 s'  # dbg
                     time.sleep(0.05)
                 else:
                     # Many GUI events coming in, so sleep only very little
                     time.sleep(0.001)
             del ea
     except KeyboardInterrupt:
         pass
     return 0
 
 # This is our default implementation
 inputhook_wx = inputhook_wx3

IPython/lib/tests/test_imports.py

@@ -1,14 +1,13 b''
-#!/usr/bin/env python
 # encoding: utf-8
 
 def test_import_backgroundjobs():
     from IPython.lib import backgroundjobs
 
 def test_import_deepreload():
     from IPython.lib import deepreload
 
 def test_import_demo():
     from IPython.lib import demo
 
 def test_import_irunner():
     from IPython.lib import demo

IPython/parallel/apps/baseapp.py

@@ -1,241 +1,240 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 The Base Application class for IPython.parallel apps
 
 Authors:
 
 * Brian Granger
 * Min RK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from __future__ import with_statement
 
 import os
 import logging
 import re
 import sys
 
 from subprocess import Popen, PIPE
 
 from IPython.core import release
 from IPython.core.crashhandler import CrashHandler
 from IPython.core.application import (
     BaseIPythonApplication,
     base_aliases as base_ip_aliases,
     base_flags as base_ip_flags
 )
 from IPython.utils.path import expand_path
 
 from IPython.utils.traitlets import Unicode, Bool, Instance, Dict, List
 
 #-----------------------------------------------------------------------------
 # Module errors
 #-----------------------------------------------------------------------------
 
 class PIDFileError(Exception):
     pass
 
 
 #-----------------------------------------------------------------------------
 # Crash handler for this application
 #-----------------------------------------------------------------------------
 
 class ParallelCrashHandler(CrashHandler):
     """sys.excepthook for IPython itself, leaves a detailed report on disk."""
 
     def __init__(self, app):
         contact_name = release.authors['Min'][0]
         contact_email = release.authors['Min'][1]
         bug_tracker = 'http://github.com/ipython/ipython/issues'
         super(ParallelCrashHandler,self).__init__(
             app, contact_name, contact_email, bug_tracker
         )
 
 
 #-----------------------------------------------------------------------------
 # Main application
 #-----------------------------------------------------------------------------
 base_aliases = {}
 base_aliases.update(base_ip_aliases)
 base_aliases.update({
     'profile-dir' : 'ProfileDir.location',
     'work-dir' : 'BaseParallelApplication.work_dir',
     'log-to-file' : 'BaseParallelApplication.log_to_file',
     'clean-logs' : 'BaseParallelApplication.clean_logs',
     'log-url' : 'BaseParallelApplication.log_url',
 })
 
 base_flags = {
     'log-to-file' : (
         {'BaseParallelApplication' : {'log_to_file' : True}},
         "send log output to a file"
     )
 }
 base_flags.update(base_ip_flags)
 
 class BaseParallelApplication(BaseIPythonApplication):
     """The base Application for IPython.parallel apps
     
     Principle extensions to BaseIPyythonApplication:
     
     * work_dir
     * remote logging via pyzmq
     * IOLoop instance
     """
 
     crash_handler_class = ParallelCrashHandler
     
     def _log_level_default(self):
         # temporarily override default_log_level to INFO
         return logging.INFO
 
     work_dir = Unicode(os.getcwdu(), config=True,
         help='Set the working dir for the process.'
     )
     def _work_dir_changed(self, name, old, new):
         self.work_dir = unicode(expand_path(new))
 
     log_to_file = Bool(config=True,
         help="whether to log to a file")
 
     clean_logs = Bool(False, config=True,
         help="whether to cleanup old logfiles before starting")
 
     log_url = Unicode('', config=True,
         help="The ZMQ URL of the iplogger to aggregate logging.")
 
     def _config_files_default(self):
         return ['ipcontroller_config.py', 'ipengine_config.py', 'ipcluster_config.py']
     
     loop = Instance('zmq.eventloop.ioloop.IOLoop')
     def _loop_default(self):
         from zmq.eventloop.ioloop import IOLoop
         return IOLoop.instance()
 
     aliases = Dict(base_aliases)
     flags = Dict(base_flags)
     
     def initialize(self, argv=None):
         """initialize the app"""
         super(BaseParallelApplication, self).initialize(argv)
         self.to_work_dir()
         self.reinit_logging()
         
     def to_work_dir(self):
         wd = self.work_dir
         if unicode(wd) != os.getcwdu():
             os.chdir(wd)
             self.log.info("Changing to working dir: %s" % wd)
         # This is the working dir by now.
         sys.path.insert(0, '')
 
     def reinit_logging(self):
         # Remove old log files
         log_dir = self.profile_dir.log_dir
         if self.clean_logs:
             for f in os.listdir(log_dir):
                 if re.match(r'%s-\d+\.(log|err|out)'%self.name,f):
                     os.remove(os.path.join(log_dir, f))
         if self.log_to_file:
             # Start logging to the new log file
             log_filename = self.name + u'-' + str(os.getpid()) + u'.log'
             logfile = os.path.join(log_dir, log_filename)
             open_log_file = open(logfile, 'w')
         else:
             open_log_file = None
         if open_log_file is not None:
             self.log.removeHandler(self._log_handler)
             self._log_handler = logging.StreamHandler(open_log_file)
             self._log_formatter = logging.Formatter("[%(name)s] %(message)s")
             self._log_handler.setFormatter(self._log_formatter)
             self.log.addHandler(self._log_handler)
 
     def write_pid_file(self, overwrite=False):
         """Create a .pid file in the pid_dir with my pid.
 
         This must be called after pre_construct, which sets `self.pid_dir`.
         This raises :exc:`PIDFileError` if the pid file exists already.
         """
         pid_file = os.path.join(self.profile_dir.pid_dir, self.name + u'.pid')
         if os.path.isfile(pid_file):
             pid = self.get_pid_from_file()
             if not overwrite:
                 raise PIDFileError(
                     'The pid file [%s] already exists. \nThis could mean that this '
                     'server is already running with [pid=%s].' % (pid_file, pid)
                 )
         with open(pid_file, 'w') as f:
             self.log.info("Creating pid file: %s" % pid_file)
             f.write(repr(os.getpid())+'\n')
 
     def remove_pid_file(self):
         """Remove the pid file.
 
         This should be called at shutdown by registering a callback with
         :func:`reactor.addSystemEventTrigger`. This needs to return
         ``None``.
         """
         pid_file = os.path.join(self.profile_dir.pid_dir, self.name + u'.pid')
         if os.path.isfile(pid_file):
             try:
                 self.log.info("Removing pid file: %s" % pid_file)
                 os.remove(pid_file)
             except:
                 self.log.warn("Error removing the pid file: %s" % pid_file)
 
     def get_pid_from_file(self):
         """Get the pid from the pid file.
 
         If the  pid file doesn't exist a :exc:`PIDFileError` is raised.
         """
         pid_file = os.path.join(self.profile_dir.pid_dir, self.name + u'.pid')
         if os.path.isfile(pid_file):
             with open(pid_file, 'r') as f:
                 s = f.read().strip()
                 try:
                     pid = int(s)
                 except:
                     raise PIDFileError("invalid pid file: %s (contents: %r)"%(pid_file, s))
                 return pid
         else:
             raise PIDFileError('pid file not found: %s' % pid_file)
     
     def check_pid(self, pid):
         if os.name == 'nt':
             try:
                 import ctypes
                 # returns 0 if no such process (of ours) exists
                 # positive int otherwise
                 p = ctypes.windll.kernel32.OpenProcess(1,0,pid)
             except Exception:
                 self.log.warn(
                     "Could not determine whether pid %i is running via `OpenProcess`. "
                     " Making the likely assumption that it is."%pid
                 )
                 return True
             return bool(p)
         else:
             try:
                 p = Popen(['ps','x'], stdout=PIPE, stderr=PIPE)
                 output,_ = p.communicate()
             except OSError:
                 self.log.warn(
                     "Could not determine whether pid %i is running via `ps x`. "
                     " Making the likely assumption that it is."%pid
                 )
                 return True
             pids = map(int, re.findall(r'^\W*\d+', output, re.MULTILINE))
             return pid in pids

IPython/parallel/apps/launcher.py

@@ -1,1142 +1,1141 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Facilities for launching IPython processes asynchronously.
 
 Authors:
 
 * Brian Granger
 * MinRK
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import copy
 import logging
 import os
 import re
 import stat
 
 # signal imports, handling various platforms, versions
 
 from signal import SIGINT, SIGTERM
 try:
     from signal import SIGKILL
 except ImportError:
     # Windows
     SIGKILL=SIGTERM
 
 try:
     # Windows >= 2.7, 3.2
     from signal import CTRL_C_EVENT as SIGINT
 except ImportError:
     pass
 
 from subprocess import Popen, PIPE, STDOUT
 try:
     from subprocess import check_output
 except ImportError:
     # pre-2.7, define check_output with Popen
     def check_output(*args, **kwargs):
         kwargs.update(dict(stdout=PIPE))
         p = Popen(*args, **kwargs)
         out,err = p.communicate()
         return out
 
 from zmq.eventloop import ioloop
 
 from IPython.config.application import Application
 from IPython.config.configurable import LoggingConfigurable
 from IPython.utils.text import EvalFormatter
 from IPython.utils.traitlets import Any, Int, List, Unicode, Dict, Instance
 from IPython.utils.path import get_ipython_module_path
 from IPython.utils.process import find_cmd, pycmd2argv, FindCmdError
 
 from .win32support import forward_read_events
 
 from .winhpcjob import IPControllerTask, IPEngineTask, IPControllerJob, IPEngineSetJob
 
 WINDOWS = os.name == 'nt'
 
 #-----------------------------------------------------------------------------
 # Paths to the kernel apps
 #-----------------------------------------------------------------------------
 
 
 ipcluster_cmd_argv = pycmd2argv(get_ipython_module_path(
     'IPython.parallel.apps.ipclusterapp'
 ))
 
 ipengine_cmd_argv = pycmd2argv(get_ipython_module_path(
     'IPython.parallel.apps.ipengineapp'
 ))
 
 ipcontroller_cmd_argv = pycmd2argv(get_ipython_module_path(
     'IPython.parallel.apps.ipcontrollerapp'
 ))
 
 #-----------------------------------------------------------------------------
 # Base launchers and errors
 #-----------------------------------------------------------------------------
 
 
 class LauncherError(Exception):
     pass
 
 
 class ProcessStateError(LauncherError):
     pass
 
 
 class UnknownStatus(LauncherError):
     pass
 
 
 class BaseLauncher(LoggingConfigurable):
     """An asbtraction for starting, stopping and signaling a process."""
 
     # In all of the launchers, the work_dir is where child processes will be
     # run. This will usually be the profile_dir, but may not be. any work_dir
     # passed into the __init__ method will override the config value.
     # This should not be used to set the work_dir for the actual engine
     # and controller. Instead, use their own config files or the
     # controller_args, engine_args attributes of the launchers to add
     # the work_dir option.
     work_dir = Unicode(u'.')
     loop = Instance('zmq.eventloop.ioloop.IOLoop')
     
     start_data = Any()
     stop_data = Any()
     
     def _loop_default(self):
         return ioloop.IOLoop.instance()
 
     def __init__(self, work_dir=u'.', config=None, **kwargs):
         super(BaseLauncher, self).__init__(work_dir=work_dir, config=config, **kwargs)
         self.state = 'before' # can be before, running, after
         self.stop_callbacks = []
         self.start_data = None
         self.stop_data = None
 
     @property
     def args(self):
         """A list of cmd and args that will be used to start the process.
 
         This is what is passed to :func:`spawnProcess` and the first element
         will be the process name.
         """
         return self.find_args()
 
     def find_args(self):
         """The ``.args`` property calls this to find the args list.
 
         Subcommand should implement this to construct the cmd and args.
         """
         raise NotImplementedError('find_args must be implemented in a subclass')
 
     @property
     def arg_str(self):
         """The string form of the program arguments."""
         return ' '.join(self.args)
 
     @property
     def running(self):
         """Am I running."""
         if self.state == 'running':
             return True
         else:
             return False
 
     def start(self):
         """Start the process."""
         raise NotImplementedError('start must be implemented in a subclass')
 
     def stop(self):
         """Stop the process and notify observers of stopping.
 
         This method will return None immediately.
         To observe the actual process stopping, see :meth:`on_stop`.
         """
         raise NotImplementedError('stop must be implemented in a subclass')
 
     def on_stop(self, f):
         """Register a callback to be called with this Launcher's stop_data
         when the process actually finishes.
         """
         if self.state=='after':
             return f(self.stop_data)
         else:
             self.stop_callbacks.append(f)
 
     def notify_start(self, data):
         """Call this to trigger startup actions.
 
         This logs the process startup and sets the state to 'running'.  It is
         a pass-through so it can be used as a callback.
         """
 
         self.log.info('Process %r started: %r' % (self.args[0], data))
         self.start_data = data
         self.state = 'running'
         return data
 
     def notify_stop(self, data):
         """Call this to trigger process stop actions.
 
         This logs the process stopping and sets the state to 'after'. Call
         this to trigger callbacks registered via :meth:`on_stop`."""
 
         self.log.info('Process %r stopped: %r' % (self.args[0], data))
         self.stop_data = data
         self.state = 'after'
         for i in range(len(self.stop_callbacks)):
             d = self.stop_callbacks.pop()
             d(data)
         return data
 
     def signal(self, sig):
         """Signal the process.
 
         Parameters
         ----------
         sig : str or int
             'KILL', 'INT', etc., or any signal number
         """
         raise NotImplementedError('signal must be implemented in a subclass')
 
 
 #-----------------------------------------------------------------------------
 # Local process launchers
 #-----------------------------------------------------------------------------
 
 
 class LocalProcessLauncher(BaseLauncher):
     """Start and stop an external process in an asynchronous manner.
 
     This will launch the external process with a working directory of
     ``self.work_dir``.
     """
 
     # This is used to to construct self.args, which is passed to 
     # spawnProcess.
     cmd_and_args = List([])
     poll_frequency = Int(100) # in ms
 
     def __init__(self, work_dir=u'.', config=None, **kwargs):
         super(LocalProcessLauncher, self).__init__(
             work_dir=work_dir, config=config, **kwargs
         )
         self.process = None
         self.poller = None
 
     def find_args(self):
         return self.cmd_and_args
 
     def start(self):
         if self.state == 'before':
             self.process = Popen(self.args,
                 stdout=PIPE,stderr=PIPE,stdin=PIPE,
                 env=os.environ,
                 cwd=self.work_dir
             )
             if WINDOWS:
                 self.stdout = forward_read_events(self.process.stdout)
                 self.stderr = forward_read_events(self.process.stderr)
             else:
                 self.stdout = self.process.stdout.fileno()
                 self.stderr = self.process.stderr.fileno()
             self.loop.add_handler(self.stdout, self.handle_stdout, self.loop.READ)
             self.loop.add_handler(self.stderr, self.handle_stderr, self.loop.READ)
             self.poller = ioloop.PeriodicCallback(self.poll, self.poll_frequency, self.loop)
             self.poller.start()
             self.notify_start(self.process.pid)
         else:
             s = 'The process was already started and has state: %r' % self.state
             raise ProcessStateError(s)
 
     def stop(self):
         return self.interrupt_then_kill()
 
     def signal(self, sig):
         if self.state == 'running':
             if WINDOWS and sig != SIGINT:
                 # use Windows tree-kill for better child cleanup
                 check_output(['taskkill', '-pid', str(self.process.pid), '-t', '-f'])
             else:
                 self.process.send_signal(sig)
 
     def interrupt_then_kill(self, delay=2.0):
         """Send INT, wait a delay and then send KILL."""
         try:
             self.signal(SIGINT)
         except Exception:
             self.log.debug("interrupt failed")
             pass
         self.killer  = ioloop.DelayedCallback(lambda : self.signal(SIGKILL), delay*1000, self.loop)
         self.killer.start()
 
     # callbacks, etc:
     
     def handle_stdout(self, fd, events):
         if WINDOWS:
             line = self.stdout.recv()
         else:
             line = self.process.stdout.readline()
         # a stopped process will be readable but return empty strings
         if line:
             self.log.info(line[:-1])
         else:
             self.poll()
     
     def handle_stderr(self, fd, events):
         if WINDOWS:
             line = self.stderr.recv()
         else:
             line = self.process.stderr.readline()
         # a stopped process will be readable but return empty strings
         if line:
             self.log.error(line[:-1])
         else:
             self.poll()
     
     def poll(self):
         status = self.process.poll()
         if status is not None:
             self.poller.stop()
             self.loop.remove_handler(self.stdout)
             self.loop.remove_handler(self.stderr)
             self.notify_stop(dict(exit_code=status, pid=self.process.pid))
         return status
 
 class LocalControllerLauncher(LocalProcessLauncher):
     """Launch a controller as a regular external process."""
 
     controller_cmd = List(ipcontroller_cmd_argv, config=True,
         help="""Popen command to launch ipcontroller.""")
     # Command line arguments to ipcontroller.
     controller_args = List(['--log-to-file','--log-level=%i'%logging.INFO], config=True,
         help="""command-line args to pass to ipcontroller""")
 
     def find_args(self):
         return self.controller_cmd + self.controller_args
 
     def start(self, profile_dir):
         """Start the controller by profile_dir."""
         self.controller_args.extend(['--profile-dir=%s'%profile_dir])
         self.profile_dir = unicode(profile_dir)
         self.log.info("Starting LocalControllerLauncher: %r" % self.args)
         return super(LocalControllerLauncher, self).start()
 
 
 class LocalEngineLauncher(LocalProcessLauncher):
     """Launch a single engine as a regular externall process."""
 
     engine_cmd = List(ipengine_cmd_argv, config=True,
         help="""command to launch the Engine.""")
     # Command line arguments for ipengine.
     engine_args = List(['--log-to-file','--log-level=%i'%logging.INFO], config=True,
         help="command-line arguments to pass to ipengine"
     )
 
     def find_args(self):
         return self.engine_cmd + self.engine_args
 
     def start(self, profile_dir):
         """Start the engine by profile_dir."""
         self.engine_args.extend(['--profile-dir=%s'%profile_dir])
         self.profile_dir = unicode(profile_dir)
         return super(LocalEngineLauncher, self).start()
 
 
 class LocalEngineSetLauncher(BaseLauncher):
     """Launch a set of engines as regular external processes."""
 
     # Command line arguments for ipengine.
     engine_args = List(
         ['--log-to-file','--log-level=%i'%logging.INFO], config=True,
         help="command-line arguments to pass to ipengine"
     )
     # launcher class
     launcher_class = LocalEngineLauncher
     
     launchers = Dict()
     stop_data = Dict()
     
     def __init__(self, work_dir=u'.', config=None, **kwargs):
         super(LocalEngineSetLauncher, self).__init__(
             work_dir=work_dir, config=config, **kwargs
         )
         self.stop_data = {}
 
     def start(self, n, profile_dir):
         """Start n engines by profile or profile_dir."""
         self.profile_dir = unicode(profile_dir)
         dlist = []
         for i in range(n):
             el = self.launcher_class(work_dir=self.work_dir, config=self.config, log=self.log)
             # Copy the engine args over to each engine launcher.
             el.engine_args = copy.deepcopy(self.engine_args)
             el.on_stop(self._notice_engine_stopped)
             d = el.start(profile_dir)
             if i==0:
                 self.log.info("Starting LocalEngineSetLauncher: %r" % el.args)
             self.launchers[i] = el
             dlist.append(d)
         self.notify_start(dlist)
         # The consumeErrors here could be dangerous
         # dfinal = gatherBoth(dlist, consumeErrors=True)
         # dfinal.addCallback(self.notify_start)
         return dlist
 
     def find_args(self):
         return ['engine set']
 
     def signal(self, sig):
         dlist = []
         for el in self.launchers.itervalues():
             d = el.signal(sig)
             dlist.append(d)
         # dfinal = gatherBoth(dlist, consumeErrors=True)
         return dlist
 
     def interrupt_then_kill(self, delay=1.0):
         dlist = []
         for el in self.launchers.itervalues():
             d = el.interrupt_then_kill(delay)
             dlist.append(d)
         # dfinal = gatherBoth(dlist, consumeErrors=True)
         return dlist
 
     def stop(self):
         return self.interrupt_then_kill()
     
     def _notice_engine_stopped(self, data):
         pid = data['pid']
         for idx,el in self.launchers.iteritems():
             if el.process.pid == pid:
                 break
         self.launchers.pop(idx)
         self.stop_data[idx] = data
         if not self.launchers:
             self.notify_stop(self.stop_data)
 
 
 #-----------------------------------------------------------------------------
 # MPIExec launchers
 #-----------------------------------------------------------------------------
 
 
 class MPIExecLauncher(LocalProcessLauncher):
     """Launch an external process using mpiexec."""
 
     mpi_cmd = List(['mpiexec'], config=True,
         help="The mpiexec command to use in starting the process."
     )
     mpi_args = List([], config=True,
         help="The command line arguments to pass to mpiexec."
     )
     program = List(['date'], config=True,
         help="The program to start via mpiexec.")
     program_args = List([], config=True,
         help="The command line argument to the program."
     )
     n = Int(1)
 
     def find_args(self):
         """Build self.args using all the fields."""
         return self.mpi_cmd + ['-n', str(self.n)] + self.mpi_args + \
                self.program + self.program_args
 
     def start(self, n):
         """Start n instances of the program using mpiexec."""
         self.n = n
         return super(MPIExecLauncher, self).start()
 
 
 class MPIExecControllerLauncher(MPIExecLauncher):
     """Launch a controller using mpiexec."""
 
     controller_cmd = List(ipcontroller_cmd_argv, config=True,
         help="Popen command to launch the Contropper"
     )
     controller_args = List(['--log-to-file','--log-level=%i'%logging.INFO], config=True,
         help="Command line arguments to pass to ipcontroller."
     )
     n = Int(1)
 
     def start(self, profile_dir):
         """Start the controller by profile_dir."""
         self.controller_args.extend(['--profile-dir=%s'%profile_dir])
         self.profile_dir = unicode(profile_dir)
         self.log.info("Starting MPIExecControllerLauncher: %r" % self.args)
         return super(MPIExecControllerLauncher, self).start(1)
 
     def find_args(self):
         return self.mpi_cmd + ['-n', str(self.n)] + self.mpi_args + \
                self.controller_cmd + self.controller_args
 
 
 class MPIExecEngineSetLauncher(MPIExecLauncher):
 
     program = List(ipengine_cmd_argv, config=True,
         help="Popen command for ipengine"
     )
     program_args = List(
         ['--log-to-file','--log-level=%i'%logging.INFO], config=True,
         help="Command line arguments for ipengine."
     )
     n = Int(1)
 
     def start(self, n, profile_dir):
         """Start n engines by profile or profile_dir."""
         self.program_args.extend(['--profile-dir=%s'%profile_dir])
         self.profile_dir = unicode(profile_dir)
         self.n = n
         self.log.info('Starting MPIExecEngineSetLauncher: %r' % self.args)
         return super(MPIExecEngineSetLauncher, self).start(n)
 
 #-----------------------------------------------------------------------------
 # SSH launchers
 #-----------------------------------------------------------------------------
 
 # TODO: Get SSH Launcher back to level of sshx in 0.10.2
 
 class SSHLauncher(LocalProcessLauncher):
     """A minimal launcher for ssh.
 
     To be useful this will probably have to be extended to use the ``sshx``
     idea for environment variables.  There could be other things this needs
     as well.
     """
 
     ssh_cmd = List(['ssh'], config=True,
         help="command for starting ssh")
     ssh_args = List(['-tt'], config=True,
         help="args to pass to ssh")
     program = List(['date'], config=True,
         help="Program to launch via ssh")
     program_args = List([], config=True,
         help="args to pass to remote program")
     hostname = Unicode('', config=True,
         help="hostname on which to launch the program")
     user = Unicode('', config=True,
         help="username for ssh")
     location = Unicode('', config=True,
         help="user@hostname location for ssh in one setting")
 
     def _hostname_changed(self, name, old, new):
         if self.user:
             self.location = u'%s@%s' % (self.user, new)
         else:
             self.location = new
 
     def _user_changed(self, name, old, new):
         self.location = u'%s@%s' % (new, self.hostname)
 
     def find_args(self):
         return self.ssh_cmd + self.ssh_args + [self.location] + \
                self.program + self.program_args
 
     def start(self, profile_dir, hostname=None, user=None):
         self.profile_dir = unicode(profile_dir)
         if hostname is not None:
             self.hostname = hostname
         if user is not None:
             self.user = user
         
         return super(SSHLauncher, self).start()
     
     def signal(self, sig):
         if self.state == 'running':
             # send escaped ssh connection-closer
             self.process.stdin.write('~.')
             self.process.stdin.flush()
         
 
 
 class SSHControllerLauncher(SSHLauncher):
 
     program = List(ipcontroller_cmd_argv, config=True,
         help="remote ipcontroller command.")
     program_args = List(['--reuse-files', '--log-to-file','--log-level=%i'%logging.INFO], config=True,
         help="Command line arguments to ipcontroller.")
 
 
 class SSHEngineLauncher(SSHLauncher):
     program = List(ipengine_cmd_argv, config=True,
         help="remote ipengine command.")
     # Command line arguments for ipengine.
     program_args = List(
         ['--log-to-file','--log_level=%i'%logging.INFO], config=True,
         help="Command line arguments to ipengine."
     )
     
 class SSHEngineSetLauncher(LocalEngineSetLauncher):
     launcher_class = SSHEngineLauncher
     engines = Dict(config=True,
         help="""dict of engines to launch.  This is a dict by hostname of ints,
         corresponding to the number of engines to start on that host.""")
     
     def start(self, n, profile_dir):
         """Start engines by profile or profile_dir.
         `n` is ignored, and the `engines` config property is used instead.
         """
         
         self.profile_dir = unicode(profile_dir)
         dlist = []
         for host, n in self.engines.iteritems():
             if isinstance(n, (tuple, list)):
                 n, args = n
             else:
                 args = copy.deepcopy(self.engine_args)
             
             if '@' in host:
                 user,host = host.split('@',1)
             else:
                 user=None
             for i in range(n):
                 el = self.launcher_class(work_dir=self.work_dir, config=self.config, log=self.log)
                 
                 # Copy the engine args over to each engine launcher.
                 i
                 el.program_args = args
                 el.on_stop(self._notice_engine_stopped)
                 d = el.start(profile_dir, user=user, hostname=host)
                 if i==0:
                     self.log.info("Starting SSHEngineSetLauncher: %r" % el.args)
                 self.launchers[host+str(i)] = el
                 dlist.append(d)
         self.notify_start(dlist)
         return dlist
     
 
 
 #-----------------------------------------------------------------------------
 # Windows HPC Server 2008 scheduler launchers
 #-----------------------------------------------------------------------------
 
 
 # This is only used on Windows.
 def find_job_cmd():
     if WINDOWS:
         try:
             return find_cmd('job')
         except (FindCmdError, ImportError):
             # ImportError will be raised if win32api is not installed
             return 'job'
     else:
         return 'job'
 
 
 class WindowsHPCLauncher(BaseLauncher):
 
     job_id_regexp = Unicode(r'\d+', config=True,
         help="""A regular expression used to get the job id from the output of the
         submit_command. """
         )
     job_file_name = Unicode(u'ipython_job.xml', config=True,
         help="The filename of the instantiated job script.")
     # The full path to the instantiated job script. This gets made dynamically
     # by combining the work_dir with the job_file_name.
     job_file = Unicode(u'')
     scheduler = Unicode('', config=True,
         help="The hostname of the scheduler to submit the job to.")
     job_cmd = Unicode(find_job_cmd(), config=True,
         help="The command for submitting jobs.")
 
     def __init__(self, work_dir=u'.', config=None, **kwargs):
         super(WindowsHPCLauncher, self).__init__(
             work_dir=work_dir, config=config, **kwargs
         )
 
     @property
     def job_file(self):
         return os.path.join(self.work_dir, self.job_file_name)
 
     def write_job_file(self, n):
         raise NotImplementedError("Implement write_job_file in a subclass.")
 
     def find_args(self):
         return [u'job.exe']
         
     def parse_job_id(self, output):
         """Take the output of the submit command and return the job id."""
         m = re.search(self.job_id_regexp, output)
         if m is not None:
             job_id = m.group()
         else:
             raise LauncherError("Job id couldn't be determined: %s" % output)
         self.job_id = job_id
         self.log.info('Job started with job id: %r' % job_id)
         return job_id
 
     def start(self, n):
         """Start n copies of the process using the Win HPC job scheduler."""
         self.write_job_file(n)
         args = [
             'submit',
             '/jobfile:%s' % self.job_file,
             '/scheduler:%s' % self.scheduler
         ]
         self.log.info("Starting Win HPC Job: %s" % (self.job_cmd + ' ' + ' '.join(args),))
 
         output = check_output([self.job_cmd]+args,
             env=os.environ,
             cwd=self.work_dir,
             stderr=STDOUT
         )
         job_id = self.parse_job_id(output)
         self.notify_start(job_id)
         return job_id
 
     def stop(self):
         args = [
             'cancel',
             self.job_id,
             '/scheduler:%s' % self.scheduler
         ]
         self.log.info("Stopping Win HPC Job: %s" % (self.job_cmd + ' ' + ' '.join(args),))
         try:
             output = check_output([self.job_cmd]+args,
                 env=os.environ,
                 cwd=self.work_dir,
                 stderr=STDOUT
             )
         except:
             output = 'The job already appears to be stoppped: %r' % self.job_id
         self.notify_stop(dict(job_id=self.job_id, output=output))  # Pass the output of the kill cmd
         return output
 
 
 class WindowsHPCControllerLauncher(WindowsHPCLauncher):
 
     job_file_name = Unicode(u'ipcontroller_job.xml', config=True,
         help="WinHPC xml job file.")
     extra_args = List([], config=False,
         help="extra args to pass to ipcontroller")
 
     def write_job_file(self, n):
         job = IPControllerJob(config=self.config)
 
         t = IPControllerTask(config=self.config)
         # The tasks work directory is *not* the actual work directory of 
         # the controller. It is used as the base path for the stdout/stderr
         # files that the scheduler redirects to.
         t.work_directory = self.profile_dir
         # Add the profile_dir and from self.start().
         t.controller_args.extend(self.extra_args)
         job.add_task(t)
 
         self.log.info("Writing job description file: %s" % self.job_file)
         job.write(self.job_file)
 
     @property
     def job_file(self):
         return os.path.join(self.profile_dir, self.job_file_name)
 
     def start(self, profile_dir):
         """Start the controller by profile_dir."""
         self.extra_args = ['--profile-dir=%s'%profile_dir]
         self.profile_dir = unicode(profile_dir)
         return super(WindowsHPCControllerLauncher, self).start(1)
 
 
 class WindowsHPCEngineSetLauncher(WindowsHPCLauncher):
 
     job_file_name = Unicode(u'ipengineset_job.xml', config=True,
         help="jobfile for ipengines job")
     extra_args = List([], config=False,
         help="extra args to pas to ipengine")
 
     def write_job_file(self, n):
         job = IPEngineSetJob(config=self.config)
 
         for i in range(n):
             t = IPEngineTask(config=self.config)
             # The tasks work directory is *not* the actual work directory of 
             # the engine. It is used as the base path for the stdout/stderr
             # files that the scheduler redirects to.
             t.work_directory = self.profile_dir
             # Add the profile_dir and from self.start().
             t.engine_args.extend(self.extra_args)
             job.add_task(t)
 
         self.log.info("Writing job description file: %s" % self.job_file)
         job.write(self.job_file)
 
     @property
     def job_file(self):
         return os.path.join(self.profile_dir, self.job_file_name)
 
     def start(self, n, profile_dir):
         """Start the controller by profile_dir."""
         self.extra_args = ['--profile-dir=%s'%profile_dir]
         self.profile_dir = unicode(profile_dir)
         return super(WindowsHPCEngineSetLauncher, self).start(n)
 
 
 #-----------------------------------------------------------------------------
 # Batch (PBS) system launchers
 #-----------------------------------------------------------------------------
 
 class BatchSystemLauncher(BaseLauncher):
     """Launch an external process using a batch system.
 
     This class is designed to work with UNIX batch systems like PBS, LSF,
     GridEngine, etc.  The overall model is that there are different commands
     like qsub, qdel, etc. that handle the starting and stopping of the process.
 
     This class also has the notion of a batch script. The ``batch_template``
     attribute can be set to a string that is a template for the batch script.
     This template is instantiated using string formatting. Thus the template can
     use {n} fot the number of instances. Subclasses can add additional variables
     to the template dict.
     """
 
     # Subclasses must fill these in.  See PBSEngineSet
     submit_command = List([''], config=True,
         help="The name of the command line program used to submit jobs.")
     delete_command = List([''], config=True,
         help="The name of the command line program used to delete jobs.")
     job_id_regexp = Unicode('', config=True,
         help="""A regular expression used to get the job id from the output of the
         submit_command.""")
     batch_template = Unicode('', config=True,
         help="The string that is the batch script template itself.")
     batch_template_file = Unicode(u'', config=True,
         help="The file that contains the batch template.")
     batch_file_name = Unicode(u'batch_script', config=True,
         help="The filename of the instantiated batch script.")
     queue = Unicode(u'', config=True,
         help="The PBS Queue.")
     
     # not configurable, override in subclasses
     # PBS Job Array regex
     job_array_regexp = Unicode('')
     job_array_template = Unicode('')
     # PBS Queue regex
     queue_regexp = Unicode('')
     queue_template = Unicode('')
     # The default batch template, override in subclasses
     default_template = Unicode('')
     # The full path to the instantiated batch script.
     batch_file = Unicode(u'')
     # the format dict used with batch_template:
     context = Dict()
     # the Formatter instance for rendering the templates:
     formatter = Instance(EvalFormatter, (), {})
 
     
     def find_args(self):
         return self.submit_command + [self.batch_file]
     
     def __init__(self, work_dir=u'.', config=None, **kwargs):
         super(BatchSystemLauncher, self).__init__(
             work_dir=work_dir, config=config, **kwargs
         )
         self.batch_file = os.path.join(self.work_dir, self.batch_file_name)
 
     def parse_job_id(self, output):
         """Take the output of the submit command and return the job id."""
         m = re.search(self.job_id_regexp, output)
         if m is not None:
             job_id = m.group()
         else:
             raise LauncherError("Job id couldn't be determined: %s" % output)
         self.job_id = job_id
         self.log.info('Job submitted with job id: %r' % job_id)
         return job_id
 
     def write_batch_script(self, n):
         """Instantiate and write the batch script to the work_dir."""
         self.context['n'] = n
         self.context['queue'] = self.queue
         # first priority is batch_template if set
         if self.batch_template_file and not self.batch_template:
             # second priority is batch_template_file
             with open(self.batch_template_file) as f:
                 self.batch_template = f.read()
         if not self.batch_template:
             # third (last) priority is default_template
             self.batch_template = self.default_template
         
             # add jobarray or queue lines to user-specified template
             # note that this is *only* when user did not specify a template.
             regex = re.compile(self.job_array_regexp)
             # print regex.search(self.batch_template)
             if not regex.search(self.batch_template):
                 self.log.info("adding job array settings to batch script")
                 firstline, rest = self.batch_template.split('\n',1)
                 self.batch_template = u'\n'.join([firstline, self.job_array_template, rest])
         
             regex = re.compile(self.queue_regexp)
             # print regex.search(self.batch_template)
             if self.queue and not regex.search(self.batch_template):
                 self.log.info("adding PBS queue settings to batch script")
                 firstline, rest = self.batch_template.split('\n',1)
                 self.batch_template = u'\n'.join([firstline, self.queue_template, rest])
             
         script_as_string = self.formatter.format(self.batch_template, **self.context)
         self.log.info('Writing instantiated batch script: %s' % self.batch_file)
     
         with open(self.batch_file, 'w') as f:
             f.write(script_as_string)
         os.chmod(self.batch_file, stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR)
 
     def start(self, n, profile_dir):
         """Start n copies of the process using a batch system."""
         # Here we save profile_dir in the context so they
         # can be used in the batch script template as {profile_dir}
         self.context['profile_dir'] = profile_dir
         self.profile_dir = unicode(profile_dir)
         self.write_batch_script(n)
         output = check_output(self.args, env=os.environ)
         
         job_id = self.parse_job_id(output)
         self.notify_start(job_id)
         return job_id
 
     def stop(self):
         output = check_output(self.delete_command+[self.job_id], env=os.environ)
         self.notify_stop(dict(job_id=self.job_id, output=output)) # Pass the output of the kill cmd
         return output
 
 
 class PBSLauncher(BatchSystemLauncher):
     """A BatchSystemLauncher subclass for PBS."""
 
     submit_command = List(['qsub'], config=True,
         help="The PBS submit command ['qsub']")
     delete_command = List(['qdel'], config=True,
         help="The PBS delete command ['qsub']")
     job_id_regexp = Unicode(r'\d+', config=True,
         help="Regular expresion for identifying the job ID [r'\d+']")
     
     batch_file = Unicode(u'')
     job_array_regexp = Unicode('#PBS\W+-t\W+[\w\d\-\$]+')
     job_array_template = Unicode('#PBS -t 1-{n}')
     queue_regexp = Unicode('#PBS\W+-q\W+\$?\w+')
     queue_template = Unicode('#PBS -q {queue}')
 
 
 class PBSControllerLauncher(PBSLauncher):
     """Launch a controller using PBS."""
 
     batch_file_name = Unicode(u'pbs_controller', config=True,
         help="batch file name for the controller job.")
     default_template= Unicode("""#!/bin/sh
 #PBS -V
 #PBS -N ipcontroller
 %s --log-to-file --profile-dir={profile_dir}
 """%(' '.join(ipcontroller_cmd_argv)))
 
     def start(self, profile_dir):
         """Start the controller by profile or profile_dir."""
         self.log.info("Starting PBSControllerLauncher: %r" % self.args)
         return super(PBSControllerLauncher, self).start(1, profile_dir)
 
 
 class PBSEngineSetLauncher(PBSLauncher):
     """Launch Engines using PBS"""
     batch_file_name = Unicode(u'pbs_engines', config=True,
         help="batch file name for the engine(s) job.")
     default_template= Unicode(u"""#!/bin/sh
 #PBS -V
 #PBS -N ipengine
 %s --profile-dir={profile_dir}
 """%(' '.join(ipengine_cmd_argv)))
 
     def start(self, n, profile_dir):
         """Start n engines by profile or profile_dir."""
         self.log.info('Starting %i engines with PBSEngineSetLauncher: %r' % (n, self.args))
         return super(PBSEngineSetLauncher, self).start(n, profile_dir)
 
 #SGE is very similar to PBS
 
 class SGELauncher(PBSLauncher):
     """Sun GridEngine is a PBS clone with slightly different syntax"""
     job_array_regexp = Unicode('#\$\W+\-t')
     job_array_template = Unicode('#$ -t 1-{n}')
     queue_regexp = Unicode('#\$\W+-q\W+\$?\w+')
     queue_template = Unicode('#$ -q {queue}')
 
 class SGEControllerLauncher(SGELauncher):
     """Launch a controller using SGE."""
 
     batch_file_name = Unicode(u'sge_controller', config=True,
         help="batch file name for the ipontroller job.")
     default_template= Unicode(u"""#$ -V
 #$ -S /bin/sh
 #$ -N ipcontroller
 %s --log-to-file --profile-dir={profile_dir}
 """%(' '.join(ipcontroller_cmd_argv)))
 
     def start(self, profile_dir):
         """Start the controller by profile or profile_dir."""
         self.log.info("Starting PBSControllerLauncher: %r" % self.args)
         return super(SGEControllerLauncher, self).start(1, profile_dir)
 
 class SGEEngineSetLauncher(SGELauncher):
     """Launch Engines with SGE"""
     batch_file_name = Unicode(u'sge_engines', config=True,
         help="batch file name for the engine(s) job.")
     default_template = Unicode("""#$ -V
 #$ -S /bin/sh
 #$ -N ipengine
 %s --profile-dir={profile_dir}
 """%(' '.join(ipengine_cmd_argv)))
 
     def start(self, n, profile_dir):
         """Start n engines by profile or profile_dir."""
         self.log.info('Starting %i engines with SGEEngineSetLauncher: %r' % (n, self.args))
         return super(SGEEngineSetLauncher, self).start(n, profile_dir)
 
 
 # LSF launchers
 
 class LSFLauncher(BatchSystemLauncher):
     """A BatchSystemLauncher subclass for LSF."""
     
     submit_command = List(['bsub'], config=True,
                           help="The PBS submit command ['bsub']")
     delete_command = List(['bkill'], config=True,
                           help="The PBS delete command ['bkill']")
     job_id_regexp = Unicode(r'\d+', config=True,
                             help="Regular expresion for identifying the job ID [r'\d+']")
     
     batch_file = Unicode(u'')
     job_array_regexp = Unicode('#BSUB[ \t]-J+\w+\[\d+-\d+\]')
     job_array_template = Unicode('#BSUB -J ipengine[1-{n}]')
     queue_regexp = Unicode('#BSUB[ \t]+-q[ \t]+\w+')
     queue_template = Unicode('#BSUB -q {queue}')
     
     def start(self, n, profile_dir):
         """Start n copies of the process using LSF batch system.
         This cant inherit from the base class because bsub expects
         to be piped a shell script in order to honor the #BSUB directives :
         bsub < script
         """
         # Here we save profile_dir in the context so they
         # can be used in the batch script template as {profile_dir}
         self.context['profile_dir'] = profile_dir
         self.profile_dir = unicode(profile_dir)
         self.write_batch_script(n)
         #output = check_output(self.args, env=os.environ)
         piped_cmd = self.args[0]+'<\"'+self.args[1]+'\"'
         p = Popen(piped_cmd, shell=True,env=os.environ,stdout=PIPE)
         output,err = p.communicate()
         job_id = self.parse_job_id(output)
         self.notify_start(job_id)
         return job_id
 
 
 class LSFControllerLauncher(LSFLauncher):
     """Launch a controller using LSF."""
     
     batch_file_name = Unicode(u'lsf_controller', config=True,
                               help="batch file name for the controller job.")
     default_template= Unicode("""#!/bin/sh
     #BSUB -J ipcontroller
     #BSUB -oo ipcontroller.o.%%J 
     #BSUB -eo ipcontroller.e.%%J 
     %s --log-to-file --profile-dir={profile_dir}
     """%(' '.join(ipcontroller_cmd_argv)))
     
     def start(self, profile_dir):
         """Start the controller by profile or profile_dir."""
         self.log.info("Starting LSFControllerLauncher: %r" % self.args)
         return super(LSFControllerLauncher, self).start(1, profile_dir)
 
 
 class LSFEngineSetLauncher(LSFLauncher):
     """Launch Engines using LSF"""
     batch_file_name = Unicode(u'lsf_engines', config=True,
                               help="batch file name for the engine(s) job.")
     default_template= Unicode(u"""#!/bin/sh
     #BSUB -oo ipengine.o.%%J 
     #BSUB -eo ipengine.e.%%J 
     %s --profile-dir={profile_dir}
     """%(' '.join(ipengine_cmd_argv)))
     
     def start(self, n, profile_dir):
         """Start n engines by profile or profile_dir."""
         self.log.info('Starting %i engines with LSFEngineSetLauncher: %r' % (n, self.args))
         return super(LSFEngineSetLauncher, self).start(n, profile_dir)
 
 
 #-----------------------------------------------------------------------------
 # A launcher for ipcluster itself!
 #-----------------------------------------------------------------------------
 
 
 class IPClusterLauncher(LocalProcessLauncher):
     """Launch the ipcluster program in an external process."""
 
     ipcluster_cmd = List(ipcluster_cmd_argv, config=True,
         help="Popen command for ipcluster")
     ipcluster_args = List(
         ['--clean-logs', '--log-to-file', '--log-level=%i'%logging.INFO], config=True,
         help="Command line arguments to pass to ipcluster.")
     ipcluster_subcommand = Unicode('start')
     ipcluster_n = Int(2)
 
     def find_args(self):
         return self.ipcluster_cmd + [self.ipcluster_subcommand] + \
             ['--n=%i'%self.ipcluster_n] + self.ipcluster_args
 
     def start(self):
         self.log.info("Starting ipcluster: %r" % self.args)
         return super(IPClusterLauncher, self).start()
 
 #-----------------------------------------------------------------------------
 # Collections of launchers
 #-----------------------------------------------------------------------------
 
 local_launchers = [
     LocalControllerLauncher,
     LocalEngineLauncher,
     LocalEngineSetLauncher,
 ]
 mpi_launchers = [
     MPIExecLauncher,
     MPIExecControllerLauncher,
     MPIExecEngineSetLauncher,
 ]
 ssh_launchers = [
     SSHLauncher,
     SSHControllerLauncher,
     SSHEngineLauncher,
     SSHEngineSetLauncher,
 ]
 winhpc_launchers = [
     WindowsHPCLauncher,
     WindowsHPCControllerLauncher,
     WindowsHPCEngineSetLauncher,
 ]
 pbs_launchers = [
     PBSLauncher,
     PBSControllerLauncher,
     PBSEngineSetLauncher,
 ]
 sge_launchers = [
     SGELauncher,
     SGEControllerLauncher,
     SGEEngineSetLauncher,
 ]
 lsf_launchers = [
     LSFLauncher,
     LSFControllerLauncher,
     LSFEngineSetLauncher,
 ]
 all_launchers = local_launchers + mpi_launchers + ssh_launchers + winhpc_launchers\
                 + pbs_launchers + sge_launchers + lsf_launchers
 

IPython/parallel/apps/logwatcher.py

@@ -1,115 +1,114 b''
-#!/usr/bin/env python
 """
 A simple logger object that consolidates messages incoming from ipcluster processes.
 
 Authors:
 
 * MinRK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 
 import logging
 import sys
 
 import zmq
 from zmq.eventloop import ioloop, zmqstream
 
 from IPython.config.configurable import LoggingConfigurable
 from IPython.utils.traitlets import Int, Unicode, Instance, List
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 
 class LogWatcher(LoggingConfigurable):
     """A simple class that receives messages on a SUB socket, as published
     by subclasses of `zmq.log.handlers.PUBHandler`, and logs them itself.
     
     This can subscribe to multiple topics, but defaults to all topics.
     """
     
     # configurables
     topics = List([''], config=True,
         help="The ZMQ topics to subscribe to. Default is to subscribe to all messages")
     url = Unicode('tcp://127.0.0.1:20202', config=True,
         help="ZMQ url on which to listen for log messages")
     
     # internals
     stream = Instance('zmq.eventloop.zmqstream.ZMQStream')
     
     context = Instance(zmq.Context)
     def _context_default(self):
         return zmq.Context.instance()
     
     loop = Instance(zmq.eventloop.ioloop.IOLoop)
     def _loop_default(self):
         return ioloop.IOLoop.instance()
     
     def __init__(self, **kwargs):
         super(LogWatcher, self).__init__(**kwargs)
         s = self.context.socket(zmq.SUB)
         s.bind(self.url)
         self.stream = zmqstream.ZMQStream(s, self.loop)
         self.subscribe()
         self.on_trait_change(self.subscribe, 'topics')
     
     def start(self):
         self.stream.on_recv(self.log_message)
     
     def stop(self):
         self.stream.stop_on_recv()
     
     def subscribe(self):
         """Update our SUB socket's subscriptions."""
         self.stream.setsockopt(zmq.UNSUBSCRIBE, '')
         if '' in self.topics:
             self.log.debug("Subscribing to: everything")
             self.stream.setsockopt(zmq.SUBSCRIBE, '')
         else:
             for topic in self.topics:
                 self.log.debug("Subscribing to: %r"%(topic))
                 self.stream.setsockopt(zmq.SUBSCRIBE, topic)
     
     def _extract_level(self, topic_str):
         """Turn 'engine.0.INFO.extra' into (logging.INFO, 'engine.0.extra')"""
         topics = topic_str.split('.')
         for idx,t in enumerate(topics):
             level = getattr(logging, t, None)
             if level is not None:
                 break
         
         if level is None:
             level = logging.INFO
         else:
             topics.pop(idx)
         
         return level, '.'.join(topics)
             
             
     def log_message(self, raw):
         """receive and parse a message, then log it."""
         if len(raw) != 2 or '.' not in raw[0]:
             self.log.error("Invalid log message: %s"%raw)
             return
         else:
             topic, msg = raw
             # don't newline, since log messages always newline:
             topic,level_name = topic.rsplit('.',1)
             level,topic = self._extract_level(topic)
             if msg[-1] == '\n':
                 msg = msg[:-1]
             self.log.log(level, "[%s] %s" % (topic, msg))
 

IPython/parallel/apps/win32support.py

@@ -1,73 +1,72 b''
-#!/usr/bin/env python
 """Utility for forwarding file read events over a zmq socket.
 
 This is necessary because select on Windows only supports sockets, not FDs.
 
 Authors:
 
 * MinRK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import uuid
 import zmq
 
 from threading import Thread
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 class ForwarderThread(Thread):
     def __init__(self, sock, fd):
         Thread.__init__(self)
         self.daemon=True
         self.sock = sock
         self.fd = fd
 
     def run(self):
         """Loop through lines in self.fd, and send them over self.sock."""
         line = self.fd.readline()
         # allow for files opened in unicode mode
         if isinstance(line, unicode):
             send = self.sock.send_unicode
         else:
             send = self.sock.send
         while line:
             send(line)
             line = self.fd.readline()
         # line == '' means EOF
         self.fd.close()
         self.sock.close()
 
 def forward_read_events(fd, context=None):
     """Forward read events from an FD over a socket.
 
     This method wraps a file in a socket pair, so it can
     be polled for read events by select (specifically zmq.eventloop.ioloop)
     """
     if context is None:
         context = zmq.Context.instance()
     push = context.socket(zmq.PUSH)
     push.setsockopt(zmq.LINGER, -1)
     pull = context.socket(zmq.PULL)
     addr='inproc://%s'%uuid.uuid4()
     push.bind(addr)
     pull.connect(addr)
     forwarder = ForwarderThread(push, fd)
     forwarder.start()
     return pull
 
 
 __all__ = ['forward_read_events']

IPython/parallel/apps/winhpcjob.py

@@ -1,320 +1,319 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Job and task components for writing .xml files that the Windows HPC Server 
 2008 can use to start jobs.
 
 Authors:
 
 * Brian Granger
 * MinRK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import re
 import uuid
 
 from xml.etree import ElementTree as ET
 
 from IPython.config.configurable import Configurable
 from IPython.utils.traitlets import (
     Unicode, Int, List, Instance,
     Enum, Bool
 )
 
 #-----------------------------------------------------------------------------
 # Job and Task classes
 #-----------------------------------------------------------------------------
 
 
 def as_str(value):
     if isinstance(value, str):
         return value
     elif isinstance(value, bool):
         if value:
             return 'true'
         else:
             return 'false'
     elif isinstance(value, (int, float)):
         return repr(value)
     else:
         return value
 
 
 def indent(elem, level=0):
     i = "\n" + level*"  "
     if len(elem):
         if not elem.text or not elem.text.strip():
             elem.text = i + "  "
         if not elem.tail or not elem.tail.strip():
             elem.tail = i
         for elem in elem:
             indent(elem, level+1)
         if not elem.tail or not elem.tail.strip():
             elem.tail = i
     else:
         if level and (not elem.tail or not elem.tail.strip()):
             elem.tail = i
 
 
 def find_username():
     domain = os.environ.get('USERDOMAIN')
     username = os.environ.get('USERNAME','')
     if domain is None:
         return username
     else:
         return '%s\\%s' % (domain, username)
 
 
 class WinHPCJob(Configurable):
 
     job_id = Unicode('')
     job_name = Unicode('MyJob', config=True)
     min_cores = Int(1, config=True)
     max_cores = Int(1, config=True)
     min_sockets = Int(1, config=True)
     max_sockets = Int(1, config=True)
     min_nodes = Int(1, config=True)
     max_nodes = Int(1, config=True)
     unit_type = Unicode("Core", config=True)
     auto_calculate_min = Bool(True, config=True)
     auto_calculate_max = Bool(True, config=True)
     run_until_canceled = Bool(False, config=True)
     is_exclusive = Bool(False, config=True)
     username = Unicode(find_username(), config=True)
     job_type = Unicode('Batch', config=True)
     priority = Enum(('Lowest','BelowNormal','Normal','AboveNormal','Highest'),
         default_value='Highest', config=True)
     requested_nodes = Unicode('', config=True)
     project = Unicode('IPython', config=True)
     xmlns = Unicode('http://schemas.microsoft.com/HPCS2008/scheduler/')
     version = Unicode("2.000")
     tasks = List([])
 
     @property
     def owner(self):
         return self.username
 
     def _write_attr(self, root, attr, key):
         s = as_str(getattr(self, attr, ''))
         if s:
             root.set(key, s)
 
     def as_element(self):
         # We have to add _A_ type things to get the right order than
         # the MSFT XML parser expects.
         root = ET.Element('Job')
         self._write_attr(root, 'version', '_A_Version')
         self._write_attr(root, 'job_name', '_B_Name')
         self._write_attr(root, 'unit_type', '_C_UnitType')
         self._write_attr(root, 'min_cores', '_D_MinCores')
         self._write_attr(root, 'max_cores', '_E_MaxCores')
         self._write_attr(root, 'min_sockets', '_F_MinSockets')
         self._write_attr(root, 'max_sockets', '_G_MaxSockets')
         self._write_attr(root, 'min_nodes', '_H_MinNodes')
         self._write_attr(root, 'max_nodes', '_I_MaxNodes')
         self._write_attr(root, 'run_until_canceled', '_J_RunUntilCanceled')
         self._write_attr(root, 'is_exclusive', '_K_IsExclusive')
         self._write_attr(root, 'username', '_L_UserName')
         self._write_attr(root, 'job_type', '_M_JobType')
         self._write_attr(root, 'priority', '_N_Priority')
         self._write_attr(root, 'requested_nodes', '_O_RequestedNodes')
         self._write_attr(root, 'auto_calculate_max', '_P_AutoCalculateMax')
         self._write_attr(root, 'auto_calculate_min', '_Q_AutoCalculateMin')
         self._write_attr(root, 'project', '_R_Project')
         self._write_attr(root, 'owner', '_S_Owner')
         self._write_attr(root, 'xmlns', '_T_xmlns')
         dependencies = ET.SubElement(root, "Dependencies")
         etasks = ET.SubElement(root, "Tasks")
         for t in self.tasks:
             etasks.append(t.as_element())
         return root
 
     def tostring(self):
         """Return the string representation of the job description XML."""
         root = self.as_element()
         indent(root)
         txt = ET.tostring(root, encoding="utf-8")
         # Now remove the tokens used to order the attributes.
         txt = re.sub(r'_[A-Z]_','',txt)
         txt = '<?xml version="1.0" encoding="utf-8"?>\n' + txt
         return txt
 
     def write(self, filename):
         """Write the XML job description to a file."""
         txt = self.tostring()
         with open(filename, 'w') as f:
             f.write(txt)
 
     def add_task(self, task):
         """Add a task to the job.
 
         Parameters
         ----------
         task : :class:`WinHPCTask`
             The task object to add.
         """
         self.tasks.append(task)
 
 
 class WinHPCTask(Configurable):
 
     task_id = Unicode('')
     task_name = Unicode('')
     version = Unicode("2.000")
     min_cores = Int(1, config=True)
     max_cores = Int(1, config=True)
     min_sockets = Int(1, config=True)
     max_sockets = Int(1, config=True)
     min_nodes = Int(1, config=True)
     max_nodes = Int(1, config=True)
     unit_type = Unicode("Core", config=True)
     command_line = Unicode('', config=True)
     work_directory = Unicode('', config=True)
     is_rerunnaable = Bool(True, config=True)
     std_out_file_path = Unicode('', config=True)
     std_err_file_path = Unicode('', config=True)
     is_parametric = Bool(False, config=True)
     environment_variables = Instance(dict, args=(), config=True)
 
     def _write_attr(self, root, attr, key):
         s = as_str(getattr(self, attr, ''))
         if s:
             root.set(key, s)
 
     def as_element(self):
         root = ET.Element('Task')
         self._write_attr(root, 'version', '_A_Version')
         self._write_attr(root, 'task_name', '_B_Name')
         self._write_attr(root, 'min_cores', '_C_MinCores')
         self._write_attr(root, 'max_cores', '_D_MaxCores')
         self._write_attr(root, 'min_sockets', '_E_MinSockets')
         self._write_attr(root, 'max_sockets', '_F_MaxSockets')
         self._write_attr(root, 'min_nodes', '_G_MinNodes')
         self._write_attr(root, 'max_nodes', '_H_MaxNodes')
         self._write_attr(root, 'command_line', '_I_CommandLine')
         self._write_attr(root, 'work_directory', '_J_WorkDirectory')
         self._write_attr(root, 'is_rerunnaable', '_K_IsRerunnable')
         self._write_attr(root, 'std_out_file_path', '_L_StdOutFilePath')
         self._write_attr(root, 'std_err_file_path', '_M_StdErrFilePath')
         self._write_attr(root, 'is_parametric', '_N_IsParametric')
         self._write_attr(root, 'unit_type', '_O_UnitType')
         root.append(self.get_env_vars())
         return root
 
     def get_env_vars(self):
         env_vars = ET.Element('EnvironmentVariables')
         for k, v in self.environment_variables.iteritems():
             variable = ET.SubElement(env_vars, "Variable")
             name = ET.SubElement(variable, "Name")
             name.text = k
             value = ET.SubElement(variable, "Value")
             value.text = v
         return env_vars
 
 
 
 # By declaring these, we can configure the controller and engine separately!
 
 class IPControllerJob(WinHPCJob):
     job_name = Unicode('IPController', config=False)
     is_exclusive = Bool(False, config=True)
     username = Unicode(find_username(), config=True)
     priority = Enum(('Lowest','BelowNormal','Normal','AboveNormal','Highest'),
         default_value='Highest', config=True)
     requested_nodes = Unicode('', config=True)
     project = Unicode('IPython', config=True)
 
 
 class IPEngineSetJob(WinHPCJob):
     job_name = Unicode('IPEngineSet', config=False)
     is_exclusive = Bool(False, config=True)
     username = Unicode(find_username(), config=True)
     priority = Enum(('Lowest','BelowNormal','Normal','AboveNormal','Highest'),
         default_value='Highest', config=True)
     requested_nodes = Unicode('', config=True)
     project = Unicode('IPython', config=True)
 
 
 class IPControllerTask(WinHPCTask):
 
     task_name = Unicode('IPController', config=True)
     controller_cmd = List(['ipcontroller.exe'], config=True)
     controller_args = List(['--log-to-file', '--log-level=40'], config=True)
     # I don't want these to be configurable
     std_out_file_path = Unicode('', config=False)
     std_err_file_path = Unicode('', config=False)
     min_cores = Int(1, config=False)
     max_cores = Int(1, config=False)
     min_sockets = Int(1, config=False)
     max_sockets = Int(1, config=False)
     min_nodes = Int(1, config=False)
     max_nodes = Int(1, config=False)
     unit_type = Unicode("Core", config=False)
     work_directory = Unicode('', config=False)
 
     def __init__(self, config=None):
         super(IPControllerTask, self).__init__(config=config)
         the_uuid = uuid.uuid1()
         self.std_out_file_path = os.path.join('log','ipcontroller-%s.out' % the_uuid)
         self.std_err_file_path = os.path.join('log','ipcontroller-%s.err' % the_uuid)
 
     @property
     def command_line(self):
         return ' '.join(self.controller_cmd + self.controller_args)
 
 
 class IPEngineTask(WinHPCTask):
 
     task_name = Unicode('IPEngine', config=True)
     engine_cmd = List(['ipengine.exe'], config=True)
     engine_args = List(['--log-to-file', '--log-level=40'], config=True)
     # I don't want these to be configurable
     std_out_file_path = Unicode('', config=False)
     std_err_file_path = Unicode('', config=False)
     min_cores = Int(1, config=False)
     max_cores = Int(1, config=False)
     min_sockets = Int(1, config=False)
     max_sockets = Int(1, config=False)
     min_nodes = Int(1, config=False)
     max_nodes = Int(1, config=False)
     unit_type = Unicode("Core", config=False)
     work_directory = Unicode('', config=False)
 
     def __init__(self, config=None):
         super(IPEngineTask,self).__init__(config=config)
         the_uuid = uuid.uuid1()
         self.std_out_file_path = os.path.join('log','ipengine-%s.out' % the_uuid)
         self.std_err_file_path = os.path.join('log','ipengine-%s.err' % the_uuid)
     
     @property
     def command_line(self):
         return ' '.join(self.engine_cmd + self.engine_args)
 
 
 # j = WinHPCJob(None)
 # j.job_name = 'IPCluster'
 # j.username = 'GNET\\bgranger'
 # j.requested_nodes = 'GREEN'
 # 
 # t = WinHPCTask(None)
 # t.task_name = 'Controller'
 # t.command_line = r"\\blue\domainusers$\bgranger\Python\Python25\Scripts\ipcontroller.exe --log-to-file -p default --log-level 10"
 # t.work_directory = r"\\blue\domainusers$\bgranger\.ipython\cluster_default"
 # t.std_out_file_path = 'controller-out.txt'
 # t.std_err_file_path = 'controller-err.txt'
 # t.environment_variables['PYTHONPATH'] = r"\\blue\domainusers$\bgranger\Python\Python25\Lib\site-packages"
 # j.add_task(t)
 

IPython/parallel/controller/hub.py

@@ -1,1291 +1,1290 b''
-#!/usr/bin/env python
 """The IPython Controller Hub with 0MQ
 This is the master object that handles connections from engines and clients,
 and monitors traffic through the various queues.
 
 Authors:
 
 * Min RK
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import print_function
 
 import sys
 import time
 from datetime import datetime
 
 import zmq
 from zmq.eventloop import ioloop
 from zmq.eventloop.zmqstream import ZMQStream
 
 # internal:
 from IPython.utils.importstring import import_item
 from IPython.utils.traitlets import (
         HasTraits, Instance, Int, Unicode, Dict, Set, Tuple, CBytes, DottedObjectName
         )
 
 from IPython.parallel import error, util
 from IPython.parallel.factory import RegistrationFactory
 
 from IPython.zmq.session import SessionFactory
 
 from .heartmonitor import HeartMonitor
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 def _passer(*args, **kwargs):
     return
 
 def _printer(*args, **kwargs):
     print (args)
     print (kwargs)
 
 def empty_record():
     """Return an empty dict with all record keys."""
     return {
         'msg_id' : None,
         'header' : None,
         'content': None,
         'buffers': None,
         'submitted': None,
         'client_uuid' : None,
         'engine_uuid' : None,
         'started': None,
         'completed': None,
         'resubmitted': None,
         'result_header' : None,
         'result_content' : None,
         'result_buffers' : None,
         'queue' : None,
         'pyin' : None,
         'pyout': None,
         'pyerr': None,
         'stdout': '',
         'stderr': '',
     }
     
 def init_record(msg):
     """Initialize a TaskRecord based on a request."""
     header = msg['header']
     return {
         'msg_id' : header['msg_id'],
         'header' : header,
         'content': msg['content'],
         'buffers': msg['buffers'],
         'submitted': header['date'],
         'client_uuid' : None,
         'engine_uuid' : None,
         'started': None,
         'completed': None,
         'resubmitted': None,
         'result_header' : None,
         'result_content' : None,
         'result_buffers' : None,
         'queue' : None,
         'pyin' : None,
         'pyout': None,
         'pyerr': None,
         'stdout': '',
         'stderr': '',
     }
 
 
 class EngineConnector(HasTraits):
     """A simple object for accessing the various zmq connections of an object.
     Attributes are:
     id (int): engine ID
     uuid (str): uuid (unused?)
     queue (str): identity of queue's XREQ socket
     registration (str): identity of registration XREQ socket
     heartbeat (str): identity of heartbeat XREQ socket
     """
     id=Int(0)
     queue=CBytes()
     control=CBytes()
     registration=CBytes()
     heartbeat=CBytes()
     pending=Set()
 
 class HubFactory(RegistrationFactory):
     """The Configurable for setting up a Hub."""
     
     # port-pairs for monitoredqueues:
     hb = Tuple(Int,Int,config=True,
         help="""XREQ/SUB Port pair for Engine heartbeats""")
     def _hb_default(self):
         return tuple(util.select_random_ports(2))
 
     mux = Tuple(Int,Int,config=True,
         help="""Engine/Client Port pair for MUX queue""")
     
     def _mux_default(self):
         return tuple(util.select_random_ports(2))
     
     task = Tuple(Int,Int,config=True,
         help="""Engine/Client Port pair for Task queue""")
     def _task_default(self):
         return tuple(util.select_random_ports(2))
 
     control = Tuple(Int,Int,config=True,
         help="""Engine/Client Port pair for Control queue""")
     
     def _control_default(self):
         return tuple(util.select_random_ports(2))
 
     iopub = Tuple(Int,Int,config=True,
         help="""Engine/Client Port pair for IOPub relay""")
     
     def _iopub_default(self):
         return tuple(util.select_random_ports(2))
     
     # single ports:
     mon_port = Int(config=True,
         help="""Monitor (SUB) port for queue traffic""")
 
     def _mon_port_default(self):
         return util.select_random_ports(1)[0]
     
     notifier_port = Int(config=True,
         help="""PUB port for sending engine status notifications""")
 
     def _notifier_port_default(self):
         return util.select_random_ports(1)[0]
     
     engine_ip = Unicode('127.0.0.1', config=True,
         help="IP on which to listen for engine connections. [default: loopback]")
     engine_transport = Unicode('tcp', config=True,
         help="0MQ transport for engine connections. [default: tcp]")
     
     client_ip = Unicode('127.0.0.1', config=True,
         help="IP on which to listen for client connections. [default: loopback]")
     client_transport = Unicode('tcp', config=True,
         help="0MQ transport for client connections. [default : tcp]")
     
     monitor_ip = Unicode('127.0.0.1', config=True,
         help="IP on which to listen for monitor messages. [default: loopback]")
     monitor_transport = Unicode('tcp', config=True,
         help="0MQ transport for monitor messages. [default : tcp]")
     
     monitor_url = Unicode('')
     
     db_class = DottedObjectName('IPython.parallel.controller.dictdb.DictDB',
         config=True, help="""The class to use for the DB backend""")
     
     # not configurable
     db = Instance('IPython.parallel.controller.dictdb.BaseDB')
     heartmonitor = Instance('IPython.parallel.controller.heartmonitor.HeartMonitor')
     
     def _ip_changed(self, name, old, new):
         self.engine_ip = new
         self.client_ip = new
         self.monitor_ip = new
         self._update_monitor_url()
     
     def _update_monitor_url(self):
         self.monitor_url = "%s://%s:%i"%(self.monitor_transport, self.monitor_ip, self.mon_port)
     
     def _transport_changed(self, name, old, new):
         self.engine_transport = new
         self.client_transport = new
         self.monitor_transport = new
         self._update_monitor_url()
         
     def __init__(self, **kwargs):
         super(HubFactory, self).__init__(**kwargs)
         self._update_monitor_url()
     
     
     def construct(self):
         self.init_hub()
     
     def start(self):
         self.heartmonitor.start()
         self.log.info("Heartmonitor started")
     
     def init_hub(self):
         """construct"""
         client_iface = "%s://%s:"%(self.client_transport, self.client_ip) + "%i"
         engine_iface = "%s://%s:"%(self.engine_transport, self.engine_ip) + "%i"
         
         ctx = self.context
         loop = self.loop
         
         # Registrar socket
         q = ZMQStream(ctx.socket(zmq.XREP), loop)
         q.bind(client_iface % self.regport)
         self.log.info("Hub listening on %s for registration."%(client_iface%self.regport))
         if self.client_ip != self.engine_ip:
             q.bind(engine_iface % self.regport)
             self.log.info("Hub listening on %s for registration."%(engine_iface%self.regport))
         
         ### Engine connections ###
 
         # heartbeat
         hpub = ctx.socket(zmq.PUB)
         hpub.bind(engine_iface % self.hb[0])
         hrep = ctx.socket(zmq.XREP)
         hrep.bind(engine_iface % self.hb[1])
         self.heartmonitor = HeartMonitor(loop=loop, config=self.config, log=self.log,
                                 pingstream=ZMQStream(hpub,loop),
                                 pongstream=ZMQStream(hrep,loop)
                             )
 
         ### Client connections ###
         # Notifier socket
         n = ZMQStream(ctx.socket(zmq.PUB), loop)
         n.bind(client_iface%self.notifier_port)
 
         ### build and launch the queues ###
 
         # monitor socket
         sub = ctx.socket(zmq.SUB)
         sub.setsockopt(zmq.SUBSCRIBE, b"")
         sub.bind(self.monitor_url)
         sub.bind('inproc://monitor')
         sub = ZMQStream(sub, loop)
         
         # connect the db
         self.log.info('Hub using DB backend: %r'%(self.db_class.split()[-1]))
         # cdir = self.config.Global.cluster_dir
         self.db = import_item(str(self.db_class))(session=self.session.session, 
                                             config=self.config, log=self.log)
         time.sleep(.25)
         try:
             scheme = self.config.TaskScheduler.scheme_name
         except AttributeError:
             from .scheduler import TaskScheduler
             scheme = TaskScheduler.scheme_name.get_default_value()
         # build connection dicts
         self.engine_info = {
             'control' : engine_iface%self.control[1],
             'mux': engine_iface%self.mux[1],
             'heartbeat': (engine_iface%self.hb[0], engine_iface%self.hb[1]),
             'task' : engine_iface%self.task[1],
             'iopub' : engine_iface%self.iopub[1],
             # 'monitor' : engine_iface%self.mon_port,
             }
 
         self.client_info = {
             'control' : client_iface%self.control[0],
             'mux': client_iface%self.mux[0],
             'task' : (scheme, client_iface%self.task[0]),
             'iopub' : client_iface%self.iopub[0],
             'notification': client_iface%self.notifier_port
             }
         self.log.debug("Hub engine addrs: %s"%self.engine_info)
         self.log.debug("Hub client addrs: %s"%self.client_info)
 
         # resubmit stream
         r = ZMQStream(ctx.socket(zmq.XREQ), loop)
         url = util.disambiguate_url(self.client_info['task'][-1])
         r.setsockopt(zmq.IDENTITY, util.asbytes(self.session.session))
         r.connect(url)
 
         self.hub = Hub(loop=loop, session=self.session, monitor=sub, heartmonitor=self.heartmonitor,
                 query=q, notifier=n, resubmit=r, db=self.db,
                 engine_info=self.engine_info, client_info=self.client_info,
                 log=self.log)
     
 
 class Hub(SessionFactory):
     """The IPython Controller Hub with 0MQ connections
     
     Parameters
     ==========
     loop: zmq IOLoop instance
     session: Session object
     <removed> context: zmq context for creating new connections (?)
     queue: ZMQStream for monitoring the command queue (SUB)
     query: ZMQStream for engine registration and client queries requests (XREP)
     heartbeat: HeartMonitor object checking the pulse of the engines
     notifier: ZMQStream for broadcasting engine registration changes (PUB)
     db: connection to db for out of memory logging of commands
                 NotImplemented
     engine_info: dict of zmq connection information for engines to connect
                 to the queues.
     client_info: dict of zmq connection information for engines to connect
                 to the queues.
     """
     # internal data structures:
     ids=Set() # engine IDs
     keytable=Dict()
     by_ident=Dict()
     engines=Dict()
     clients=Dict()
     hearts=Dict()
     pending=Set()
     queues=Dict()  # pending msg_ids keyed by engine_id
     tasks=Dict() # pending msg_ids submitted as tasks, keyed by client_id
     completed=Dict() # completed msg_ids keyed by engine_id
     all_completed=Set() # completed msg_ids keyed by engine_id
     dead_engines=Set() # completed msg_ids keyed by engine_id
     unassigned=Set() # set of task msg_ds not yet assigned a destination
     incoming_registrations=Dict()
     registration_timeout=Int()
     _idcounter=Int(0)
     
     # objects from constructor:
     query=Instance(ZMQStream)
     monitor=Instance(ZMQStream)
     notifier=Instance(ZMQStream)
     resubmit=Instance(ZMQStream)
     heartmonitor=Instance(HeartMonitor)
     db=Instance(object)
     client_info=Dict()
     engine_info=Dict()
     
     
     def __init__(self, **kwargs):
         """
         # universal:
         loop: IOLoop for creating future connections
         session: streamsession for sending serialized data
         # engine:
         queue: ZMQStream for monitoring queue messages
         query: ZMQStream for engine+client registration and client requests
         heartbeat: HeartMonitor object for tracking engines
         # extra:
         db: ZMQStream for db connection (NotImplemented)
         engine_info: zmq address/protocol dict for engine connections
         client_info: zmq address/protocol dict for client connections
         """
         
         super(Hub, self).__init__(**kwargs)
         self.registration_timeout = max(5000, 2*self.heartmonitor.period)
         
         # validate connection dicts:
         for k,v in self.client_info.iteritems():
             if k == 'task':
                 util.validate_url_container(v[1])
             else:
                 util.validate_url_container(v)
         # util.validate_url_container(self.client_info)
         util.validate_url_container(self.engine_info)
         
         # register our callbacks
         self.query.on_recv(self.dispatch_query)
         self.monitor.on_recv(self.dispatch_monitor_traffic)
         
         self.heartmonitor.add_heart_failure_handler(self.handle_heart_failure)
         self.heartmonitor.add_new_heart_handler(self.handle_new_heart)
         
         self.monitor_handlers = {b'in' : self.save_queue_request,
                                 b'out': self.save_queue_result,
                                 b'intask': self.save_task_request,
                                 b'outtask': self.save_task_result,
                                 b'tracktask': self.save_task_destination,
                                 b'incontrol': _passer,
                                 b'outcontrol': _passer,
                                 b'iopub': self.save_iopub_message,
         }
         
         self.query_handlers = {'queue_request': self.queue_status,
                                 'result_request': self.get_results,
                                 'history_request': self.get_history,
                                 'db_request': self.db_query,
                                 'purge_request': self.purge_results,
                                 'load_request': self.check_load,
                                 'resubmit_request': self.resubmit_task,
                                 'shutdown_request': self.shutdown_request,
                                 'registration_request' : self.register_engine,
                                 'unregistration_request' : self.unregister_engine,
                                 'connection_request': self.connection_request,
         }
         
         # ignore resubmit replies
         self.resubmit.on_recv(lambda msg: None, copy=False)
 
         self.log.info("hub::created hub")
     
     @property
     def _next_id(self):
         """gemerate a new ID.
         
         No longer reuse old ids, just count from 0."""
         newid = self._idcounter
         self._idcounter += 1
         return newid
         # newid = 0
         # incoming = [id[0] for id in self.incoming_registrations.itervalues()]
         # # print newid, self.ids, self.incoming_registrations
         # while newid in self.ids or newid in incoming:
         #     newid += 1
         # return newid
     
     #-----------------------------------------------------------------------------
     # message validation
     #-----------------------------------------------------------------------------
     
     def _validate_targets(self, targets):
         """turn any valid targets argument into a list of integer ids"""
         if targets is None:
             # default to all
             targets = self.ids
             
         if isinstance(targets, (int,str,unicode)):
             # only one target specified
             targets = [targets]
         _targets = []
         for t in targets:
             # map raw identities to ids
             if isinstance(t, (str,unicode)):
                 t = self.by_ident.get(t, t)
             _targets.append(t)
         targets = _targets
         bad_targets = [ t for t in targets if t not in self.ids ]
         if bad_targets:
             raise IndexError("No Such Engine: %r"%bad_targets)
         if not targets:
             raise IndexError("No Engines Registered")
         return targets
     
     #-----------------------------------------------------------------------------
     # dispatch methods (1 per stream)
     #-----------------------------------------------------------------------------
     
     
     def dispatch_monitor_traffic(self, msg):
         """all ME and Task queue messages come through here, as well as
         IOPub traffic."""
         self.log.debug("monitor traffic: %r"%msg[:2])
         switch = msg[0]
         try:
             idents, msg = self.session.feed_identities(msg[1:])
         except ValueError:
             idents=[]
         if not idents:
             self.log.error("Bad Monitor Message: %r"%msg)
             return
         handler = self.monitor_handlers.get(switch, None)
         if handler is not None:
             handler(idents, msg)
         else:
             self.log.error("Invalid monitor topic: %r"%switch)
         
     
     def dispatch_query(self, msg):
         """Route registration requests and queries from clients."""
         try:
             idents, msg = self.session.feed_identities(msg)
         except ValueError:
             idents = []
         if not idents:
             self.log.error("Bad Query Message: %r"%msg)
             return
         client_id = idents[0]
         try:
             msg = self.session.unpack_message(msg, content=True)
         except Exception:
             content = error.wrap_exception()
             self.log.error("Bad Query Message: %r"%msg, exc_info=True)
             self.session.send(self.query, "hub_error", ident=client_id, 
                     content=content)
             return
         # print client_id, header, parent, content
         #switch on message type:
         msg_type = msg['msg_type']
         self.log.info("client::client %r requested %r"%(client_id, msg_type))
         handler = self.query_handlers.get(msg_type, None)
         try:
             assert handler is not None, "Bad Message Type: %r"%msg_type
         except:
             content = error.wrap_exception()
             self.log.error("Bad Message Type: %r"%msg_type, exc_info=True)
             self.session.send(self.query, "hub_error", ident=client_id, 
                     content=content)
             return
 
         else:
             handler(idents, msg)
             
     def dispatch_db(self, msg):
         """"""
         raise NotImplementedError
     
     #---------------------------------------------------------------------------
     # handler methods (1 per event)
     #---------------------------------------------------------------------------
     
     #----------------------- Heartbeat --------------------------------------
     
     def handle_new_heart(self, heart):
         """handler to attach to heartbeater.
         Called when a new heart starts to beat.
         Triggers completion of registration."""
         self.log.debug("heartbeat::handle_new_heart(%r)"%heart)
         if heart not in self.incoming_registrations:
             self.log.info("heartbeat::ignoring new heart: %r"%heart)
         else:
             self.finish_registration(heart)
         
     
     def handle_heart_failure(self, heart):
         """handler to attach to heartbeater.
         called when a previously registered heart fails to respond to beat request.
         triggers unregistration"""
         self.log.debug("heartbeat::handle_heart_failure(%r)"%heart)
         eid = self.hearts.get(heart, None)
         queue = self.engines[eid].queue
         if eid is None:
             self.log.info("heartbeat::ignoring heart failure %r"%heart)
         else:
             self.unregister_engine(heart, dict(content=dict(id=eid, queue=queue)))
     
     #----------------------- MUX Queue Traffic ------------------------------
     
     def save_queue_request(self, idents, msg):
         if len(idents) < 2:
             self.log.error("invalid identity prefix: %r"%idents)
             return
         queue_id, client_id = idents[:2]
         try:
             msg = self.session.unpack_message(msg)
         except Exception:
             self.log.error("queue::client %r sent invalid message to %r: %r"%(client_id, queue_id, msg), exc_info=True)
             return
         
         eid = self.by_ident.get(queue_id, None)
         if eid is None:
             self.log.error("queue::target %r not registered"%queue_id)
             self.log.debug("queue::    valid are: %r"%(self.by_ident.keys()))
             return
         record = init_record(msg)
         msg_id = record['msg_id']
         # Unicode in records
         record['engine_uuid'] = queue_id.decode('ascii')
         record['client_uuid'] = client_id.decode('ascii')
         record['queue'] = 'mux'
 
         try:
             # it's posible iopub arrived first:
             existing = self.db.get_record(msg_id)
             for key,evalue in existing.iteritems():
                 rvalue = record.get(key, None)
                 if evalue and rvalue and evalue != rvalue:
                     self.log.warn("conflicting initial state for record: %r:%r <%r> %r"%(msg_id, rvalue, key, evalue))
                 elif evalue and not rvalue:
                     record[key] = evalue
             try:
                 self.db.update_record(msg_id, record)
             except Exception:
                 self.log.error("DB Error updating record %r"%msg_id, exc_info=True)
         except KeyError:
             try:
                 self.db.add_record(msg_id, record)
             except Exception:
                 self.log.error("DB Error adding record %r"%msg_id, exc_info=True)
                 
         
         self.pending.add(msg_id)
         self.queues[eid].append(msg_id)
     
     def save_queue_result(self, idents, msg):
         if len(idents) < 2:
             self.log.error("invalid identity prefix: %r"%idents)
             return
             
         client_id, queue_id = idents[:2]
         try:
             msg = self.session.unpack_message(msg)
         except Exception:
             self.log.error("queue::engine %r sent invalid message to %r: %r"%(
                     queue_id,client_id, msg), exc_info=True)
             return
         
         eid = self.by_ident.get(queue_id, None)
         if eid is None:
             self.log.error("queue::unknown engine %r is sending a reply: "%queue_id)
             return
         
         parent = msg['parent_header']
         if not parent:
             return
         msg_id = parent['msg_id']
         if msg_id in self.pending:
             self.pending.remove(msg_id)
             self.all_completed.add(msg_id)
             self.queues[eid].remove(msg_id)
             self.completed[eid].append(msg_id)
         elif msg_id not in self.all_completed:
             # it could be a result from a dead engine that died before delivering the
             # result
             self.log.warn("queue:: unknown msg finished %r"%msg_id)
             return
         # update record anyway, because the unregistration could have been premature
         rheader = msg['header']
         completed = rheader['date']
         started = rheader.get('started', None)
         result = {
             'result_header' : rheader,
             'result_content': msg['content'],
             'started' : started,
             'completed' : completed
         }
 
         result['result_buffers'] = msg['buffers']
         try:
             self.db.update_record(msg_id, result)
         except Exception:
             self.log.error("DB Error updating record %r"%msg_id, exc_info=True)
         
             
     #--------------------- Task Queue Traffic ------------------------------
     
     def save_task_request(self, idents, msg):
         """Save the submission of a task."""
         client_id = idents[0]
         
         try:
             msg = self.session.unpack_message(msg)
         except Exception:
             self.log.error("task::client %r sent invalid task message: %r"%(
                     client_id, msg), exc_info=True)
             return
         record = init_record(msg)
 
         record['client_uuid'] = client_id
         record['queue'] = 'task'
         header = msg['header']
         msg_id = header['msg_id']
         self.pending.add(msg_id)
         self.unassigned.add(msg_id)
         try:
             # it's posible iopub arrived first:
             existing = self.db.get_record(msg_id)
             if existing['resubmitted']:
                 for key in ('submitted', 'client_uuid', 'buffers'):
                     # don't clobber these keys on resubmit
                     # submitted and client_uuid should be different
                     # and buffers might be big, and shouldn't have changed
                     record.pop(key)
                     # still check content,header which should not change
                     # but are not expensive to compare as buffers
 
             for key,evalue in existing.iteritems():
                 if key.endswith('buffers'):
                     # don't compare buffers
                     continue
                 rvalue = record.get(key, None)
                 if evalue and rvalue and evalue != rvalue:
                     self.log.warn("conflicting initial state for record: %r:%r <%r> %r"%(msg_id, rvalue, key, evalue))
                 elif evalue and not rvalue:
                     record[key] = evalue
             try:
                 self.db.update_record(msg_id, record)
             except Exception:
                 self.log.error("DB Error updating record %r"%msg_id, exc_info=True)
         except KeyError:
             try:
                 self.db.add_record(msg_id, record)
             except Exception:
                 self.log.error("DB Error adding record %r"%msg_id, exc_info=True)
         except Exception:
             self.log.error("DB Error saving task request %r"%msg_id, exc_info=True)
     
     def save_task_result(self, idents, msg):
         """save the result of a completed task."""
         client_id = idents[0]
         try:
             msg = self.session.unpack_message(msg)
         except Exception:
             self.log.error("task::invalid task result message send to %r: %r"%(
                     client_id, msg), exc_info=True)
             return
         
         parent = msg['parent_header']
         if not parent:
             # print msg
             self.log.warn("Task %r had no parent!"%msg)
             return
         msg_id = parent['msg_id']
         if msg_id in self.unassigned:
             self.unassigned.remove(msg_id)
         
         header = msg['header']
         engine_uuid = header.get('engine', None)
         eid = self.by_ident.get(engine_uuid, None)
         
         if msg_id in self.pending:
             self.pending.remove(msg_id)
             self.all_completed.add(msg_id)
             if eid is not None:
                 self.completed[eid].append(msg_id)
                 if msg_id in self.tasks[eid]:
                     self.tasks[eid].remove(msg_id)
             completed = header['date']
             started = header.get('started', None)
             result = {
                 'result_header' : header,
                 'result_content': msg['content'],
                 'started' : started,
                 'completed' : completed,
                 'engine_uuid': engine_uuid
             }
 
             result['result_buffers'] = msg['buffers']
             try:
                 self.db.update_record(msg_id, result)
             except Exception:
                 self.log.error("DB Error saving task request %r"%msg_id, exc_info=True)
             
         else:
             self.log.debug("task::unknown task %r finished"%msg_id)
     
     def save_task_destination(self, idents, msg):
         try:
             msg = self.session.unpack_message(msg, content=True)
         except Exception:
             self.log.error("task::invalid task tracking message", exc_info=True)
             return
         content = msg['content']
         # print (content)
         msg_id = content['msg_id']
         engine_uuid = content['engine_id']
         eid = self.by_ident[util.asbytes(engine_uuid)]
         
         self.log.info("task::task %r arrived on %r"%(msg_id, eid))
         if msg_id in self.unassigned:
             self.unassigned.remove(msg_id)
         # else:
         #     self.log.debug("task::task %r not listed as MIA?!"%(msg_id))
         
         self.tasks[eid].append(msg_id)
         # self.pending[msg_id][1].update(received=datetime.now(),engine=(eid,engine_uuid))
         try:
             self.db.update_record(msg_id, dict(engine_uuid=engine_uuid))
         except Exception:
             self.log.error("DB Error saving task destination %r"%msg_id, exc_info=True)
             
     
     def mia_task_request(self, idents, msg):
         raise NotImplementedError
         client_id = idents[0]
         # content = dict(mia=self.mia,status='ok')
         # self.session.send('mia_reply', content=content, idents=client_id)
         
         
     #--------------------- IOPub Traffic ------------------------------
     
     def save_iopub_message(self, topics, msg):
         """save an iopub message into the db"""
         # print (topics)
         try:
             msg = self.session.unpack_message(msg, content=True)
         except Exception:
             self.log.error("iopub::invalid IOPub message", exc_info=True)
             return
         
         parent = msg['parent_header']
         if not parent:
             self.log.error("iopub::invalid IOPub message: %r"%msg)
             return
         msg_id = parent['msg_id']
         msg_type = msg['msg_type']
         content = msg['content']
         
         # ensure msg_id is in db
         try:
             rec = self.db.get_record(msg_id)
         except KeyError:
             rec = empty_record()
             rec['msg_id'] = msg_id
             self.db.add_record(msg_id, rec)
         # stream
         d = {}
         if msg_type == 'stream':
             name = content['name']
             s = rec[name] or ''
             d[name] = s + content['data']
             
         elif msg_type == 'pyerr':
             d['pyerr'] = content
         elif msg_type == 'pyin':
             d['pyin'] = content['code']
         else:
             d[msg_type] = content.get('data', '')
         
         try:
             self.db.update_record(msg_id, d)
         except Exception:
             self.log.error("DB Error saving iopub message %r"%msg_id, exc_info=True)
         
     
             
     #-------------------------------------------------------------------------
     # Registration requests
     #-------------------------------------------------------------------------
         
     def connection_request(self, client_id, msg):
         """Reply with connection addresses for clients."""
         self.log.info("client::client %r connected"%client_id)
         content = dict(status='ok')
         content.update(self.client_info)
         jsonable = {}
         for k,v in self.keytable.iteritems():
             if v not in self.dead_engines:
                 jsonable[str(k)] = v.decode('ascii')
         content['engines'] = jsonable
         self.session.send(self.query, 'connection_reply', content, parent=msg, ident=client_id)
     
     def register_engine(self, reg, msg):
         """Register a new engine."""
         content = msg['content']
         try:
             queue = util.asbytes(content['queue'])
         except KeyError:
             self.log.error("registration::queue not specified", exc_info=True)
             return
         heart = content.get('heartbeat', None)
         if heart:
             heart = util.asbytes(heart)
         """register a new engine, and create the socket(s) necessary"""
         eid = self._next_id
         # print (eid, queue, reg, heart)
         
         self.log.debug("registration::register_engine(%i, %r, %r, %r)"%(eid, queue, reg, heart))
         
         content = dict(id=eid,status='ok')
         content.update(self.engine_info)
         # check if requesting available IDs:
         if queue in self.by_ident:
             try:
                 raise KeyError("queue_id %r in use"%queue)
             except:
                 content = error.wrap_exception()
                 self.log.error("queue_id %r in use"%queue, exc_info=True)
         elif heart in self.hearts: # need to check unique hearts?
             try:
                 raise KeyError("heart_id %r in use"%heart)
             except:
                 self.log.error("heart_id %r in use"%heart, exc_info=True)
                 content = error.wrap_exception()
         else:
             for h, pack in self.incoming_registrations.iteritems():
                 if heart == h:
                     try:
                         raise KeyError("heart_id %r in use"%heart)
                     except:
                         self.log.error("heart_id %r in use"%heart, exc_info=True)
                         content = error.wrap_exception()
                     break
                 elif queue == pack[1]:
                     try:
                         raise KeyError("queue_id %r in use"%queue)
                     except:
                         self.log.error("queue_id %r in use"%queue, exc_info=True)
                         content = error.wrap_exception()
                     break
         
         msg = self.session.send(self.query, "registration_reply", 
                 content=content, 
                 ident=reg)
         
         if content['status'] == 'ok':
             if heart in self.heartmonitor.hearts:
                 # already beating
                 self.incoming_registrations[heart] = (eid,queue,reg[0],None)
                 self.finish_registration(heart)
             else:
                 purge = lambda : self._purge_stalled_registration(heart)
                 dc = ioloop.DelayedCallback(purge, self.registration_timeout, self.loop)
                 dc.start()
                 self.incoming_registrations[heart] = (eid,queue,reg[0],dc)
         else:
             self.log.error("registration::registration %i failed: %r"%(eid, content['evalue']))
         return eid
     
     def unregister_engine(self, ident, msg):
         """Unregister an engine that explicitly requested to leave."""
         try:
             eid = msg['content']['id']
         except:
             self.log.error("registration::bad engine id for unregistration: %r"%ident, exc_info=True)
             return
         self.log.info("registration::unregister_engine(%r)"%eid)
         # print (eid)
         uuid = self.keytable[eid]
         content=dict(id=eid, queue=uuid.decode('ascii'))
         self.dead_engines.add(uuid)
         # self.ids.remove(eid)
         # uuid = self.keytable.pop(eid)
         # 
         # ec = self.engines.pop(eid)
         # self.hearts.pop(ec.heartbeat)
         # self.by_ident.pop(ec.queue)
         # self.completed.pop(eid)
         handleit = lambda : self._handle_stranded_msgs(eid, uuid)
         dc = ioloop.DelayedCallback(handleit, self.registration_timeout, self.loop)
         dc.start()
         ############## TODO: HANDLE IT ################
         
         if self.notifier:
             self.session.send(self.notifier, "unregistration_notification", content=content)
     
     def _handle_stranded_msgs(self, eid, uuid):
         """Handle messages known to be on an engine when the engine unregisters.
         
         It is possible that this will fire prematurely - that is, an engine will
         go down after completing a result, and the client will be notified
         that the result failed and later receive the actual result.
         """
         
         outstanding = self.queues[eid]
         
         for msg_id in outstanding:
             self.pending.remove(msg_id)
             self.all_completed.add(msg_id)
             try:
                 raise error.EngineError("Engine %r died while running task %r"%(eid, msg_id))
             except:
                 content = error.wrap_exception()
             # build a fake header:
             header = {}
             header['engine'] = uuid
             header['date'] = datetime.now()
             rec = dict(result_content=content, result_header=header, result_buffers=[])
             rec['completed'] = header['date']
             rec['engine_uuid'] = uuid
             try:
                 self.db.update_record(msg_id, rec)
             except Exception:
                 self.log.error("DB Error handling stranded msg %r"%msg_id, exc_info=True)
                 
     
     def finish_registration(self, heart):
         """Second half of engine registration, called after our HeartMonitor
         has received a beat from the Engine's Heart."""
         try: 
             (eid,queue,reg,purge) = self.incoming_registrations.pop(heart)
         except KeyError:
             self.log.error("registration::tried to finish nonexistant registration", exc_info=True)
             return
         self.log.info("registration::finished registering engine %i:%r"%(eid,queue))
         if purge is not None:
             purge.stop()
         control = queue
         self.ids.add(eid)
         self.keytable[eid] = queue
         self.engines[eid] = EngineConnector(id=eid, queue=queue, registration=reg, 
                                     control=control, heartbeat=heart)
         self.by_ident[queue] = eid
         self.queues[eid] = list()
         self.tasks[eid] = list()
         self.completed[eid] = list()
         self.hearts[heart] = eid
         content = dict(id=eid, queue=self.engines[eid].queue.decode('ascii'))
         if self.notifier:
             self.session.send(self.notifier, "registration_notification", content=content)
         self.log.info("engine::Engine Connected: %i"%eid)
     
     def _purge_stalled_registration(self, heart):
         if heart in self.incoming_registrations:
             eid = self.incoming_registrations.pop(heart)[0]
             self.log.info("registration::purging stalled registration: %i"%eid)
         else:
             pass
             
     #-------------------------------------------------------------------------
     # Client Requests
     #-------------------------------------------------------------------------
     
     def shutdown_request(self, client_id, msg):
         """handle shutdown request."""
         self.session.send(self.query, 'shutdown_reply', content={'status': 'ok'}, ident=client_id)
         # also notify other clients of shutdown
         self.session.send(self.notifier, 'shutdown_notice', content={'status': 'ok'})
         dc = ioloop.DelayedCallback(lambda : self._shutdown(), 1000, self.loop)
         dc.start()
     
     def _shutdown(self):
         self.log.info("hub::hub shutting down.")
         time.sleep(0.1)
         sys.exit(0)
         
     
     def check_load(self, client_id, msg):
         content = msg['content']
         try:
             targets = content['targets']
             targets = self._validate_targets(targets)
         except:
             content = error.wrap_exception()
             self.session.send(self.query, "hub_error", 
                     content=content, ident=client_id)
             return
         
         content = dict(status='ok')
         # loads = {}
         for t in targets:
             content[bytes(t)] = len(self.queues[t])+len(self.tasks[t])
         self.session.send(self.query, "load_reply", content=content, ident=client_id)
             
     
     def queue_status(self, client_id, msg):
         """Return the Queue status of one or more targets.
         if verbose: return the msg_ids
         else: return len of each type.
         keys: queue (pending MUX jobs)
             tasks (pending Task jobs)
             completed (finished jobs from both queues)"""
         content = msg['content']
         targets = content['targets']
         try:
             targets = self._validate_targets(targets)
         except:
             content = error.wrap_exception()
             self.session.send(self.query, "hub_error", 
                     content=content, ident=client_id)
             return
         verbose = content.get('verbose', False)
         content = dict(status='ok')
         for t in targets:
             queue = self.queues[t]
             completed = self.completed[t]
             tasks = self.tasks[t]
             if not verbose:
                 queue = len(queue)
                 completed = len(completed)
                 tasks = len(tasks)
             content[str(t)] = {'queue': queue, 'completed': completed , 'tasks': tasks}
         content['unassigned'] = list(self.unassigned) if verbose else len(self.unassigned)
         # print (content)
         self.session.send(self.query, "queue_reply", content=content, ident=client_id)
     
     def purge_results(self, client_id, msg):
         """Purge results from memory. This method is more valuable before we move
         to a DB based message storage mechanism."""
         content = msg['content']
         self.log.info("Dropping records with %s", content)
         msg_ids = content.get('msg_ids', [])
         reply = dict(status='ok')
         if msg_ids == 'all':
             try:
                 self.db.drop_matching_records(dict(completed={'$ne':None}))
             except Exception:
                 reply = error.wrap_exception()
         else:
             pending = filter(lambda m: m in self.pending, msg_ids)
             if pending:
                 try:
                     raise IndexError("msg pending: %r"%pending[0])
                 except:
                     reply = error.wrap_exception()
             else:
                 try:
                     self.db.drop_matching_records(dict(msg_id={'$in':msg_ids}))
                 except Exception:
                     reply = error.wrap_exception()
 
             if reply['status'] == 'ok':
                 eids = content.get('engine_ids', [])
                 for eid in eids:
                     if eid not in self.engines:
                         try:
                             raise IndexError("No such engine: %i"%eid)
                         except:
                             reply = error.wrap_exception()
                         break
                     uid = self.engines[eid].queue
                     try:
                         self.db.drop_matching_records(dict(engine_uuid=uid, completed={'$ne':None}))
                     except Exception:
                         reply = error.wrap_exception()
                         break
         
         self.session.send(self.query, 'purge_reply', content=reply, ident=client_id)
     
     def resubmit_task(self, client_id, msg):
         """Resubmit one or more tasks."""
         def finish(reply):
             self.session.send(self.query, 'resubmit_reply', content=reply, ident=client_id)
 
         content = msg['content']
         msg_ids = content['msg_ids']
         reply = dict(status='ok')
         try:
             records = self.db.find_records({'msg_id' : {'$in' : msg_ids}}, keys=[
                 'header', 'content', 'buffers'])
         except Exception:
             self.log.error('db::db error finding tasks to resubmit', exc_info=True)
             return finish(error.wrap_exception())
 
         # validate msg_ids
         found_ids = [ rec['msg_id'] for rec in records ]
         invalid_ids = filter(lambda m: m in self.pending, found_ids)
         if len(records) > len(msg_ids):
             try:
                 raise RuntimeError("DB appears to be in an inconsistent state."
                     "More matching records were found than should exist")
             except Exception:
                 return finish(error.wrap_exception())
         elif len(records) < len(msg_ids):
             missing = [ m for m in msg_ids if m not in found_ids ]
             try:
                 raise KeyError("No such msg(s): %r"%missing)
             except KeyError:
                 return finish(error.wrap_exception())
         elif invalid_ids:
             msg_id = invalid_ids[0]
             try:
                 raise ValueError("Task %r appears to be inflight"%(msg_id))
             except Exception:
                 return finish(error.wrap_exception())
 
         # clear the existing records
         now = datetime.now()
         rec = empty_record()
         map(rec.pop, ['msg_id', 'header', 'content', 'buffers', 'submitted'])
         rec['resubmitted'] = now
         rec['queue'] = 'task'
         rec['client_uuid'] = client_id[0]
         try:
             for msg_id in msg_ids:
                 self.all_completed.discard(msg_id)
                 self.db.update_record(msg_id, rec)
         except Exception:
             self.log.error('db::db error upating record', exc_info=True)
             reply = error.wrap_exception()
         else:
             # send the messages
             for rec in records:
                 header = rec['header']
                 # include resubmitted in header to prevent digest collision
                 header['resubmitted'] = now
                 msg = self.session.msg(header['msg_type'])
                 msg['content'] = rec['content']
                 msg['header'] = header
                 msg['msg_id'] = rec['msg_id']
                 self.session.send(self.resubmit, msg, buffers=rec['buffers'])
 
         finish(dict(status='ok'))
 
     
     def _extract_record(self, rec):
         """decompose a TaskRecord dict into subsection of reply for get_result"""
         io_dict = {}
         for key in 'pyin pyout pyerr stdout stderr'.split():
                 io_dict[key] = rec[key]
         content = { 'result_content': rec['result_content'],
                             'header': rec['header'],
                             'result_header' : rec['result_header'],
                             'io' : io_dict,
                           }
         if rec['result_buffers']:
             buffers = map(bytes, rec['result_buffers'])
         else:
             buffers = []
         
         return content, buffers
     
     def get_results(self, client_id, msg):
         """Get the result of 1 or more messages."""
         content = msg['content']
         msg_ids = sorted(set(content['msg_ids']))
         statusonly = content.get('status_only', False)
         pending = []
         completed = []
         content = dict(status='ok')
         content['pending'] = pending
         content['completed'] = completed
         buffers = []
         if not statusonly:
             try:
                 matches = self.db.find_records(dict(msg_id={'$in':msg_ids}))
                 # turn match list into dict, for faster lookup
                 records = {}
                 for rec in matches:
                     records[rec['msg_id']] = rec
             except Exception:
                 content = error.wrap_exception()
                 self.session.send(self.query, "result_reply", content=content, 
                                                     parent=msg, ident=client_id)
                 return
         else:
             records = {}
         for msg_id in msg_ids:
             if msg_id in self.pending:
                 pending.append(msg_id)
             elif msg_id in self.all_completed:
                 completed.append(msg_id)
                 if not statusonly:
                     c,bufs = self._extract_record(records[msg_id])
                     content[msg_id] = c
                     buffers.extend(bufs)
             elif msg_id in records:
                 if rec['completed']:
                     completed.append(msg_id)
                     c,bufs = self._extract_record(records[msg_id])
                     content[msg_id] = c
                     buffers.extend(bufs)
                 else:
                     pending.append(msg_id)
             else:
                 try:
                     raise KeyError('No such message: '+msg_id)
                 except:
                     content = error.wrap_exception()
                 break
         self.session.send(self.query, "result_reply", content=content, 
                                             parent=msg, ident=client_id,
                                             buffers=buffers)
 
     def get_history(self, client_id, msg):
         """Get a list of all msg_ids in our DB records"""
         try:
             msg_ids = self.db.get_history()
         except Exception as e:
             content = error.wrap_exception()
         else:
             content = dict(status='ok', history=msg_ids)
         
         self.session.send(self.query, "history_reply", content=content, 
                                             parent=msg, ident=client_id)
 
     def db_query(self, client_id, msg):
         """Perform a raw query on the task record database."""
         content = msg['content']
         query = content.get('query', {})
         keys = content.get('keys', None)
         buffers = []
         empty = list()
         try:
             records = self.db.find_records(query, keys)
         except Exception as e:
             content = error.wrap_exception()
         else:
             # extract buffers from reply content:
             if keys is not None:
                 buffer_lens = [] if 'buffers' in keys else None
                 result_buffer_lens = [] if 'result_buffers' in keys else None
             else:
                 buffer_lens = []
                 result_buffer_lens = []
             
             for rec in records:
                 # buffers may be None, so double check
                 if buffer_lens is not None:
                     b = rec.pop('buffers', empty) or empty
                     buffer_lens.append(len(b))
                     buffers.extend(b)
                 if result_buffer_lens is not None:
                     rb = rec.pop('result_buffers', empty) or empty
                     result_buffer_lens.append(len(rb))
                     buffers.extend(rb)
             content = dict(status='ok', records=records, buffer_lens=buffer_lens,
                                     result_buffer_lens=result_buffer_lens)
         # self.log.debug (content)
         self.session.send(self.query, "db_reply", content=content, 
                                             parent=msg, ident=client_id,
                                             buffers=buffers)
 

IPython/parallel/engine/engine.py

@@ -1,174 +1,173 b''
-#!/usr/bin/env python
 """A simple engine that talks to a controller over 0MQ.
 it handles registration, etc. and launches a kernel
 connected to the Controller's Schedulers.
 
 Authors:
 
 * Min RK
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 from __future__ import print_function
 
 import sys
 import time
 
 import zmq
 from zmq.eventloop import ioloop, zmqstream
 
 # internal
 from IPython.utils.traitlets import Instance, Dict, Int, Type, CFloat, Unicode, CBytes
 # from IPython.utils.localinterfaces import LOCALHOST 
 
 from IPython.parallel.controller.heartmonitor import Heart
 from IPython.parallel.factory import RegistrationFactory
 from IPython.parallel.util import disambiguate_url, asbytes
 
 from IPython.zmq.session import Message
 
 from .streamkernel import Kernel
 
 class EngineFactory(RegistrationFactory):
     """IPython engine"""
     
     # configurables:
     out_stream_factory=Type('IPython.zmq.iostream.OutStream', config=True,
         help="""The OutStream for handling stdout/err.
         Typically 'IPython.zmq.iostream.OutStream'""")
     display_hook_factory=Type('IPython.zmq.displayhook.ZMQDisplayHook', config=True,
         help="""The class for handling displayhook.
         Typically 'IPython.zmq.displayhook.ZMQDisplayHook'""")
     location=Unicode(config=True,
         help="""The location (an IP address) of the controller.  This is
         used for disambiguating URLs, to determine whether
         loopback should be used to connect or the public address.""")
     timeout=CFloat(2,config=True,
         help="""The time (in seconds) to wait for the Controller to respond
         to registration requests before giving up.""")
     
     # not configurable:
     user_ns=Dict()
     id=Int(allow_none=True)
     registrar=Instance('zmq.eventloop.zmqstream.ZMQStream')
     kernel=Instance(Kernel)
     
     bident = CBytes()
     ident = Unicode()
     def _ident_changed(self, name, old, new):
         self.bident = asbytes(new)
     
     
     def __init__(self, **kwargs):
         super(EngineFactory, self).__init__(**kwargs)
         self.ident = self.session.session
         ctx = self.context
         
         reg = ctx.socket(zmq.XREQ)
         reg.setsockopt(zmq.IDENTITY, self.bident)
         reg.connect(self.url)
         self.registrar = zmqstream.ZMQStream(reg, self.loop)
         
     def register(self):
         """send the registration_request"""
         
         self.log.info("Registering with controller at %s"%self.url)
         content = dict(queue=self.ident, heartbeat=self.ident, control=self.ident)
         self.registrar.on_recv(self.complete_registration)
         # print (self.session.key)
         self.session.send(self.registrar, "registration_request",content=content)
     
     def complete_registration(self, msg):
         # print msg
         self._abort_dc.stop()
         ctx = self.context
         loop = self.loop
         identity = self.bident
         idents,msg = self.session.feed_identities(msg)
         msg = Message(self.session.unpack_message(msg))
         
         if msg.content.status == 'ok':
             self.id = int(msg.content.id)
             
             # create Shell Streams (MUX, Task, etc.):
             queue_addr = msg.content.mux
             shell_addrs = [ str(queue_addr) ]
             task_addr = msg.content.task
             if task_addr:
                 shell_addrs.append(str(task_addr))
             
             # Uncomment this to go back to two-socket model
             # shell_streams = []
             # for addr in shell_addrs:
             #     stream = zmqstream.ZMQStream(ctx.socket(zmq.XREP), loop)
             #     stream.setsockopt(zmq.IDENTITY, identity)
             #     stream.connect(disambiguate_url(addr, self.location))
             #     shell_streams.append(stream)
             
             # Now use only one shell stream for mux and tasks
             stream = zmqstream.ZMQStream(ctx.socket(zmq.XREP), loop)
             stream.setsockopt(zmq.IDENTITY, identity)
             shell_streams = [stream]
             for addr in shell_addrs:
                 stream.connect(disambiguate_url(addr, self.location))
             # end single stream-socket
             
             # control stream:
             control_addr = str(msg.content.control)
             control_stream = zmqstream.ZMQStream(ctx.socket(zmq.XREP), loop)
             control_stream.setsockopt(zmq.IDENTITY, identity)
             control_stream.connect(disambiguate_url(control_addr, self.location))
             
             # create iopub stream:
             iopub_addr = msg.content.iopub
             iopub_stream = zmqstream.ZMQStream(ctx.socket(zmq.PUB), loop)
             iopub_stream.setsockopt(zmq.IDENTITY, identity)
             iopub_stream.connect(disambiguate_url(iopub_addr, self.location))
             
             # launch heartbeat
             hb_addrs = msg.content.heartbeat
             # print (hb_addrs)
             
             # # Redirect input streams and set a display hook.
             if self.out_stream_factory:
                 sys.stdout = self.out_stream_factory(self.session, iopub_stream, u'stdout')
                 sys.stdout.topic = 'engine.%i.stdout'%self.id
                 sys.stderr = self.out_stream_factory(self.session, iopub_stream, u'stderr')
                 sys.stderr.topic = 'engine.%i.stderr'%self.id
             if self.display_hook_factory:
                 sys.displayhook = self.display_hook_factory(self.session, iopub_stream)
                 sys.displayhook.topic = 'engine.%i.pyout'%self.id
 
             self.kernel = Kernel(config=self.config, int_id=self.id, ident=self.ident, session=self.session, 
                     control_stream=control_stream, shell_streams=shell_streams, iopub_stream=iopub_stream, 
                     loop=loop, user_ns = self.user_ns, log=self.log)
             self.kernel.start()
             hb_addrs = [ disambiguate_url(addr, self.location) for addr in hb_addrs ]
             heart = Heart(*map(str, hb_addrs), heart_id=identity)
             heart.start()
             
             
         else:
             self.log.fatal("Registration Failed: %s"%msg)
             raise Exception("Registration Failed: %s"%msg)
         
         self.log.info("Completed registration with id %i"%self.id)
     
     
     def abort(self):
         self.log.fatal("Registration timed out after %.1f seconds"%self.timeout)
         self.session.send(self.registrar, "unregistration_request", content=dict(id=self.id))
         time.sleep(1)
         sys.exit(255)
     
     def start(self):
         dc = ioloop.DelayedCallback(self.register, 0, self.loop)
         dc.start()
         self._abort_dc = ioloop.DelayedCallback(self.abort, self.timeout*1000, self.loop)
         self._abort_dc.start()
 

IPython/parallel/engine/streamkernel.py

@@ -1,438 +1,437 b''
-#!/usr/bin/env python
 """
 Kernel adapted from kernel.py to use ZMQ Streams
 
 Authors:
 
 * Min RK
 * Brian Granger
 * Fernando Perez
 * Evan Patterson
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Standard library imports.
 from __future__ import print_function
 
 import sys
 import time
 
 from code import CommandCompiler
 from datetime import datetime
 from pprint import pprint
 
 # System library imports.
 import zmq
 from zmq.eventloop import ioloop, zmqstream
 
 # Local imports.
 from IPython.utils.traitlets import Instance, List, Int, Dict, Set, Unicode, CBytes
 from IPython.zmq.completer import KernelCompleter
 
 from IPython.parallel.error import wrap_exception
 from IPython.parallel.factory import SessionFactory
 from IPython.parallel.util import serialize_object, unpack_apply_message, asbytes
 
 def printer(*args):
     pprint(args, stream=sys.__stdout__)
 
 
 class _Passer(zmqstream.ZMQStream):
     """Empty class that implements `send()` that does nothing.
     
     Subclass ZMQStream for Session typechecking
     
     """
     def __init__(self, *args, **kwargs):
         pass
     
     def send(self, *args, **kwargs):
         pass
     send_multipart = send
     
 
 #-----------------------------------------------------------------------------
 # Main kernel class
 #-----------------------------------------------------------------------------
 
 class Kernel(SessionFactory):
 
     #---------------------------------------------------------------------------
     # Kernel interface
     #---------------------------------------------------------------------------
     
     # kwargs:
     exec_lines = List(Unicode, config=True,
         help="List of lines to execute")
     
     # identities:
     int_id = Int(-1)
     bident = CBytes()
     ident = Unicode()
     def _ident_changed(self, name, old, new):
         self.bident = asbytes(new)
     
     user_ns = Dict(config=True,  help="""Set the user's namespace of the Kernel""")
     
     control_stream = Instance(zmqstream.ZMQStream)
     task_stream = Instance(zmqstream.ZMQStream)
     iopub_stream = Instance(zmqstream.ZMQStream)
     client = Instance('IPython.parallel.Client')
     
     # internals
     shell_streams = List()
     compiler = Instance(CommandCompiler, (), {})
     completer = Instance(KernelCompleter)
     
     aborted = Set()
     shell_handlers = Dict()
     control_handlers = Dict()
     
     def _set_prefix(self):
         self.prefix = "engine.%s"%self.int_id
     
     def _connect_completer(self):
         self.completer = KernelCompleter(self.user_ns)
     
     def __init__(self, **kwargs):
         super(Kernel, self).__init__(**kwargs)
         self._set_prefix()
         self._connect_completer()
         
         self.on_trait_change(self._set_prefix, 'id')
         self.on_trait_change(self._connect_completer, 'user_ns')
         
         # Build dict of handlers for message types
         for msg_type in ['execute_request', 'complete_request', 'apply_request', 
                 'clear_request']:
             self.shell_handlers[msg_type] = getattr(self, msg_type)
         
         for msg_type in ['shutdown_request', 'abort_request']+self.shell_handlers.keys():
             self.control_handlers[msg_type] = getattr(self, msg_type)
         
         self._initial_exec_lines()
     
     def _wrap_exception(self, method=None):
         e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method=method)
         content=wrap_exception(e_info)
         return content
     
     def _initial_exec_lines(self):
         s = _Passer()
         content = dict(silent=True, user_variable=[],user_expressions=[])
         for line in self.exec_lines:
             self.log.debug("executing initialization: %s"%line)
             content.update({'code':line})
             msg = self.session.msg('execute_request', content)
             self.execute_request(s, [], msg)
         
         
     #-------------------- control handlers -----------------------------
     def abort_queues(self):
         for stream in self.shell_streams:
             if stream:
                 self.abort_queue(stream)
     
     def abort_queue(self, stream):
         while True:
             idents,msg = self.session.recv(stream, zmq.NOBLOCK, content=True)
             if msg is None:
                 return
                 
             self.log.info("Aborting:")
             self.log.info(str(msg))
             msg_type = msg['msg_type']
             reply_type = msg_type.split('_')[0] + '_reply'
             # reply_msg = self.session.msg(reply_type, {'status' : 'aborted'}, msg)
             # self.reply_socket.send(ident,zmq.SNDMORE)
             # self.reply_socket.send_json(reply_msg)
             reply_msg = self.session.send(stream, reply_type, 
                         content={'status' : 'aborted'}, parent=msg, ident=idents)
             self.log.debug(str(reply_msg))
             # We need to wait a bit for requests to come in. This can probably
             # be set shorter for true asynchronous clients.
             time.sleep(0.05)
     
     def abort_request(self, stream, ident, parent):
         """abort a specifig msg by id"""
         msg_ids = parent['content'].get('msg_ids', None)
         if isinstance(msg_ids, basestring):
             msg_ids = [msg_ids]
         if not msg_ids:
             self.abort_queues()
         for mid in msg_ids:
             self.aborted.add(str(mid))
         
         content = dict(status='ok')
         reply_msg = self.session.send(stream, 'abort_reply', content=content, 
                 parent=parent, ident=ident)
         self.log.debug(str(reply_msg))
     
     def shutdown_request(self, stream, ident, parent):
         """kill ourself.  This should really be handled in an external process"""
         try:
             self.abort_queues()
         except:
             content = self._wrap_exception('shutdown')
         else:
             content = dict(parent['content'])
             content['status'] = 'ok'
         msg = self.session.send(stream, 'shutdown_reply',
                                 content=content, parent=parent, ident=ident)
         self.log.debug(str(msg))
         dc = ioloop.DelayedCallback(lambda : sys.exit(0), 1000, self.loop)
         dc.start()
     
     def dispatch_control(self, msg):
         idents,msg = self.session.feed_identities(msg, copy=False)
         try:
             msg = self.session.unpack_message(msg, content=True, copy=False)
         except:
             self.log.error("Invalid Message", exc_info=True)
             return
         else:
             self.log.debug("Control received, %s", msg)
         
         header = msg['header']
         msg_id = header['msg_id']
         
         handler = self.control_handlers.get(msg['msg_type'], None)
         if handler is None:
             self.log.error("UNKNOWN CONTROL MESSAGE TYPE: %r"%msg['msg_type'])
         else:
             handler(self.control_stream, idents, msg)
     
 
     #-------------------- queue helpers ------------------------------
     
     def check_dependencies(self, dependencies):
         if not dependencies:
             return True
         if len(dependencies) == 2 and dependencies[0] in 'any all'.split():
             anyorall = dependencies[0]
             dependencies = dependencies[1]
         else:
             anyorall = 'all'
         results = self.client.get_results(dependencies,status_only=True)
         if results['status'] != 'ok':
             return False
         
         if anyorall == 'any':
             if not results['completed']:
                 return False
         else:
             if results['pending']:
                 return False
         
         return True
     
     def check_aborted(self, msg_id):
         return msg_id in self.aborted
     
     #-------------------- queue handlers -----------------------------
     
     def clear_request(self, stream, idents, parent):
         """Clear our namespace."""
         self.user_ns = {}
         msg = self.session.send(stream, 'clear_reply', ident=idents, parent=parent, 
                 content = dict(status='ok'))
         self._initial_exec_lines()
     
     def execute_request(self, stream, ident, parent):
         self.log.debug('execute request %s'%parent)
         try:
             code = parent[u'content'][u'code']
         except:
             self.log.error("Got bad msg: %s"%parent, exc_info=True)
             return
         self.session.send(self.iopub_stream, u'pyin', {u'code':code},parent=parent,
                             ident=asbytes('%s.pyin'%self.prefix))
         started = datetime.now()
         try:
             comp_code = self.compiler(code, '<zmq-kernel>')
             # allow for not overriding displayhook
             if hasattr(sys.displayhook, 'set_parent'):
                 sys.displayhook.set_parent(parent)
                 sys.stdout.set_parent(parent)
                 sys.stderr.set_parent(parent)
             exec comp_code in self.user_ns, self.user_ns
         except:
             exc_content = self._wrap_exception('execute')
             # exc_msg = self.session.msg(u'pyerr', exc_content, parent)
             self.session.send(self.iopub_stream, u'pyerr', exc_content, parent=parent,
                             ident=asbytes('%s.pyerr'%self.prefix))
             reply_content = exc_content
         else:
             reply_content = {'status' : 'ok'}
         
         reply_msg = self.session.send(stream, u'execute_reply', reply_content, parent=parent, 
                     ident=ident, subheader = dict(started=started))
         self.log.debug(str(reply_msg))
         if reply_msg['content']['status'] == u'error':
             self.abort_queues()
 
     def complete_request(self, stream, ident, parent):
         matches = {'matches' : self.complete(parent),
                    'status' : 'ok'}
         completion_msg = self.session.send(stream, 'complete_reply',
                                            matches, parent, ident)
         # print >> sys.__stdout__, completion_msg
 
     def complete(self, msg):
         return self.completer.complete(msg.content.line, msg.content.text)
     
     def apply_request(self, stream, ident, parent):
         # flush previous reply, so this request won't block it
         stream.flush(zmq.POLLOUT)
         try:
             content = parent[u'content']
             bufs = parent[u'buffers']
             msg_id = parent['header']['msg_id']
             # bound = parent['header'].get('bound', False)
         except:
             self.log.error("Got bad msg: %s"%parent, exc_info=True)
             return
         # pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
         # self.iopub_stream.send(pyin_msg)
         # self.session.send(self.iopub_stream, u'pyin', {u'code':code},parent=parent)
         sub = {'dependencies_met' : True, 'engine' : self.ident,
                 'started': datetime.now()}
         try:
             # allow for not overriding displayhook
             if hasattr(sys.displayhook, 'set_parent'):
                 sys.displayhook.set_parent(parent)
                 sys.stdout.set_parent(parent)
                 sys.stderr.set_parent(parent)
             # exec "f(*args,**kwargs)" in self.user_ns, self.user_ns
             working = self.user_ns
             # suffix = 
             prefix = "_"+str(msg_id).replace("-","")+"_"
             
             f,args,kwargs = unpack_apply_message(bufs, working, copy=False)
             # if bound:
             #     bound_ns = Namespace(working)
             #     args = [bound_ns]+list(args)
 
             fname = getattr(f, '__name__', 'f')
             
             fname = prefix+"f"
             argname = prefix+"args"
             kwargname = prefix+"kwargs"
             resultname = prefix+"result"
             
             ns = { fname : f, argname : args, kwargname : kwargs , resultname : None }
             # print ns
             working.update(ns)
             code = "%s=%s(*%s,**%s)"%(resultname, fname, argname, kwargname)
             try:
                 exec code in working,working
                 result = working.get(resultname)
             finally:
                 for key in ns.iterkeys():
                     working.pop(key)
             # if bound:
             #     working.update(bound_ns)
             
             packed_result,buf = serialize_object(result)
             result_buf = [packed_result]+buf
         except:
             exc_content = self._wrap_exception('apply')
             # exc_msg = self.session.msg(u'pyerr', exc_content, parent)
             self.session.send(self.iopub_stream, u'pyerr', exc_content, parent=parent,
                                 ident=asbytes('%s.pyerr'%self.prefix))
             reply_content = exc_content
             result_buf = []
             
             if exc_content['ename'] == 'UnmetDependency':
                 sub['dependencies_met'] = False
         else:
             reply_content = {'status' : 'ok'}
         
         # put 'ok'/'error' status in header, for scheduler introspection:
         sub['status'] = reply_content['status']
         
         reply_msg = self.session.send(stream, u'apply_reply', reply_content, 
                     parent=parent, ident=ident,buffers=result_buf, subheader=sub)
         
         # flush i/o
         # should this be before reply_msg is sent, like in the single-kernel code, 
         # or should nothing get in the way of real results?
         sys.stdout.flush()
         sys.stderr.flush()
     
     def dispatch_queue(self, stream, msg):
         self.control_stream.flush()
         idents,msg = self.session.feed_identities(msg, copy=False)
         try:
             msg = self.session.unpack_message(msg, content=True, copy=False)
         except:
             self.log.error("Invalid Message", exc_info=True)
             return
         else:
             self.log.debug("Message received, %s", msg)
             
         
         header = msg['header']
         msg_id = header['msg_id']
         if self.check_aborted(msg_id):
             self.aborted.remove(msg_id)
             # is it safe to assume a msg_id will not be resubmitted?
             reply_type = msg['msg_type'].split('_')[0] + '_reply'
             status = {'status' : 'aborted'}
             reply_msg = self.session.send(stream, reply_type, subheader=status,
                         content=status, parent=msg, ident=idents)
             return
         handler = self.shell_handlers.get(msg['msg_type'], None)
         if handler is None:
             self.log.error("UNKNOWN MESSAGE TYPE: %r"%msg['msg_type'])
         else:
             handler(stream, idents, msg)
     
     def start(self):
         #### stream mode:
         if self.control_stream:
             self.control_stream.on_recv(self.dispatch_control, copy=False)
             self.control_stream.on_err(printer)
         
         def make_dispatcher(stream):
             def dispatcher(msg):
                 return self.dispatch_queue(stream, msg)
             return dispatcher
         
         for s in self.shell_streams:
             s.on_recv(make_dispatcher(s), copy=False)
             s.on_err(printer)
         
         if self.iopub_stream:
             self.iopub_stream.on_err(printer)
         
         #### while True mode:
         # while True:
         #     idle = True
         #     try:
         #         msg = self.shell_stream.socket.recv_multipart(
         #                     zmq.NOBLOCK, copy=False)
         #     except zmq.ZMQError, e:
         #         if e.errno != zmq.EAGAIN:
         #             raise e
         #     else:
         #         idle=False
         #         self.dispatch_queue(self.shell_stream, msg)
         #             
         #     if not self.task_stream.empty():
         #         idle=False
         #         msg = self.task_stream.recv_multipart()
         #         self.dispatch_queue(self.task_stream, msg)
         #     if idle:
         #         # don't busywait
         #         time.sleep(1e-3)
 

IPython/quarantine/ipy_gnuglobal.py

@@ -1,38 +1,35 b''
-#!/usr/bin/env python
-
-
 """
 Add %global magic for GNU Global usage.
 
 http://www.gnu.org/software/global/
 
 """
 
 from IPython.core import ipapi
 ip = ipapi.get()
 import os
 
 # alter to your liking
 global_bin = 'd:/opt/global/bin/global'
 
 def global_f(self,cmdline):
     simple = 0
     if '-' not in cmdline:
         cmdline  = '-rx ' + cmdline
         simple = 1
         
     lines = [l.rstrip() for l in os.popen( global_bin + ' ' + cmdline ).readlines()]
     
     if simple:
         parts = [l.split(None,3) for l in lines]
         lines = ['%s [%s]\n%s' % (p[2].rjust(70),p[1],p[3].rstrip()) for p in parts]
     print "\n".join(lines)
 
 ip.define_magic('global', global_f)
 
 def global_completer(self,event):
     compl = [l.rstrip() for l in os.popen(global_bin + ' -c ' + event.symbol).readlines()]
     return compl    
 
 ip.set_hook('complete_command', global_completer, str_key = '%global')
 

IPython/quarantine/ipy_render.py

@@ -1,68 +1,65 b''
-#!/usr/bin/env python
-
 """ IPython extension: Render templates from variables and paste to clipbard """
 
 from IPython.core import ipapi
 
 ip = ipapi.get()
 
 from string import Template
 import sys,os
 
 from IPython.external.Itpl import itplns
 
 def toclip_w32(s):
     """ Places contents of s to clipboard
     
     Needs pyvin32 to work:
     http://sourceforge.net/projects/pywin32/
     """
     import win32clipboard as cl
     import win32con
     cl.OpenClipboard()
     cl.EmptyClipboard()
     cl.SetClipboardText( s.replace('\n','\r\n' ))
     cl.CloseClipboard()
 
 try:
     import win32clipboard    
     toclip = toclip_w32
 except ImportError:
     def toclip(s): pass
     
 
 def render(tmpl):
     """ Render a template (Itpl format) from ipython variables
 
     Example:
     
     $ import ipy_render
     $ my_name = 'Bob'  # %store this for convenience
     $ t_submission_form = "Submission report, author: $my_name"  # %store also
     $ render t_submission_form
     
     => returns "Submission report, author: Bob" and copies to clipboard on win32
 
     # if template exist as a file, read it. Note: ;f hei vaan => f("hei vaan")
     $ ;render c:/templates/greeting.txt  
     
     Template examples (Ka-Ping Yee's Itpl library):
     
     Here is a $string.
     Here is a $module.member.
     Here is an $object.member.
     Here is a $functioncall(with, arguments).
     Here is an ${arbitrary + expression}.
     Here is an $array[3] member.
     Here is a $dictionary['member'].
     """
     
     if os.path.isfile(tmpl):
         tmpl = open(tmpl).read()
         
     res = itplns(tmpl, ip.user_ns)
     toclip(res)
     return res
 
 ip.push('render')
-    
  No newline at end of file

IPython/quarantine/ipy_workdir.py

@@ -1,43 +1,41 b''
-#!/usr/bin/env python
-
 from IPython.core import ipapi
 ip = ipapi.get()
 
 import os, subprocess
 
 workdir = None
 def workdir_f(ip,line):
     """ Exceute commands residing in cwd elsewhere 
     
     Example::
       
       workdir /myfiles
       cd bin
       workdir myscript.py 
       
     executes myscript.py (stored in bin, but not in path) in /myfiles
     """
     global workdir
     dummy,cmd  = line.split(None,1)
     if os.path.isdir(cmd):
         workdir = os.path.abspath(cmd)
         print "Set workdir",workdir
     elif workdir is None:
         print "Please set workdir first by doing e.g. 'workdir q:/'"
     else:
         sp = cmd.split(None,1)
         if len(sp) == 1:
             head, tail = cmd, ''
         else:
             head, tail = sp
         if os.path.isfile(head):
             cmd = os.path.abspath(head) + ' ' + tail
         print "Execute command '" + cmd+ "' in",workdir
         olddir = os.getcwdu()
         os.chdir(workdir)
         try:
             os.system(cmd)
         finally:
             os.chdir(olddir)
 
 ip.define_alias("workdir",workdir_f)

IPython/testing/tests/test_tools.py

@@ -1,74 +1,73 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Tests for testing.tools
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import with_statement
 
 import os
 import sys
 
 import nose.tools as nt
 
 from IPython.testing import decorators as dec
 from IPython.testing import tools as tt
 
 #-----------------------------------------------------------------------------
 # Tests
 #-----------------------------------------------------------------------------
 
 @dec.skip_win32
 def test_full_path_posix():
     spath = '/foo/bar.py'
     result = tt.full_path(spath,['a.txt','b.txt'])
     nt.assert_equal(result, ['/foo/a.txt', '/foo/b.txt'])
     spath = '/foo'
     result = tt.full_path(spath,['a.txt','b.txt'])
     nt.assert_equal(result, ['/a.txt', '/b.txt'])
     result = tt.full_path(spath,'a.txt')
     nt.assert_equal(result, ['/a.txt'])
 
 
 @dec.skip_if_not_win32
 def test_full_path_win32():
     spath = 'c:\\foo\\bar.py'
     result = tt.full_path(spath,['a.txt','b.txt'])
     nt.assert_equal(result, ['c:\\foo\\a.txt', 'c:\\foo\\b.txt'])
     spath = 'c:\\foo'
     result = tt.full_path(spath,['a.txt','b.txt'])
     nt.assert_equal(result, ['c:\\a.txt', 'c:\\b.txt'])
     result = tt.full_path(spath,'a.txt')
     nt.assert_equal(result, ['c:\\a.txt'])
 
     
 @dec.parametric
 def test_parser():
     err = ("FAILED (errors=1)", 1, 0)
     fail = ("FAILED (failures=1)", 0, 1)
     both = ("FAILED (errors=1, failures=1)", 1, 1)
     for txt, nerr, nfail in [err, fail, both]:
         nerr1, nfail1 = tt.parse_test_output(txt)
         yield nt.assert_equal(nerr, nerr1)
         yield nt.assert_equal(nfail, nfail1)
 
         
 @dec.parametric
 def test_temp_pyfile():
     src = 'pass\n'
     fname, fh = tt.temp_pyfile(src)
     yield nt.assert_true(os.path.isfile(fname))
     fh.close()
     with open(fname) as fh2:
         src2 = fh2.read()
     yield nt.assert_equal(src2, src)

IPython/utils/ipstruct.py

@@ -1,396 +1,395 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """A dict subclass that supports attribute style access.
 
 Authors:  
 
 * Fernando Perez (original)
 * Brian Granger (refactoring to a dict subclass)
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from IPython.utils.data import list2dict2
 
 __all__ = ['Struct']
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 
 class Struct(dict):
     """A dict subclass with attribute style access.
 
     This dict subclass has a a few extra features:
 
     * Attribute style access.
     * Protection of class members (like keys, items) when using attribute
       style access.
     * The ability to restrict assignment to only existing keys.
     * Intelligent merging.
     * Overloaded operators.
     """
     _allownew = True
     def __init__(self, *args, **kw):
         """Initialize with a dictionary, another Struct, or data.
 
         Parameters
         ----------
         args : dict, Struct
             Initialize with one dict or Struct
         kw : dict
             Initialize with key, value pairs.
 
         Examples
         --------
 
         >>> s = Struct(a=10,b=30)
         >>> s.a
         10
         >>> s.b
         30
         >>> s2 = Struct(s,c=30)
         >>> s2.keys()
         ['a', 'c', 'b']
         """
         object.__setattr__(self, '_allownew', True)
         dict.__init__(self, *args, **kw)
 
     def __setitem__(self, key, value):
         """Set an item with check for allownew.
 
         Examples
         --------
 
         >>> s = Struct()
         >>> s['a'] = 10
         >>> s.allow_new_attr(False)
         >>> s['a'] = 10
         >>> s['a']
         10
         >>> try:
         ...     s['b'] = 20
         ... except KeyError:
         ...     print 'this is not allowed'
         ...     
         this is not allowed
         """
         if not self._allownew and not self.has_key(key):
             raise KeyError(
                 "can't create new attribute %s when allow_new_attr(False)" % key)
         dict.__setitem__(self, key, value)
 
     def __setattr__(self, key, value):
         """Set an attr with protection of class members.
 
         This calls :meth:`self.__setitem__` but convert :exc:`KeyError` to 
         :exc:`AttributeError`.
 
         Examples
         --------
 
         >>> s = Struct()
         >>> s.a = 10
         >>> s.a
         10
         >>> try:
         ...     s.get = 10
         ... except AttributeError:
         ...     print "you can't set a class member"
         ...     
         you can't set a class member
         """
         # If key is an str it might be a class member or instance var
         if isinstance(key, str):
             # I can't simply call hasattr here because it calls getattr, which
             # calls self.__getattr__, which returns True for keys in 
             # self._data.  But I only want keys in the class and in
             # self.__dict__
             if key in self.__dict__ or hasattr(Struct, key):
                 raise AttributeError(
                     'attr %s is a protected member of class Struct.' % key
                 )
         try:
             self.__setitem__(key, value)
         except KeyError, e:
             raise AttributeError(e)
 
     def __getattr__(self, key):
         """Get an attr by calling :meth:`dict.__getitem__`.
 
         Like :meth:`__setattr__`, this method converts :exc:`KeyError` to 
         :exc:`AttributeError`.
 
         Examples
         --------
 
         >>> s = Struct(a=10)
         >>> s.a
         10
         >>> type(s.get)
         <type 'builtin_function_or_method'>
         >>> try:
         ...     s.b
         ... except AttributeError:
         ...     print "I don't have that key"
         ...     
         I don't have that key
         """
         try:
             result = self[key]
         except KeyError:
             raise AttributeError(key)
         else:
             return result
 
     def __iadd__(self, other):
         """s += s2 is a shorthand for s.merge(s2).
         
         Examples
         --------
         
         >>> s = Struct(a=10,b=30)
         >>> s2 = Struct(a=20,c=40)
         >>> s += s2
         >>> s
         {'a': 10, 'c': 40, 'b': 30}
         """
         self.merge(other)
         return self
 
     def __add__(self,other):
         """s + s2 -> New Struct made from s.merge(s2).
         
         Examples
         --------
         
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=20,c=40)
         >>> s = s1 + s2
         >>> s
         {'a': 10, 'c': 40, 'b': 30}
         """
         sout = self.copy()
         sout.merge(other)
         return sout
 
     def __sub__(self,other):
         """s1 - s2 -> remove keys in s2 from s1.
         
         Examples
         --------
         
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=40)
         >>> s = s1 - s2
         >>> s
         {'b': 30}
         """
         sout = self.copy()
         sout -= other
         return sout
 
     def __isub__(self,other):
         """Inplace remove keys from self that are in other.
         
         Examples
         --------
         
         >>> s1 = Struct(a=10,b=30)
         >>> s2 = Struct(a=40)
         >>> s1 -= s2
         >>> s1
         {'b': 30}
         """
         for k in other.keys():
             if self.has_key(k):
                 del self[k]
         return self
 
     def __dict_invert(self, data):
         """Helper function for merge. 
 
         Takes a dictionary whose values are lists and returns a dict with 
         the elements of each list as keys and the original keys as values.
         """
         outdict = {}
         for k,lst in data.items():
             if isinstance(lst, str):
                 lst = lst.split()
             for entry in lst:
                 outdict[entry] = k
         return outdict
 
     def dict(self):
         return self
 
     def copy(self):
         """Return a copy as a Struct.
         
         Examples
         --------
         
         >>> s = Struct(a=10,b=30)
         >>> s2 = s.copy()
         >>> s2
         {'a': 10, 'b': 30}
         >>> type(s2).__name__
         'Struct'
         """
         return Struct(dict.copy(self))
 
     def hasattr(self, key):
         """hasattr function available as a method.
 
         Implemented like has_key.
 
         Examples
         --------
 
         >>> s = Struct(a=10)
         >>> s.hasattr('a')
         True
         >>> s.hasattr('b')
         False
         >>> s.hasattr('get')
         False
         """
         return self.has_key(key)
 
     def allow_new_attr(self, allow = True):
         """Set whether new attributes can be created in this Struct.
 
         This can be used to catch typos by verifying that the attribute user
         tries to change already exists in this Struct.
         """
         object.__setattr__(self, '_allownew', allow)
 
     def merge(self, __loc_data__=None, __conflict_solve=None, **kw):
         """Merge two Structs with customizable conflict resolution.
 
         This is similar to :meth:`update`, but much more flexible. First, a
         dict is made from data+key=value pairs. When merging this dict with
         the Struct S, the optional dictionary 'conflict' is used to decide
         what to do.
 
         If conflict is not given, the default behavior is to preserve any keys
         with their current value (the opposite of the :meth:`update` method's
         behavior).
 
         Parameters
         ----------
         __loc_data : dict, Struct
             The data to merge into self
         __conflict_solve : dict
             The conflict policy dict.  The keys are binary functions used to
             resolve the conflict and the values are lists of strings naming
             the keys the conflict resolution function applies to.  Instead of
             a list of strings a space separated string can be used, like
             'a b c'.
         kw : dict
             Additional key, value pairs to merge in
 
         Notes
         -----
 
         The `__conflict_solve` dict is a dictionary of binary functions which will be used to
         solve key conflicts.  Here is an example::
         
             __conflict_solve = dict(
                 func1=['a','b','c'],
                 func2=['d','e']
             )
         
         In this case, the function :func:`func1` will be used to resolve
         keys 'a', 'b' and 'c' and the function :func:`func2` will be used for 
         keys 'd' and 'e'.  This could also be written as::
 
             __conflict_solve = dict(func1='a b c',func2='d e')
 
         These functions will be called for each key they apply to with the
         form::
 
             func1(self['a'], other['a'])
 
         The return value is used as the final merged value.
 
         As a convenience, merge() provides five (the most commonly needed)
         pre-defined policies: preserve, update, add, add_flip and add_s. The
         easiest explanation is their implementation::
 
             preserve = lambda old,new: old
             update   = lambda old,new: new
             add      = lambda old,new: old + new
             add_flip = lambda old,new: new + old  # note change of order!
             add_s    = lambda old,new: old + ' ' + new  # only for str!
 
         You can use those four words (as strings) as keys instead
         of defining them as functions, and the merge method will substitute
         the appropriate functions for you.
 
         For more complicated conflict resolution policies, you still need to
         construct your own functions.
 
         Examples
         --------
 
         This show the default policy:
         
         >>> s = Struct(a=10,b=30)
         >>> s2 = Struct(a=20,c=40)
         >>> s.merge(s2)
         >>> s
         {'a': 10, 'c': 40, 'b': 30}
         
         Now, show how to specify a conflict dict:
         
         >>> s = Struct(a=10,b=30)
         >>> s2 = Struct(a=20,b=40)
         >>> conflict = {'update':'a','add':'b'}
         >>> s.merge(s2,conflict)
         >>> s
         {'a': 20, 'b': 70}
         """
 
         data_dict = dict(__loc_data__,**kw)
 
         # policies for conflict resolution: two argument functions which return
         # the value that will go in the new struct
         preserve = lambda old,new: old
         update   = lambda old,new: new
         add      = lambda old,new: old + new
         add_flip = lambda old,new: new + old  # note change of order!
         add_s    = lambda old,new: old + ' ' + new
 
         # default policy is to keep current keys when there's a conflict
         conflict_solve = list2dict2(self.keys(), default = preserve)
 
         # the conflict_solve dictionary is given by the user 'inverted': we
         # need a name-function mapping, it comes as a function -> names
         # dict. Make a local copy (b/c we'll make changes), replace user
         # strings for the three builtin policies and invert it.
         if __conflict_solve:
             inv_conflict_solve_user = __conflict_solve.copy()
             for name, func in [('preserve',preserve), ('update',update),
                                ('add',add), ('add_flip',add_flip),
                                ('add_s',add_s)]:
                 if name in inv_conflict_solve_user.keys():
                     inv_conflict_solve_user[func] = inv_conflict_solve_user[name]
                     del inv_conflict_solve_user[name]
             conflict_solve.update(self.__dict_invert(inv_conflict_solve_user))
         for key in data_dict:
             if key not in self:
                 self[key] = data_dict[key]
             else:
                 self[key] = conflict_solve[key](self[key],data_dict[key])
 

IPython/utils/notification.py

@@ -1,143 +1,142 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 The IPython Core Notification Center.
 
 See docs/source/development/notification_blueprint.txt for an overview of the
 notification module.
 
 Authors:
 
 * Barry Wark
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 
 class NotificationError(Exception):
     pass
 
 
 class NotificationCenter(object):
     """Synchronous notification center.
     
     Examples
     --------
     Here is a simple example of how to use this::
 
         import IPython.util.notification as notification
         def callback(ntype, theSender, args={}):
             print ntype,theSender,args
 
         notification.sharedCenter.add_observer(callback, 'NOTIFICATION_TYPE', None)
         notification.sharedCenter.post_notification('NOTIFICATION_TYPE', object()) # doctest:+ELLIPSIS
         NOTIFICATION_TYPE ...
     """
     def __init__(self):
         super(NotificationCenter, self).__init__()
         self._init_observers()
 
     def _init_observers(self):
         """Initialize observer storage"""
 
         self.registered_types = set() #set of types that are observed
         self.registered_senders = set() #set of senders that are observed
         self.observers = {} #map (type,sender) => callback (callable)
 
     def post_notification(self, ntype, sender, *args, **kwargs):
         """Post notification to all registered observers.
 
         The registered callback will be called as::
 
             callback(ntype, sender, *args, **kwargs)
 
         Parameters
         ----------
         ntype : hashable
             The notification type.
         sender : hashable
             The object sending the notification.
         *args : tuple
             The positional arguments to be passed to the callback.
         **kwargs : dict
             The keyword argument to be passed to the callback.
 
         Notes
         -----
         * If no registered observers, performance is O(1).
         * Notificaiton order is undefined.
         * Notifications are posted synchronously.
         """
 
         if(ntype==None or sender==None):
             raise NotificationError(
                 "Notification type and sender are required.")
 
         # If there are no registered observers for the type/sender pair
         if((ntype not in self.registered_types and 
                 None not in self.registered_types) or
             (sender not in self.registered_senders and 
                 None not in self.registered_senders)):
             return
 
         for o in self._observers_for_notification(ntype, sender):
             o(ntype, sender, *args, **kwargs)
 
     def _observers_for_notification(self, ntype, sender):
         """Find all registered observers that should recieve notification"""
 
         keys = (
                    (ntype,sender),
                    (ntype, None),
                    (None, sender),
                    (None,None)
                )
 
         obs = set()
         for k in keys:
             obs.update(self.observers.get(k, set()))
 
         return obs
 
     def add_observer(self, callback, ntype, sender):
         """Add an observer callback to this notification center.
         
         The given callback will be called upon posting of notifications of
         the given type/sender and will receive any additional arguments passed
         to post_notification.
         
         Parameters
         ----------
         callback : callable
             The callable that will be called by :meth:`post_notification`
             as ``callback(ntype, sender, *args, **kwargs)
         ntype : hashable
             The notification type. If None, all notifications from sender
             will be posted.
         sender : hashable
             The notification sender. If None, all notifications of ntype
             will be posted.
         """
         assert(callback != None)
         self.registered_types.add(ntype)
         self.registered_senders.add(sender)
         self.observers.setdefault((ntype,sender), set()).add(callback)
     
     def remove_all_observers(self):
         """Removes all observers from this notification center"""
         
         self._init_observers()
     
 
 
 shared_center = NotificationCenter()

IPython/utils/syspathcontext.py

@@ -1,70 +1,69 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Context managers for adding things to sys.path temporarily.
 
 Authors:
 
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import sys
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 class appended_to_syspath(object):
     """A context for appending a directory to sys.path for a second."""
 
     def __init__(self, dir):
         self.dir = dir
 
     def __enter__(self):
         if self.dir not in sys.path:
             sys.path.append(self.dir)
             self.added = True
         else:
             self.added = False
 
     def __exit__(self, type, value, traceback):
         if self.added:
             try:
                 sys.path.remove(self.dir)
             except ValueError:
                 pass
         # Returning False causes any exceptions to be re-raised.
         return False
 
 class prepended_to_syspath(object):
     """A context for prepending a directory to sys.path for a second."""
 
     def __init__(self, dir):
         self.dir = dir
 
     def __enter__(self):
         if self.dir not in sys.path:
             sys.path.insert(0,self.dir)
             self.added = True
         else:
             self.added = False
 
     def __exit__(self, type, value, traceback):
         if self.added:
             try:
                 sys.path.remove(self.dir)
             except ValueError:
                 pass
         # Returning False causes any exceptions to be re-raised.
         return False

IPython/utils/tests/test_traitlets.py

@@ -1,847 +1,846 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 Tests for IPython.utils.traitlets.
 
 Authors:
 
 * Brian Granger
 * Enthought, Inc.  Some of the code in this file comes from enthought.traits
   and is licensed under the BSD license.  Also, many of the ideas also come
   from enthought.traits even though our implementation is very different.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import sys
 from unittest import TestCase
 
 from IPython.utils.traitlets import (
     HasTraits, MetaHasTraits, TraitType, Any, CBytes,
     Int, Long, Float, Complex, Bytes, Unicode, TraitError,
     Undefined, Type, This, Instance, TCPAddress, List, Tuple,
     ObjectName, DottedObjectName
 )
 
 
 #-----------------------------------------------------------------------------
 # Helper classes for testing
 #-----------------------------------------------------------------------------
 
 
 class HasTraitsStub(HasTraits):
 
     def _notify_trait(self, name, old, new):
         self._notify_name = name
         self._notify_old = old
         self._notify_new = new
 
 
 #-----------------------------------------------------------------------------
 # Test classes
 #-----------------------------------------------------------------------------
 
 
 class TestTraitType(TestCase):
 
     def test_get_undefined(self):
         class A(HasTraits):
             a = TraitType
         a = A()
         self.assertEquals(a.a, Undefined)
 
     def test_set(self):
         class A(HasTraitsStub):
             a = TraitType
 
         a = A()
         a.a = 10
         self.assertEquals(a.a, 10)
         self.assertEquals(a._notify_name, 'a')
         self.assertEquals(a._notify_old, Undefined)
         self.assertEquals(a._notify_new, 10)
 
     def test_validate(self):
         class MyTT(TraitType):
             def validate(self, inst, value):
                 return -1
         class A(HasTraitsStub):
             tt = MyTT
         
         a = A()
         a.tt = 10
         self.assertEquals(a.tt, -1)
 
     def test_default_validate(self):
         class MyIntTT(TraitType):
             def validate(self, obj, value):
                 if isinstance(value, int):
                     return value
                 self.error(obj, value)
         class A(HasTraits):
             tt = MyIntTT(10)
         a = A()
         self.assertEquals(a.tt, 10)
 
         # Defaults are validated when the HasTraits is instantiated
         class B(HasTraits):
             tt = MyIntTT('bad default')
         self.assertRaises(TraitError, B)
 
     def test_is_valid_for(self):
         class MyTT(TraitType):
             def is_valid_for(self, value):
                 return True
         class A(HasTraits):
             tt = MyTT
 
         a = A()
         a.tt = 10
         self.assertEquals(a.tt, 10)
 
     def test_value_for(self):
         class MyTT(TraitType):
             def value_for(self, value):
                 return 20
         class A(HasTraits):
             tt = MyTT
 
         a = A()
         a.tt = 10
         self.assertEquals(a.tt, 20)
 
     def test_info(self):
         class A(HasTraits):
             tt = TraitType
         a = A()
         self.assertEquals(A.tt.info(), 'any value')
 
     def test_error(self):
         class A(HasTraits):
             tt = TraitType
         a = A()
         self.assertRaises(TraitError, A.tt.error, a, 10)
 
     def test_dynamic_initializer(self):
         class A(HasTraits):
             x = Int(10)
             def _x_default(self):
                 return 11
         class B(A):
             x = Int(20)
         class C(A):
             def _x_default(self):
                 return 21
 
         a = A()
         self.assertEquals(a._trait_values, {})
         self.assertEquals(a._trait_dyn_inits.keys(), ['x'])
         self.assertEquals(a.x, 11)
         self.assertEquals(a._trait_values, {'x': 11})
         b = B()
         self.assertEquals(b._trait_values, {'x': 20})
         self.assertEquals(a._trait_dyn_inits.keys(), ['x'])
         self.assertEquals(b.x, 20)
         c = C()
         self.assertEquals(c._trait_values, {})
         self.assertEquals(a._trait_dyn_inits.keys(), ['x'])
         self.assertEquals(c.x, 21)
         self.assertEquals(c._trait_values, {'x': 21})
         # Ensure that the base class remains unmolested when the _default
         # initializer gets overridden in a subclass.
         a = A()
         c = C()
         self.assertEquals(a._trait_values, {})
         self.assertEquals(a._trait_dyn_inits.keys(), ['x'])
         self.assertEquals(a.x, 11)
         self.assertEquals(a._trait_values, {'x': 11})
 
 
 
 class TestHasTraitsMeta(TestCase):
 
     def test_metaclass(self):
         self.assertEquals(type(HasTraits), MetaHasTraits)
 
         class A(HasTraits):
             a = Int
 
         a = A()
         self.assertEquals(type(a.__class__), MetaHasTraits)
         self.assertEquals(a.a,0)
         a.a = 10
         self.assertEquals(a.a,10)
 
         class B(HasTraits):
             b = Int()
 
         b = B()
         self.assertEquals(b.b,0)
         b.b = 10
         self.assertEquals(b.b,10)
 
         class C(HasTraits):
             c = Int(30)
 
         c = C()
         self.assertEquals(c.c,30)
         c.c = 10
         self.assertEquals(c.c,10)
 
     def test_this_class(self):
         class A(HasTraits):
             t = This()
             tt = This()
         class B(A):
             tt = This()
             ttt = This()
         self.assertEquals(A.t.this_class, A)
         self.assertEquals(B.t.this_class, A)
         self.assertEquals(B.tt.this_class, B)
         self.assertEquals(B.ttt.this_class, B)
 
 class TestHasTraitsNotify(TestCase):
 
     def setUp(self):
         self._notify1 = []
         self._notify2 = []
 
     def notify1(self, name, old, new):
         self._notify1.append((name, old, new))
 
     def notify2(self, name, old, new):
         self._notify2.append((name, old, new))
 
     def test_notify_all(self):
 
         class A(HasTraits):
             a = Int
             b = Float
 
         a = A()
         a.on_trait_change(self.notify1)
         a.a = 0
         self.assertEquals(len(self._notify1),0)
         a.b = 0.0
         self.assertEquals(len(self._notify1),0)
         a.a = 10
         self.assert_(('a',0,10) in self._notify1)
         a.b = 10.0
         self.assert_(('b',0.0,10.0) in self._notify1)
         self.assertRaises(TraitError,setattr,a,'a','bad string')
         self.assertRaises(TraitError,setattr,a,'b','bad string')
         self._notify1 = []
         a.on_trait_change(self.notify1,remove=True)
         a.a = 20
         a.b = 20.0
         self.assertEquals(len(self._notify1),0)
 
     def test_notify_one(self):
 
         class A(HasTraits):
             a = Int
             b = Float
 
         a = A()
         a.on_trait_change(self.notify1, 'a')
         a.a = 0
         self.assertEquals(len(self._notify1),0)
         a.a = 10
         self.assert_(('a',0,10) in self._notify1)
         self.assertRaises(TraitError,setattr,a,'a','bad string')
 
     def test_subclass(self):
 
         class A(HasTraits):
             a = Int
 
         class B(A):
             b = Float
 
         b = B()
         self.assertEquals(b.a,0)
         self.assertEquals(b.b,0.0)
         b.a = 100
         b.b = 100.0
         self.assertEquals(b.a,100)
         self.assertEquals(b.b,100.0)
 
     def test_notify_subclass(self):
 
         class A(HasTraits):
             a = Int
 
         class B(A):
             b = Float
 
         b = B()
         b.on_trait_change(self.notify1, 'a')
         b.on_trait_change(self.notify2, 'b')
         b.a = 0
         b.b = 0.0
         self.assertEquals(len(self._notify1),0)
         self.assertEquals(len(self._notify2),0)
         b.a = 10
         b.b = 10.0
         self.assert_(('a',0,10) in self._notify1)
         self.assert_(('b',0.0,10.0) in self._notify2)
 
     def test_static_notify(self):
 
         class A(HasTraits):
             a = Int
             _notify1 = []
             def _a_changed(self, name, old, new):
                 self._notify1.append((name, old, new))
 
         a = A()
         a.a = 0
         # This is broken!!!
         self.assertEquals(len(a._notify1),0)
         a.a = 10
         self.assert_(('a',0,10) in a._notify1)
 
         class B(A):
             b = Float
             _notify2 = []
             def _b_changed(self, name, old, new):
                 self._notify2.append((name, old, new))
 
         b = B()
         b.a = 10
         b.b = 10.0
         self.assert_(('a',0,10) in b._notify1)
         self.assert_(('b',0.0,10.0) in b._notify2)
 
     def test_notify_args(self):
 
         def callback0():
             self.cb = ()
         def callback1(name):
             self.cb = (name,)
         def callback2(name, new):
             self.cb = (name, new)
         def callback3(name, old, new):
             self.cb = (name, old, new)
 
         class A(HasTraits):
             a = Int
 
         a = A()
         a.on_trait_change(callback0, 'a')
         a.a = 10
         self.assertEquals(self.cb,())
         a.on_trait_change(callback0, 'a', remove=True)
 
         a.on_trait_change(callback1, 'a')
         a.a = 100
         self.assertEquals(self.cb,('a',))
         a.on_trait_change(callback1, 'a', remove=True)
 
         a.on_trait_change(callback2, 'a')
         a.a = 1000
         self.assertEquals(self.cb,('a',1000))
         a.on_trait_change(callback2, 'a', remove=True)
 
         a.on_trait_change(callback3, 'a')
         a.a = 10000
         self.assertEquals(self.cb,('a',1000,10000))
         a.on_trait_change(callback3, 'a', remove=True)
 
         self.assertEquals(len(a._trait_notifiers['a']),0)
 
 
 class TestHasTraits(TestCase):
 
     def test_trait_names(self):
         class A(HasTraits):
             i = Int
             f = Float
         a = A()
         self.assertEquals(a.trait_names(),['i','f'])
         self.assertEquals(A.class_trait_names(),['i','f'])
 
     def test_trait_metadata(self):
         class A(HasTraits):
             i = Int(config_key='MY_VALUE')
         a = A()
         self.assertEquals(a.trait_metadata('i','config_key'), 'MY_VALUE')
 
     def test_traits(self):
         class A(HasTraits):
             i = Int
             f = Float
         a = A()
         self.assertEquals(a.traits(), dict(i=A.i, f=A.f))
         self.assertEquals(A.class_traits(), dict(i=A.i, f=A.f))
 
     def test_traits_metadata(self):
         class A(HasTraits):
             i = Int(config_key='VALUE1', other_thing='VALUE2')
             f = Float(config_key='VALUE3', other_thing='VALUE2')
             j = Int(0)
         a = A()
         self.assertEquals(a.traits(), dict(i=A.i, f=A.f, j=A.j))
         traits = a.traits(config_key='VALUE1', other_thing='VALUE2')
         self.assertEquals(traits, dict(i=A.i))
 
         # This passes, but it shouldn't because I am replicating a bug in 
         # traits.
         traits = a.traits(config_key=lambda v: True)
         self.assertEquals(traits, dict(i=A.i, f=A.f, j=A.j))
 
     def test_init(self):
         class A(HasTraits):
             i = Int()
             x = Float()
         a = A(i=1, x=10.0)
         self.assertEquals(a.i, 1)
         self.assertEquals(a.x, 10.0)
 
 #-----------------------------------------------------------------------------
 # Tests for specific trait types
 #-----------------------------------------------------------------------------
 
 
 class TestType(TestCase):
 
     def test_default(self):
 
         class B(object): pass
         class A(HasTraits):
             klass = Type
 
         a = A()
         self.assertEquals(a.klass, None)
 
         a.klass = B
         self.assertEquals(a.klass, B)
         self.assertRaises(TraitError, setattr, a, 'klass', 10)
 
     def test_value(self):
 
         class B(object): pass
         class C(object): pass
         class A(HasTraits):
             klass = Type(B)
         
         a = A()
         self.assertEquals(a.klass, B)
         self.assertRaises(TraitError, setattr, a, 'klass', C)
         self.assertRaises(TraitError, setattr, a, 'klass', object)
         a.klass = B
 
     def test_allow_none(self):
 
         class B(object): pass
         class C(B): pass
         class A(HasTraits):
             klass = Type(B, allow_none=False)
 
         a = A()
         self.assertEquals(a.klass, B)
         self.assertRaises(TraitError, setattr, a, 'klass', None)
         a.klass = C
         self.assertEquals(a.klass, C)
 
     def test_validate_klass(self):
 
         class A(HasTraits):
             klass = Type('no strings allowed')
 
         self.assertRaises(ImportError, A)
 
         class A(HasTraits):
             klass = Type('rub.adub.Duck')
 
         self.assertRaises(ImportError, A)
 
     def test_validate_default(self):
 
         class B(object): pass
         class A(HasTraits):
             klass = Type('bad default', B)
 
         self.assertRaises(ImportError, A)
 
         class C(HasTraits):
             klass = Type(None, B, allow_none=False)
 
         self.assertRaises(TraitError, C)
 
     def test_str_klass(self):
 
         class A(HasTraits):
             klass = Type('IPython.utils.ipstruct.Struct')
 
         from IPython.utils.ipstruct import Struct
         a = A()
         a.klass = Struct
         self.assertEquals(a.klass, Struct)
         
         self.assertRaises(TraitError, setattr, a, 'klass', 10)
 
 class TestInstance(TestCase):
 
     def test_basic(self):
         class Foo(object): pass
         class Bar(Foo): pass
         class Bah(object): pass
         
         class A(HasTraits):
             inst = Instance(Foo)
 
         a = A()
         self.assert_(a.inst is None)
         a.inst = Foo()
         self.assert_(isinstance(a.inst, Foo))
         a.inst = Bar()
         self.assert_(isinstance(a.inst, Foo))
         self.assertRaises(TraitError, setattr, a, 'inst', Foo)
         self.assertRaises(TraitError, setattr, a, 'inst', Bar)
         self.assertRaises(TraitError, setattr, a, 'inst', Bah())
 
     def test_unique_default_value(self):
         class Foo(object): pass
         class A(HasTraits):
             inst = Instance(Foo,(),{})
 
         a = A()
         b = A()
         self.assert_(a.inst is not b.inst)
 
     def test_args_kw(self):
         class Foo(object):
             def __init__(self, c): self.c = c
         class Bar(object): pass
         class Bah(object):
             def __init__(self, c, d):
                 self.c = c; self.d = d
 
         class A(HasTraits):
             inst = Instance(Foo, (10,))
         a = A()
         self.assertEquals(a.inst.c, 10)
 
         class B(HasTraits):
             inst = Instance(Bah, args=(10,), kw=dict(d=20))
         b = B()
         self.assertEquals(b.inst.c, 10)
         self.assertEquals(b.inst.d, 20)
 
         class C(HasTraits):
             inst = Instance(Foo)
         c = C()
         self.assert_(c.inst is None)
 
     def test_bad_default(self):
         class Foo(object): pass
 
         class A(HasTraits):
             inst = Instance(Foo, allow_none=False)
         
         self.assertRaises(TraitError, A)
 
     def test_instance(self):
         class Foo(object): pass
 
         def inner():
             class A(HasTraits):
                 inst = Instance(Foo())
         
         self.assertRaises(TraitError, inner)
 
 
 class TestThis(TestCase):
 
     def test_this_class(self):
         class Foo(HasTraits):
             this = This
 
         f = Foo()
         self.assertEquals(f.this, None)
         g = Foo()
         f.this = g
         self.assertEquals(f.this, g)
         self.assertRaises(TraitError, setattr, f, 'this', 10)
 
     def test_this_inst(self):
         class Foo(HasTraits):
             this = This()
         
         f = Foo()
         f.this = Foo()
         self.assert_(isinstance(f.this, Foo))
 
     def test_subclass(self):
         class Foo(HasTraits):
             t = This()
         class Bar(Foo):
             pass
         f = Foo()
         b = Bar()
         f.t = b
         b.t = f
         self.assertEquals(f.t, b)
         self.assertEquals(b.t, f)
 
     def test_subclass_override(self):
         class Foo(HasTraits):
             t = This()
         class Bar(Foo):
             t = This()
         f = Foo()
         b = Bar()
         f.t = b
         self.assertEquals(f.t, b)
         self.assertRaises(TraitError, setattr, b, 't', f)
 
 class TraitTestBase(TestCase):
     """A best testing class for basic trait types."""
 
     def assign(self, value):
         self.obj.value = value
 
     def coerce(self, value):
         return value
 
     def test_good_values(self):
         if hasattr(self, '_good_values'):
             for value in self._good_values:
                 self.assign(value)
                 self.assertEquals(self.obj.value, self.coerce(value))
 
     def test_bad_values(self):
         if hasattr(self, '_bad_values'):
             for value in self._bad_values:
                 self.assertRaises(TraitError, self.assign, value)
 
     def test_default_value(self):
         if hasattr(self, '_default_value'):
             self.assertEquals(self._default_value, self.obj.value)
 
 
 class AnyTrait(HasTraits):
 
     value = Any
 
 class AnyTraitTest(TraitTestBase):
 
     obj = AnyTrait()
 
     _default_value = None
     _good_values   = [10.0, 'ten', u'ten', [10], {'ten': 10},(10,), None, 1j]
     _bad_values    = []
 
 
 class IntTrait(HasTraits):
 
     value = Int(99)
 
 class TestInt(TraitTestBase):
 
     obj = IntTrait()
     _default_value = 99
     _good_values   = [10, -10]
     _bad_values    = ['ten', u'ten', [10], {'ten': 10},(10,), None, 1j, 10L,
                       -10L, 10.1, -10.1, '10L', '-10L', '10.1', '-10.1', u'10L',
                       u'-10L', u'10.1', u'-10.1',  '10', '-10', u'10', u'-10']
 
 
 class LongTrait(HasTraits):
 
     value = Long(99L)
 
 class TestLong(TraitTestBase):
 
     obj = LongTrait()
 
     _default_value = 99L
     _good_values   = [10, -10, 10L, -10L]
     _bad_values    = ['ten', u'ten', [10], [10l], {'ten': 10},(10,),(10L,),
                       None, 1j, 10.1, -10.1, '10', '-10', '10L', '-10L', '10.1',
                       '-10.1', u'10', u'-10', u'10L', u'-10L', u'10.1',
                       u'-10.1']
 
 
 class FloatTrait(HasTraits):
 
     value = Float(99.0)
 
 class TestFloat(TraitTestBase):
 
     obj = FloatTrait()
 
     _default_value = 99.0
     _good_values   = [10, -10, 10.1, -10.1]
     _bad_values    = [10L, -10L, 'ten', u'ten', [10], {'ten': 10},(10,), None,
                       1j, '10', '-10', '10L', '-10L', '10.1', '-10.1', u'10',
                       u'-10', u'10L', u'-10L', u'10.1', u'-10.1']
 
 
 class ComplexTrait(HasTraits):
 
     value = Complex(99.0-99.0j)
 
 class TestComplex(TraitTestBase):
 
     obj = ComplexTrait()
 
     _default_value = 99.0-99.0j
     _good_values   = [10, -10, 10.1, -10.1, 10j, 10+10j, 10-10j, 
                       10.1j, 10.1+10.1j, 10.1-10.1j]
     _bad_values    = [10L, -10L, u'10L', u'-10L', 'ten', [10], {'ten': 10},(10,), None]
 
 
 class BytesTrait(HasTraits):
 
     value = Bytes(b'string')
 
 class TestBytes(TraitTestBase):
 
     obj = BytesTrait()
 
     _default_value = b'string'
     _good_values   = [b'10', b'-10', b'10L',
                       b'-10L', b'10.1', b'-10.1', b'string']
     _bad_values    = [10, -10, 10L, -10L, 10.1, -10.1, 1j, [10],
                       ['ten'],{'ten': 10},(10,), None,  u'string']
 
 
 class UnicodeTrait(HasTraits):
 
     value = Unicode(u'unicode')
 
 class TestUnicode(TraitTestBase):
 
     obj = UnicodeTrait()
 
     _default_value = u'unicode'
     _good_values   = ['10', '-10', '10L', '-10L', '10.1', 
                       '-10.1', '', u'', 'string', u'string', u"€"]
     _bad_values    = [10, -10, 10L, -10L, 10.1, -10.1, 1j,
                       [10], ['ten'], [u'ten'], {'ten': 10},(10,), None]
 
 
 class ObjectNameTrait(HasTraits):
     value = ObjectName("abc")
     
 class TestObjectName(TraitTestBase):
     obj = ObjectNameTrait()
     
     _default_value = "abc"
     _good_values = ["a", "gh", "g9", "g_", "_G", u"a345_"]
     _bad_values = [1, "", u"€", "9g", "!", "#abc", "aj@", "a.b", "a()", "a[0]",
                                                             object(), object]
     if sys.version_info[0] < 3:
         _bad_values.append(u"þ")
     else:
         _good_values.append(u"þ")  # þ=1 is valid in Python 3 (PEP 3131).
 
 
 class DottedObjectNameTrait(HasTraits):
     value = DottedObjectName("a.b")
 
 class TestDottedObjectName(TraitTestBase):
     obj = DottedObjectNameTrait()
     
     _default_value = "a.b"
     _good_values = ["A", "y.t", "y765.__repr__", "os.path.join", u"os.path.join"]
     _bad_values = [1, u"abc.€", "_.@", ".", ".abc", "abc.", ".abc."]
     if sys.version_info[0] < 3:
         _bad_values.append(u"t.þ")
     else:
         _good_values.append(u"t.þ")
 
 
 class TCPAddressTrait(HasTraits):
 
     value = TCPAddress()
 
 class TestTCPAddress(TraitTestBase):
 
     obj = TCPAddressTrait()
 
     _default_value = ('127.0.0.1',0)
     _good_values = [('localhost',0),('192.168.0.1',1000),('www.google.com',80)]
     _bad_values = [(0,0),('localhost',10.0),('localhost',-1)]
 
 class ListTrait(HasTraits):
 
     value = List(Int)
 
 class TestList(TraitTestBase):
 
     obj = ListTrait()
 
     _default_value = []
     _good_values = [[], [1], range(10)]
     _bad_values = [10, [1,'a'], 'a', (1,2)]
 
 class LenListTrait(HasTraits):
 
     value = List(Int, [0], minlen=1, maxlen=2)
 
 class TestLenList(TraitTestBase):
 
     obj = LenListTrait()
 
     _default_value = [0]
     _good_values = [[1], range(2)]
     _bad_values = [10, [1,'a'], 'a', (1,2), [], range(3)]
 
 class TupleTrait(HasTraits):
 
     value = Tuple(Int)
 
 class TestTupleTrait(TraitTestBase):
 
     obj = TupleTrait()
 
     _default_value = None
     _good_values = [(1,), None,(0,)]
     _bad_values = [10, (1,2), [1],('a'), ()]
 
     def test_invalid_args(self):
         self.assertRaises(TypeError, Tuple, 5)
         self.assertRaises(TypeError, Tuple, default_value='hello')
         t = Tuple(Int, CBytes, default_value=(1,5))
 
 class LooseTupleTrait(HasTraits):
 
     value = Tuple((1,2,3))
 
 class TestLooseTupleTrait(TraitTestBase):
 
     obj = LooseTupleTrait()
 
     _default_value = (1,2,3)
     _good_values = [(1,), None, (0,), tuple(range(5)), tuple('hello'), ('a',5), ()]
     _bad_values = [10, 'hello', [1], []]
 
     def test_invalid_args(self):
         self.assertRaises(TypeError, Tuple, 5)
         self.assertRaises(TypeError, Tuple, default_value='hello')
         t = Tuple(Int, CBytes, default_value=(1,5))
 
 
 class MultiTupleTrait(HasTraits):
 
     value = Tuple(Int, Bytes, default_value=[99,'bottles'])
 
 class TestMultiTuple(TraitTestBase):
 
     obj = MultiTupleTrait()
 
     _default_value = (99,'bottles')
     _good_values = [(1,'a'), (2,'b')]
     _bad_values = ((),10, 'a', (1,'a',3), ('a',1))

IPython/utils/traitlets.py

@@ -1,1397 +1,1396 b''
-#!/usr/bin/env python
 # encoding: utf-8
 """
 A lightweight Traits like module.
 
 This is designed to provide a lightweight, simple, pure Python version of
 many of the capabilities of enthought.traits.  This includes:
 
 * Validation
 * Type specification with defaults
 * Static and dynamic notification
 * Basic predefined types
 * An API that is similar to enthought.traits
 
 We don't support:
 
 * Delegation
 * Automatic GUI generation
 * A full set of trait types.  Most importantly, we don't provide container
   traits (list, dict, tuple) that can trigger notifications if their
   contents change.
 * API compatibility with enthought.traits
 
 There are also some important difference in our design:
 
 * enthought.traits does not validate default values.  We do.
 
 We choose to create this module because we need these capabilities, but
 we need them to be pure Python so they work in all Python implementations,
 including Jython and IronPython.
 
 Authors:
 
 * Brian Granger
 * Enthought, Inc.  Some of the code in this file comes from enthought.traits
   and is licensed under the BSD license.  Also, many of the ideas also come
   from enthought.traits even though our implementation is very different.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 
 import inspect
 import re
 import sys
 import types
 from types import (
     InstanceType, ClassType, FunctionType,
     ListType, TupleType
 )
 from .importstring import import_item
 
 ClassTypes = (ClassType, type)
 
 SequenceTypes = (ListType, TupleType, set, frozenset)
 
 #-----------------------------------------------------------------------------
 # Basic classes
 #-----------------------------------------------------------------------------
 
 
 class NoDefaultSpecified ( object ): pass
 NoDefaultSpecified = NoDefaultSpecified()
 
 
 class Undefined ( object ): pass
 Undefined = Undefined()
 
 class TraitError(Exception):
     pass
 
 #-----------------------------------------------------------------------------
 # Utilities
 #-----------------------------------------------------------------------------
 
 
 def class_of ( object ):
     """ Returns a string containing the class name of an object with the
     correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image',
     'a PlotValue').
     """
     if isinstance( object, basestring ):
         return add_article( object )
 
     return add_article( object.__class__.__name__ )
 
 
 def add_article ( name ):
     """ Returns a string containing the correct indefinite article ('a' or 'an')
     prefixed to the specified string.
     """
     if name[:1].lower() in 'aeiou':
        return 'an ' + name
 
     return 'a ' + name
 
 
 def repr_type(obj):
     """ Return a string representation of a value and its type for readable
     error messages.
     """
     the_type = type(obj)
     if the_type is InstanceType:
         # Old-style class.
         the_type = obj.__class__
     msg = '%r %r' % (obj, the_type)
     return msg
 
 
 def parse_notifier_name(name):
     """Convert the name argument to a list of names.
     
     Examples
     --------
     
     >>> parse_notifier_name('a')
     ['a']
     >>> parse_notifier_name(['a','b'])
     ['a', 'b']
     >>> parse_notifier_name(None)
     ['anytrait']
     """
     if isinstance(name, str):
         return [name]
     elif name is None:
         return ['anytrait']
     elif isinstance(name, (list, tuple)):
         for n in name:
             assert isinstance(n, str), "names must be strings"
         return name
 
 
 class _SimpleTest:
     def __init__ ( self, value ): self.value = value
     def __call__ ( self, test  ):
         return test == self.value
     def __repr__(self):
         return "<SimpleTest(%r)" % self.value
     def __str__(self):
         return self.__repr__()
 
 
 def getmembers(object, predicate=None):
     """A safe version of inspect.getmembers that handles missing attributes.
 
     This is useful when there are descriptor based attributes that for 
     some reason raise AttributeError even though they exist.  This happens
     in zope.inteface with the __provides__ attribute.
     """
     results = []
     for key in dir(object):
         try:
             value = getattr(object, key)
         except AttributeError:
             pass
         else:
             if not predicate or predicate(value):
                 results.append((key, value))
     results.sort()
     return results
 
 
 #-----------------------------------------------------------------------------
 # Base TraitType for all traits
 #-----------------------------------------------------------------------------
 
 
 class TraitType(object):
     """A base class for all trait descriptors.
 
     Notes
     -----
     Our implementation of traits is based on Python's descriptor
     prototol.  This class is the base class for all such descriptors.  The
     only magic we use is a custom metaclass for the main :class:`HasTraits`
     class that does the following:
 
     1. Sets the :attr:`name` attribute of every :class:`TraitType`
        instance in the class dict to the name of the attribute.
     2. Sets the :attr:`this_class` attribute of every :class:`TraitType`
        instance in the class dict to the *class* that declared the trait.
        This is used by the :class:`This` trait to allow subclasses to
        accept superclasses for :class:`This` values.
     """
     
 
     metadata = {}
     default_value = Undefined
     info_text = 'any value'
 
     def __init__(self, default_value=NoDefaultSpecified, **metadata):
         """Create a TraitType.
         """
         if default_value is not NoDefaultSpecified:
             self.default_value = default_value
 
         if len(metadata) > 0:
             if len(self.metadata) > 0:
                 self._metadata = self.metadata.copy()
                 self._metadata.update(metadata)
             else:
                 self._metadata = metadata
         else:
             self._metadata = self.metadata
 
         self.init()
 
     def init(self):
         pass
 
     def get_default_value(self):
         """Create a new instance of the default value."""
         return self.default_value
 
     def instance_init(self, obj):
         """This is called by :meth:`HasTraits.__new__` to finish init'ing.
 
         Some stages of initialization must be delayed until the parent
         :class:`HasTraits` instance has been created.  This method is
         called in :meth:`HasTraits.__new__` after the instance has been
         created.
 
         This method trigger the creation and validation of default values
         and also things like the resolution of str given class names in 
         :class:`Type` and :class`Instance`.
 
         Parameters
         ----------
         obj : :class:`HasTraits` instance
             The parent :class:`HasTraits` instance that has just been
             created.
         """
         self.set_default_value(obj)
 
     def set_default_value(self, obj):
         """Set the default value on a per instance basis.
 
         This method is called by :meth:`instance_init` to create and
         validate the default value.  The creation and validation of 
         default values must be delayed until the parent :class:`HasTraits`
         class has been instantiated.
         """
         # Check for a deferred initializer defined in the same class as the
         # trait declaration or above.
         mro = type(obj).mro()
         meth_name = '_%s_default' % self.name
         for cls in mro[:mro.index(self.this_class)+1]:
             if meth_name in cls.__dict__:
                 break
         else:
             # We didn't find one. Do static initialization.
             dv = self.get_default_value()
             newdv = self._validate(obj, dv)
             obj._trait_values[self.name] = newdv
             return
         # Complete the dynamic initialization.
         obj._trait_dyn_inits[self.name] = cls.__dict__[meth_name]
 
     def __get__(self, obj, cls=None):
         """Get the value of the trait by self.name for the instance.
 
         Default values are instantiated when :meth:`HasTraits.__new__`
         is called.  Thus by the time this method gets called either the 
         default value or a user defined value (they called :meth:`__set__`)
         is in the :class:`HasTraits` instance.
         """
         if obj is None:
             return self
         else:
             try:
                 value = obj._trait_values[self.name]
             except KeyError:
                 # Check for a dynamic initializer.
                 if self.name in obj._trait_dyn_inits:
                     value = obj._trait_dyn_inits[self.name](obj)
                     # FIXME: Do we really validate here?
                     value = self._validate(obj, value)
                     obj._trait_values[self.name] = value
                     return value
                 else:
                     raise TraitError('Unexpected error in TraitType: '
                         'both default value and dynamic initializer are '
                         'absent.')
             except Exception:
                 # HasTraits should call set_default_value to populate
                 # this.  So this should never be reached.
                 raise TraitError('Unexpected error in TraitType: '
                                     'default value not set properly')
             else:
                 return value
 
     def __set__(self, obj, value):
         new_value = self._validate(obj, value)
         old_value = self.__get__(obj)
         if old_value != new_value:
             obj._trait_values[self.name] = new_value
             obj._notify_trait(self.name, old_value, new_value)
 
     def _validate(self, obj, value):
         if hasattr(self, 'validate'):
             return self.validate(obj, value)
         elif hasattr(self, 'is_valid_for'):
             valid = self.is_valid_for(value)
             if valid:
                 return value
             else:
                 raise TraitError('invalid value for type: %r' % value)
         elif hasattr(self, 'value_for'):
             return self.value_for(value)
         else:
             return value
 
     def info(self):
         return self.info_text
 
     def error(self, obj, value):
         if obj is not None:
             e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
                 % (self.name, class_of(obj),
                    self.info(), repr_type(value))
         else:
             e = "The '%s' trait must be %s, but a value of %r was specified." \
                 % (self.name, self.info(), repr_type(value))
         raise TraitError(e)
 
     def get_metadata(self, key):
         return getattr(self, '_metadata', {}).get(key, None)
 
     def set_metadata(self, key, value):
         getattr(self, '_metadata', {})[key] = value
 
 
 #-----------------------------------------------------------------------------
 # The HasTraits implementation
 #-----------------------------------------------------------------------------
 
 
 class MetaHasTraits(type):
     """A metaclass for HasTraits.
     
     This metaclass makes sure that any TraitType class attributes are
     instantiated and sets their name attribute.
     """
     
     def __new__(mcls, name, bases, classdict):
         """Create the HasTraits class.
         
         This instantiates all TraitTypes in the class dict and sets their
         :attr:`name` attribute.
         """
         # print "MetaHasTraitlets (mcls, name): ", mcls, name
         # print "MetaHasTraitlets (bases): ", bases
         # print "MetaHasTraitlets (classdict): ", classdict
         for k,v in classdict.iteritems():
             if isinstance(v, TraitType):
                 v.name = k
             elif inspect.isclass(v):
                 if issubclass(v, TraitType):
                     vinst = v()
                     vinst.name = k
                     classdict[k] = vinst
         return super(MetaHasTraits, mcls).__new__(mcls, name, bases, classdict)
 
     def __init__(cls, name, bases, classdict):
         """Finish initializing the HasTraits class.
         
         This sets the :attr:`this_class` attribute of each TraitType in the
         class dict to the newly created class ``cls``.
         """
         for k, v in classdict.iteritems():
             if isinstance(v, TraitType):
                 v.this_class = cls
         super(MetaHasTraits, cls).__init__(name, bases, classdict)
 
 class HasTraits(object):
 
     __metaclass__ = MetaHasTraits
 
     def __new__(cls, **kw):
         # This is needed because in Python 2.6 object.__new__ only accepts
         # the cls argument.
         new_meth = super(HasTraits, cls).__new__
         if new_meth is object.__new__:
             inst = new_meth(cls)
         else:
             inst = new_meth(cls, **kw)
         inst._trait_values = {}
         inst._trait_notifiers = {}
         inst._trait_dyn_inits = {}
         # Here we tell all the TraitType instances to set their default
         # values on the instance. 
         for key in dir(cls):
             # Some descriptors raise AttributeError like zope.interface's
             # __provides__ attributes even though they exist.  This causes
             # AttributeErrors even though they are listed in dir(cls).
             try:
                 value = getattr(cls, key)
             except AttributeError:
                 pass
             else:
                 if isinstance(value, TraitType):
                     value.instance_init(inst)
 
         return inst
 
     def __init__(self, **kw):
         # Allow trait values to be set using keyword arguments.
         # We need to use setattr for this to trigger validation and
         # notifications.
         for key, value in kw.iteritems():
             setattr(self, key, value)
 
     def _notify_trait(self, name, old_value, new_value):
 
         # First dynamic ones
         callables = self._trait_notifiers.get(name,[])
         more_callables = self._trait_notifiers.get('anytrait',[])
         callables.extend(more_callables)
 
         # Now static ones
         try:
             cb = getattr(self, '_%s_changed' % name)
         except:
             pass
         else:
             callables.append(cb)
 
         # Call them all now
         for c in callables:
             # Traits catches and logs errors here.  I allow them to raise
             if callable(c):
                 argspec = inspect.getargspec(c)
                 nargs = len(argspec[0])
                 # Bound methods have an additional 'self' argument
                 # I don't know how to treat unbound methods, but they
                 # can't really be used for callbacks.
                 if isinstance(c, types.MethodType):
                     offset = -1
                 else:
                     offset = 0
                 if nargs + offset == 0:
                     c()
                 elif nargs + offset == 1:
                     c(name)
                 elif nargs + offset == 2:
                     c(name, new_value)
                 elif nargs + offset == 3:
                     c(name, old_value, new_value)
                 else:
                     raise TraitError('a trait changed callback '
                                         'must have 0-3 arguments.')
             else:
                 raise TraitError('a trait changed callback '
                                     'must be callable.')
                 
 
     def _add_notifiers(self, handler, name):
         if not self._trait_notifiers.has_key(name):
             nlist = []
             self._trait_notifiers[name] = nlist
         else:
             nlist = self._trait_notifiers[name]
         if handler not in nlist:
             nlist.append(handler)
 
     def _remove_notifiers(self, handler, name):
         if self._trait_notifiers.has_key(name):
             nlist = self._trait_notifiers[name]
             try:
                 index = nlist.index(handler)
             except ValueError:
                 pass
             else:
                 del nlist[index]
 
     def on_trait_change(self, handler, name=None, remove=False):
         """Setup a handler to be called when a trait changes.
 
         This is used to setup dynamic notifications of trait changes.
         
         Static handlers can be created by creating methods on a HasTraits
         subclass with the naming convention '_[traitname]_changed'.  Thus,
         to create static handler for the trait 'a', create the method
         _a_changed(self, name, old, new) (fewer arguments can be used, see
         below).
         
         Parameters
         ----------
         handler : callable
             A callable that is called when a trait changes.  Its 
             signature can be handler(), handler(name), handler(name, new)
             or handler(name, old, new).
         name : list, str, None
             If None, the handler will apply to all traits.  If a list
             of str, handler will apply to all names in the list.  If a
             str, the handler will apply just to that name.
         remove : bool
             If False (the default), then install the handler.  If True
             then unintall it.
         """
         if remove:
             names = parse_notifier_name(name)
             for n in names:
                 self._remove_notifiers(handler, n)
         else:
             names = parse_notifier_name(name)
             for n in names:
                 self._add_notifiers(handler, n)
 
     @classmethod
     def class_trait_names(cls, **metadata):
         """Get a list of all the names of this classes traits.
 
         This method is just like the :meth:`trait_names` method, but is unbound.
         """
         return cls.class_traits(**metadata).keys()
 
     @classmethod
     def class_traits(cls, **metadata):
         """Get a list of all the traits of this class.
 
         This method is just like the :meth:`traits` method, but is unbound.
 
         The TraitTypes returned don't know anything about the values
         that the various HasTrait's instances are holding.
 
         This follows the same algorithm as traits does and does not allow
         for any simple way of specifying merely that a metadata name
         exists, but has any value.  This is because get_metadata returns
         None if a metadata key doesn't exist.
         """
         traits = dict([memb for memb in getmembers(cls) if \
                      isinstance(memb[1], TraitType)])
 
         if len(metadata) == 0:
             return traits
 
         for meta_name, meta_eval in metadata.items():
             if type(meta_eval) is not FunctionType:
                 metadata[meta_name] = _SimpleTest(meta_eval)
 
         result = {}
         for name, trait in traits.items():
             for meta_name, meta_eval in metadata.items():
                 if not meta_eval(trait.get_metadata(meta_name)):
                     break
             else:
                 result[name] = trait
 
         return result
 
     def trait_names(self, **metadata):
         """Get a list of all the names of this classes traits."""
         return self.traits(**metadata).keys()
 
     def traits(self, **metadata):
         """Get a list of all the traits of this class.
 
         The TraitTypes returned don't know anything about the values
         that the various HasTrait's instances are holding.
 
         This follows the same algorithm as traits does and does not allow
         for any simple way of specifying merely that a metadata name
         exists, but has any value.  This is because get_metadata returns
         None if a metadata key doesn't exist.
         """
         traits = dict([memb for memb in getmembers(self.__class__) if \
                      isinstance(memb[1], TraitType)])
 
         if len(metadata) == 0:
             return traits
 
         for meta_name, meta_eval in metadata.items():
             if type(meta_eval) is not FunctionType:
                 metadata[meta_name] = _SimpleTest(meta_eval)
 
         result = {}
         for name, trait in traits.items():
             for meta_name, meta_eval in metadata.items():
                 if not meta_eval(trait.get_metadata(meta_name)):
                     break
             else:
                 result[name] = trait
 
         return result
 
     def trait_metadata(self, traitname, key):
         """Get metadata values for trait by key."""
         try:
             trait = getattr(self.__class__, traitname)
         except AttributeError:
             raise TraitError("Class %s does not have a trait named %s" %
                                 (self.__class__.__name__, traitname))
         else:
             return trait.get_metadata(key)
 
 #-----------------------------------------------------------------------------
 # Actual TraitTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # TraitTypes subclasses for handling classes and instances of classes
 #-----------------------------------------------------------------------------
 
 
 class ClassBasedTraitType(TraitType):
     """A trait with error reporting for Type, Instance and This."""
 
     def error(self, obj, value):
         kind = type(value)
         if kind is InstanceType:
             msg = 'class %s' % value.__class__.__name__
         else:
             msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) )
 
         if obj is not None:
             e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
                 % (self.name, class_of(obj),
                    self.info(), msg)
         else:
             e = "The '%s' trait must be %s, but a value of %r was specified." \
                 % (self.name, self.info(), msg)
 
         raise TraitError(e)
 
 
 class Type(ClassBasedTraitType):
     """A trait whose value must be a subclass of a specified class."""
 
     def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ):
         """Construct a Type trait
 
         A Type trait specifies that its values must be subclasses of
         a particular class.
 
         If only ``default_value`` is given, it is used for the ``klass`` as
         well.
 
         Parameters
         ----------
         default_value : class, str or None
             The default value must be a subclass of klass.  If an str,
             the str must be a fully specified class name, like 'foo.bar.Bah'.
             The string is resolved into real class, when the parent 
             :class:`HasTraits` class is instantiated.
         klass : class, str, None
             Values of this trait must be a subclass of klass.  The klass
             may be specified in a string like: 'foo.bar.MyClass'.
             The string is resolved into real class, when the parent 
             :class:`HasTraits` class is instantiated.
         allow_none : boolean
             Indicates whether None is allowed as an assignable value. Even if
             ``False``, the default value may be ``None``.
         """
         if default_value is None:
             if klass is None:
                 klass = object
         elif klass is None:
             klass = default_value
 
         if not (inspect.isclass(klass) or isinstance(klass, basestring)):
             raise TraitError("A Type trait must specify a class.")
 
         self.klass       = klass
         self._allow_none = allow_none
 
         super(Type, self).__init__(default_value, **metadata)
 
     def validate(self, obj, value):
         """Validates that the value is a valid object instance."""
         try:
             if issubclass(value, self.klass):
                 return value
         except:
             if (value is None) and (self._allow_none):
                 return value
 
         self.error(obj, value)
 
     def info(self):
         """ Returns a description of the trait."""
         if isinstance(self.klass, basestring):
             klass = self.klass
         else:
             klass = self.klass.__name__
         result = 'a subclass of ' + klass
         if self._allow_none:
             return result + ' or None'
         return result
 
     def instance_init(self, obj):
         self._resolve_classes()
         super(Type, self).instance_init(obj)
 
     def _resolve_classes(self):
         if isinstance(self.klass, basestring):
             self.klass = import_item(self.klass)
         if isinstance(self.default_value, basestring):
             self.default_value = import_item(self.default_value)
 
     def get_default_value(self):
         return self.default_value
 
 
 class DefaultValueGenerator(object):
     """A class for generating new default value instances."""
 
     def __init__(self, *args, **kw):
         self.args = args
         self.kw = kw
 
     def generate(self, klass):
         return klass(*self.args, **self.kw)
 
 
 class Instance(ClassBasedTraitType):
     """A trait whose value must be an instance of a specified class.
     
     The value can also be an instance of a subclass of the specified class.
     """
 
     def __init__(self, klass=None, args=None, kw=None, 
                  allow_none=True, **metadata ):
         """Construct an Instance trait.
 
         This trait allows values that are instances of a particular
         class or its sublclasses.  Our implementation is quite different
         from that of enthough.traits as we don't allow instances to be used
         for klass and we handle the ``args`` and ``kw`` arguments differently.
 
         Parameters
         ----------
         klass : class, str
             The class that forms the basis for the trait.  Class names
             can also be specified as strings, like 'foo.bar.Bar'.
         args : tuple
             Positional arguments for generating the default value.
         kw : dict
             Keyword arguments for generating the default value.
         allow_none : bool
             Indicates whether None is allowed as a value.
 
         Default Value
         -------------
         If both ``args`` and ``kw`` are None, then the default value is None.
         If ``args`` is a tuple and ``kw`` is a dict, then the default is
         created as ``klass(*args, **kw)``.  If either ``args`` or ``kw`` is 
         not (but not both), None is replace by ``()`` or ``{}``.
         """
 
         self._allow_none = allow_none
 
         if (klass is None) or (not (inspect.isclass(klass) or isinstance(klass, basestring))):
             raise TraitError('The klass argument must be a class'
                                 ' you gave: %r' % klass)
         self.klass = klass
         
         # self.klass is a class, so handle default_value
         if args is None and kw is None:
             default_value = None
         else:
             if args is None:
                 # kw is not None
                 args = ()
             elif kw is None:
                 # args is not None
                 kw = {}
         
             if not isinstance(kw, dict):
                 raise TraitError("The 'kw' argument must be a dict or None.")
             if not isinstance(args, tuple):
                 raise TraitError("The 'args' argument must be a tuple or None.")
             
             default_value = DefaultValueGenerator(*args, **kw)
 
         super(Instance, self).__init__(default_value, **metadata)
 
     def validate(self, obj, value):
         if value is None:
             if self._allow_none:
                 return value
             self.error(obj, value)
 
         if isinstance(value, self.klass):
             return value
         else:
             self.error(obj, value)
 
     def info(self):
         if isinstance(self.klass, basestring):
             klass = self.klass
         else:
             klass = self.klass.__name__
         result = class_of(klass)
         if self._allow_none:
             return result + ' or None'
 
         return result
 
     def instance_init(self, obj):
         self._resolve_classes()
         super(Instance, self).instance_init(obj)
 
     def _resolve_classes(self):
         if isinstance(self.klass, basestring):
             self.klass = import_item(self.klass)
 
     def get_default_value(self):
         """Instantiate a default value instance.
         
         This is called when the containing HasTraits classes'
         :meth:`__new__` method is called to ensure that a unique instance
         is created for each HasTraits instance.
         """
         dv  = self.default_value
         if isinstance(dv, DefaultValueGenerator):
             return dv.generate(self.klass)
         else:
             return dv
 
 
 class This(ClassBasedTraitType):
     """A trait for instances of the class containing this trait.
 
     Because how how and when class bodies are executed, the ``This``
     trait can only have a default value of None.  This, and because we 
     always validate default values, ``allow_none`` is *always* true.
     """
 
     info_text = 'an instance of the same type as the receiver or None'
 
     def __init__(self, **metadata):
         super(This, self).__init__(None, **metadata)
 
     def validate(self, obj, value):
         # What if value is a superclass of obj.__class__?  This is
         # complicated if it was the superclass that defined the This
         # trait.
         if isinstance(value, self.this_class) or (value is None):
             return value
         else:
             self.error(obj, value)
 
 
 #-----------------------------------------------------------------------------
 # Basic TraitTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
 
 class Any(TraitType):
     default_value = None
     info_text = 'any value'
 
 
 class Int(TraitType):
     """A integer trait."""
 
     default_value = 0
     info_text = 'an integer'
 
     def validate(self, obj, value):
         if isinstance(value, int):
             return value
         self.error(obj, value)
 
 class CInt(Int):
     """A casting version of the int trait."""
 
     def validate(self, obj, value):
         try:
             return int(value)
         except:
             self.error(obj, value)
 
 
 class Long(TraitType):
     """A long integer trait."""
 
     default_value = 0L
     info_text = 'a long'
 
     def validate(self, obj, value):
         if isinstance(value, long):
             return value
         if isinstance(value, int):
             return long(value)
         self.error(obj, value)
 
 
 class CLong(Long):
     """A casting version of the long integer trait."""
 
     def validate(self, obj, value):
         try:
             return long(value)
         except:
             self.error(obj, value)
 
 
 class Float(TraitType):
     """A float trait."""
 
     default_value = 0.0
     info_text = 'a float'
 
     def validate(self, obj, value):
         if isinstance(value, float):
             return value
         if isinstance(value, int):
             return float(value)
         self.error(obj, value)
 
 
 class CFloat(Float):
     """A casting version of the float trait."""
 
     def validate(self, obj, value):
         try:
             return float(value)
         except:
             self.error(obj, value)
 
 class Complex(TraitType):
     """A trait for complex numbers."""
 
     default_value = 0.0 + 0.0j
     info_text = 'a complex number'
 
     def validate(self, obj, value):
         if isinstance(value, complex):
             return value
         if isinstance(value, (float, int)):
             return complex(value)
         self.error(obj, value)
 
 
 class CComplex(Complex):
     """A casting version of the complex number trait."""
 
     def validate (self, obj, value):
         try:
             return complex(value)
         except:
             self.error(obj, value)
 
 # We should always be explicit about whether we're using bytes or unicode, both
 # for Python 3 conversion and for reliable unicode behaviour on Python 2. So
 # we don't have a Str type.
 class Bytes(TraitType):
     """A trait for strings."""
 
     default_value = ''
     info_text = 'a string'
 
     def validate(self, obj, value):
         if isinstance(value, bytes):
             return value
         self.error(obj, value)
 
 
 class CBytes(Bytes):
     """A casting version of the string trait."""
 
     def validate(self, obj, value):
         try:
             return bytes(value)
         except:
             self.error(obj, value)
 
 
 class Unicode(TraitType):
     """A trait for unicode strings."""
 
     default_value = u''
     info_text = 'a unicode string'
 
     def validate(self, obj, value):
         if isinstance(value, unicode):
             return value
         if isinstance(value, bytes):
             return unicode(value)
         self.error(obj, value)
 
 
 class CUnicode(Unicode):
     """A casting version of the unicode trait."""
 
     def validate(self, obj, value):
         try:
             return unicode(value)
         except:
             self.error(obj, value)
   
             
 class ObjectName(TraitType):
     """A string holding a valid object name in this version of Python.
     
     This does not check that the name exists in any scope."""
     info_text = "a valid object identifier in Python"
 
     if sys.version_info[0] < 3:
         # Python 2:
         _name_re = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*$")
         def isidentifier(self, s):
             return bool(self._name_re.match(s))
         
         def coerce_str(self, obj, value):
             "In Python 2, coerce ascii-only unicode to str"
             if isinstance(value, unicode):
                 try:
                     return str(value)
                 except UnicodeEncodeError:
                     self.error(obj, value)
             return value
     
     else:
         # Python 3:
         isidentifier = staticmethod(lambda s: s.isidentifier())
         coerce_str = staticmethod(lambda _,s: s)
     
     def validate(self, obj, value):
         value = self.coerce_str(obj, value)
         
         if isinstance(value, str) and self.isidentifier(value):
             return value
         self.error(obj, value)
 
 class DottedObjectName(ObjectName):
     """A string holding a valid dotted object name in Python, such as A.b3._c"""
     def validate(self, obj, value):
         value = self.coerce_str(obj, value)
         
         if isinstance(value, str) and all(self.isidentifier(x) \
                                                     for x in value.split('.')):
             return value
         self.error(obj, value)
 
 
 class Bool(TraitType):
     """A boolean (True, False) trait."""
 
     default_value = False
     info_text = 'a boolean'
 
     def validate(self, obj, value):
         if isinstance(value, bool):
             return value
         self.error(obj, value)
 
 
 class CBool(Bool):
     """A casting version of the boolean trait."""
 
     def validate(self, obj, value):
         try:
             return bool(value)
         except:
             self.error(obj, value)
 
 
 class Enum(TraitType):
     """An enum that whose value must be in a given sequence."""
 
     def __init__(self, values, default_value=None, allow_none=True, **metadata):
         self.values = values
         self._allow_none = allow_none
         super(Enum, self).__init__(default_value, **metadata)
 
     def validate(self, obj, value):
         if value is None:
             if self._allow_none:
                 return value
 
         if value in self.values:
                 return value
         self.error(obj, value)
 
     def info(self):
         """ Returns a description of the trait."""
         result = 'any of ' + repr(self.values)
         if self._allow_none:
             return result + ' or None'
         return result
 
 class CaselessStrEnum(Enum):
     """An enum of strings that are caseless in validate."""
 
     def validate(self, obj, value):
         if value is None:
             if self._allow_none:
                 return value
 
         if not isinstance(value, basestring):
             self.error(obj, value)
 
         for v in self.values:
             if v.lower() == value.lower():
                 return v
         self.error(obj, value)
 
 class Container(Instance):
     """An instance of a container (list, set, etc.)
 
     To be subclassed by overriding klass.
     """
     klass = None
     _valid_defaults = SequenceTypes
     _trait = None
 
     def __init__(self, trait=None, default_value=None, allow_none=True,
                 **metadata):
         """Create a container trait type from a list, set, or tuple.
 
         The default value is created by doing ``List(default_value)``,
         which creates a copy of the ``default_value``.
 
         ``trait`` can be specified, which restricts the type of elements
         in the container to that TraitType.
 
         If only one arg is given and it is not a Trait, it is taken as
         ``default_value``:
 
         ``c = List([1,2,3])``
 
         Parameters
         ----------
 
         trait : TraitType [ optional ]
             the type for restricting the contents of the Container.  If unspecified,
             types are not checked.
 
         default_value : SequenceType [ optional ]
             The default value for the Trait.  Must be list/tuple/set, and
             will be cast to the container type.
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         istrait = lambda t: isinstance(t, type) and issubclass(t, TraitType)
 
         # allow List([values]):
         if default_value is None and not istrait(trait):
             default_value = trait
             trait = None
 
         if default_value is None:
             args = ()
         elif isinstance(default_value, self._valid_defaults):
             args = (default_value,)
         else:
             raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
 
         if istrait(trait):
             self._trait = trait()
             self._trait.name = 'element'
         elif trait is not None:
             raise TypeError("`trait` must be a Trait or None, got %s"%repr_type(trait))
 
         super(Container,self).__init__(klass=self.klass, args=args,
                                   allow_none=allow_none, **metadata)
 
     def element_error(self, obj, element, validator):
         e = "Element of the '%s' trait of %s instance must be %s, but a value of %s was specified." \
             % (self.name, class_of(obj), validator.info(), repr_type(element))
         raise TraitError(e)
 
     def validate(self, obj, value):
         value = super(Container, self).validate(obj, value)
         if value is None:
             return value
 
         value = self.validate_elements(obj, value)
 
         return value
 
     def validate_elements(self, obj, value):
         validated = []
         if self._trait is None or isinstance(self._trait, Any):
             return value
         for v in value:
             try:
                 v = self._trait.validate(obj, v)
             except TraitError:
                 self.element_error(obj, v, self._trait)
             else:
                 validated.append(v)
         return self.klass(validated)
 
 
 class List(Container):
     """An instance of a Python list."""
     klass = list
 
     def __init__(self, trait=None, default_value=None, minlen=0, maxlen=sys.maxint,
                 allow_none=True, **metadata):
         """Create a List trait type from a list, set, or tuple.
 
         The default value is created by doing ``List(default_value)``,
         which creates a copy of the ``default_value``.
 
         ``trait`` can be specified, which restricts the type of elements
         in the container to that TraitType.
 
         If only one arg is given and it is not a Trait, it is taken as
         ``default_value``:
 
         ``c = List([1,2,3])``
 
         Parameters
         ----------
 
         trait : TraitType [ optional ]
             the type for restricting the contents of the Container.  If unspecified,
             types are not checked.
 
         default_value : SequenceType [ optional ]
             The default value for the Trait.  Must be list/tuple/set, and
             will be cast to the container type.
 
         minlen : Int [ default 0 ]
             The minimum length of the input list
 
         maxlen : Int [ default sys.maxint ]
             The maximum length of the input list
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         self._minlen = minlen
         self._maxlen = maxlen
         super(List, self).__init__(trait=trait, default_value=default_value,
                                 allow_none=allow_none, **metadata)
 
     def length_error(self, obj, value):
         e = "The '%s' trait of %s instance must be of length %i <= L <= %i, but a value of %s was specified." \
             % (self.name, class_of(obj), self._minlen, self._maxlen, value)
         raise TraitError(e)
 
     def validate_elements(self, obj, value):
         length = len(value)
         if length < self._minlen or length > self._maxlen:
             self.length_error(obj, value)
 
         return super(List, self).validate_elements(obj, value)
 
 
 class Set(Container):
     """An instance of a Python set."""
     klass = set
 
 class Tuple(Container):
     """An instance of a Python tuple."""
     klass = tuple
 
     def __init__(self, *traits, **metadata):
         """Tuple(*traits, default_value=None, allow_none=True, **medatata)
 
         Create a tuple from a list, set, or tuple.
 
         Create a fixed-type tuple with Traits:
 
         ``t = Tuple(Int, Str, CStr)``
 
         would be length 3, with Int,Str,CStr for each element.
 
         If only one arg is given and it is not a Trait, it is taken as
         default_value:
 
         ``t = Tuple((1,2,3))``
 
         Otherwise, ``default_value`` *must* be specified by keyword.
 
         Parameters
         ----------
 
         *traits : TraitTypes [ optional ]
             the tsype for restricting the contents of the Tuple.  If unspecified,
             types are not checked. If specified, then each positional argument
             corresponds to an element of the tuple.  Tuples defined with traits
             are of fixed length.
 
         default_value : SequenceType [ optional ]
             The default value for the Tuple.  Must be list/tuple/set, and
             will be cast to a tuple. If `traits` are specified, the
             `default_value` must conform to the shape and type they specify.
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         default_value = metadata.pop('default_value', None)
         allow_none = metadata.pop('allow_none', True)
 
         istrait = lambda t: isinstance(t, type) and issubclass(t, TraitType)
 
         # allow Tuple((values,)):
         if len(traits) == 1 and default_value is None and not istrait(traits[0]):
             default_value = traits[0]
             traits = ()
 
         if default_value is None:
             args = ()
         elif isinstance(default_value, self._valid_defaults):
             args = (default_value,)
         else:
             raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
 
         self._traits = []
         for trait in traits:
             t = trait()
             t.name = 'element'
             self._traits.append(t)
 
         if self._traits and default_value is None:
             # don't allow default to be an empty container if length is specified
             args = None
         super(Container,self).__init__(klass=self.klass, args=args,
                                   allow_none=allow_none, **metadata)
 
     def validate_elements(self, obj, value):
         if not self._traits:
             # nothing to validate
             return value
         if len(value) != len(self._traits):
             e = "The '%s' trait of %s instance requires %i elements, but a value of %s was specified." \
                 % (self.name, class_of(obj), len(self._traits), repr_type(value))
             raise TraitError(e)
 
         validated = []
         for t,v in zip(self._traits, value):
             try:
                 v = t.validate(obj, v)
             except TraitError:
                 self.element_error(obj, v, t)
             else:
                 validated.append(v)
         return tuple(validated)
 
 
 class Dict(Instance):
     """An instance of a Python dict."""
 
     def __init__(self, default_value=None, allow_none=True, **metadata):
         """Create a dict trait type from a dict.
 
         The default value is created by doing ``dict(default_value)``, 
         which creates a copy of the ``default_value``.
         """
         if default_value is None:
             args = ((),)
         elif isinstance(default_value, dict):
             args = (default_value,)
         elif isinstance(default_value, SequenceTypes):
             args = (default_value,)
         else:
             raise TypeError('default value of Dict was %s' % default_value)
 
         super(Dict,self).__init__(klass=dict, args=args, 
                                   allow_none=allow_none, **metadata)
 
 class TCPAddress(TraitType):
     """A trait for an (ip, port) tuple.
 
     This allows for both IPv4 IP addresses as well as hostnames.
     """
 
     default_value = ('127.0.0.1', 0)
     info_text = 'an (ip, port) tuple'
 
     def validate(self, obj, value):
         if isinstance(value, tuple):
             if len(value) == 2:
                 if isinstance(value[0], basestring) and isinstance(value[1], int):
                     port = value[1]
                     if port >= 0 and port <= 65535:
                         return value
         self.error(obj, value)

IPython/zmq/kernelapp.py

@@ -1,227 +1,226 b''
-#!/usr/bin/env python
 """An Application for launching a kernel
 
 Authors
 -------
 * MinRK
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING.txt, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Standard library imports.
 import os
 import sys
 
 # System library imports.
 import zmq
 
 # IPython imports.
 from IPython.core.ultratb import FormattedTB
 from IPython.core.application import (
     BaseIPythonApplication, base_flags, base_aliases
 )
 from IPython.utils import io
 from IPython.utils.localinterfaces import LOCALHOST
 from IPython.utils.traitlets import (Any, Instance, Dict, Unicode, Int, Bool,
                                         DottedObjectName)
 from IPython.utils.importstring import import_item
 # local imports
 from IPython.zmq.heartbeat import Heartbeat
 from IPython.zmq.parentpoller import ParentPollerUnix, ParentPollerWindows
 from IPython.zmq.session import Session
 
 
 #-----------------------------------------------------------------------------
 # Flags and Aliases
 #-----------------------------------------------------------------------------
 
 kernel_aliases = dict(base_aliases)
 kernel_aliases.update({
     'ip' : 'KernelApp.ip',
     'hb' : 'KernelApp.hb_port',
     'shell' : 'KernelApp.shell_port',
     'iopub' : 'KernelApp.iopub_port',
     'stdin' : 'KernelApp.stdin_port',
     'parent': 'KernelApp.parent',
 })
 if sys.platform.startswith('win'):
     kernel_aliases['interrupt'] = 'KernelApp.interrupt'
 
 kernel_flags = dict(base_flags)
 kernel_flags.update({
     'no-stdout' : (
             {'KernelApp' : {'no_stdout' : True}},
             "redirect stdout to the null device"),
     'no-stderr' : (
             {'KernelApp' : {'no_stderr' : True}},
             "redirect stderr to the null device"),
 })
 
 
 #-----------------------------------------------------------------------------
 # Application class for starting a Kernel
 #-----------------------------------------------------------------------------
 
 class KernelApp(BaseIPythonApplication):
     name='pykernel'
     aliases = Dict(kernel_aliases)
     flags = Dict(kernel_flags)
     classes = [Session]
     # the kernel class, as an importstring
     kernel_class = DottedObjectName('IPython.zmq.pykernel.Kernel')
     kernel = Any()
     poller = Any() # don't restrict this even though current pollers are all Threads
     heartbeat = Instance(Heartbeat)
     session = Instance('IPython.zmq.session.Session')
     ports = Dict()
     
     # inherit config file name from parent:
     parent_appname = Unicode(config=True)
     def _parent_appname_changed(self, name, old, new):
         if self.config_file_specified:
             # it was manually specified, ignore
             return
         self.config_file_name = new.replace('-','_') + u'_config.py'
         # don't let this count as specifying the config file
         self.config_file_specified = False
         
     # connection info:
     ip = Unicode(LOCALHOST, config=True,
         help="Set the IP or interface on which the kernel will listen.")
     hb_port = Int(0, config=True, help="set the heartbeat port [default: random]")
     shell_port = Int(0, config=True, help="set the shell (XREP) port [default: random]")
     iopub_port = Int(0, config=True, help="set the iopub (PUB) port [default: random]")
     stdin_port = Int(0, config=True, help="set the stdin (XREQ) port [default: random]")
 
     # streams, etc.
     no_stdout = Bool(False, config=True, help="redirect stdout to the null device")
     no_stderr = Bool(False, config=True, help="redirect stderr to the null device")
     outstream_class = DottedObjectName('IPython.zmq.iostream.OutStream',
         config=True, help="The importstring for the OutStream factory")
     displayhook_class = DottedObjectName('IPython.zmq.displayhook.ZMQDisplayHook',
         config=True, help="The importstring for the DisplayHook factory")
 
     # polling
     parent = Int(0, config=True,
         help="""kill this process if its parent dies.  On Windows, the argument
         specifies the HANDLE of the parent process, otherwise it is simply boolean.
         """)
     interrupt = Int(0, config=True,
         help="""ONLY USED ON WINDOWS
         Interrupt this process when the parent is signalled.
         """)
 
     def init_crash_handler(self):
         # Install minimal exception handling
         sys.excepthook = FormattedTB(mode='Verbose', color_scheme='NoColor',
                                      ostream=sys.__stdout__)
 
     def init_poller(self):
         if sys.platform == 'win32':
             if self.interrupt or self.parent:
                 self.poller = ParentPollerWindows(self.interrupt, self.parent)
         elif self.parent:
             self.poller = ParentPollerUnix()
 
     def _bind_socket(self, s, port):
         iface = 'tcp://%s' % self.ip
         if port <= 0:
             port = s.bind_to_random_port(iface)
         else:
             s.bind(iface + ':%i'%port)
         return port
 
     def init_sockets(self):
         # Create a context, a session, and the kernel sockets.
         self.log.info("Starting the kernel at pid: %i", os.getpid())
         context = zmq.Context.instance()
         # Uncomment this to try closing the context.
         # atexit.register(context.term)
 
         self.shell_socket = context.socket(zmq.XREP)
         self.shell_port = self._bind_socket(self.shell_socket, self.shell_port)
         self.log.debug("shell XREP Channel on port: %i"%self.shell_port)
 
         self.iopub_socket = context.socket(zmq.PUB)
         self.iopub_port = self._bind_socket(self.iopub_socket, self.iopub_port)
         self.log.debug("iopub PUB Channel on port: %i"%self.iopub_port)
 
         self.stdin_socket = context.socket(zmq.XREQ)
         self.stdin_port = self._bind_socket(self.stdin_socket, self.stdin_port)
         self.log.debug("stdin XREQ Channel on port: %i"%self.stdin_port)
 
         self.heartbeat = Heartbeat(context, (self.ip, self.hb_port))
         self.hb_port = self.heartbeat.port
         self.log.debug("Heartbeat REP Channel on port: %i"%self.hb_port)
 
         # Helper to make it easier to connect to an existing kernel, until we have
         # single-port connection negotiation fully implemented.
         # set log-level to critical, to make sure it is output
         self.log.critical("To connect another client to this kernel, use:")
         self.log.critical("--existing --shell={0} --iopub={1} --stdin={2} --hb={3}".format(
             self.shell_port, self.iopub_port, self.stdin_port, self.hb_port))
 
 
         self.ports = dict(shell=self.shell_port, iopub=self.iopub_port,
                                 stdin=self.stdin_port, hb=self.hb_port)
 
     def init_session(self):
         """create our session object"""
         self.session = Session(config=self.config, username=u'kernel')
 
     def init_blackhole(self):
         """redirects stdout/stderr to devnull if necessary"""
         if self.no_stdout or self.no_stderr:
             blackhole = file(os.devnull, 'w')
             if self.no_stdout:
                 sys.stdout = sys.__stdout__ = blackhole
             if self.no_stderr:
                 sys.stderr = sys.__stderr__ = blackhole
     
     def init_io(self):
         """Redirect input streams and set a display hook."""
         if self.outstream_class:
             outstream_factory = import_item(str(self.outstream_class))
             sys.stdout = outstream_factory(self.session, self.iopub_socket, u'stdout')
             sys.stderr = outstream_factory(self.session, self.iopub_socket, u'stderr')
         if self.displayhook_class:
             displayhook_factory = import_item(str(self.displayhook_class))
             sys.displayhook = displayhook_factory(self.session, self.iopub_socket)
 
     def init_kernel(self):
         """Create the Kernel object itself"""
         kernel_factory = import_item(str(self.kernel_class))
         self.kernel = kernel_factory(config=self.config, session=self.session,
                                 shell_socket=self.shell_socket,
                                 iopub_socket=self.iopub_socket,
                                 stdin_socket=self.stdin_socket,
                                 log=self.log
         )
         self.kernel.record_ports(self.ports)
 
     def initialize(self, argv=None):
         super(KernelApp, self).initialize(argv)
         self.init_blackhole()
         self.init_session()
         self.init_poller()
         self.init_sockets()
         self.init_io()
         self.init_kernel()
 
     def start(self):
         self.heartbeat.start()
         if self.poller is not None:
             self.poller.start()
         try:
             self.kernel.start()
         except KeyboardInterrupt:
             pass
 

IPython/zmq/session.py

@@ -1,679 +1,678 b''
-#!/usr/bin/env python
 """Session object for building, serializing, sending, and receiving messages in
 IPython. The Session object supports serialization, HMAC signatures, and
 metadata on messages.
 
 Also defined here are utilities for working with Sessions:
 * A SessionFactory to be used as a base class for configurables that work with
 Sessions.
 * A Message object for convenience that allows attribute-access to the msg dict.
 
 Authors:
 
 * Min RK
 * Brian Granger
 * Fernando Perez
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import hmac
 import logging
 import os
 import pprint
 import uuid
 from datetime import datetime
 
 try:
     import cPickle
     pickle = cPickle
 except:
     cPickle = None
     import pickle
 
 import zmq
 from zmq.utils import jsonapi
 from zmq.eventloop.ioloop import IOLoop
 from zmq.eventloop.zmqstream import ZMQStream
 
 from IPython.config.configurable import Configurable, LoggingConfigurable
 from IPython.utils.importstring import import_item
 from IPython.utils.jsonutil import extract_dates, squash_dates, date_default
 from IPython.utils.traitlets import (CBytes, Unicode, Bool, Any, Instance, Set,
                                         DottedObjectName)
 
 #-----------------------------------------------------------------------------
 # utility functions
 #-----------------------------------------------------------------------------
 
 def squash_unicode(obj):
     """coerce unicode back to bytestrings."""
     if isinstance(obj,dict):
         for key in obj.keys():
             obj[key] = squash_unicode(obj[key])
             if isinstance(key, unicode):
                 obj[squash_unicode(key)] = obj.pop(key)
     elif isinstance(obj, list):
         for i,v in enumerate(obj):
             obj[i] = squash_unicode(v)
     elif isinstance(obj, unicode):
         obj = obj.encode('utf8')
     return obj
 
 #-----------------------------------------------------------------------------
 # globals and defaults
 #-----------------------------------------------------------------------------
 key = 'on_unknown' if jsonapi.jsonmod.__name__ == 'jsonlib' else 'default'
 json_packer = lambda obj: jsonapi.dumps(obj, **{key:date_default})
 json_unpacker = lambda s: extract_dates(jsonapi.loads(s))
 
 pickle_packer = lambda o: pickle.dumps(o,-1)
 pickle_unpacker = pickle.loads
 
 default_packer = json_packer
 default_unpacker = json_unpacker
 
 
 DELIM=b"<IDS|MSG>"
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class SessionFactory(LoggingConfigurable):
     """The Base class for configurables that have a Session, Context, logger,
     and IOLoop.
     """
     
     logname = Unicode('')
     def _logname_changed(self, name, old, new):
         self.log = logging.getLogger(new)
     
     # not configurable:
     context = Instance('zmq.Context')
     def _context_default(self):
         return zmq.Context.instance()
     
     session = Instance('IPython.zmq.session.Session')
     
     loop = Instance('zmq.eventloop.ioloop.IOLoop', allow_none=False)
     def _loop_default(self):
         return IOLoop.instance()
     
     def __init__(self, **kwargs):
         super(SessionFactory, self).__init__(**kwargs)
         
         if self.session is None:
             # construct the session
             self.session = Session(**kwargs)
     
 
 class Message(object):
     """A simple message object that maps dict keys to attributes.
 
     A Message can be created from a dict and a dict from a Message instance
     simply by calling dict(msg_obj)."""
     
     def __init__(self, msg_dict):
         dct = self.__dict__
         for k, v in dict(msg_dict).iteritems():
             if isinstance(v, dict):
                 v = Message(v)
             dct[k] = v
 
     # Having this iterator lets dict(msg_obj) work out of the box.
     def __iter__(self):
         return iter(self.__dict__.iteritems())
     
     def __repr__(self):
         return repr(self.__dict__)
 
     def __str__(self):
         return pprint.pformat(self.__dict__)
 
     def __contains__(self, k):
         return k in self.__dict__
 
     def __getitem__(self, k):
         return self.__dict__[k]
 
 
 def msg_header(msg_id, msg_type, username, session):
     date = datetime.now()
     return locals()
 
 def extract_header(msg_or_header):
     """Given a message or header, return the header."""
     if not msg_or_header:
         return {}
     try:
         # See if msg_or_header is the entire message.
         h = msg_or_header['header']
     except KeyError:
         try:
             # See if msg_or_header is just the header
             h = msg_or_header['msg_id']
         except KeyError:
             raise
         else:
             h = msg_or_header
     if not isinstance(h, dict):
         h = dict(h)
     return h
 
 class Session(Configurable):
     """Object for handling serialization and sending of messages.
     
     The Session object handles building messages and sending them
     with ZMQ sockets or ZMQStream objects.  Objects can communicate with each
     other over the network via Session objects, and only need to work with the
     dict-based IPython message spec. The Session will handle 
     serialization/deserialization, security, and metadata.
     
     Sessions support configurable serialiization via packer/unpacker traits,
     and signing with HMAC digests via the key/keyfile traits.
     
     Parameters
     ----------
     
     debug : bool
         whether to trigger extra debugging statements
     packer/unpacker : str : 'json', 'pickle' or import_string
         importstrings for methods to serialize message parts.  If just
         'json' or 'pickle', predefined JSON and pickle packers will be used.
         Otherwise, the entire importstring must be used.
         
         The functions must accept at least valid JSON input, and output *bytes*.
         
         For example, to use msgpack:
         packer = 'msgpack.packb', unpacker='msgpack.unpackb'
     pack/unpack : callables
         You can also set the pack/unpack callables for serialization directly.
     session : bytes
         the ID of this Session object.  The default is to generate a new UUID.
     username : unicode
         username added to message headers.  The default is to ask the OS.
     key : bytes
         The key used to initialize an HMAC signature.  If unset, messages
         will not be signed or checked.
     keyfile : filepath
         The file containing a key.  If this is set, `key` will be initialized
         to the contents of the file.
     
     """
     
     debug=Bool(False, config=True, help="""Debug output in the Session""")
     
     packer = DottedObjectName('json',config=True,
             help="""The name of the packer for serializing messages.
             Should be one of 'json', 'pickle', or an import name
             for a custom callable serializer.""")
     def _packer_changed(self, name, old, new):
         if new.lower() == 'json':
             self.pack = json_packer
             self.unpack = json_unpacker
         elif new.lower() == 'pickle':
             self.pack = pickle_packer
             self.unpack = pickle_unpacker
         else:
             self.pack = import_item(str(new))
 
     unpacker = DottedObjectName('json', config=True,
         help="""The name of the unpacker for unserializing messages.
         Only used with custom functions for `packer`.""")
     def _unpacker_changed(self, name, old, new):
         if new.lower() == 'json':
             self.pack = json_packer
             self.unpack = json_unpacker
         elif new.lower() == 'pickle':
             self.pack = pickle_packer
             self.unpack = pickle_unpacker
         else:
             self.unpack = import_item(str(new))
         
     session = CBytes(b'', config=True,
         help="""The UUID identifying this session.""")
     def _session_default(self):
         return bytes(uuid.uuid4())
     
     username = Unicode(os.environ.get('USER','username'), config=True,
         help="""Username for the Session. Default is your system username.""")
     
     # message signature related traits:
     key = CBytes(b'', config=True,
         help="""execution key, for extra authentication.""")
     def _key_changed(self, name, old, new):
         if new:
             self.auth = hmac.HMAC(new)
         else:
             self.auth = None
     auth = Instance(hmac.HMAC)
     digest_history = Set()
     
     keyfile = Unicode('', config=True,
         help="""path to file containing execution key.""")
     def _keyfile_changed(self, name, old, new):
         with open(new, 'rb') as f:
             self.key = f.read().strip()
 
     pack = Any(default_packer) # the actual packer function
     def _pack_changed(self, name, old, new):
         if not callable(new):
             raise TypeError("packer must be callable, not %s"%type(new))
     
     unpack = Any(default_unpacker) # the actual packer function
     def _unpack_changed(self, name, old, new):
         # unpacker is not checked - it is assumed to be 
         if not callable(new):
             raise TypeError("unpacker must be callable, not %s"%type(new))
 
     def __init__(self, **kwargs):
         """create a Session object
         
         Parameters
         ----------
 
         debug : bool
             whether to trigger extra debugging statements
         packer/unpacker : str : 'json', 'pickle' or import_string
             importstrings for methods to serialize message parts.  If just
             'json' or 'pickle', predefined JSON and pickle packers will be used.
             Otherwise, the entire importstring must be used.
 
             The functions must accept at least valid JSON input, and output
             *bytes*.
 
             For example, to use msgpack:
             packer = 'msgpack.packb', unpacker='msgpack.unpackb'
         pack/unpack : callables
             You can also set the pack/unpack callables for serialization
             directly.
         session : bytes
             the ID of this Session object.  The default is to generate a new 
             UUID.
         username : unicode
             username added to message headers.  The default is to ask the OS.
         key : bytes
             The key used to initialize an HMAC signature.  If unset, messages
             will not be signed or checked.
         keyfile : filepath
             The file containing a key.  If this is set, `key` will be 
             initialized to the contents of the file.
         """
         super(Session, self).__init__(**kwargs)
         self._check_packers()
         self.none = self.pack({})
 
     @property
     def msg_id(self):
         """always return new uuid"""
         return str(uuid.uuid4())
 
     def _check_packers(self):
         """check packers for binary data and datetime support."""
         pack = self.pack
         unpack = self.unpack
         
         # check simple serialization
         msg = dict(a=[1,'hi'])
         try:
             packed = pack(msg)
         except Exception:
             raise ValueError("packer could not serialize a simple message")
         
         # ensure packed message is bytes
         if not isinstance(packed, bytes):
             raise ValueError("message packed to %r, but bytes are required"%type(packed))
         
         # check that unpack is pack's inverse
         try:
             unpacked = unpack(packed)
         except Exception:
             raise ValueError("unpacker could not handle the packer's output")
         
         # check datetime support
         msg = dict(t=datetime.now())
         try:
             unpacked = unpack(pack(msg))
         except Exception:
             self.pack = lambda o: pack(squash_dates(o))
             self.unpack = lambda s: extract_dates(unpack(s))
     
     def msg_header(self, msg_type):
         return msg_header(self.msg_id, msg_type, self.username, self.session)
 
     def msg(self, msg_type, content=None, parent=None, subheader=None):
         """Return the nested message dict.
 
         This format is different from what is sent over the wire. The
         self.serialize method converts this nested message dict to the wire
         format, which uses a message list.
         """
         msg = {}
         msg['header'] = self.msg_header(msg_type)
         msg['msg_id'] = msg['header']['msg_id']
         msg['parent_header'] = {} if parent is None else extract_header(parent)
         msg['msg_type'] = msg_type
         msg['content'] = {} if content is None else content
         sub = {} if subheader is None else subheader
         msg['header'].update(sub)
         return msg
 
     def sign(self, msg_list):
         """Sign a message with HMAC digest. If no auth, return b''.
 
         Parameters
         ----------
         msg_list : list
             The [p_header,p_parent,p_content] part of the message list. 
         """
         if self.auth is None:
             return b''
         h = self.auth.copy()
         for m in msg_list:
             h.update(m)
         return h.hexdigest()
     
     def serialize(self, msg, ident=None):
         """Serialize the message components to bytes.
 
         Parameters
         ----------
         msg : dict or Message
             The nexted message dict as returned by the self.msg method.
 
         Returns
         -------
         msg_list : list
             The list of bytes objects to be sent with the format:
             [ident1,ident2,...,DELIM,HMAC,p_header,p_parent,p_content,
              buffer1,buffer2,...]. In this list, the p_* entities are
             the packed or serialized versions, so if JSON is used, these
             are uft8 encoded JSON strings.
         """
         content = msg.get('content', {})
         if content is None:
             content = self.none
         elif isinstance(content, dict):
             content = self.pack(content)
         elif isinstance(content, bytes):
             # content is already packed, as in a relayed message
             pass
         elif isinstance(content, unicode):
             # should be bytes, but JSON often spits out unicode
             content = content.encode('utf8')
         else:
             raise TypeError("Content incorrect type: %s"%type(content))
         
         real_message = [self.pack(msg['header']), 
                         self.pack(msg['parent_header']), 
                         content
         ]
         
         to_send = []
 
         if isinstance(ident, list):
             # accept list of idents
             to_send.extend(ident)
         elif ident is not None:
             to_send.append(ident)
         to_send.append(DELIM)
         
         signature = self.sign(real_message)
         to_send.append(signature)
         
         to_send.extend(real_message)
 
         return to_send
         
     def send(self, stream, msg_or_type, content=None, parent=None, ident=None, 
                                     buffers=None, subheader=None, track=False):
         """Build and send a message via stream or socket.
 
         The message format used by this function internally is as follows:
 
         [ident1,ident2,...,DELIM,HMAC,p_header,p_parent,p_content,
          buffer1,buffer2,...] 
 
         The self.serialize method converts the nested message dict into this
         format.
 
         Parameters
         ----------
         
         stream : zmq.Socket or ZMQStream
             the socket-like object used to send the data
         msg_or_type : str or Message/dict
             Normally, msg_or_type will be a msg_type unless a message is being 
             sent more than once.
         
         content : dict or None
             the content of the message (ignored if msg_or_type is a message)
         parent : Message or dict or None
             the parent or parent header describing the parent of this message
         ident : bytes or list of bytes
             the zmq.IDENTITY routing path
         subheader : dict or None
             extra header keys for this message's header
         buffers : list or None
             the already-serialized buffers to be appended to the message
         track : bool
             whether to track.  Only for use with Sockets, 
             because ZMQStream objects cannot track messages.
         
         Returns
         -------
         msg : message dict
             the constructed message
         (msg,tracker) : (message dict, MessageTracker)
             if track=True, then a 2-tuple will be returned, 
             the first element being the constructed
             message, and the second being the MessageTracker
             
         """
 
         if not isinstance(stream, (zmq.Socket, ZMQStream)):
             raise TypeError("stream must be Socket or ZMQStream, not %r"%type(stream))
         elif track and isinstance(stream, ZMQStream):
             raise TypeError("ZMQStream cannot track messages")
         
         if isinstance(msg_or_type, (Message, dict)):
             # we got a Message, not a msg_type
             # don't build a new Message
             msg = msg_or_type
         else:
             msg = self.msg(msg_or_type, content, parent, subheader)
         
         buffers = [] if buffers is None else buffers
         to_send = self.serialize(msg, ident)
         flag = 0
         if buffers:
             flag = zmq.SNDMORE
             _track = False
         else:
             _track=track
         if track:
             tracker = stream.send_multipart(to_send, flag, copy=False, track=_track)
         else:
             tracker = stream.send_multipart(to_send, flag, copy=False)
         for b in buffers[:-1]:
             stream.send(b, flag, copy=False)
         if buffers:
             if track:
                 tracker = stream.send(buffers[-1], copy=False, track=track)
             else:
                 tracker = stream.send(buffers[-1], copy=False)
 
         # omsg = Message(msg)
         if self.debug:
             pprint.pprint(msg)
             pprint.pprint(to_send)
             pprint.pprint(buffers)
         
         msg['tracker'] = tracker
         
         return msg
     
     def send_raw(self, stream, msg_list, flags=0, copy=True, ident=None):
         """Send a raw message via ident path.
 
         This method is used to send a already serialized message.
 
         Parameters
         ----------
         stream : ZMQStream or Socket
             The ZMQ stream or socket to use for sending the message.
         msg_list : list
             The serialized list of messages to send. This only includes the
             [p_header,p_parent,p_content,buffer1,buffer2,...] portion of
             the message.
         ident : ident or list
             A single ident or a list of idents to use in sending.
         """
         to_send = []
         if isinstance(ident, bytes):
             ident = [ident]
         if ident is not None:
             to_send.extend(ident)
             
         to_send.append(DELIM)
         to_send.append(self.sign(msg_list))
         to_send.extend(msg_list)
         stream.send_multipart(msg_list, flags, copy=copy)
     
     def recv(self, socket, mode=zmq.NOBLOCK, content=True, copy=True):
         """Receive and unpack a message.
 
         Parameters
         ----------
         socket : ZMQStream or Socket
             The socket or stream to use in receiving.
 
         Returns
         -------
         [idents], msg
             [idents] is a list of idents and msg is a nested message dict of
             same format as self.msg returns.
         """
         if isinstance(socket, ZMQStream):
             socket = socket.socket
         try:
             msg_list = socket.recv_multipart(mode)
         except zmq.ZMQError as e:
             if e.errno == zmq.EAGAIN:
                 # We can convert EAGAIN to None as we know in this case
                 # recv_multipart won't return None.
                 return None,None
             else:
                 raise
         # split multipart message into identity list and message dict
         # invalid large messages can cause very expensive string comparisons
         idents, msg_list = self.feed_identities(msg_list, copy)
         try:
             return idents, self.unpack_message(msg_list, content=content, copy=copy)
         except Exception as e:
             print (idents, msg_list)
             # TODO: handle it
             raise e
     
     def feed_identities(self, msg_list, copy=True):
         """Split the identities from the rest of the message.
 
         Feed until DELIM is reached, then return the prefix as idents and
         remainder as msg_list. This is easily broken by setting an IDENT to DELIM,
         but that would be silly.
         
         Parameters
         ----------
         msg_list : a list of Message or bytes objects
             The message to be split.
         copy : bool
             flag determining whether the arguments are bytes or Messages
         
         Returns
         -------
         (idents,msg_list) : two lists
             idents will always be a list of bytes - the indentity prefix
             msg_list will be a list of bytes or Messages, unchanged from input
             msg_list should be unpackable via self.unpack_message at this point.
         """
         if copy:
             idx = msg_list.index(DELIM)
             return msg_list[:idx], msg_list[idx+1:]
         else:
             failed = True
             for idx,m in enumerate(msg_list):
                 if m.bytes == DELIM:
                     failed = False
                     break
             if failed:
                 raise ValueError("DELIM not in msg_list")
             idents, msg_list = msg_list[:idx], msg_list[idx+1:]
             return [m.bytes for m in idents], msg_list
     
     def unpack_message(self, msg_list, content=True, copy=True):
         """Return a message object from the format
         sent by self.send.
         
         Parameters:
         -----------
         
         content : bool (True)
             whether to unpack the content dict (True), 
             or leave it serialized (False)
         
         copy : bool (True)
             whether to return the bytes (True), 
             or the non-copying Message object in each place (False)
         
         """
         minlen = 4
         message = {}
         if not copy:
             for i in range(minlen):
                 msg_list[i] = msg_list[i].bytes
         if self.auth is not None:
             signature = msg_list[0]
             if signature in self.digest_history:
                 raise ValueError("Duplicate Signature: %r"%signature)
             self.digest_history.add(signature)
             check = self.sign(msg_list[1:4])
             if not signature == check:
                 raise ValueError("Invalid Signature: %r"%signature)
         if not len(msg_list) >= minlen:
             raise TypeError("malformed message, must have at least %i elements"%minlen)
         message['header'] = self.unpack(msg_list[1])
         message['msg_type'] = message['header']['msg_type']
         message['parent_header'] = self.unpack(msg_list[2])
         if content:
             message['content'] = self.unpack(msg_list[3])
         else:
             message['content'] = msg_list[3]
         
         message['buffers'] = msg_list[4:]
         return message
 
 def test_msg2obj():
     am = dict(x=1)
     ao = Message(am)
     assert ao.x == am['x']
 
     am['y'] = dict(z=1)
     ao = Message(am)
     assert ao.y.z == am['y']['z']
     
     k1, k2 = 'y', 'z'
     assert ao[k1][k2] == am[k1][k2]
     
     am2 = dict(ao)
     assert am['x'] == am2['x']
     assert am['y']['z'] == am2['y']['z']