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))

You can also add callbacks to a trait dynamically:

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