Traitlets API reference

Any class with trait attributes must inherit from HasTraits.

You then declare the trait attributes on the class like this:

from traitlets import HasTraits, Int, Unicode

class Requester(HasTraits):
    url = Unicode()
    timeout = Int(30)  # 30 will be the default value

For the available trait types and the arguments you can give them, see Trait Types.

Dynamic default values

To calculate a default value dynamically, decorate a method of your class with @default({traitname}). This method will be called on the instance, and should return the default value. For example:

import getpass

class Identity(HasTraits):
    username = Unicode()

    @default('username')
    def _username_default(self):
        return getpass.getuser()

Callbacks when trait attributes change

To do something when a trait attribute is changed, decorate a method with traitlets.observe(). The method will be called with a single argument, a dictionary of the form:

{
  'owner': object, # The HasTraits instance
  'new': 6, # The new value
  'old': 5, # The old value
  'name': "foo", # The name of the changed trait
  'type': 'change', # The event type of the notification, usually 'change'
}

For example:

from traitlets import HasTraits, Integer, observe

class TraitletsExample(HasTraits):
    num = Integer(5, help="a number").tag(config=True)

    @observe('num')
    def _num_changed(self, change):
        print("{name} changed from {old} to {new}".format(**change))

Changed in version 4.1: The _{trait}_changed magic method-name approach is deprecated.

You can also add callbacks to a trait dynamically:

Note

If a trait attribute with a dynamic default value has another value set before it is used, the default will not be calculated. Any callbacks on that trait will will fire, and old_value will be None.

Validating proposed changes

Validator methods can be used to enforce certain aspects of a property. These are called on proposed changes, and can raise a TraitError if the change should be rejected, or coerce the value if it should be accepted with some modification. This can be useful for things such as ensuring a path string is always absolute, or check if it points to an existing directory.

For example:

from traitlets import HasTraits, Unicode, validate, TraitError

class TraitletsExample(HasTraits):
    path = Unicode('', help="a path")

    @validate('path')
    def _check_prime(self, proposal):
        path = proposal['value']
        if not path.endswith('/'):
            # ensure path always has trailing /
            path = path + '/'
        if not os.path.exists(path):
            raise TraitError("path %r does not exist" % path)
        return path