### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »

# utils.traitlets

## Module: `utils.traitlets`

Inheritance diagram for `IPython.utils.traitlets`:

A lightweight Traits like module.

This is designed to provide a lightweight, simple, pure Python version of many of the capabilities of enthought.traits. This includes:

- Validation
- Type specification with defaults
- Static and dynamic notification
- Basic predefined types
- An API that is similar to enthought.traits

We don’t support:

- Delegation
- Automatic GUI generation
- A full set of trait types. Most importantly, we don’t provide container traits (list, dict, tuple) that can trigger notifications if their contents change.
- API compatibility with enthought.traits

There are also some important difference in our design:

- enthought.traits does not validate default values. We do.

We choose to create this module because we need these capabilities, but we need them to be pure Python so they work in all Python implementations, including Jython and IronPython.

Authors:

- Brian Granger
- Enthought, Inc. Some of the code in this file comes from enthought.traits and is licensed under the BSD license. Also, many of the ideas also come from enthought.traits even though our implementation is very different.

## Classes

### `Any`

class `IPython.utils.traitlets.``Any`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)

### `Bool`

class `IPython.utils.traitlets.``Bool`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  A boolean (True, False) trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `Bytes`

class `IPython.utils.traitlets.``Bytes`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  A trait for byte strings.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `CBool`

class `IPython.utils.traitlets.``CBool`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.Bool`

  A casting version of the boolean trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `CBytes`

class `IPython.utils.traitlets.``CBytes`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.Bytes`

  A casting version of the byte string trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `CComplex`

class `IPython.utils.traitlets.``CComplex`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.Complex`

  A casting version of the complex number trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `CFloat`

class `IPython.utils.traitlets.``CFloat`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.Float`

  A casting version of the float trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `CInt`

class `IPython.utils.traitlets.``CInt`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.Int`

  A casting version of the int trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `CUnicode`

class `IPython.utils.traitlets.``CUnicode`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.Unicode`

  A casting version of the unicode trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `CaselessStrEnum`

class `IPython.utils.traitlets.``CaselessStrEnum`(values, default_value=None, allow_none=True, **metadata)

  Bases: `IPython.utils.traitlets.Enum`

  An enum of strings that are caseless in validate.

  `__init__`(values, default_value=None, allow_none=True, **metadata)
  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()

    Returns a description of the trait.

  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `ClassBasedTraitType`

class `IPython.utils.traitlets.``ClassBasedTraitType`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  A trait with error reporting for Type, Instance and This.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)

### `Complex`

class `IPython.utils.traitlets.``Complex`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  A trait for complex numbers.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `Container`

class `IPython.utils.traitlets.``Container`(trait=None, default_value=None, allow_none=True, **metadata)

  Bases: `IPython.utils.traitlets.Instance`

  An instance of a container (list, set, etc.)

  To be subclassed by overriding klass.

  `__init__`(trait=None, default_value=None, allow_none=True, **metadata)

    Create a container trait type from a list, set, or tuple.

    The default value is created by doing `List(default_value)`, which creates a copy of the `default_value`.

    `trait` can be specified, which restricts the type of elements in the container to that TraitType.

    If only one arg is given and it is not a Trait, it is taken as `default_value`:

    `c = List([1,2,3])`

    Parameters :

    trait : TraitType [ optional ]

    > the type for restricting the contents of the Container. If unspecified, types are not checked.

    default_value : SequenceType [ optional ]

    > The default value for the Trait. Must be list/tuple/set, and will be cast to the container type.

    allow_none : Bool [ default True ]

    > Whether to allow the value to be None

    **metadata : any

    > further keys for extensions to the Trait (e.g. config)

  `element_error`(obj, element, validator)
  `error`(obj, value)
  `get_default_value`()

    Instantiate a default value instance.

    This is called when the containing HasTraits classes’ `__new__()` method is called to ensure that a unique instance is created for each HasTraits instance.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)
  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)
  `validate_elements`(obj, value)

### `DefaultValueGenerator`

class `IPython.utils.traitlets.``DefaultValueGenerator`(*args, **kw)

  Bases: `object`

  A class for generating new default value instances.

  `__init__`(*args, **kw)
  `generate`(klass)

### `Dict`

