Traitlets¶

Default values, and checking type and value¶

At its most basic, traitlets provides type checking, and dynamic default value generation of attributes on :class:traitlets.HasTraits subclasses:

import getpass

class Identity(HasTraits):
    username = Unicode()

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

class Foo(HasTraits):
    bar = Int()

foo = Foo(bar='3')  # raises a TraitError

TraitError: The 'bar' trait of a Foo instance must be an int,
but a value of '3' <class 'str'> was specified

observe¶

Traitlets implement the observer pattern

class Foo(HasTraits):
    bar = Int()
    baz = Unicode()

foo = Foo()

def func(change):
    print(change['old'])
    print(change['new'])   # as of traitlets 4.3, one should be able to
                           # write print(change.new) instead

foo.observe(func, names=['bar'])
foo.bar = 1  # prints '0\n 1'
foo.baz = 'abc'  # prints nothing

When observers are methods of the class, a decorator syntax can be used.

class Foo(HasTraits):
    bar = Int()
    baz = Unicode()

    @observe('bar')
    def _observe_bar(self, change):
        print(change['old'])
        print(change['new'])

Validation¶

Custom validation logic on trait classes

from traitlets import HasTraits, TraitError, Int, Bool, validate

class Parity(HasTraits):
    value = Int()
    parity = Int()

    @validate('value')
    def _valid_value(self, proposal):
        if proposal['value'] % 2 != self.parity:
            raise TraitError('value and parity should be consistent')
        return proposal['value']

    @validate('parity')
    def _valid_parity(self, proposal):
        parity = proposal['value']
        if parity not in [0, 1]:
            raise TraitError('parity should be 0 or 1')
        if self.value % 2 != parity:
            raise TraitError('value and parity should be consistent')
        return proposal['value']

parity_check = Parity(value=2)

# Changing required parity and value together while holding cross validation
with parity_check.hold_trait_notifications():
    parity_check.value = 1
    parity_check.parity = 1

In the case where the a validation error occurs when hold_trait_notifications context manager is released, changes are rolled back to the initial state.

• Finally, trait type can have other events than trait changes. This capability was added so as to enable notifications on change of values in container classes. The items available in the dictionary passed to the observer registered with observe depends on the event type.

Numbers¶

class traitlets.Integer¶

An integer trait. On Python 2, this automatically uses the int or long types as necessary.

class traitlets.Int¶

class traitlets.Long¶

On Python 2, these are traitlets for values where the int and long types are not interchangeable. On Python 3, they are both aliases for Integer.

In almost all situations, you should use Integer instead of these.

class traitlets.CInt¶

class traitlets.CLong¶

class traitlets.CFloat¶

class traitlets.CComplex¶

Casting variants of the above. When a value is assigned to the attribute, these will attempt to convert it by calling e.g. value = int(value).

Strings¶

class traitlets.CUnicode¶

class traitlets.CBytes¶

Casting variants. When a value is assigned to the attribute, these will attempt to convert it to their type. They will not automatically encode/decode between unicode and bytes, however.

Containers¶

Classes and instances¶

Miscellaneous¶

class traitlets.CBool¶

Casting variant. When a value is assigned to the attribute, this will attempt to convert it by calling value = bool(value).

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

The main concepts¶

There are a number of abstractions that the IPython configuration system uses. Each of these abstractions is represented by a Python class.

Configuration object: Config

A configuration object is a simple dictionary-like class that holds configuration attributes and sub-configuration objects. These classes support dotted attribute style access (cfg.Foo.bar) in addition to the regular dictionary style access (cfg['Foo']['bar']). The Config object is a wrapper around a simple dictionary with some convenience methods, such as merging and automatic section creation.

Application: Application

An application is a process that does a specific job. The most obvious application is the ipython command line program. Each application reads one or more configuration files and a single set of command line options and then produces a master configuration object for the application. This configuration object is then passed to the configurable objects that the application creates. These configurable objects implement the actual logic of the application and know how to configure themselves given the configuration object.

Applications always have a log attribute that is a configured Logger. This allows centralized logging configuration per-application.

Configurable: Configurable

A configurable is a regular Python class that serves as a base class for all main classes in an application. The Configurable base class is lightweight and only does one things.

This Configurable is a subclass of HasTraits that knows how to configure itself. Class level traits with the metadata config=True become values that can be configured from the command line and configuration files.

