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:

Traits have predefined values that do not need to be explicitly initialized in the class constructor or elsewhere.
Trait attributes have flexible, type-checked values.
Trait attributes’ values can be delegated to other objects.
Trait attributes can automatically notify interested parties when their values change.
Trait attributes can automatically construct (automatic or programmer-defined) user interfaces that allow their values to be edited or displayed)


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


class traits.traits.CTrait[source]

Extends the underlying C-based cTrait type.


Returns whether or not this trait is of a specified trait type.


Returns the user interface editor associated with the trait.


Returns the help text for a trait.

Parameters:full (bool) – Indicates whether to return the value of the help attribute of the trait itself.


If full is False or the trait does not have a help string, the returned string is constructed from the desc attribute on the trait and the info string on the trait’s handler.

full_info(object, name, value)[source]

Returns a description of the trait.


Returns a description of the trait.

class traits.traits.TraitFactory(maker_function=None)[source]
class traits.traits.TraitImportError(message)[source]

Defines a factory class for deferring import problems until encountering code that actually tries to use the unimportable trait.

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

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)[source]

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



traits.traits.Trait(*value_type, **metadata)[source]

Creates a trait definition.

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.
class MyClass:
foo = Trait(
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:
foo = Trait(
None, MyClass)
Similar to the previous format, but None can be assigned as a value.
class MyClass:
i = MyClass()
foo =
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:


: str
Describes the intended meaning of the trait. It is used in exception messages and fly-over help in user interfaces.
: str
Provides a human-readable name for the trait. It is used to label user interface editors for traits.
: traits.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.
: int

Indicates when trait change notifications should be generated based upon the result of comparing the old and new values of a trait assignment:

  • 0 (NO_COMPARE): The values are not compared and a trait change notification is generated on each assignment.
  • 1 (OBJECT_IDENTITY_COMPARE): A trait change notification is generated if the old and new values are not the same object.
  • 2 (RICH_COMPARE): A trait change notification is generated if the old and new values are not equal using Python’s ‘rich comparison’ operator. This is the default.
: bool

Indicates whether the basis for considering a trait attribute value to have changed is a “rich” comparison (True, the default), or simple object identity (False). This attribute can be useful in cases where a detailed comparison of two objects is very expensive, or where you do not care whether the details of an object change, as long as the same object is used.

Deprecated since version 3.0.3: Use comparison_mode instead

traits.traits.password_editor(auto_set=True, enter_set=False)[source]

Factory function that returns an editor for passwords.

traits.traits.multi_line_text_editor(auto_set=True, enter_set=False)[source]

Factory function that returns a text editor for multi-line strings.


Factory function that returns an editor that treats a multi-line string as source code.


Factory function that returns a Python shell for editing Python values.


Factory function that returns a Time editor for editing Time values.


Factory function that returns a Date editor for editing Date values.


Casts a CTrait, TraitFactory or TraitType to a CTrait but returns None if it is none of those.


Attempts to cast a value to a trait. Returns either a trait or the original value.


Returns a trait derived from its input.

Private Classes

class traits.traits._InstanceArgs(factory, args, kw)[source]
class traits.traits._TraitMaker(*value_type, **metadata)[source]