class `IPython.utils.traitlets.``Dict`(default_value=None, allow_none=True, **metadata)

  Bases: `IPython.utils.traitlets.Instance`

  An instance of a Python dict.

  `__init__`(default_value=None, allow_none=True, **metadata)

    Create a dict trait type from a dict.

    The default value is created by doing `dict(default_value)`, which creates a copy of the `default_value`.

  `error`(obj, value)
  `get_default_value`()

    Instantiate a default value instance.

    This is called when the containing HasTraits classes’ `__new__()` method is called to ensure that a unique instance is created for each HasTraits instance.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)
  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `DottedObjectName`

class `IPython.utils.traitlets.``DottedObjectName`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.ObjectName`

  A string holding a valid dotted object name in Python, such as A.b3._c

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `coerce_str`(obj, value)

    In Python 2, coerce ascii-only unicode to str

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `Enum`

class `IPython.utils.traitlets.``Enum`(values, default_value=None, allow_none=True, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  An enum that whose value must be in a given sequence.

  `__init__`(values, default_value=None, allow_none=True, **metadata)
  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()

    Returns a description of the trait.

  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `Float`

class `IPython.utils.traitlets.``Float`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  A float trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `HasTraits`

class `IPython.utils.traitlets.``HasTraits`(**kw)

  Bases: `object`

  `__init__`(**kw)
  classmethod `class_trait_names`(**metadata)

    Get a list of all the names of this classes traits.

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

  classmethod `class_traits`(**metadata)

    Get a list of all the traits of this class.

    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.

    This follows the same algorithm as traits does and does not allow for any simple way of specifying merely that a metadata name exists, but has any value. This is because get_metadata returns None if a metadata key doesn’t exist.

  `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.

  `trait_metadata`(traitname, key)

    Get metadata values for trait by key.

  `trait_names`(**metadata)

    Get a list of all the names of this classes traits.

  `traits`(**metadata)

    Get a list of all the traits of this class.

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

    This follows the same algorithm as traits does and does not allow for any simple way of specifying merely that a metadata name exists, but has any value. This is because get_metadata returns None if a metadata key doesn’t exist.

### `Instance`

class `IPython.utils.traitlets.``Instance`(klass=None, args=None, kw=None, allow_none=True, **metadata)

  Bases: `IPython.utils.traitlets.ClassBasedTraitType`

  A trait whose value must be an instance of a specified class.

  The value can also be an instance of a subclass of the specified class.

  `__init__`(klass=None, args=None, kw=None, allow_none=True, **metadata)

    Construct an Instance trait.

    This trait allows values that are instances of a particular class or its sublclasses. Our implementation is quite different from that of enthough.traits as we don’t allow instances to be used for klass and we handle the `args` and `kw` arguments differently.

    Parameters :

    klass : class, str

    > The class that forms the basis for the trait. Class names can also be specified as strings, like ‘foo.bar.Bar’.

    args : tuple

    > Positional arguments for generating the default value.

    kw : dict

    > Keyword arguments for generating the default value.

    allow_none : bool

    > Indicates whether None is allowed as a value.

  `error`(obj, value)
  `get_default_value`()

    Instantiate a default value instance.

    This is called when the containing HasTraits classes’ `__new__()` method is called to ensure that a unique instance is created for each HasTraits instance.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)
  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `Int`

class `IPython.utils.traitlets.``Int`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  An int trait.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `List`

class `IPython.utils.traitlets.``List`(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, allow_none=True, **metadata)

  Bases: `IPython.utils.traitlets.Container`

  An instance of a Python list.

  `__init__`(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, allow_none=True, **metadata)

    Create a List trait type from a list, set, or tuple.

    The default value is created by doing `List(default_value)`, which creates a copy of the `default_value`.

    `trait` can be specified, which restricts the type of elements in the container to that TraitType.

    If only one arg is given and it is not a Trait, it is taken as `default_value`:

    `c = List([1,2,3])`

    Parameters :

    trait : TraitType [ optional ]

    > the type for restricting the contents of the Container. If unspecified, types are not checked.

    default_value : SequenceType [ optional ]

    > The default value for the Trait. Must be list/tuple/set, and will be cast to the container type.

    minlen : Int [ default 0 ]

    > The minimum length of the input list

    maxlen : Int [ default sys.maxint ]

    > The maximum length of the input list

    allow_none : Bool [ default True ]

    > Whether to allow the value to be None

    **metadata : any

    > further keys for extensions to the Trait (e.g. config)

  `element_error`(obj, element, validator)
  `error`(obj, value)
  `get_default_value`()

    Instantiate a default value instance.

    This is called when the containing HasTraits classes’ `__new__()` method is called to ensure that a unique instance is created for each HasTraits instance.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)
  `klass`

    alias of `list`

  `length_error`(obj, value)
  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)
  `validate_elements`(obj, value)