Developers create Configurable subclasses that implement all of the logic in the application. Each of these subclasses has its own configuration information that controls how instances are created.

Singletons: SingletonConfigurable

Any object for which there is a single canonical instance. These are just like Configurables, except they have a class method instance(), that returns the current active instance (or creates one if it does not exist). instance()`.

Having described these main concepts, we can now state the main idea in our configuration system: “configuration” allows the default values of class attributes to be controlled on a class by class basis. Thus all instances of a given class are configured in the same way. Furthermore, if two instances need to be configured differently, they need to be instances of two different classes. While this model may seem a bit restrictive, we have found that it expresses most things that need to be configured extremely well. However, it is possible to create two instances of the same class that have different trait values. This is done by overriding the configuration.

Now, we show what our configuration objects and files look like.

Configuration objects and files¶

A configuration object is little more than a wrapper around a dictionary. A configuration file is simply a mechanism for producing that object. The main IPython configuration file is a plain Python script, which can perform extensive logic to populate the config object. IPython 2.0 introduces a JSON configuration file, which is just a direct JSON serialization of the config dictionary, which is easily processed by external software.

When both Python and JSON configuration file are present, both will be loaded, with JSON configuration having higher priority.

# Sample configurable:
from traitlets.config.configurable import Configurable
from traitlets import Int, Float, Unicode, Bool

class MyClass(Configurable):
    name = Unicode(u'defaultname'
        help="the name of the object"
    ).tag(config=True)
    ranking = Integer(0, help="the class's ranking").tag(config=True)
    value = Float(99.0)
    # The rest of the class implementation would go here..

# Sample config file
c.MyClass.name = 'coolname'
c.MyClass.ranking = 10

c.ClassName.attribute_name = attribute_value

{
  "version": "1.0",
  "MyClass": {
    "name": "coolname",
    "ranking": 10
  }
}

Configuration files inheritance¶

Let’s say you want to have different configuration files for various purposes. Our configuration system makes it easy for one configuration file to inherit the information in another configuration file. The load_subconfig() command can be used in a configuration file for this purpose. Here is a simple example that loads all of the values from the file base_config.py:

# base_config.py
c = get_config()
c.MyClass.name = 'coolname'
c.MyClass.ranking = 100

into the configuration file main_config.py:

# main_config.py
c = get_config()

# Load everything from base_config.py
load_subconfig('base_config.py')

# Now override one of the values
c.MyClass.name = 'bettername'

In a situation like this the load_subconfig() makes sure that the search path for sub-configuration files is inherited from that of the parent. Thus, you can typically put the two in the same directory and everything will just work.

Class based configuration inheritance¶

There is another aspect of configuration where inheritance comes into play. Sometimes, your classes will have an inheritance hierarchy that you want to be reflected in the configuration system. Here is a simple example:

from traitlets.config.configurable import Configurable
from traitlets import Integer, Float, Unicode, Bool

class Foo(Configurable):
    name = Unicode(u'fooname', config=True)
    value = Float(100.0, config=True)

class Bar(Foo):
    name = Unicode(u'barname', config=True)
    othervalue = Int(0, config=True)

Now, we can create a configuration file to configure instances of Foo and Bar:

# config file
c = get_config()

c.Foo.name = u'bestname'
c.Bar.othervalue = 10

This class hierarchy and configuration file accomplishes the following:

• The default value for Foo.name and Bar.name will be ‘bestname’. Because Bar is a Foo subclass it also picks up the configuration information for Foo.
• The default value for Foo.value and Bar.value will be 100.0, which is the value specified as the class default.
• The default value for Bar.othervalue will be 10 as set in the configuration file. Because Foo is the parent of Bar it doesn’t know anything about the othervalue attribute.

Command-line arguments¶

All configurable options can also be supplied at the command line when launching the application. Applications use a parser called KeyValueLoader to load values into a Config object.

By default, values are assigned in much the same way as in a config file:

$ ipython --InteractiveShell.use_readline=False --BaseIPythonApplication.profile='myprofile'

Is the same as adding:

c.InteractiveShell.use_readline=False
c.BaseIPythonApplication.profile='myprofile'

to your configuration file. Key/Value arguments always take a value, separated by ‘=’ and no spaces.

$ ipython -i -c "import numpy; x=numpy.linspace(0,1)" --profile testing --colors=lightbg

$ ipython --profile myprofile
# and
$ ipython --profile='myprofile'
# are equivalent to
$ ipython --BaseIPythonApplication.profile='myprofile'

$ ipcontroller --debug
# is equivalent to
$ ipcontroller --Application.log_level=DEBUG
# and
$ ipython --matplotlib
# is equivalent to
$ ipython --matplotlib auto
# or
$ ipython --no-banner
# is equivalent to
$ ipython --TerminalIPythonApp.display_banner=False

$ ipython qtconsole --profile myprofile

Design requirements¶

Here are the main requirements we wanted our configuration system to have:

• Support for hierarchical configuration information.
• Full integration with command line option parsers. Often, you want to read a configuration file, but then override some of the values with command line options. Our configuration system automates this process and allows each command line option to be linked to a particular attribute in the configuration hierarchy that it will override.
• Configuration files that are themselves valid Python code. This accomplishes many things. First, it becomes possible to put logic in your configuration files that sets attributes based on your operating system, network setup, Python version, etc. Second, Python has a super simple syntax for accessing hierarchical data structures, namely regular attribute access (Foo.Bar.Bam.name). Third, using Python makes it easy for users to import configuration attributes from one configuration file to another. Fourth, even though Python is dynamically typed, it does have types that can be checked at runtime. Thus, a 1 in a config file is the integer ‘1’, while a '1' is a string.
• A fully automated method for getting the configuration information to the classes that need it at runtime. Writing code that walks a configuration hierarchy to extract a particular attribute is painful. When you have complex configuration information with hundreds of attributes, this makes you want to cry.
• Type checking and validation that doesn’t require the entire configuration hierarchy to be specified statically before runtime. Python is a very dynamic language and you don’t always know everything that needs to be configured when a program starts.

Separation of metadata and keyword arguments in TraitType contructors¶

In traitlets 4.0, trait types constructors used all unrecognized keyword arguments passed to the constructor (like sync or config) to populate the metadata dictionary.

In trailets 4.1, we deprecated this behavior. The preferred method to populate the metadata for a trait type instance is to use the new tag method.

x = Int(allow_none=True, sync=True)      # deprecated
x = Int(allow_none=True).tag(sync=True)  # ok

We also deprecated the get_metadata method. The metadata of a trait type instance can directly be accessed via the metadata attribute.

Deprecation of on_trait_change¶

The most important change in this release is the deprecation of the on_trait_change method.

Instead, we introduced two methods, observe and unobserve to register and unregister handlers (instead of passing remove=True to on_trait_change for the removal).

• The observe method takes one positional argument (the handler), and two keyword arguments, names and type, which are used to filter by notification type or by the names of the observed trait attribute. The special value All corresponds to listening to all the notification types or all notifications from the trait attributes. The names argument can be a list of string, a string, or All and type can be a string or All.
• The observe handler’s signature is different from the signature of on_trait_change. It takes a single change dictionary argument, containing

{
    'type': The type of notification.
}

In the case where type is the string 'change', the following additional attributes are provided:

{
    'owner': the HasTraits instance,
    'old': the old trait attribute value,
    'new': the new trait attribute value,
    'name': the name of the changing attribute,
}

The type key in the change dictionary is meant to enable protocols for other notification types. By default, its value is equal to the 'change' string which corresponds to the change of a trait value.

Example:

from traitlets import HasTraits, Int, Unicode

class Foo(HasTraits):

    bar = Int()
    baz = Unicode()

def handle_change(change):
    print("{name} changed from {old} to {new}".format(**change))

foo = Foo()
foo.observe(handle_change, names='bar')

The new @observe decorator¶

The use of the magic methods _{trait}_changed as change handlers is deprecated, in favor of a new @observe method decorator.

The @observe method decorator takes the names of traits to be observed as positional arguments and has a type keyword-only argument (defaulting to 'change') to filter by notification type.

Example:

class Foo(HasTraits):
    bar = Int()
    baz = EnventfulContainer()  # hypothetical trait type emitting
                                # other notifications types

    @observe('bar')  # 'change' notifications for `bar`
    def handler_bar(self, change):
        pass

    @observe('baz ', type='element_change')  # 'element_change' notifications for `baz`
    def handler_baz(self, change):
        pass

    @observe('bar', 'baz', type=All)  # all notifications for `bar` and `baz`
    def handler_all(self, change):
        pass

Deprecation of magic method for dynamic defaults generation¶

The use of the magic methods _{trait}_default for dynamic default generation is deprecated, in favor a new @default method decorator.

Example:

Default generators should only be called if they are registered in subclasses of trait.this_type.

from traitlets import HasTraits, Int, Float, default

class A(HasTraits):
    bar = Int()

    @default('bar')
    def get_bar_default(self):
        return 11

class B(A):
    bar = Float()  # This ignores the default generator
                   # defined in the base class A

class C(B):

    @default('bar')
    def some_other_default(self):  # This should not be ignored since
        return 3.0                 # it is defined in a class derived
                                   # from B.a.this_class.

Deprecation of magic method for cross-validation¶

traitlets enables custom cross validation between the different attributes of a HasTraits instance. For example, a slider value should remain bounded by the min and max attribute. This validation occurs before the trait notification fires.

The use of the magic methods _{name}_validate for custom cross-validation is deprecated, in favor of a new @validate method decorator.

The method decorated with the @validate decorator take a single proposal dictionary

{
    'trait': the trait type instance being validated
    'value': the proposed value,
    'owner': the underlying HasTraits instance,
}

Custom validators may raise TraitError exceptions in case of invalid proposal, and should return the value that will be eventually assigned.

Example:

from traitlets import HasTraits, TraitError, Int, Bool, validate

class Parity(HasTraits):
    value = Int()
    parity = Int()

    @validate('value')
    def _valid_value(self, proposal):
        if proposal['value'] % 2 != self.parity:
            raise TraitError('value and parity should be consistent')
        return proposal['value']

    @validate('parity')
    def _valid_parity(self, proposal):
        parity = proposal['value']
        if parity not in [0, 1]:
            raise TraitError('parity should be 0 or 1')
        if self.value % 2 != parity:
            raise TraitError('value and parity should be consistent')
        return proposal['value']

parity_check = Parity(value=2)

# Changing required parity and value together while holding cross validation
with parity_check.hold_trait_notifications():
    parity_check.value = 1
    parity_check.parity = 1

The presence of the owner key in the proposal dictionary enable the use of other attributes of the object in the cross validation logic. However, we recommend that the custom cross validator don’t modify the other attributes of the object but only coerce the proposed value.

Backward-compatible upgrades¶

One challenge in adoption of a changing API is how to adopt the new API while maintaining backward compatibility for subclasses, as event listeners methods are de facto public APIs.

Take for instance the following class:

from traitlets import HasTraits, Unicode

class Parent(HasTraits):
    prefix = Unicode()
    path = Unicode()
    def _path_changed(self, name, old, new):
        self.prefix = os.path.dirname(new)

And you know another package has the subclass:

from parent import Parent
class Child(Parent):
    def _path_changed(self, name, old, new):
        super()._path_changed(name, old, new)
        if not os.path.exists(new):
            os.makedirs(new)

If the parent package wants to upgrade without breaking Child, it needs to preserve the signature of _path_changed. For this, we have provided an @observe_compat decorator, which automatically shims the deprecated signature into the new signature:

from traitlets import HasTraits, Unicode, observe, observe_compat

class Parent(HasTraits):
    prefix = Unicode()
    path = Unicode()

    @observe('path')
    @observe_compat # <- this allows super()._path_changed in subclasses to work with the old signature.
    def _path_changed(self, change):
        self.prefix = os.path.dirname(change['value'])

4.3¶

4.2¶

4.1¶

4.1 on GitHub

Traitlets 4.1 introduces a totally new decorator-based API for configuring traitlets. Highlights:

• Decorators are used, rather than magic method names, for registering trait-related methods. See Using Traitlets and Migration from Traitlets 4.0 to Traitlets 4.1 for more info.
• Deprecate Trait(config=True) in favor of Trait().tag(config=True). In general, metadata is added via tag instead of the constructor.

Other changes:

• Trait attributes initialized with read_only=True can only be set with the set_trait method. Attempts to directly modify a read-only trait attribute raises a TraitError.
• The directional link now takes an optional transform attribute allowing the modification of the value.
• Various fixes and improvements to config-file generation (fixed ordering, Undefined showing up, etc.)
• Warn on unrecognized traits that aren’t configurable, to avoid silently ignoring mistyped config.

4.0¶

4.0 on GitHub

First release of traitlets as a standalone package.