traits.trait_type Module

Defines the TraitType class.

The TraitType class a trait handler that is the base class for modern traits, and provides a richer API than the old-style traits derived from TraitHandler.

Classes

traits.trait_type.NoDefaultSpecified = <traits.trait_type._NoDefaultSpecifiedType object>

Singleton object that can be passed for the default_value argument in the TraitType constructor, to indicate that no default value was specified.

class traits.trait_type.TraitType(default_value=<traits.trait_type._NoDefaultSpecifiedType object>, **metadata)

Base class for new trait types.

This class enables you to define new traits using a class-based approach, instead of by calling the Trait() factory function with an instance of a TraitHandler derived object.

When subclassing this class, you can implement one or more of the method signatures below. Note that these methods are defined only as comments, because the absence of method definitions in the subclass definition implicitly provides information about how the trait should operate.

The optional methods are as follows:

get(self, object, name)

This is the getter method of a trait that behaves like a property.

If neither this method nor the set() method is defined, the value of the trait is handled like a normal object attribute. If this method is not defined, but the set() method is defined, the trait behaves like a write-only property. This method should return the value of the name property for the object object.

Parameters

objectany

The object that the property applies to.

namestr

The name of the property on object.

set(self, object, name, value)

This is the setter method of a trait that behaves like a property.

If neither this method nor the get() method is implemented, the trait behaves like a normal trait attribute. If this method is not defined, but the get() method is defined, the trait behaves like a read-only property. This method does not need to return a value, but it should raise a TraitError exception if the specified value is not valid and cannot be coerced or adapted to a valid value.

Parameters

objectany

The object that the property applies to.

namestr

The name of the property on object.

valueany

The value being assigned as the value of the property.

validate(self, object, name, value)

This method validates, coerces, or adapts the specified value as the value of the name trait of the object object. This method is called when a value is assigned to an object trait that is based on this subclass of TraitType and the class does not contain a definition for either the get() or set() methods. This method must return the original value or any suitably coerced or adapted value that is a legal value for the trait. If value is not a legal value for the trait, and cannot be coerced or adapted to a legal value, the method should either raise a TraitError or call the error method to raise the TraitError on its behalf.

is_valid_for(self, value)

As an alternative to implementing the validate method, you can instead implement the is_valid_for method, which receives only the value being assigned. It should return True if the value is valid, and False otherwise.

value_for(self, value)

As another alternative to implementing the validate method, you can instead implement the value_for method, which receives only the value being assigned. It should return the validated form of value if it is valid, or raise a TraitError if the value is not valid.

post_setattr(self, object, name, value)

This method allows the trait to do additional processing after value has been successfully assigned to the name trait of the object object. For most traits there is no additional processing that needs to be done, and this method need not be defined. It is normally used for creating “shadow” (i.e., “mapped” traits), but other uses may arise as well. This method does not need to return a value, and should normally not raise any exceptions.

metadata = {}

The metadata for the trait.

default_value = <undefined>

The default value for the trait type.

init()

Allows the trait to perform any additional initialization needed.

get_default_value()

Get information about the default value.

The default implementation analyzes the value of the trait’s default_value attribute and determines an appropriate default_value_type for the default_value. If you need to override this method to provide a different result tuple, the following values are valid values for default_value_type:

• 0, 1: The default_value item of the tuple is the default value.

• 2: The object containing the trait is the default value.

• 3: A new copy of the list specified by default_value is the default value.

• 4: A new copy of the dictionary specified by default_value is the default value.

• 5: A new instance of TraitListObject constructed using the default_value list is the default value.

• 6: A new instance of TraitDictObject constructed using the default_value dictionary is the default value.

• 7: default_value is a tuple of the form: (callable, args, kw), where callable is a callable, args is a tuple, and kw is either a dictionary or None. The default value is the result obtained by invoking callable(\*args, \*\*kw).

• 8: default_value is a callable. The default value is the result obtained by invoking default_value(object), where object is the object containing the trait. If the trait has a validate() method, the validate() method is also called to validate the result.

• 9: A new instance of TraitSetObject constructed using the default_value set is the default value.

Returns:

default_value_type, default_value – The default value information, consisting of an integer, giving the type of default value, and the corresponding default value as described above.

Return type:

int, any

clone(default_value=<traits.trait_type._NoDefaultSpecifiedType object>, **metadata)

Copy, optionally modifying default value and metadata.

Clones the contents of this object into a new instance of the same class, and then modifies the cloned copy using the specified default_value and metadata. Returns the cloned object as the result.

Note that subclasses can change the signature of this method if needed, but should always call the ‘super’ method if possible.

Parameters:

• default_value (any) – The new default value for the trait.

• **metadata (dict) – A dictionary of metadata names and corresponding values as arbitrary keyword arguments.

Returns:

clone – Clone of self.

Return type:

TraitType

get_value(object, name, trait=None)

Returns the current value of a property-based trait.

set_value(object, name, value)

Sets the cached value of a property-based trait and fires the appropriate trait change event.

as_ctrait()

Returns a CTrait corresponding to the trait defined by this class.

classmethod instantiate_and_get_ctrait()

Instantiate the class an return a CTrait instance

This is primarily to allow traits to be defined within classes without having to explicitly call them.

Private Functions

traits.trait_type._infer_default_value_type(default_value)

Figure out the default value type given a default value.

traits.trait_type._write_only(object, name)

Raise a trait error for a write-only trait.

traits.trait_type._read_only(object, name, value)

Raise a trait error for a read-only trait.