# Using Traitlets

Any class with traitlet attributes must inherit from `HasTraits`.

class `traitlets.``HasTraits`(*args, **kw)

  The base class for all classes that have traitlets.

  `has_trait`(name)

    Returns True if the object has a trait with the specified name.

  `trait_names`(**metadata)

    Get a list of all the names of this class’ traits.

  classmethod `class_trait_names`(**metadata)

    Get a list of all the names of this class’ traits.

    This method is just like the `trait_names()` method, but is unbound.

  `traits`(**metadata)

    Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

    The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

    The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. This does not allow for any simple way of testing that a metadata name exists and has any value because get_metadata returns None if a metadata key doesn’t exist.

  classmethod `class_traits`(**metadata)

    Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

    This method is just like the `traits()` method, but is unbound.

    The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

    The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. This does not allow for any simple way of testing that a metadata name exists and has any value because get_metadata returns None if a metadata key doesn’t exist.

  `trait_metadata`(traitname, key, default=None)

    Get metadata values for trait by key.

  `add_traits`(**traits)

    Dynamically add trait attributes to the HasTraits instance.

You then declare the traitlets 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 traitlet types and the arguments you can give them, see Trait Types.

## Dynamic default values

To calculate a default value dynamically, give your class a method named `_traitname_default`. This will be called on the instance, and should return the default value. For example:

    import getpass

    class Identity(HasTraits):
        username = Unicode()
        def _username_default(self):
            return getpass.getuser()

## Callbacks when traitlets change

To do something when a traitlet is changed, define a method named `_traitname_changed`. This can have several possible signatures:

class `traitlets.``TraitletsCallbacksExample`
  `_traitlet1_changed`()
  `_traitlet2_changed`(traitlet_name)
  `_traitlet3_changed`(traitlet_name, new_value)
  `_traitlet4_changed`(traitlet_name, old_value, new_value)

You can also add callbacks to a trait dynamically:

`HasTraits.``on_trait_change`(handler, name=None, remove=False)

  Setup a handler to be called when a trait changes.

  This is used to setup dynamic notifications of trait changes.

  Static handlers can be created by creating methods on a HasTraits subclass with the naming convention ‘_[traitname]_changed’. Thus, to create static handler for the trait ‘a’, create the method _a_changed(self, name, old, new) (fewer arguments can be used, see below).

  Parameters:

  - handler (callable) – A callable that is called when a trait changes. Its signature can be handler(), handler(name), handler(name, new) or handler(name, old, new).
  - name (list, str, None) – If None, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.
  - remove (bool) – If False (the default), then install the handler. If True then unintall it.

Note

If a traitlet 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`.