make sentinel class for some kwargs.

The signature is a little more sane with
`fun(..., default=module.value)`
instead of
`fun(..., default=<object object at 0x12345678>)`

IPython/core/formatters.py

@@ -1,965 +1,972 b''
 # -*- coding: utf-8 -*-
 """Display formatters.
 
 Inheritance diagram:
 
 .. inheritance-diagram:: IPython.core.formatters
    :parts: 3
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import abc
 import inspect
 import json
 import sys
 import traceback
 import warnings
 
 from decorator import decorator
 
 from IPython.config.configurable import Configurable
 from IPython.core.getipython import get_ipython
+from IPython.utils.signatures import Sentinel
 from IPython.lib import pretty
 from IPython.utils.traitlets import (
     Bool, Dict, Integer, Unicode, CUnicode, ObjectName, List,
     ForwardDeclaredInstance,
 )
 from IPython.utils.py3compat import (
     with_metaclass, string_types, unicode_type,
 )
 
 
 #-----------------------------------------------------------------------------
 # The main DisplayFormatter class
 #-----------------------------------------------------------------------------
 
 
 def _safe_get_formatter_method(obj, name):
     """Safely get a formatter method
     
     - Classes cannot have formatter methods, only instance
     - protect against proxy objects that claim to have everything
     """
     if inspect.isclass(obj):
         # repr methods only make sense on instances, not classes
         return None
     method = pretty._safe_getattr(obj, name, None)
     if callable(method):
         # obj claims to have repr method...
         if callable(pretty._safe_getattr(obj, '_ipython_canary_method_should_not_exist_', None)):
             # ...but don't trust proxy objects that claim to have everything
             return None
         return method
 
 
 class DisplayFormatter(Configurable):
 
     # When set to true only the default plain text formatter will be used.
     plain_text_only = Bool(False, config=True)
     def _plain_text_only_changed(self, name, old, new):
         warnings.warn("""DisplayFormatter.plain_text_only is deprecated.
         
         Use DisplayFormatter.active_types = ['text/plain']
         for the same effect.
         """, DeprecationWarning)
         if new:
             self.active_types = ['text/plain']
         else:
             self.active_types = self.format_types
     
     active_types = List(Unicode, config=True,
         help="""List of currently active mime-types to display.
         You can use this to set a white-list for formats to display.
         
         Most users will not need to change this value.
         """)
     def _active_types_default(self):
         return self.format_types
     
     def _active_types_changed(self, name, old, new):
         for key, formatter in self.formatters.items():
             if key in new:
                 formatter.enabled = True
             else:
                 formatter.enabled = False
     
     ipython_display_formatter = ForwardDeclaredInstance('FormatterABC')
     def _ipython_display_formatter_default(self):
         return IPythonDisplayFormatter(parent=self)
     
     # A dict of formatter whose keys are format types (MIME types) and whose
     # values are subclasses of BaseFormatter.
     formatters = Dict()
     def _formatters_default(self):
         """Activate the default formatters."""
         formatter_classes = [
             PlainTextFormatter,
             HTMLFormatter,
             MarkdownFormatter,
             SVGFormatter,
             PNGFormatter,
             PDFFormatter,
             JPEGFormatter,
             LatexFormatter,
             JSONFormatter,
             JavascriptFormatter
         ]
         d = {}
         for cls in formatter_classes:
             f = cls(parent=self)
             d[f.format_type] = f
         return d
 
     def format(self, obj, include=None, exclude=None):
         """Return a format data dict for an object.
 
         By default all format types will be computed.
 
         The following MIME types are currently implemented:
 
         * text/plain
         * text/html
         * text/markdown
         * text/latex
         * application/json
         * application/javascript
         * application/pdf
         * image/png
         * image/jpeg
         * image/svg+xml
 
         Parameters
         ----------
         obj : object
             The Python object whose format data will be computed.
         include : list or tuple, optional
             A list of format type strings (MIME types) to include in the
             format data dict. If this is set *only* the format types included
             in this list will be computed.
         exclude : list or tuple, optional
             A list of format type string (MIME types) to exclude in the format
             data dict. If this is set all format types will be computed,
             except for those included in this argument.
 
         Returns
         -------
         (format_dict, metadata_dict) : tuple of two dicts
         
             format_dict is a dictionary of key/value pairs, one of each format that was
             generated for the object. The keys are the format types, which
             will usually be MIME type strings and the values and JSON'able
             data structure containing the raw data for the representation in
             that format.
             
             metadata_dict is a dictionary of metadata about each mime-type output.
             Its keys will be a strict subset of the keys in format_dict.
         """
         format_dict = {}
         md_dict = {}
         
         if self.ipython_display_formatter(obj):
             # object handled itself, don't proceed
             return {}, {}
         
         for format_type, formatter in self.formatters.items():
             if include and format_type not in include:
                 continue
             if exclude and format_type in exclude:
                 continue
             
             md = None
             try:
                 data = formatter(obj)
             except:
                 # FIXME: log the exception
                 raise
             
             # formatters can return raw data or (data, metadata)
             if isinstance(data, tuple) and len(data) == 2:
                 data, md = data
             
             if data is not None:
                 format_dict[format_type] = data
             if md is not None:
                 md_dict[format_type] = md
             
         return format_dict, md_dict
 
     @property
     def format_types(self):
         """Return the format types (MIME types) of the active formatters."""
         return list(self.formatters.keys())
 
 
 #-----------------------------------------------------------------------------
 # Formatters for specific format types (text, html, svg, etc.)
 #-----------------------------------------------------------------------------
 
 
 def _safe_repr(obj):
     """Try to return a repr of an object
 
     always returns a string, at least.
     """
     try:
         return repr(obj)
     except Exception as e:
         return "un-repr-able object (%r)" % e
 
 
 class FormatterWarning(UserWarning):
     """Warning class for errors in formatters"""
 
 @decorator
 def catch_format_error(method, self, *args, **kwargs):
     """show traceback on failed format call"""
     try:
         r = method(self, *args, **kwargs)
     except NotImplementedError:
         # don't warn on NotImplementedErrors
         return None
     except Exception:
         exc_info = sys.exc_info()
         ip = get_ipython()
         if ip is not None:
             ip.showtraceback(exc_info)
         else:
             traceback.print_exception(*exc_info)
         return None
     return self._check_return(r, args[0])
 
 
 class FormatterABC(with_metaclass(abc.ABCMeta, object)):
     """ Abstract base class for Formatters.
 
     A formatter is a callable class that is responsible for computing the
     raw format data for a particular format type (MIME type). For example,
     an HTML formatter would have a format type of `text/html` and would return
     the HTML representation of the object when called.
     """
 
     # The format type of the data returned, usually a MIME type.
     format_type = 'text/plain'
 
     # Is the formatter enabled...
     enabled = True
     
     @abc.abstractmethod
     def __call__(self, obj):
         """Return a JSON'able representation of the object.
 
         If the object cannot be formatted by this formatter,
         warn and return None.
         """
         return repr(obj)
 
 
 def _mod_name_key(typ):
     """Return a (__module__, __name__) tuple for a type.
     
     Used as key in Formatter.deferred_printers.
     """
     module = getattr(typ, '__module__', None)
     name = getattr(typ, '__name__', None)
     return (module, name)
 
 
 def _get_type(obj):
     """Return the type of an instance (old and new-style)"""
     return getattr(obj, '__class__', None) or type(obj)
 
-_raise_key_error = object()
+
+_raise_key_error = Sentinel('_raise_key_error', __name__, 
+"""
+Special value to raise a KeyError
+
+Raise KeyError in `BaseFormatter.pop` if passed as the default value to `pop`
+""")
 
 
 class BaseFormatter(Configurable):
     """A base formatter class that is configurable.
 
     This formatter should usually be used as the base class of all formatters.
     It is a traited :class:`Configurable` class and includes an extensible
     API for users to determine how their objects are formatted. The following
     logic is used to find a function to format an given object.
 
     1. The object is introspected to see if it has a method with the name
        :attr:`print_method`. If is does, that object is passed to that method
        for formatting.
     2. If no print method is found, three internal dictionaries are consulted
        to find print method: :attr:`singleton_printers`, :attr:`type_printers`
        and :attr:`deferred_printers`.
 
     Users should use these dictionaries to register functions that will be
     used to compute the format data for their objects (if those objects don't
     have the special print methods). The easiest way of using these
     dictionaries is through the :meth:`for_type` and :meth:`for_type_by_name`
     methods.
 
     If no function/callable is found to compute the format data, ``None`` is
     returned and this format type is not used.
     """
 
     format_type = Unicode('text/plain')
     _return_type = string_types
 
     enabled = Bool(True, config=True)
 
     print_method = ObjectName('__repr__')
 
     # The singleton printers.
     # Maps the IDs of the builtin singleton objects to the format functions.
     singleton_printers = Dict(config=True)
 
     # The type-specific printers.
     # Map type objects to the format functions.
     type_printers = Dict(config=True)
 
     # The deferred-import type-specific printers.
     # Map (modulename, classname) pairs to the format functions.
     deferred_printers = Dict(config=True)
     
     @catch_format_error
     def __call__(self, obj):
         """Compute the format for an object."""
         if self.enabled:
             # lookup registered printer
             try:
                 printer = self.lookup(obj)
             except KeyError:
                 pass
             else:
                 return printer(obj)
             # Finally look for special method names
             method = _safe_get_formatter_method(obj, self.print_method)
             if method is not None:
                 return method()
             return None
         else:
             return None
     
     def __contains__(self, typ):
         """map in to lookup_by_type"""
         try:
             self.lookup_by_type(typ)
         except KeyError:
             return False
         else:
             return True
     
     def _check_return(self, r, obj):
         """Check that a return value is appropriate
         
         Return the value if so, None otherwise, warning if invalid.
         """
         if r is None or isinstance(r, self._return_type) or \
             (isinstance(r, tuple) and r and isinstance(r[0], self._return_type)):
             return r
         else:
             warnings.warn(
                 "%s formatter returned invalid type %s (expected %s) for object: %s" % \
                 (self.format_type, type(r), self._return_type, _safe_repr(obj)),
                 FormatterWarning
             )
     
     def lookup(self, obj):
         """Look up the formatter for a given instance.
         
         Parameters
         ----------
         obj  : object instance
 
         Returns
         -------
         f : callable
             The registered formatting callable for the type.
 
         Raises
         ------
         KeyError if the type has not been registered.
         """
         # look for singleton first
         obj_id = id(obj)
         if obj_id in self.singleton_printers:
             return self.singleton_printers[obj_id]
         # then lookup by type
         return self.lookup_by_type(_get_type(obj))
     
     def lookup_by_type(self, typ):
         """Look up the registered formatter for a type.
 
         Parameters
         ----------
         typ  : type or '__module__.__name__' string for a type
 
         Returns
         -------
         f : callable
             The registered formatting callable for the type.
 
         Raises
         ------
         KeyError if the type has not been registered.
         """
         if isinstance(typ, string_types):
             typ_key = tuple(typ.rsplit('.',1))
             if typ_key not in self.deferred_printers:
                 # We may have it cached in the type map. We will have to
                 # iterate over all of the types to check.
                 for cls in self.type_printers:
                     if _mod_name_key(cls) == typ_key:
                         return self.type_printers[cls]
             else:
                 return self.deferred_printers[typ_key]
         else:
             for cls in pretty._get_mro(typ):
                 if cls in self.type_printers or self._in_deferred_types(cls):
                     return self.type_printers[cls]
         
         # If we have reached here, the lookup failed.
         raise KeyError("No registered printer for {0!r}".format(typ))
 
     def for_type(self, typ, func=None):
         """Add a format function for a given type.
         
         Parameters
         -----------
         typ : type or '__module__.__name__' string for a type
             The class of the object that will be formatted using `func`.
         func : callable
             A callable for computing the format data.
             `func` will be called with the object to be formatted,
             and will return the raw data in this formatter's format.
             Subclasses may use a different call signature for the
             `func` argument.
             
             If `func` is None or not specified, there will be no change,
             only returning the current value.
         
         Returns
         -------
         oldfunc : callable
             The currently registered callable.
             If you are registering a new formatter,
             this will be the previous value (to enable restoring later).
         """
         # if string given, interpret as 'pkg.module.class_name'
         if isinstance(typ, string_types):
             type_module, type_name = typ.rsplit('.', 1)
             return self.for_type_by_name(type_module, type_name, func)
         
         try:
             oldfunc = self.lookup_by_type(typ)
         except KeyError:
             oldfunc = None
         
         if func is not None:
             self.type_printers[typ] = func
         
         return oldfunc
 
     def for_type_by_name(self, type_module, type_name, func=None):
         """Add a format function for a type specified by the full dotted
         module and name of the type, rather than the type of the object.
 
         Parameters
         ----------
         type_module : str
             The full dotted name of the module the type is defined in, like
             ``numpy``.
         type_name : str
             The name of the type (the class name), like ``dtype``
         func : callable
             A callable for computing the format data.
             `func` will be called with the object to be formatted,
             and will return the raw data in this formatter's format.
             Subclasses may use a different call signature for the
             `func` argument.
             
             If `func` is None or unspecified, there will be no change,
             only returning the current value.
         
         Returns
         -------
         oldfunc : callable
             The currently registered callable.
             If you are registering a new formatter,
             this will be the previous value (to enable restoring later).
         """
         key = (type_module, type_name)
         
         try:
             oldfunc = self.lookup_by_type("%s.%s" % key)
         except KeyError:
             oldfunc = None
         
         if func is not None:
             self.deferred_printers[key] = func
         return oldfunc
     
     def pop(self, typ, default=_raise_key_error):
         """Pop a formatter for the given type.
 
         Parameters
         ----------
         typ : type or '__module__.__name__' string for a type
         default : object
             value to be returned if no formatter is registered for typ.
 
         Returns
         -------
         obj : object
             The last registered object for the type.
 
         Raises
         ------
         KeyError if the type is not registered and default is not specified.
         """
         
         if isinstance(typ, string_types):
             typ_key = tuple(typ.rsplit('.',1))
             if typ_key not in self.deferred_printers:
                 # We may have it cached in the type map. We will have to
                 # iterate over all of the types to check.
                 for cls in self.type_printers:
                     if _mod_name_key(cls) == typ_key:
                         old = self.type_printers.pop(cls)
                         break
                 else:
                     old = default
             else:
                 old = self.deferred_printers.pop(typ_key)
         else:
             if typ in self.type_printers:
                 old = self.type_printers.pop(typ)
             else:
                 old = self.deferred_printers.pop(_mod_name_key(typ), default)
         if old is _raise_key_error:
             raise KeyError("No registered value for {0!r}".format(typ))
         return old
 
     def _in_deferred_types(self, cls):
         """
         Check if the given class is specified in the deferred type registry.
 
         Successful matches will be moved to the regular type registry for future use.
         """
         mod = getattr(cls, '__module__', None)
         name = getattr(cls, '__name__', None)
         key = (mod, name)
         if key in self.deferred_printers:
             # Move the printer over to the regular registry.
             printer = self.deferred_printers.pop(key)
             self.type_printers[cls] = printer
             return True
         return False
 
 
 class PlainTextFormatter(BaseFormatter):
     """The default pretty-printer.
 
     This uses :mod:`IPython.lib.pretty` to compute the format data of
     the object. If the object cannot be pretty printed, :func:`repr` is used.
     See the documentation of :mod:`IPython.lib.pretty` for details on
     how to write pretty printers.  Here is a simple example::
 
         def dtype_pprinter(obj, p, cycle):
             if cycle:
                 return p.text('dtype(...)')
             if hasattr(obj, 'fields'):
                 if obj.fields is None:
                     p.text(repr(obj))
                 else:
                     p.begin_group(7, 'dtype([')
                     for i, field in enumerate(obj.descr):
                         if i > 0:
                             p.text(',')
                             p.breakable()
                         p.pretty(field)
                     p.end_group(7, '])')
     """
 
     # The format type of data returned.
     format_type = Unicode('text/plain')
 
     # This subclass ignores this attribute as it always need to return
     # something.
     enabled = Bool(True, config=False)
     
     max_seq_length = Integer(pretty.MAX_SEQ_LENGTH, config=True,
         help="""Truncate large collections (lists, dicts, tuples, sets) to this size.
         
         Set to 0 to disable truncation.
         """
     )
     
     # Look for a _repr_pretty_ methods to use for pretty printing.
     print_method = ObjectName('_repr_pretty_')
 
     # Whether to pretty-print or not.
     pprint = Bool(True, config=True)
 
     # Whether to be verbose or not.
     verbose = Bool(False, config=True)
 
     # The maximum width.
     max_width = Integer(79, config=True)
 
     # The newline character.
     newline = Unicode('\n', config=True)
 
     # format-string for pprinting floats
     float_format = Unicode('%r')
     # setter for float precision, either int or direct format-string
     float_precision = CUnicode('', config=True)
 
     def _float_precision_changed(self, name, old, new):
         """float_precision changed, set float_format accordingly.
 
         float_precision can be set by int or str.
         This will set float_format, after interpreting input.
         If numpy has been imported, numpy print precision will also be set.
 
         integer `n` sets format to '%.nf', otherwise, format set directly.
 
         An empty string returns to defaults (repr for float, 8 for numpy).
 
         This parameter can be set via the '%precision' magic.
         """
 
         if '%' in new:
             # got explicit format string
             fmt = new
             try:
                 fmt%3.14159
             except Exception:
                 raise ValueError("Precision must be int or format string, not %r"%new)
         elif new:
             # otherwise, should be an int
             try:
                 i = int(new)
                 assert i >= 0
             except ValueError:
                 raise ValueError("Precision must be int or format string, not %r"%new)
             except AssertionError:
                 raise ValueError("int precision must be non-negative, not %r"%i)
 
             fmt = '%%.%if'%i
             if 'numpy' in sys.modules:
                 # set numpy precision if it has been imported
                 import numpy
                 numpy.set_printoptions(precision=i)
         else:
             # default back to repr
             fmt = '%r'
             if 'numpy' in sys.modules:
                 import numpy
                 # numpy default is 8
                 numpy.set_printoptions(precision=8)
         self.float_format = fmt
 
     # Use the default pretty printers from IPython.lib.pretty.
     def _singleton_printers_default(self):
         return pretty._singleton_pprinters.copy()
 
     def _type_printers_default(self):
         d = pretty._type_pprinters.copy()
         d[float] = lambda obj,p,cycle: p.text(self.float_format%obj)
         return d
 
     def _deferred_printers_default(self):
         return pretty._deferred_type_pprinters.copy()
 
     #### FormatterABC interface ####
 
     @catch_format_error
     def __call__(self, obj):
         """Compute the pretty representation of the object."""
         if not self.pprint:
             return repr(obj)
         else:
             # handle str and unicode on Python 2
             # io.StringIO only accepts unicode,
             # cStringIO doesn't handle unicode on py2,
             # StringIO allows str, unicode but only ascii str
             stream = pretty.CUnicodeIO()
             printer = pretty.RepresentationPrinter(stream, self.verbose,
                 self.max_width, self.newline,
                 max_seq_length=self.max_seq_length,
                 singleton_pprinters=self.singleton_printers,
                 type_pprinters=self.type_printers,
                 deferred_pprinters=self.deferred_printers)
             printer.pretty(obj)
             printer.flush()
             return stream.getvalue()
 
 
 class HTMLFormatter(BaseFormatter):
     """An HTML formatter.
 
     To define the callables that compute the HTML representation of your
     objects, define a :meth:`_repr_html_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be a valid HTML snippet that
     could be injected into an existing DOM. It should *not* include the
     ```<html>`` or ```<body>`` tags.
     """
     format_type = Unicode('text/html')
 
     print_method = ObjectName('_repr_html_')
 
 
 class MarkdownFormatter(BaseFormatter):
     """A Markdown formatter.
 
     To define the callables that compute the Markdown representation of your
     objects, define a :meth:`_repr_markdown_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be a valid Markdown.
     """
     format_type = Unicode('text/markdown')
 
     print_method = ObjectName('_repr_markdown_')
 
 class SVGFormatter(BaseFormatter):
     """An SVG formatter.
 
     To define the callables that compute the SVG representation of your
     objects, define a :meth:`_repr_svg_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be valid SVG enclosed in
     ```<svg>``` tags, that could be injected into an existing DOM. It should
     *not* include the ```<html>`` or ```<body>`` tags.
     """
     format_type = Unicode('image/svg+xml')
 
     print_method = ObjectName('_repr_svg_')
 
 
 class PNGFormatter(BaseFormatter):
     """A PNG formatter.
 
     To define the callables that compute the PNG representation of your
     objects, define a :meth:`_repr_png_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be raw PNG data, *not*
     base64 encoded.
     """
     format_type = Unicode('image/png')
 
     print_method = ObjectName('_repr_png_')
     
     _return_type = (bytes, unicode_type)
 
 
 class JPEGFormatter(BaseFormatter):
     """A JPEG formatter.
 
     To define the callables that compute the JPEG representation of your
     objects, define a :meth:`_repr_jpeg_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be raw JPEG data, *not*
     base64 encoded.
     """
     format_type = Unicode('image/jpeg')
 
     print_method = ObjectName('_repr_jpeg_')
 
     _return_type = (bytes, unicode_type)
 
 
 class LatexFormatter(BaseFormatter):
     """A LaTeX formatter.
 
     To define the callables that compute the LaTeX representation of your
     objects, define a :meth:`_repr_latex_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be a valid LaTeX equation,
     enclosed in either ```$```, ```$$``` or another LaTeX equation
     environment.
     """
     format_type = Unicode('text/latex')
 
     print_method = ObjectName('_repr_latex_')
 
 
 class JSONFormatter(BaseFormatter):
     """A JSON string formatter.
 
     To define the callables that compute the JSONable representation of
     your objects, define a :meth:`_repr_json_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be a JSONable list or dict.
     JSON scalars (None, number, string) are not allowed, only dict or list containers.
     """
     format_type = Unicode('application/json')
     _return_type = (list, dict)
 
     print_method = ObjectName('_repr_json_')
     
     def _check_return(self, r, obj):
         """Check that a return value is appropriate
         
         Return the value if so, None otherwise, warning if invalid.
         """
         if r is None:
             return
         md = None
         if isinstance(r, tuple):
             # unpack data, metadata tuple for type checking on first element
             r, md = r
         
         # handle deprecated JSON-as-string form from IPython < 3
         if isinstance(r, string_types):
             warnings.warn("JSON expects JSONable list/dict containers, not JSON strings",
             FormatterWarning)
             r = json.loads(r)
         
         if md is not None:
             # put the tuple back together
             r = (r, md)
         return super(JSONFormatter, self)._check_return(r, obj)
 
 
 class JavascriptFormatter(BaseFormatter):
     """A Javascript formatter.
 
     To define the callables that compute the Javascript representation of
     your objects, define a :meth:`_repr_javascript_` method or use the
     :meth:`for_type` or :meth:`for_type_by_name` methods to register functions
     that handle this.
 
     The return value of this formatter should be valid Javascript code and
     should *not* be enclosed in ```<script>``` tags.
     """
     format_type = Unicode('application/javascript')
 
     print_method = ObjectName('_repr_javascript_')
 
 
 class PDFFormatter(BaseFormatter):
     """A PDF formatter.
 
     To define the callables that compute the PDF representation of your
     objects, define a :meth:`_repr_pdf_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be raw PDF data, *not*
     base64 encoded.
     """
     format_type = Unicode('application/pdf')
 
     print_method = ObjectName('_repr_pdf_')
 
     _return_type = (bytes, unicode_type)
 
 class IPythonDisplayFormatter(BaseFormatter):
     """A Formatter for objects that know how to display themselves.
     
     To define the callables that compute the representation of your
     objects, define a :meth:`_ipython_display_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this. Unlike mime-type displays, this method should not return anything,
     instead calling any appropriate display methods itself.
     
     This display formatter has highest priority.
     If it fires, no other display formatter will be called.
     """
     print_method = ObjectName('_ipython_display_')
     _return_type = (type(None), bool)
     
 
     @catch_format_error
     def __call__(self, obj):
         """Compute the format for an object."""
         if self.enabled:
             # lookup registered printer
             try:
                 printer = self.lookup(obj)
             except KeyError:
                 pass
             else:
                 printer(obj)
                 return True
             # Finally look for special method names
             method = _safe_get_formatter_method(obj, self.print_method)
             if method is not None:
                 method()
                 return True
 
 
 FormatterABC.register(BaseFormatter)
 FormatterABC.register(PlainTextFormatter)
 FormatterABC.register(HTMLFormatter)
 FormatterABC.register(MarkdownFormatter)
 FormatterABC.register(SVGFormatter)
 FormatterABC.register(PNGFormatter)
 FormatterABC.register(PDFFormatter)
 FormatterABC.register(JPEGFormatter)
 FormatterABC.register(LatexFormatter)
 FormatterABC.register(JSONFormatter)
 FormatterABC.register(JavascriptFormatter)
 FormatterABC.register(IPythonDisplayFormatter)
 
 
 def format_display_data(obj, include=None, exclude=None):
     """Return a format data dict for an object.
 
     By default all format types will be computed.
 
     The following MIME types are currently implemented:
 
     * text/plain
     * text/html
     * text/markdown
     * text/latex
     * application/json
     * application/javascript
     * application/pdf
     * image/png
     * image/jpeg
     * image/svg+xml
 
     Parameters
     ----------
     obj : object
         The Python object whose format data will be computed.
 
     Returns
     -------
     format_dict : dict
         A dictionary of key/value pairs, one or each format that was
         generated for the object. The keys are the format types, which
         will usually be MIME type strings and the values and JSON'able
         data structure containing the raw data for the representation in
         that format.
     include : list or tuple, optional
         A list of format type strings (MIME types) to include in the
         format data dict. If this is set *only* the format types included
         in this list will be computed.
     exclude : list or tuple, optional
         A list of format type string (MIME types) to exclue in the format
         data dict. If this is set all format types will be computed,
         except for those included in this argument.
     """
     from IPython.core.interactiveshell import InteractiveShell
 
     InteractiveShell.instance().display_formatter.format(
         obj,
         include,
         exclude
     )
 

IPython/utils/signatures.py

@@ -1,816 +1,832 b''
 """Function signature objects for callables.
 
 Back port of Python 3.3's function signature tools from the inspect module,
 modified to be compatible with Python 2.7 and 3.2+.
 """
 
 #-----------------------------------------------------------------------------
 #  Python 3.3 stdlib inspect.py is public domain
 # 
 #  Backports Copyright (C) 2013 Aaron Iles
 #  Used under Apache License Version 2.0
 #
 #  Further Changes are Copyright (C) 2013 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 absolute_import, division, print_function
 import itertools
 import functools
 import re
 import types
 
 
 # patch for single-file
 # we don't support 2.6, so we can just import OrderedDict
 from collections import OrderedDict
 
 __version__ = '0.3'
 # end patch
 
 __all__ = ['BoundArguments', 'Parameter', 'Signature', 'signature']
 
 
 _WrapperDescriptor = type(type.__call__)
 _MethodWrapper = type(all.__call__)
 
 _NonUserDefinedCallables = (_WrapperDescriptor,
                             _MethodWrapper,
                             types.BuiltinFunctionType)
 
 
 def formatannotation(annotation, base_module=None):
     if isinstance(annotation, type):
         if annotation.__module__ in ('builtins', '__builtin__', base_module):
             return annotation.__name__
         return annotation.__module__+'.'+annotation.__name__
     return repr(annotation)
 
 
 def _get_user_defined_method(cls, method_name, *nested):
     try:
         if cls is type:
             return
         meth = getattr(cls, method_name)
         for name in nested:
             meth = getattr(meth, name, meth)
     except AttributeError:
         return
     else:
         if not isinstance(meth, _NonUserDefinedCallables):
             # Once '__signature__' will be added to 'C'-level
             # callables, this check won't be necessary
             return meth
 
 
 def signature(obj):
     '''Get a signature object for the passed callable.'''
 
     if not callable(obj):
         raise TypeError('{0!r} is not a callable object'.format(obj))
 
     if isinstance(obj, types.MethodType):
         if obj.__self__ is None:
             # Unbound method - treat it as a function (no distinction in Py 3)
             obj = obj.__func__
         else:
             # Bound method: trim off the first parameter (typically self or cls)
             sig = signature(obj.__func__)
             return sig.replace(parameters=tuple(sig.parameters.values())[1:])
 
     try:
         sig = obj.__signature__
     except AttributeError:
         pass
     else:
         if sig is not None:
             return sig
 
     try:
         # Was this function wrapped by a decorator?
         wrapped = obj.__wrapped__
     except AttributeError:
         pass
     else:
         return signature(wrapped)
 
     if isinstance(obj, types.FunctionType):
         return Signature.from_function(obj)
 
     if isinstance(obj, functools.partial):
         sig = signature(obj.func)
 
         new_params = OrderedDict(sig.parameters.items())
 
         partial_args = obj.args or ()
         partial_keywords = obj.keywords or {}
         try:
             ba = sig.bind_partial(*partial_args, **partial_keywords)
         except TypeError as ex:
             msg = 'partial object {0!r} has incorrect arguments'.format(obj)
             raise ValueError(msg)
 
         for arg_name, arg_value in ba.arguments.items():
             param = new_params[arg_name]
             if arg_name in partial_keywords:
                 # We set a new default value, because the following code
                 # is correct:
                 #
                 #   >>> def foo(a): print(a)
                 #   >>> print(partial(partial(foo, a=10), a=20)())
                 #   20
                 #   >>> print(partial(partial(foo, a=10), a=20)(a=30))
                 #   30
                 #
                 # So, with 'partial' objects, passing a keyword argument is
                 # like setting a new default value for the corresponding
                 # parameter
                 #
                 # We also mark this parameter with '_partial_kwarg'
                 # flag.  Later, in '_bind', the 'default' value of this
                 # parameter will be added to 'kwargs', to simulate
                 # the 'functools.partial' real call.
                 new_params[arg_name] = param.replace(default=arg_value,
                                                      _partial_kwarg=True)
 
             elif (param.kind not in (_VAR_KEYWORD, _VAR_POSITIONAL) and
                             not param._partial_kwarg):
                 new_params.pop(arg_name)
 
         return sig.replace(parameters=new_params.values())
 
     sig = None
     if isinstance(obj, type):
         # obj is a class or a metaclass
 
         # First, let's see if it has an overloaded __call__ defined
         # in its metaclass
         call = _get_user_defined_method(type(obj), '__call__')
         if call is not None:
             sig = signature(call)
         else:
             # Now we check if the 'obj' class has a '__new__' method
             new = _get_user_defined_method(obj, '__new__')
             if new is not None:
                 sig = signature(new)
             else:
                 # Finally, we should have at least __init__ implemented
                 init = _get_user_defined_method(obj, '__init__')
                 if init is not None:
                     sig = signature(init)
     elif not isinstance(obj, _NonUserDefinedCallables):
         # An object with __call__
         # We also check that the 'obj' is not an instance of
         # _WrapperDescriptor or _MethodWrapper to avoid
         # infinite recursion (and even potential segfault)
         call = _get_user_defined_method(type(obj), '__call__', 'im_func')
         if call is not None:
             sig = signature(call)
 
     if sig is not None:
         return sig
 
     if isinstance(obj, types.BuiltinFunctionType):
         # Raise a nicer error message for builtins
         msg = 'no signature found for builtin function {0!r}'.format(obj)
         raise ValueError(msg)
 
     raise ValueError('callable {0!r} is not supported by signature'.format(obj))
 
 
 class _void(object):
     '''A private marker - used in Parameter & Signature'''
 
 
 class _empty(object):
     pass
 
 
 class _ParameterKind(int):
     def __new__(self, *args, **kwargs):
         obj = int.__new__(self, *args)
         obj._name = kwargs['name']
         return obj
 
     def __str__(self):
         return self._name
 
     def __repr__(self):
         return '<_ParameterKind: {0!r}>'.format(self._name)
 
 
 _POSITIONAL_ONLY        = _ParameterKind(0, name='POSITIONAL_ONLY')
 _POSITIONAL_OR_KEYWORD  = _ParameterKind(1, name='POSITIONAL_OR_KEYWORD')
 _VAR_POSITIONAL         = _ParameterKind(2, name='VAR_POSITIONAL')
 _KEYWORD_ONLY           = _ParameterKind(3, name='KEYWORD_ONLY')
 _VAR_KEYWORD            = _ParameterKind(4, name='VAR_KEYWORD')
 
 
 class Parameter(object):
     '''Represents a parameter in a function signature.
 
     Has the following public attributes:
 
     * name : str
         The name of the parameter as a string.
     * default : object
         The default value for the parameter if specified.  If the
         parameter has no default value, this attribute is not set.
     * annotation
         The annotation for the parameter if specified.  If the
         parameter has no annotation, this attribute is not set.
     * kind : str
         Describes how argument values are bound to the parameter.
         Possible values: `Parameter.POSITIONAL_ONLY`,
         `Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
         `Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
     '''
 
     __slots__ = ('_name', '_kind', '_default', '_annotation', '_partial_kwarg')
 
     POSITIONAL_ONLY         = _POSITIONAL_ONLY
     POSITIONAL_OR_KEYWORD   = _POSITIONAL_OR_KEYWORD
     VAR_POSITIONAL          = _VAR_POSITIONAL
     KEYWORD_ONLY            = _KEYWORD_ONLY
     VAR_KEYWORD             = _VAR_KEYWORD
 
     empty = _empty
 
     def __init__(self, name, kind, default=_empty, annotation=_empty,
                  _partial_kwarg=False):
 
         if kind not in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD,
                         _VAR_POSITIONAL, _KEYWORD_ONLY, _VAR_KEYWORD):
             raise ValueError("invalid value for 'Parameter.kind' attribute")
         self._kind = kind
 
         if default is not _empty:
             if kind in (_VAR_POSITIONAL, _VAR_KEYWORD):
                 msg = '{0} parameters cannot have default values'.format(kind)
                 raise ValueError(msg)
         self._default = default
         self._annotation = annotation
 
         if name is None:
             if kind != _POSITIONAL_ONLY:
                 raise ValueError("None is not a valid name for a "
                                  "non-positional-only parameter")
             self._name = name
         else:
             name = str(name)
             if kind != _POSITIONAL_ONLY and not re.match(r'[a-z_]\w*$', name, re.I):
                 msg = '{0!r} is not a valid parameter name'.format(name)
                 raise ValueError(msg)
             self._name = name
 
         self._partial_kwarg = _partial_kwarg
 
     @property
     def name(self):
         return self._name
 
     @property
     def default(self):
         return self._default
 
     @property
     def annotation(self):
         return self._annotation
 
     @property
     def kind(self):
         return self._kind
 
     def replace(self, name=_void, kind=_void, annotation=_void,
                 default=_void, _partial_kwarg=_void):
         '''Creates a customized copy of the Parameter.'''
 
         if name is _void:
             name = self._name
 
         if kind is _void:
             kind = self._kind
 
         if annotation is _void:
             annotation = self._annotation
 
         if default is _void:
             default = self._default
 
         if _partial_kwarg is _void:
             _partial_kwarg = self._partial_kwarg
 
         return type(self)(name, kind, default=default, annotation=annotation,
                           _partial_kwarg=_partial_kwarg)
 
     def __str__(self):
         kind = self.kind
 
         formatted = self._name
         if kind == _POSITIONAL_ONLY:
             if formatted is None:
                 formatted = ''
             formatted = '<{0}>'.format(formatted)
 
         # Add annotation and default value
         if self._annotation is not _empty:
             formatted = '{0}:{1}'.format(formatted,
                                        formatannotation(self._annotation))
 
         if self._default is not _empty:
             formatted = '{0}={1}'.format(formatted, repr(self._default))
 
         if kind == _VAR_POSITIONAL:
             formatted = '*' + formatted
         elif kind == _VAR_KEYWORD:
             formatted = '**' + formatted
 
         return formatted
 
     def __repr__(self):
         return '<{0} at {1:#x} {2!r}>'.format(self.__class__.__name__,
                                            id(self), self.name)
 
     def __hash__(self):
         msg = "unhashable type: '{0}'".format(self.__class__.__name__)
         raise TypeError(msg)
 
     def __eq__(self, other):
         return (issubclass(other.__class__, Parameter) and
                 self._name == other._name and
                 self._kind == other._kind and
                 self._default == other._default and
                 self._annotation == other._annotation)
 
     def __ne__(self, other):
         return not self.__eq__(other)
 
 
 class BoundArguments(object):
     '''Result of :meth:`Signature.bind` call.  Holds the mapping of arguments
     to the function's parameters.
 
     Has the following public attributes:
 
     arguments : :class:`collections.OrderedDict`
       An ordered mutable mapping of parameters' names to arguments' values.
       Does not contain arguments' default values.
     signature : :class:`Signature`
       The Signature object that created this instance.
     args : tuple
       Tuple of positional arguments values.
     kwargs : dict
       Dict of keyword arguments values.
     '''
 
     def __init__(self, signature, arguments):
         self.arguments = arguments
         self._signature = signature
 
     @property
     def signature(self):
         return self._signature
 
     @property
     def args(self):
         args = []
         for param_name, param in self._signature.parameters.items():
             if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
                                                     param._partial_kwarg):
                 # Keyword arguments mapped by 'functools.partial'
                 # (Parameter._partial_kwarg is True) are mapped
                 # in 'BoundArguments.kwargs', along with VAR_KEYWORD &
                 # KEYWORD_ONLY
                 break
 
             try:
                 arg = self.arguments[param_name]
             except KeyError:
                 # We're done here. Other arguments
                 # will be mapped in 'BoundArguments.kwargs'
                 break
             else:
                 if param.kind == _VAR_POSITIONAL:
                     # *args
                     args.extend(arg)
                 else:
                     # plain argument
                     args.append(arg)
 
         return tuple(args)
 
     @property
     def kwargs(self):
         kwargs = {}
         kwargs_started = False
         for param_name, param in self._signature.parameters.items():
             if not kwargs_started:
                 if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
                                                 param._partial_kwarg):
                     kwargs_started = True
                 else:
                     if param_name not in self.arguments:
                         kwargs_started = True
                         continue
 
             if not kwargs_started:
                 continue
 
             try:
                 arg = self.arguments[param_name]
             except KeyError:
                 pass
             else:
                 if param.kind == _VAR_KEYWORD:
                     # **kwargs
                     kwargs.update(arg)
                 else:
                     # plain keyword argument
                     kwargs[param_name] = arg
 
         return kwargs
 
     def __hash__(self):
         msg = "unhashable type: '{0}'".format(self.__class__.__name__)
         raise TypeError(msg)
 
     def __eq__(self, other):
         return (issubclass(other.__class__, BoundArguments) and
                 self.signature == other.signature and
                 self.arguments == other.arguments)
 
     def __ne__(self, other):
         return not self.__eq__(other)
 
 
 class Signature(object):
     '''A Signature object represents the overall signature of a function.
     It stores a Parameter object for each parameter accepted by the
     function, as well as information specific to the function itself.
 
     A Signature object has the following public attributes:
 
     parameters : :class:`collections.OrderedDict`
       An ordered mapping of parameters' names to the corresponding
       Parameter objects (keyword-only arguments are in the same order
       as listed in `code.co_varnames`).
     return_annotation
       The annotation for the return type of the function if specified.
       If the function has no annotation for its return type, this
       attribute is not set.
     '''
 
     __slots__ = ('_return_annotation', '_parameters')
 
     _parameter_cls = Parameter
     _bound_arguments_cls = BoundArguments
 
     empty = _empty
 
     def __init__(self, parameters=None, return_annotation=_empty,
                  __validate_parameters__=True):
         '''Constructs Signature from the given list of Parameter
         objects and 'return_annotation'.  All arguments are optional.
         '''
 
         if parameters is None:
             params = OrderedDict()
         else:
             if __validate_parameters__:
                 params = OrderedDict()
                 top_kind = _POSITIONAL_ONLY
 
                 for idx, param in enumerate(parameters):
                     kind = param.kind
                     if kind < top_kind:
                         msg = 'wrong parameter order: {0} before {1}'
                         msg = msg.format(top_kind, param.kind)
                         raise ValueError(msg)
                     else:
                         top_kind = kind
 
                     name = param.name
                     if name is None:
                         name = str(idx)
                         param = param.replace(name=name)
 
                     if name in params:
                         msg = 'duplicate parameter name: {0!r}'.format(name)
                         raise ValueError(msg)
                     params[name] = param
             else:
                 params = OrderedDict(((param.name, param)
                                                 for param in parameters))
 
         self._parameters = params
         self._return_annotation = return_annotation
 
     @classmethod
     def from_function(cls, func):
         '''Constructs Signature for the given python function'''
 
         if not isinstance(func, types.FunctionType):
             raise TypeError('{0!r} is not a Python function'.format(func))
 
         Parameter = cls._parameter_cls
 
         # Parameter information.
         func_code = func.__code__
         pos_count = func_code.co_argcount
         arg_names = func_code.co_varnames
         positional = tuple(arg_names[:pos_count])
         keyword_only_count = getattr(func_code, 'co_kwonlyargcount', 0)
         keyword_only = arg_names[pos_count:(pos_count + keyword_only_count)]
         annotations = getattr(func, '__annotations__', {})
         defaults = func.__defaults__
         kwdefaults = getattr(func, '__kwdefaults__', None)
 
         if defaults:
             pos_default_count = len(defaults)
         else:
             pos_default_count = 0
 
         parameters = []
 
         # Non-keyword-only parameters w/o defaults.
         non_default_count = pos_count - pos_default_count
         for name in positional[:non_default_count]:
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_POSITIONAL_OR_KEYWORD))
 
         # ... w/ defaults.
         for offset, name in enumerate(positional[non_default_count:]):
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_POSITIONAL_OR_KEYWORD,
                                         default=defaults[offset]))
 
         # *args
         if func_code.co_flags & 0x04:
             name = arg_names[pos_count + keyword_only_count]
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_VAR_POSITIONAL))
 
         # Keyword-only parameters.
         for name in keyword_only:
             default = _empty
             if kwdefaults is not None:
                 default = kwdefaults.get(name, _empty)
 
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_KEYWORD_ONLY,
                                         default=default))
         # **kwargs
         if func_code.co_flags & 0x08:
             index = pos_count + keyword_only_count
             if func_code.co_flags & 0x04:
                 index += 1
 
             name = arg_names[index]
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_VAR_KEYWORD))
 
         return cls(parameters,
                    return_annotation=annotations.get('return', _empty),
                    __validate_parameters__=False)
 
     @property
     def parameters(self):
         try:
             return types.MappingProxyType(self._parameters)
         except AttributeError:
             return OrderedDict(self._parameters.items())
 
     @property
     def return_annotation(self):
         return self._return_annotation
 
     def replace(self, parameters=_void, return_annotation=_void):
         '''Creates a customized copy of the Signature.
         Pass 'parameters' and/or 'return_annotation' arguments
         to override them in the new copy.
         '''
 
         if parameters is _void:
             parameters = self.parameters.values()
 
         if return_annotation is _void:
             return_annotation = self._return_annotation
 
         return type(self)(parameters,
                           return_annotation=return_annotation)
 
     def __hash__(self):
         msg = "unhashable type: '{0}'".format(self.__class__.__name__)
         raise TypeError(msg)
 
     def __eq__(self, other):
         if (not issubclass(type(other), Signature) or
                     self.return_annotation != other.return_annotation or
                     len(self.parameters) != len(other.parameters)):
             return False
 
         other_positions = dict((param, idx)
                            for idx, param in enumerate(other.parameters.keys()))
 
         for idx, (param_name, param) in enumerate(self.parameters.items()):
             if param.kind == _KEYWORD_ONLY:
                 try:
                     other_param = other.parameters[param_name]
                 except KeyError:
                     return False
                 else:
                     if param != other_param:
                         return False
             else:
                 try:
                     other_idx = other_positions[param_name]
                 except KeyError:
                     return False
                 else:
                     if (idx != other_idx or
                                     param != other.parameters[param_name]):
                         return False
 
         return True
 
     def __ne__(self, other):
         return not self.__eq__(other)
 
     def _bind(self, args, kwargs, partial=False):
         '''Private method.  Don't use directly.'''
 
         arguments = OrderedDict()
 
         parameters = iter(self.parameters.values())
         parameters_ex = ()
         arg_vals = iter(args)
 
         if partial:
             # Support for binding arguments to 'functools.partial' objects.
             # See 'functools.partial' case in 'signature()' implementation
             # for details.
             for param_name, param in self.parameters.items():
                 if (param._partial_kwarg and param_name not in kwargs):
                     # Simulating 'functools.partial' behavior
                     kwargs[param_name] = param.default
 
         while True:
             # Let's iterate through the positional arguments and corresponding
             # parameters
             try:
                 arg_val = next(arg_vals)
             except StopIteration:
                 # No more positional arguments
                 try:
                     param = next(parameters)
                 except StopIteration:
                     # No more parameters. That's it. Just need to check that
                     # we have no `kwargs` after this while loop
                     break
                 else:
                     if param.kind == _VAR_POSITIONAL:
                         # That's OK, just empty *args.  Let's start parsing
                         # kwargs
                         break
                     elif param.name in kwargs:
                         if param.kind == _POSITIONAL_ONLY:
                             msg = '{arg!r} parameter is positional only, ' \
                                   'but was passed as a keyword'
                             msg = msg.format(arg=param.name)
                             raise TypeError(msg)
                         parameters_ex = (param,)
                         break
                     elif (param.kind == _VAR_KEYWORD or
                                                 param.default is not _empty):
                         # That's fine too - we have a default value for this
                         # parameter.  So, lets start parsing `kwargs`, starting
                         # with the current parameter
                         parameters_ex = (param,)
                         break
                     else:
                         if partial:
                             parameters_ex = (param,)
                             break
                         else:
                             msg = '{arg!r} parameter lacking default value'
                             msg = msg.format(arg=param.name)
                             raise TypeError(msg)
             else:
                 # We have a positional argument to process
                 try:
                     param = next(parameters)
                 except StopIteration:
                     raise TypeError('too many positional arguments')
                 else:
                     if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
                         # Looks like we have no parameter for this positional
                         # argument
                         raise TypeError('too many positional arguments')
 
                     if param.kind == _VAR_POSITIONAL:
                         # We have an '*args'-like argument, let's fill it with
                         # all positional arguments we have left and move on to
                         # the next phase
                         values = [arg_val]
                         values.extend(arg_vals)
                         arguments[param.name] = tuple(values)
                         break
 
                     if param.name in kwargs:
                         raise TypeError('multiple values for argument '
                                         '{arg!r}'.format(arg=param.name))
 
                     arguments[param.name] = arg_val
 
         # Now, we iterate through the remaining parameters to process
         # keyword arguments
         kwargs_param = None
         for param in itertools.chain(parameters_ex, parameters):
             if param.kind == _POSITIONAL_ONLY:
                 # This should never happen in case of a properly built
                 # Signature object (but let's have this check here
                 # to ensure correct behaviour just in case)
                 raise TypeError('{arg!r} parameter is positional only, '
                                 'but was passed as a keyword'. \
                                 format(arg=param.name))
 
             if param.kind == _VAR_KEYWORD:
                 # Memorize that we have a '**kwargs'-like parameter
                 kwargs_param = param
                 continue
 
             param_name = param.name
             try:
                 arg_val = kwargs.pop(param_name)
             except KeyError:
                 # We have no value for this parameter.  It's fine though,
                 # if it has a default value, or it is an '*args'-like
                 # parameter, left alone by the processing of positional
                 # arguments.
                 if (not partial and param.kind != _VAR_POSITIONAL and
                                                     param.default is _empty):
                     raise TypeError('{arg!r} parameter lacking default value'. \
                                     format(arg=param_name))
 
             else:
                 arguments[param_name] = arg_val
 
         if kwargs:
             if kwargs_param is not None:
                 # Process our '**kwargs'-like parameter
                 arguments[kwargs_param.name] = kwargs
             else:
                 raise TypeError('too many keyword arguments')
 
         return self._bound_arguments_cls(self, arguments)
 
     def bind(self, *args, **kwargs):
         '''Get a :class:`BoundArguments` object, that maps the passed `args`
         and `kwargs` to the function's signature.  Raises :exc:`TypeError`
         if the passed arguments can not be bound.
         '''
         return self._bind(args, kwargs)
 
     def bind_partial(self, *args, **kwargs):
         '''Get a :class:`BoundArguments` object, that partially maps the
         passed `args` and `kwargs` to the function's signature.
         Raises :exc:`TypeError` if the passed arguments can not be bound.
         '''
         return self._bind(args, kwargs, partial=True)
 
     def __str__(self):
         result = []
         render_kw_only_separator = True
         for idx, param in enumerate(self.parameters.values()):
             formatted = str(param)
 
             kind = param.kind
             if kind == _VAR_POSITIONAL:
                 # OK, we have an '*args'-like parameter, so we won't need
                 # a '*' to separate keyword-only arguments
                 render_kw_only_separator = False
             elif kind == _KEYWORD_ONLY and render_kw_only_separator:
                 # We have a keyword-only parameter to render and we haven't
                 # rendered an '*args'-like parameter before, so add a '*'
                 # separator to the parameters list ("foo(arg1, *, arg2)" case)
                 result.append('*')
                 # This condition should be only triggered once, so
                 # reset the flag
                 render_kw_only_separator = False
 
             result.append(formatted)
 
         rendered = '({0})'.format(', '.join(result))
 
         if self.return_annotation is not _empty:
             anno = formatannotation(self.return_annotation)
             rendered += ' -> {0}'.format(anno)
 
         return rendered
+
+## Fake unique value as KWargs, in some places.
+# do not put docstrings here or they will appear 
+# on created fake values.
+class Sentinel(object):
+
+    def __init__(self, name, module, docstring=None):
+        self.name = name
+        self.module = module
+        if docstring:
+            self.__doc__ = docstring
+
+
+    def __repr__(self):
+        return str(self.module)+'.'+self.name
+

jupyter_nbformat/__init__.py

@@ -1,178 +1,167 b''
 """The IPython notebook format
 
 Use this module to read or write notebook files as particular nbformat versions.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 import io
 from IPython.utils import py3compat
 
 from IPython.utils.log import get_logger
 
 from . import v1
 from . import v2
 from . import v3
 from . import v4
+from IPython.utils.signatures import Sentinel
 
 __all__ = ['versions', 'validate', 'ValidationError', 'convert', 'from_dict',
            'NotebookNode', 'current_nbformat', 'current_nbformat_minor',
            'NBFormatError', 'NO_CONVERT', 'reads', 'read', 'writes', 'write']
 
 versions = {
     1: v1,
     2: v2,
     3: v3,
     4: v4,
 }
 
 from .validator import validate, ValidationError
 from .converter import convert
 from . import reader
 from .notebooknode import from_dict, NotebookNode
 
 from .v4 import (
     nbformat as current_nbformat,
     nbformat_minor as current_nbformat_minor,
 )
 
 class NBFormatError(ValueError):
     pass
 
 # no-conversion singleton
-class Sentinel(object):
-
-    def __init__(self, name, module, docstring=None):
-        self.name = name
-        self.module = module
-        if docstring:
-            self.__doc__ = docstring
-
-
-    def __repr__(self):
-        return str(self.module)+'.'+self.name
-
 NO_CONVERT = Sentinel('NO_CONVERT', __name__,
     """Value to prevent nbformat to convert notebooks to most recent version.
     """)
 
 
 def reads(s, as_version, **kwargs):
     """Read a notebook from a string and return the NotebookNode object as the given version.
     
     The string can contain a notebook of any version.
     The notebook will be returned `as_version`, converting, if necessary.
 
     Notebook format errors will be logged.
 
     Parameters
     ----------
     s : unicode
         The raw unicode string to read the notebook from.
     as_version : int
         The version of the notebook format to return.
         The notebook will be converted, if necessary.
         Pass nbformat.NO_CONVERT to prevent conversion.
 
     Returns
     -------
     nb : NotebookNode
         The notebook that was read.
     """
     nb = reader.reads(s, **kwargs)
     if as_version is not NO_CONVERT:
         nb = convert(nb, as_version)
     try:
         validate(nb)
     except ValidationError as e:
         get_logger().error("Notebook JSON is invalid: %s", e)
     return nb
 
 
 def writes(nb, version=NO_CONVERT, **kwargs):
     """Write a notebook to a string in a given format in the given nbformat version.
 
     Any notebook format errors will be logged.
 
     Parameters
     ----------
     nb : NotebookNode
         The notebook to write.
     version : int, optional
         The nbformat version to write.
         If unspecified, or specified as nbformat.NO_CONVERT,
         the notebook's own version will be used and no conversion performed.
 
     Returns
     -------
     s : unicode
         The notebook as a JSON string.
     """
     if version is not NO_CONVERT:
         nb = convert(nb, version)
     else:
         version, _ = reader.get_version(nb)
     try:
         validate(nb)
     except ValidationError as e:
         get_logger().error("Notebook JSON is invalid: %s", e)
     return versions[version].writes_json(nb, **kwargs)
 
 
 def read(fp, as_version, **kwargs):
     """Read a notebook from a file as a NotebookNode of the given version.
 
     The string can contain a notebook of any version.
     The notebook will be returned `as_version`, converting, if necessary.
 
     Notebook format errors will be logged.
 
     Parameters
     ----------
     fp : file or str
         Any file-like object with a read method, or a path to a file.
     as_version: int
         The version of the notebook format to return.
         The notebook will be converted, if necessary.
         Pass nbformat.NO_CONVERT to prevent conversion.
 
     Returns
     -------
     nb : NotebookNode
         The notebook that was read.
     """
     if isinstance(fp, py3compat.string_types):
         with io.open(fp, encoding='utf-8') as f:
             return read(f, as_version, **kwargs)
 
     return reads(fp.read(), as_version, **kwargs)
 
 
 def write(nb, fp, version=NO_CONVERT, **kwargs):
     """Write a notebook to a file in a given nbformat version.
     
     The file-like object must accept unicode input.
     
     Parameters
     ----------
     nb : NotebookNode
         The notebook to write.
     fp : file or str
         Any file-like object with a write method that accepts unicode, or
         a path to write a file.
     version : int, optional
         The nbformat version to write.
         If nb is not this version, it will be converted.
         If unspecified, or specified as nbformat.NO_CONVERT,
         the notebook's own version will be used and no conversion performed.
     """
     if isinstance(fp, py3compat.string_types):
         with io.open(fp, 'w', encoding='utf-8') as f:
             return write(nb, f, version=version, **kwargs)
 
     s = writes(nb, version, **kwargs)
     if isinstance(s, bytes):
         s = s.decode('utf8')
     fp.write(s)
     if not s.endswith(u'\n'):
         fp.write(u'\n')

traitlets/traitlets.py

@@ -1,1874 +1,1878 b''
 # 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.
 
 Inheritance diagram:
 
 .. inheritance-diagram:: IPython.utils.traitlets
    :parts: 3
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 #
 # Adapted from enthought.traits, Copyright (c) Enthought, Inc.,
 # also under the terms of the Modified BSD License.
 
 import contextlib
 import inspect
 import re
 import sys
 import types
 from types import FunctionType
 try:
     from types import ClassType, InstanceType
     ClassTypes = (ClassType, type)
 except:
     ClassTypes = (type,)
 from warnings import warn
 
 from IPython.utils import py3compat
 from IPython.utils import eventful
 from IPython.utils.getargspec import getargspec
+from IPython.utils.signatures import Sentinel
 from IPython.utils.importstring import import_item
 from IPython.utils.py3compat import iteritems, string_types
 from IPython.testing.skipdoctest import skip_doctest
 
 SequenceTypes = (list, tuple, set, frozenset)
 
 #-----------------------------------------------------------------------------
 # Basic classes
 #-----------------------------------------------------------------------------
 
 
-class NoDefaultSpecified ( object ): pass
-NoDefaultSpecified = NoDefaultSpecified()
+NoDefaultSpecified = Sentinel('NoDefaultSpecified', __name__, 
+'''
+Used in Traitlets to specify that no defaults are set in kwargs
+'''
+)
 
 
 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, py3compat.string_types ):
         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 (not py3compat.PY3) and the_type is InstanceType:
         # Old-style class.
         the_type = obj.__class__
     msg = '%r %r' % (obj, the_type)
     return msg
 
 
 def is_trait(t):
     """ Returns whether the given value is an instance or subclass of TraitType.
     """
     return (isinstance(t, TraitType) or
             (isinstance(t, type) and issubclass(t, TraitType)))
 
 
 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, string_types):
         return [name]
     elif name is None:
         return ['anytrait']
     elif isinstance(name, (list, tuple)):
         for n in name:
             assert isinstance(n, string_types), "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
 
 def _validate_link(*tuples):
     """Validate arguments for traitlet link functions"""
     for t in tuples:
         if not len(t) == 2:
             raise TypeError("Each linked traitlet must be specified as (HasTraits, 'trait_name'), not %r" % t)
         obj, trait_name = t
         if not isinstance(obj, HasTraits):
             raise TypeError("Each object must be HasTraits, not %r" % type(obj))
         if not trait_name in obj.traits():
             raise TypeError("%r has no trait %r" % (obj, trait_name))
 
 @skip_doctest
 class link(object):
     """Link traits from different objects together so they remain in sync.
 
     Parameters
     ----------
     *args : pairs of objects/attributes
 
     Examples
     --------
 
     >>> c = link((obj1, 'value'), (obj2, 'value'), (obj3, 'value'))
     >>> obj1.value = 5 # updates other objects as well
     """
     updating = False
     def __init__(self, *args):
         if len(args) < 2:
             raise TypeError('At least two traitlets must be provided.')
         _validate_link(*args)
 
         self.objects = {}
 
         initial = getattr(args[0][0], args[0][1])
         for obj, attr in args:
             setattr(obj, attr, initial)
 
             callback = self._make_closure(obj, attr)
             obj.on_trait_change(callback, attr)
             self.objects[(obj, attr)] = callback
 
     @contextlib.contextmanager
     def _busy_updating(self):
         self.updating = True
         try:
             yield
         finally:
             self.updating = False
 
     def _make_closure(self, sending_obj, sending_attr):
         def update(name, old, new):
             self._update(sending_obj, sending_attr, new)
         return update
 
     def _update(self, sending_obj, sending_attr, new):
         if self.updating:
             return
         with self._busy_updating():
             for obj, attr in self.objects.keys():
                 setattr(obj, attr, new)
 
     def unlink(self):
         for key, callback in self.objects.items():
             (obj, attr) = key
             obj.on_trait_change(callback, attr, remove=True)
 
 @skip_doctest
 class directional_link(object):
     """Link the trait of a source object with traits of target objects.
 
     Parameters
     ----------
     source : pair of object, name
     targets : pairs of objects/attributes
 
     Examples
     --------
 
     >>> c = directional_link((src, 'value'), (tgt1, 'value'), (tgt2, 'value'))
     >>> src.value = 5  # updates target objects
     >>> tgt1.value = 6 # does not update other objects
     """
     updating = False
 
     def __init__(self, source, *targets):
         if len(targets) < 1:
             raise TypeError('At least two traitlets must be provided.')
         _validate_link(source, *targets)
         self.source = source
         self.targets = targets
 
         # Update current value
         src_attr_value = getattr(source[0], source[1])
         for obj, attr in targets:
             setattr(obj, attr, src_attr_value)
 
         # Wire
         self.source[0].on_trait_change(self._update, self.source[1])
 
     @contextlib.contextmanager
     def _busy_updating(self):
         self.updating = True
         try:
             yield
         finally:
             self.updating = False
 
     def _update(self, name, old, new):
         if self.updating:
             return
         with self._busy_updating():
             for obj, attr in self.targets:
                 setattr(obj, attr, new)
 
     def unlink(self):
         self.source[0].on_trait_change(self._update, self.source[1], remove=True)
         self.source = None
         self.targets = []
 
 dlink = directional_link
 
 
 #-----------------------------------------------------------------------------
 # 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
     allow_none = False
     info_text = 'any value'
 
     def __init__(self, default_value=NoDefaultSpecified, allow_none=None, **metadata):
         """Create a TraitType.
         """
         if default_value is not NoDefaultSpecified:
             self.default_value = default_value
         if allow_none is not None:
             self.allow_none = allow_none
 
         if 'default' in metadata:
             # Warn the user that they probably meant default_value.
             warn(
                 "Parameter 'default' passed to TraitType. "
                 "Did you mean '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):
         """Part of the initialization which may depends on the underlying
         HasTraits instance.
 
         It is typically overloaded for specific trait types.
 
         This method is called by :meth:`HasTraits.__new__` and in the
         :meth:`TraitType.instance_init` method of trait types holding
         other trait types.
         """
         pass
 
     def init_default_value(self, obj):
         """Instantiate the default value for the trait type.
 
         This method is called by :meth:`TraitType.set_default_value` in the
         case a default value is provided at construction time or later when
         accessing the trait value for the first time in
         :meth:`HasTraits.__get__`.
         """
         value = self.get_default_value()
         value = self._validate(obj, value)
         obj._trait_values[self.name] = value
         return value
 
     def set_default_value(self, obj):
         """Set the default value on a per instance basis.
 
         This method is called by :meth:`HasTraits.__new__` to instantiate and
         validate the default value. The creation and validation of
         default values must be delayed until the parent :class:`HasTraits`
         class has been instantiated.
         Parameters
         ----------
         obj : :class:`HasTraits` instance
             The parent :class:`HasTraits` instance that has just been
             created.
         """
         # 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.
             self.init_default_value(obj)
             return
         # Complete the dynamic initialization.
         obj._trait_dyn_inits[self.name] = 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:
                     method = getattr(obj, obj._trait_dyn_inits[self.name])
                     value = method()
                     # FIXME: Do we really validate here?
                     value = self._validate(obj, value)
                     obj._trait_values[self.name] = value
                     return value
                 else:
                     return self.init_default_value(obj)
             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)
         try:
             old_value = obj._trait_values[self.name]
         except KeyError:
             old_value = Undefined
 
         obj._trait_values[self.name] = new_value
         try:
             silent = bool(old_value == new_value)
         except:
             # if there is an error in comparing, default to notify
             silent = False
         if silent is not True:
             # we explicitly compare silent to True just in case the equality
             # comparison above returns something other than True/False
             obj._notify_trait(self.name, old_value, new_value)
 
     def _validate(self, obj, value):
         if value is None and self.allow_none:
             return value
         if hasattr(self, 'validate'):
             value = self.validate(obj, value)
         if obj._cross_validation_lock is False:
             value = self._cross_validate(obj, value)
         return value
 
     def _cross_validate(self, obj, value):
         if hasattr(obj, '_%s_validate' % self.name):
             cross_validate = getattr(obj, '_%s_validate' % self.name)
             value = cross_validate(value, self)
         return value
 
     def __or__(self, other):
         if isinstance(other, Union):
             return Union([self] + other.trait_types)
         else:
             return Union([self, other])
 
     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, default=None):
         return getattr(self, '_metadata', {}).get(key, default)
 
     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 iteritems(classdict):
             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 iteritems(classdict):
             if isinstance(v, TraitType):
                 v.this_class = cls
         super(MetaHasTraits, cls).__init__(name, bases, classdict)
 
 
 class HasTraits(py3compat.with_metaclass(MetaHasTraits, object)):
 
     def __new__(cls, *args, **kw):
         # This is needed because 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 = {}
         inst._cross_validation_lock = True
         # 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()
                     if key not in kw:
                         value.set_default_value(inst)
         inst._cross_validation_lock = False
         return inst
 
     def __init__(self, *args, **kw):
         # Allow trait values to be set using keyword arguments.
         # We need to use setattr for this to trigger validation and
         # notifications.
         with self.hold_trait_notifications():
             for key, value in iteritems(kw):
                 setattr(self, key, value)
 
     @contextlib.contextmanager
     def hold_trait_notifications(self):
         """Context manager for bundling trait change notifications and cross
         validation.
 
         Use this when doing multiple trait assignments (init, config), to avoid
         race conditions in trait notifiers requesting other trait values.
         All trait notifications will fire after all values have been assigned.
         """
         if self._cross_validation_lock is True:
             yield
             return
         else:
             self._cross_validation_lock = True
             cache = {}
             notifications = {}
             _notify_trait = self._notify_trait
 
             def cache_values(*a):
                 cache[a[0]] = a
 
             def hold_notifications(*a):
                 notifications[a[0]] = a
 
             self._notify_trait = cache_values
 
             try:
                 yield
             finally:
                 try:
                     self._notify_trait = hold_notifications
                     for name in cache:
                         if hasattr(self, '_%s_validate' % name):
                             cross_validate = getattr(self, '_%s_validate' % name)
                             setattr(self, name, cross_validate(getattr(self, name), self))
                 except TraitError as e:
                     self._notify_trait = lambda *x: None
                     for name in cache:
                         if cache[name][1] is not Undefined:
                             setattr(self, name, cache[name][1])
                         else:
                             delattr(self, name)
                     cache = {}
                     notifications = {}
                     raise e
                 finally:
                     self._notify_trait = _notify_trait
                     self._cross_validation_lock = False
                     if isinstance(_notify_trait, types.MethodType):
                         # FIXME: remove when support is bumped to 3.4.
                         # when original method is restored,
                         # remove the redundant value from __dict__
                         # (only used to preserve pickleability on Python < 3.4)
                         self.__dict__.pop('_notify_trait', None)
                     # trigger delayed notifications
                     for v in dict(cache, **notifications).values():
                         self._notify_trait(*v)
 
     def _notify_trait(self, name, old_value, new_value):
 
         # First dynamic ones
         callables = []
         callables.extend(self._trait_notifiers.get(name,[]))
         callables.extend(self._trait_notifiers.get('anytrait',[]))
 
         # 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 = 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 name not in self._trait_notifiers:
             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 name in self._trait_notifiers:
             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 class' 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 `dict` of all the traits of this class.  The dictionary
         is keyed on the name and the values are the TraitType objects.
 
         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.
 
         The metadata kwargs allow functions to be passed in which
         filter traits based on metadata values.  The functions should
         take a single value as an argument and return a boolean.  If
         any function returns False, then the trait is not included in
         the output.  This does not allow for any simple way of
         testing that a metadata name exists and has any
         value 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 class' traits."""
         return self.traits(**metadata).keys()
 
     def traits(self, **metadata):
         """Get a `dict` of all the traits of this class.  The dictionary
         is keyed on the name and the values are the TraitType objects.
 
         The TraitTypes returned don't know anything about the values
         that the various HasTrait's instances are holding.
 
         The metadata kwargs allow functions to be passed in which
         filter traits based on metadata values.  The functions should
         take a single value as an argument and return a boolean.  If
         any function returns False, then the trait is not included in
         the output.  This does not allow for any simple way of
         testing that a metadata name exists and has any
         value 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, default=None):
         """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, default)
 
     def add_trait(self, traitname, trait):
         """Dynamically add a trait attribute to the HasTraits instance."""
         self.__class__ = type(self.__class__.__name__, (self.__class__,),
                               {traitname: trait})
         trait.set_default_value(self)
 
 #-----------------------------------------------------------------------------
 # Actual TraitTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # TraitTypes subclasses for handling classes and instances of classes
 #-----------------------------------------------------------------------------
 
 
 class ClassBasedTraitType(TraitType):
     """
     A trait with error reporting and string -> type resolution for Type,
     Instance and This.
     """
 
     def _resolve_string(self, string):
         """
         Resolve a string supplied for a type into an actual object.
         """
         return import_item(string)
 
     def error(self, obj, value):
         kind = type(value)
         if (not py3compat.PY3) and 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=False,
                   **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 : bool [ default True ]
             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, py3compat.string_types)):
             raise TraitError("A Type trait must specify a class.")
 
         self.klass       = klass
 
         super(Type, self).__init__(default_value, allow_none=allow_none, **metadata)
 
     def validate(self, obj, value):
         """Validates that the value is a valid object instance."""
         if isinstance(value, py3compat.string_types):
             try:
                 value = self._resolve_string(value)
             except ImportError:
                 raise TraitError("The '%s' trait of %s instance must be a type, but "
                                  "%r could not be imported" % (self.name, obj, value))
         try:
             if issubclass(value, self.klass):
                 return value
         except:
             pass
 
         self.error(obj, value)
 
     def info(self):
         """ Returns a description of the trait."""
         if isinstance(self.klass, py3compat.string_types):
             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):
         self._resolve_classes()
         super(Type, self).instance_init()
 
     def _resolve_classes(self):
         if isinstance(self.klass, py3compat.string_types):
             self.klass = self._resolve_string(self.klass)
         if isinstance(self.default_value, py3compat.string_types):
             self.default_value = self._resolve_string(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.
 
     Subclasses can declare default classes by overriding the klass attribute
     """
 
     klass = None
 
     def __init__(self, klass=None, args=None, kw=None, allow_none=False,
                  **metadata ):
         """Construct an Instance trait.
 
         This trait allows values that are instances of a particular
         class or its subclasses.  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 [default True]
             Indicates whether None is allowed as a value.
 
         Notes
         -----
         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 exactly one of ``args`` or ``kw`` is
         None, the None is replaced by ``()`` or ``{}``, respectively.
         """
         if klass is None:
             klass = self.klass
         
         if (klass is not None) and (inspect.isclass(klass) or isinstance(klass, py3compat.string_types)):
             self.klass = klass
         else:
             raise TraitError('The klass attribute must be a class'
                                 ' not: %r' % 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, allow_none=allow_none, **metadata)
 
     def validate(self, obj, value):
         if isinstance(value, self.klass):
             return value
         else:
             self.error(obj, value)
 
     def info(self):
         if isinstance(self.klass, py3compat.string_types):
             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):
         self._resolve_classes()
         super(Instance, self).instance_init()
 
     def _resolve_classes(self):
         if isinstance(self.klass, py3compat.string_types):
             self.klass = self._resolve_string(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 ForwardDeclaredMixin(object):
     """
     Mixin for forward-declared versions of Instance and Type.
     """
     def _resolve_string(self, string):
         """
         Find the specified class name by looking for it in the module in which
         our this_class attribute was defined.
         """
         modname = self.this_class.__module__
         return import_item('.'.join([modname, string]))
 
 
 class ForwardDeclaredType(ForwardDeclaredMixin, Type):
     """
     Forward-declared version of Type.
     """
     pass
 
 
 class ForwardDeclaredInstance(ForwardDeclaredMixin, Instance):
     """
     Forward-declared version of Instance.
     """
     pass
 
 
 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)
 
 
 class Union(TraitType):
     """A trait type representing a Union type."""
 
     def __init__(self, trait_types, **metadata):
         """Construct a Union  trait.
 
         This trait allows values that are allowed by at least one of the
         specified trait types. A Union traitlet cannot have metadata on
         its own, besides the metadata of the listed types.
 
         Parameters
         ----------
         trait_types: sequence
             The list of trait types of length at least 1.
 
         Notes
         -----
         Union([Float(), Bool(), Int()]) attempts to validate the provided values
         with the validation function of Float, then Bool, and finally Int.
         """
         self.trait_types = trait_types
         self.info_text = " or ".join([tt.info_text for tt in self.trait_types])
         self.default_value = self.trait_types[0].get_default_value()
         super(Union, self).__init__(**metadata)
 
     def instance_init(self):
         for trait_type in self.trait_types:
             trait_type.name = self.name
             trait_type.this_class = self.this_class
             trait_type.instance_init()
         super(Union, self).instance_init()
 
     def validate(self, obj, value):
         for trait_type in self.trait_types:
             try:
                 v = trait_type._validate(obj, value)
                 self._metadata = trait_type._metadata
                 return v
             except TraitError:
                 continue
         self.error(obj, value)
 
     def __or__(self, other):
         if isinstance(other, Union):
             return Union(self.trait_types + other.trait_types)
         else:
             return Union(self.trait_types + [other])
 
 #-----------------------------------------------------------------------------
 # Basic TraitTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
 
 class Any(TraitType):
     default_value = None
     info_text = 'any value'
 
 
 class Int(TraitType):
     """An int trait."""
 
     default_value = 0
     info_text = 'an int'
 
     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)
 
 if py3compat.PY3:
     Long, CLong = Int, CInt
     Integer = Int
 else:
     class Long(TraitType):
         """A long integer trait."""
 
         default_value = 0
         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 Integer(TraitType):
         """An integer trait.
 
         Longs that are unnecessary (<= sys.maxint) are cast to ints."""
 
         default_value = 0
         info_text = 'an integer'
 
         def validate(self, obj, value):
             if isinstance(value, int):
                 return value
             if isinstance(value, long):
                 # downcast longs that fit in int:
                 # note that int(n > sys.maxint) returns a long, so
                 # we don't need a condition on this cast
                 return int(value)
             if sys.platform == "cli":
                 from System import Int64
                 if isinstance(value, Int64):
                     return int(value)
             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 byte strings."""
 
     default_value = b''
     info_text = 'a bytes object'
 
     def validate(self, obj, value):
         if isinstance(value, bytes):
             return value
         self.error(obj, value)
 
 
 class CBytes(Bytes):
     """A casting version of the byte 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, py3compat.unicode_type):
             return value
         if isinstance(value, bytes):
             try:
                 return value.decode('ascii', 'strict')
             except UnicodeDecodeError:
                 msg = "Could not decode {!r} for unicode trait '{}' of {} instance."
                 raise TraitError(msg.format(value, self.name, class_of(obj)))
         self.error(obj, value)
 
 
 class CUnicode(Unicode):
     """A casting version of the unicode trait."""
 
     def validate(self, obj, value):
         try:
             return py3compat.unicode_type(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 py3compat.PY3:
         # Python 3:
         coerce_str = staticmethod(lambda _,s: s)
 
     else:
         # Python 2:
         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
 
     def validate(self, obj, value):
         value = self.coerce_str(obj, value)
 
         if isinstance(value, string_types) and py3compat.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, string_types) and py3compat.isidentifier(value, dotted=True):
             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, **metadata):
         self.values = values
         super(Enum, self).__init__(default_value, **metadata)
 
     def validate(self, obj, 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 not isinstance(value, py3compat.string_types):
             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
     _cast_types = ()
     _valid_defaults = SequenceTypes
     _trait = None
 
     def __init__(self, trait=None, default_value=None, allow_none=False,
                 **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 False ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         # allow List([values]):
         if default_value is None and not is_trait(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 is_trait(trait):
             self._trait = trait() if isinstance(trait, type) else 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):
         if isinstance(value, self._cast_types):
             value = self.klass(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)
 
     def instance_init(self):
         if isinstance(self._trait, TraitType):
             self._trait.this_class = self.this_class
             self._trait.instance_init()
         super(Container, self).instance_init()
 
 
 class List(Container):
     """An instance of a Python list."""
     klass = list
     _cast_types = (tuple,)
 
     def __init__(self, trait=None, default_value=None, minlen=0, maxlen=sys.maxsize, **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.maxsize ]
             The maximum length of the input list
 
         allow_none : bool [ default False ]
             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,
                                 **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)
 
     def validate(self, obj, value):
         value = super(List, self).validate(obj, value)
         value = self.validate_elements(obj, value)
         return value
 
 
 class Set(List):
     """An instance of a Python set."""
     klass = set
     _cast_types = (tuple, list)
 
 
 class Tuple(Container):
     """An instance of a Python tuple."""
     klass = tuple
     _cast_types = (list,)
 
     def __init__(self, *traits, **metadata):
         """Tuple(*traits, default_value=None, **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 types 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 False ]
             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)
 
         # allow Tuple((values,)):
         if len(traits) == 1 and default_value is None and not is_trait(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() if isinstance(trait, type) else 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)
 
     def instance_init(self):
         for trait in self._traits:
             if isinstance(trait, TraitType):
                 trait.this_class = self.this_class
                 trait.instance_init()
         super(Container, self).instance_init()
 
 
 class Dict(Instance):
     """An instance of a Python dict."""
     _trait = None
 
     def __init__(self, trait=None, default_value=NoDefaultSpecified, allow_none=False, **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``.
 
         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 Dict.  Must be dict, tuple, or None, and
             will be cast to a dict if not None. If `trait` is specified, the
             `default_value` must conform to the constraints it specifies.
 
         allow_none : bool [ default False ]
             Whether to allow the value to be None
 
         """
         if default_value is NoDefaultSpecified and trait is not None:
             if not is_trait(trait):
                 default_value = trait
                 trait = None
         if default_value is NoDefaultSpecified:
             default_value = {}
         if default_value is None:
             args = None
         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)
 
         if is_trait(trait):
             self._trait = trait() if isinstance(trait, type) else 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(Dict,self).__init__(klass=dict, 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(Dict, self).validate(obj, value)
         if value is None:
             return value
         value = self.validate_elements(obj, value)
         return value
 
     def validate_elements(self, obj, value):
         if self._trait is None or isinstance(self._trait, Any):
             return value
         validated = {}
         for key in value:
             v = value[key]
             try:
                 v = self._trait._validate(obj, v)
             except TraitError:
                 self.element_error(obj, v, self._trait)
             else:
                 validated[key] = v
         return self.klass(validated)
 
     def instance_init(self):
         if isinstance(self._trait, TraitType):
             self._trait.this_class = self.this_class
             self._trait.instance_init()
         super(Dict, self).instance_init()
 
 
 class EventfulDict(Instance):
     """An instance of an EventfulDict."""
 
     def __init__(self, default_value={}, allow_none=False, **metadata):
         """Create a EventfulDict trait type from a dict.
 
         The default value is created by doing
         ``eventful.EvenfulDict(default_value)``, which creates a copy of the
         ``default_value``.
         """
         if default_value is None:
             args = None
         elif isinstance(default_value, dict):
             args = (default_value,)
         elif isinstance(default_value, SequenceTypes):
             args = (default_value,)
         else:
             raise TypeError('default value of EventfulDict was %s' % default_value)
 
         super(EventfulDict, self).__init__(klass=eventful.EventfulDict, args=args,
                                   allow_none=allow_none, **metadata)
 
 
 class EventfulList(Instance):
     """An instance of an EventfulList."""
 
     def __init__(self, default_value=None, allow_none=False, **metadata):
         """Create a EventfulList trait type from a dict.
 
         The default value is created by doing 
         ``eventful.EvenfulList(default_value)``, which creates a copy of the 
         ``default_value``.
         """
         if default_value is None:
             args = ((),)
         else:
             args = (default_value,)
 
         super(EventfulList, self).__init__(klass=eventful.EventfulList, 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], py3compat.string_types) and isinstance(value[1], int):
                     port = value[1]
                     if port >= 0 and port <= 65535:
                         return value
         self.error(obj, value)
 
 class CRegExp(TraitType):
     """A casting compiled regular expression trait.
 
     Accepts both strings and compiled regular expressions. The resulting
     attribute will be a compiled regular expression."""
 
     info_text = 'a regular expression'
 
     def validate(self, obj, value):
         try:
             return re.compile(value)
         except:
             self.error(obj, value)