Trait Types¶

class traitlets.TraitType¶

The base class for all trait types.

__init__(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

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.Float(default_value=traitlets.Undefined, allow_none=False, **kwargs)¶: A float trait.

class traitlets.Complex(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶: A trait for complex numbers.

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.Unicode(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶: A trait for unicode strings.

class traitlets.Bytes(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶: A trait for byte 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.

class traitlets.ObjectName(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶

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

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

class traitlets.DottedObjectName(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶: A string holding a valid dotted object name in Python, such as A.b3._c

Containers¶

class traitlets.List(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, **kwargs)¶

An instance of a Python list.

__init__(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, **kwargs)¶

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.maxsize ]) – The maximum length of the input list

class traitlets.Set(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, **kwargs)¶

An instance of a Python set.

__init__(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, **kwargs)¶

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

The default value is created by doing set(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 = Set({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.maxsize ]) – The maximum length of the input list

class traitlets.Tuple(*traits, **kwargs)¶

An instance of a Python tuple.

__init__(*traits, **kwargs)¶

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 types 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, default_value must conform to the shape and type they specify.

class traitlets.Dict(trait=None, traits=None, default_value=traitlets.Undefined, **kwargs)¶

An instance of a Python dict.

__init__(trait=None, traits=None, default_value=traitlets.Undefined, **kwargs)¶

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.

trait: The type for restricting the contents of the Container. If unspecified, types are not checked.
traits: The type for restricting the content of the Dictionary for certain keys.
default_value: The default value for the Dict. Must be dict, tuple, or None, and will be cast to a dict if not None. If trait is specified, the default_value must conform to the constraints it specifies.

Classes and instances¶

class traitlets.Instance(klass=None, args=None, kw=None, **kwargs)¶

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.

Subclasses can declare default classes by overriding the klass attribute

__init__(klass=None, args=None, kw=None, **kwargs)¶

Construct an Instance trait.

This trait allows values that are instances of a particular class or its subclasses. 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 [ default False ]) – Indicates whether None is allowed as a value.

Notes

If both args and kw are None, then the default value is None. If args is a tuple and kw is a dict, then the default is created as klass(*args, **kw). If exactly one of args or kw is None, the None is replaced by () or {}, respectively.

class traitlets.Type(default_value=traitlets.Undefined, klass=None, **kwargs)¶

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

__init__(default_value=traitlets.Undefined, klass=None, **kwargs)¶

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. If neither are given, both default to object.

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 [ default object ]) – 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 (bool [ default False ]) – Indicates whether None is allowed as an assignable value.

class traitlets.This(**kwargs)¶

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.

class traitlets.ForwardDeclaredInstance(klass=None, args=None, kw=None, **kwargs)¶: Forward-declared version of Instance.

class traitlets.ForwardDeclaredType(default_value=traitlets.Undefined, klass=None, **kwargs)¶: Forward-declared version of Type.

Miscellaneous¶

class traitlets.Bool(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶: A boolean (True, False) trait.

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

class traitlets.Enum(values, default_value=traitlets.Undefined, **kwargs)¶: An enum whose value must be in a given sequence.

class traitlets.CaselessStrEnum(values, default_value=traitlets.Undefined, **kwargs)¶: An enum of strings where the case should be ignored.

class traitlets.UseEnum(enum_class, default_value=None, **kwargs)¶

Use a Enum class as model for the data type description. Note that if no default-value is provided, the first enum-value is used as default-value.

# -- SINCE: Python 3.4 (or install backport: pip install enum34)
import enum
from traitlets import HasTraits, UseEnum

class Color(enum.Enum):
    red = 1         # -- IMPLICIT: default_value
    blue = 2
    green = 3

class MyEntity(HasTraits):
    color = UseEnum(Color, default_value=Color.blue)

entity = MyEntity(color=Color.red)
entity.color = Color.green    # USE: Enum-value (preferred)
entity.color = "green"        # USE: name (as string)
entity.color = "Color.green"  # USE: scoped-name (as string)
entity.color = 3              # USE: number (as int)
assert entity.color is Color.green

class traitlets.TCPAddress(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶

A trait for an (ip, port) tuple.

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

class traitlets.CRegExp(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶

A casting compiled regular expression trait.

Accepts both strings and compiled regular expressions. The resulting attribute will be a compiled regular expression.

class traitlets.Union(trait_types, **kwargs)¶

A trait type representing a Union type.

__init__(trait_types, **kwargs)¶

Construct a Union trait.

This trait allows values that are allowed by at least one of the specified trait types. A Union traitlet cannot have metadata on its own, besides the metadata of the listed types.

Parameters:	trait_types (sequence) – The list of trait types of length at least 1.

Notes

Union([Float(), Bool(), Int()]) attempts to validate the provided values with the validation function of Float, then Bool, and finally Int.

class traitlets.Any(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, **kwargs)¶: A trait which allows any value.