Better Errors for Nested Traits

[rmorshea]

Summary

Right now nested traits have pretty horrid error messages.

The following code produces three different tracebacks with three bad error messages:

class MyClass(HasTraits):
    
    l = List(List(Int()))

mc = MyClass()
mc.l = [["value"]]

Error messages (tracebacks excluded):

The 'None' trait of a MyClass instance must be an int, but a value of 'str' <class 'str'> was specified.``

Element of the 'None' trait of a MyClass instance must be an int, but a value of 'str' <class 'str'> was specified.

Element of the 'l' trait of a MyClass instance must be a list, but a value of ['str'] <class 'list'> was specified.

The First two messages, while accurate, don't have a trait name associated with them which makes them confusing to read. The last one has a trait name but is inaccurate since it complains of a list being provided to a List trait!

Solution

A generic TraitType.error(obj, value, error=None) method that can be used to easily handle nested errors. To use it, one only needs to catch the nested error in a parent trait and pass it to error.

With the proposed changes, the code above would create one concise traceback and message:

TraitError: The 'l' trait of a MyClass instance contains an Int of a List of a List which expected an int, not the str 'value'

Notes

There is an added utility file descriptions.py which has a new describe function in addition to others that were previously present in traitlets.py like add_article or repr_type. The describe function provides a common way to represent a value as a readable string (see docstring for use details).

[rmorshea]

@minrk, this should probably get the 5.0 milestone.

[rmorshea]

@minrk, this now passes after #406.

[minrk]

Thanks, @rmorshea!