### `MetaHasTraits`

class `IPython.utils.traitlets.``MetaHasTraits`(name, bases, classdict)

  Bases: `type`

  A metaclass for HasTraits.

  This metaclass makes sure that any TraitType class attributes are instantiated and sets their name attribute.

  `__init__`(name, bases, classdict)

    Finish initializing the HasTraits class.

    This sets the `this_class` attribute of each TraitType in the class dict to the newly created class `cls`.

  `mro`

    mro() -> list return a type’s method resolution order

### `NoDefaultSpecified`

`IPython.utils.traitlets.``NoDefaultSpecified`

### `ObjectName`

class `IPython.utils.traitlets.``ObjectName`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  A string holding a valid object name in this version of Python.

  This does not check that the name exists in any scope.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `coerce_str`(obj, value)

    In Python 2, coerce ascii-only unicode to str

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `Set`

class `IPython.utils.traitlets.``Set`(trait=None, default_value=None, allow_none=True, **metadata)

  Bases: `IPython.utils.traitlets.Container`

  An instance of a Python set.

  `__init__`(trait=None, default_value=None, allow_none=True, **metadata)

    Create a container trait type from a list, set, or tuple.

    The default value is created by doing `List(default_value)`, which creates a copy of the `default_value`.

    `trait` can be specified, which restricts the type of elements in the container to that TraitType.

    If only one arg is given and it is not a Trait, it is taken as `default_value`:

    `c = List([1,2,3])`

    Parameters :

    trait : TraitType [ optional ]

    > the type for restricting the contents of the Container. If unspecified, types are not checked.

    default_value : SequenceType [ optional ]

    > The default value for the Trait. Must be list/tuple/set, and will be cast to the container type.

    allow_none : Bool [ default True ]

    > Whether to allow the value to be None

    **metadata : any

    > further keys for extensions to the Trait (e.g. config)

  `element_error`(obj, element, validator)
  `error`(obj, value)
  `get_default_value`()

    Instantiate a default value instance.

    This is called when the containing HasTraits classes’ `__new__()` method is called to ensure that a unique instance is created for each HasTraits instance.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)
  `klass`

    alias of `set`

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)
  `validate_elements`(obj, value)

### `TCPAddress`

class `IPython.utils.traitlets.``TCPAddress`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  A trait for an (ip, port) tuple.

  This allows for both IPv4 IP addresses as well as hostnames.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `This`

class `IPython.utils.traitlets.``This`(**metadata)

  Bases: `IPython.utils.traitlets.ClassBasedTraitType`

  A trait for instances of the class containing this trait.

  Because how how and when class bodies are executed, the `This` trait can only have a default value of None. This, and because we always validate default values, `allow_none` is always true.

  `__init__`(**metadata)
  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

### `TraitError`

class `IPython.utils.traitlets.``TraitError`

  Bases: `exceptions.Exception`

  `__init__`()

    x.__init__(...) initializes x; see help(type(x)) for signature

  `args`
  `message`

### `TraitType`

class `IPython.utils.traitlets.``TraitType`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `object`

  A base class for all trait descriptors.

  Notes

  Our implementation of traits is based on Python’s descriptor prototol. This class is the base class for all such descriptors. The only magic we use is a custom metaclass for the main `HasTraits` class that does the following:

  1. Sets the `name` attribute of every `TraitType` instance in the class dict to the name of the attribute.
  2. Sets the `this_class` attribute of every `TraitType` instance in the class dict to the class that declared the trait. This is used by the `This` trait to allow subclasses to accept superclasses for `This` values.
  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)

### `Tuple`

