traits.traits Module

Defines the ‘core’ traits for the Traits package. A trait is a type definition that can be used for normal Python object attributes, giving the attributes some additional characteristics:

Initialization:

Traits have predefined values that do not need to be explicitly initialized in the class constructor or elsewhere.

Validation:

Trait attributes have flexible, type-checked values.

Delegation:

Trait attributes’ values can be delegated to other objects.

Notification:

Trait attributes can automatically notify interested parties when their values change.

Visualization:

Trait attributes can automatically construct (automatic or programmer-defined) user interfaces that allow their values to be edited or displayed)

Note

‘trait’ is a synonym for ‘property’, but is used instead of the word ‘property’ to differentiate it from the Python language ‘property’ feature.

Classes

class traits.traits.Default(func=None, args=(), kw=None)

Generates a value the first time it is accessed.

A Default object can be used anywhere a default trait value would normally be specified, to generate a default value dynamically.

class traits.traits.ForwardProperty(metadata, validate=None, handler=None)

Used to implement Property traits where accessor functions are defined implicitly on the class.

Functions

traits.traits.Trait(*value_type, **metadata)

Creates a trait definition.

Note

The Trait() function is not recommended for use in new code, and may eventually be deprecated and removed. Consider using Union instead.

This function accepts a variety of forms of parameter lists:

Format	Example	Description
Trait(default)	Trait(150.0)	The type of the trait is inferred from the type of the default value, which must be in ConstantTypes.
Trait(default, other1, other2, …)	Trait(None, 0, 1, 2, ‘many’)	The trait accepts any of the enumerated values, with the first value being the default value. The values must be of types in ConstantTypes, but they need not be of the same type. The default value is not valid for assignment unless it is repeated later in the list.
Trait([default, other1, other2, …])	Trait([None, 0, 1, 2, ‘many’])	Similar to the previous format, but takes an explicit list or a list variable.
Trait(type)	Trait(Int)	The type parameter must be a name of a Python type (see PythonTypes). Assigned values must be of exactly the specified type; no casting or coercion is performed. The default value is the appropriate form of zero, False, or emtpy string, set or sequence.
Trait(class)	class MyClass: pass foo = Trait( MyClass)	Values must be instances of class or of a subclass of class. The default value is None, but None cannot be assigned as a value.
Trait(None, class)	class MyClass: pass foo = Trait( None, MyClass)	Similar to the previous format, but None can be assigned as a value.
Trait(instance)	class MyClass: pass i = MyClass() foo = Trait(i)	Values must be instances of the same class as instance, or of a subclass of that class. The specified instance is the default value.
Trait(handler)	Trait( TraitEnum )	Assignment to this trait is validated by an object derived from traits.TraitHandler.
Trait(default, { type | constant | dict | class | function | handler | trait }+ )	Trait(0.0, 0.0 ‘stuff’, TupleType)	This is the most general form of the function. The notation: {...|...|...}+ means a list of one or more of any of the items listed between the braces. Thus, the most general form of the function consists of a default value, followed by one or more of several possible items. A trait defined by multiple items is called a “compound” trait.

All forms of the Trait function accept both predefined and arbitrary keyword arguments. The value of each keyword argument becomes bound to the resulting trait object as the value of an attribute having the same name as the keyword. This feature lets you associate metadata with a trait.

The following predefined keywords are accepted:

descstr

Describes the intended meaning of the trait. It is used in exception messages and fly-over help in user interfaces.

labelstr

Provides a human-readable name for the trait. It is used to label user interface editors for traits.

editortraits.api.Editor

Instance of a subclass Editor object to use when creating a user interface editor for the trait. See the “Traits UI User Guide” for more information on trait editors.

comparison_modeint

Indicates when trait change notifications should be generated based upon the result of comparing the old and new values of a trait assignment. Possible values come from the ComparisonMode enum:

• 0 (none): The values are not compared and a trait change notification is generated on each assignment.

• 1 (identity): A trait change notification is generated if the old and new values are not the same object.

• 2 (equality): A trait change notification is generated if the old and new values are not equal using Python’s standard equality testing. This is the default.

traits.traits.Property(*args, **metadata)

Returns a trait whose value is a Python property.

If no getter, setter or validate functions are specified (and force is not True), it is assumed that they are defined elsewhere on the class whose attribute this trait is assigned to. For example:

class Bar(HasTraits):

    # A float traits Property that should be always positive.
    foo = Property(Float)

    # Shadow trait attribute
    _foo = Float

    def _set_foo(self,x):
        self._foo = x

    def _validate_foo(self, x):
        if x <= 0:
            raise TraitError(
                'foo property should be a positive number')
        return x

    def _get_foo(self):
        return self._foo

You can use the observe metadata attribute to indicate that the property depends on the value of another trait. The value of observe follows the same signature as the expression parameter in HasTraits.observe. The property will fire a trait change notification if any of the traits specified by observe change. For example:

class Wheel(Part):
    axle = Instance(Axle)
    position = Property(observe='axle.chassis.position')

For details of the extended trait name syntax, refer to the observe() method of the HasTraits class.

Parameters

• fget (function) – The “getter” function for the property.

• fset (function) – The “setter” function for the property.

• fvalidate (function) – The validation function for the property. The method should return the value to set or raise TraitError if the new value is not valid.

• force (bool) – Indicates whether to use only the function definitions specified by fget and fset, and not look elsewhere on the class.

• handler (function) – A trait handler function for the trait.

• trait (Trait or value) – A trait definition or a value that can be converted to a trait that constrains the values of the property trait.

traits.traits.Color(*args, **metadata)

Returns a trait whose value must be a GUI toolkit-specific color.

Deprecated since version 6.1.0: Color trait in this package will be removed in the future. It is replaced by Color trait in TraitsUI package.

traits.traits.RGBColor(*args, **metadata)

Returns a trait whose value must be a GUI toolkit-specific RGB-based color.

Deprecated since version 6.1.0: RGBColor trait in this package will be removed in the future. It is replaced by RGBColor trait in TraitsUI package.

traits.traits.Font(*args, **metadata)

Returns a trait whose value must be a GUI toolkit-specific font.

Deprecated since version 6.1.0: Font trait in this package will be removed in the future. It is replaced by Font trait in TraitsUI package.

Private Classes

class traits.traits._InstanceArgs(factory, args, kw)

class traits.traits._TraitMaker(*value_type, **metadata)

define(*value_type, **metadata)

Define the trait.

do_list(list, enum, map, other)

Determine the correct TraitHandler for each item in a list.

as_ctrait()

Return a properly initialized ‘CTrait’ instance.