class `IPython.utils.traitlets.``Tuple`(*traits, **metadata)

  Bases: `IPython.utils.traitlets.Container`

  An instance of a Python tuple.

  `__init__`(*traits, default_value=None, allow_none=True, **medatata)

    Create a tuple from a list, set, or tuple.

    Create a fixed-type tuple with Traits:

    `t = Tuple(Int, Str, CStr)`

    would be length 3, with Int,Str,CStr for each element.

    If only one arg is given and it is not a Trait, it is taken as default_value:

    `t = Tuple((1,2,3))`

    Otherwise, `default_value` must be specified by keyword.

    Parameters :

    *traits : TraitTypes [ optional ]

    > the tsype for restricting the contents of the Tuple. If unspecified, types are not checked. If specified, then each positional argument corresponds to an element of the tuple. Tuples defined with traits are of fixed length.

    default_value : SequenceType [ optional ]

    > The default value for the Tuple. Must be list/tuple/set, and will be cast to a tuple. If traits are specified, the default_value must conform to the shape and type they specify.

    allow_none : Bool [ default True ]

    > Whether to allow the value to be None

    **metadata : any

    > further keys for extensions to the Trait (e.g. config)

  `element_error`(obj, element, validator)
  `error`(obj, value)
  `get_default_value`()

    Instantiate a default value instance.

    This is called when the containing HasTraits classes’ `__new__()` method is called to ensure that a unique instance is created for each HasTraits instance.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)
  `klass`

    alias of `tuple`

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)
  `validate_elements`(obj, value)

### `Type`

class `IPython.utils.traitlets.``Type`(default_value=None, klass=None, allow_none=True, **metadata)

  Bases: `IPython.utils.traitlets.ClassBasedTraitType`

  A trait whose value must be a subclass of a specified class.

  `__init__`(default_value=None, klass=None, allow_none=True, **metadata)

    Construct a Type trait

    A Type trait specifies that its values must be subclasses of a particular class.

    If only `default_value` is given, it is used for the `klass` as well.

    Parameters :

    default_value : class, str or None

    > The default value must be a subclass of klass. If an str, the str must be a fully specified class name, like ‘foo.bar.Bah’. The string is resolved into real class, when the parent `HasTraits` class is instantiated.

    klass : class, str, None

    > Values of this trait must be a subclass of klass. The klass may be specified in a string like: ‘foo.bar.MyClass’. The string is resolved into real class, when the parent `HasTraits` class is instantiated.

    allow_none : boolean

    > Indicates whether None is allowed as an assignable value. Even if `False`, the default value may be `None`.

  `error`(obj, value)
  `get_default_value`()
  `get_metadata`(key)
  `info`()

    Returns a description of the trait.

  `init`()
  `instance_init`(obj)
  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

    Validates that the value is a valid object instance.

### `Undefined`

`IPython.utils.traitlets.``Undefined`

### `Unicode`

class `IPython.utils.traitlets.``Unicode`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

  Bases: `IPython.utils.traitlets.TraitType`

  A trait for unicode strings.

  `__init__`(default_value=<IPython.utils.traitlets.NoDefaultSpecified object at 0x2c12c10>, **metadata)

    Create a TraitType.

  `error`(obj, value)
  `get_default_value`()

    Create a new instance of the default value.

  `get_metadata`(key)
  `info`()
  `init`()
  `instance_init`(obj)

    This is called by `HasTraits.__new__()` to finish init’ing.

    Some stages of initialization must be delayed until the parent `HasTraits` instance has been created. This method is called in `HasTraits.__new__()` after the instance has been created.

    This method trigger the creation and validation of default values and also things like the resolution of str given class names in `Type` and :class`Instance`.

    Parameters :

    obj : `HasTraits` instance

    > The parent `HasTraits` instance that has just been created.

  `set_default_value`(obj)

    Set the default value on a per instance basis.

    This method is called by `instance_init()` to create and validate the default value. The creation and validation of default values must be delayed until the parent `HasTraits` class has been instantiated.

  `set_metadata`(key, value)
  `validate`(obj, value)

## Functions

`IPython.utils.traitlets.``add_article`(name)

  Returns a string containing the correct indefinite article (‘a’ or ‘an’) prefixed to the specified string.

`IPython.utils.traitlets.``class_of`(object)

  Returns a string containing the class name of an object with the correct indefinite article (‘a’ or ‘an’) preceding it (e.g., ‘an Image’, ‘a PlotValue’).

`IPython.utils.traitlets.``getmembers`(object, predicate=None)

  A safe version of inspect.getmembers that handles missing attributes.

  This is useful when there are descriptor based attributes that for some reason raise AttributeError even though they exist. This happens in zope.inteface with the __provides__ attribute.

`IPython.utils.traitlets.``parse_notifier_name`(name)

  Convert the name argument to a list of names.

  Examples

      >>> parse_notifier_name('a')
      ['a']
      >>> parse_notifier_name(['a','b'])
      ['a', 'b']
      >>> parse_notifier_name(None)
      ['anytrait']

`IPython.utils.traitlets.``repr_type`(obj)

  Return a string representation of a value and its type for readable error messages.

### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »