Note
This documentation is for a development version of Traitlets. There may be significant differences from the latest stable release.
Defining new trait types¶
To define a new trait type, subclass from TraitType
. You can define the
following things:
-
class
traitlets.
MyTrait
¶ -
info_text
¶ A short string describing what this trait should hold.
-
default_value
¶ A default value, if one makes sense for this trait type. If there is no obvious default, don’t provide this.
-
validate
(obj, value)¶ Check whether a given value is valid. If it is, it should return the value (coerced to the desired type, if necessary). If not, it should raise
TraitError
.TraitType.error()
is a convenient way to raise an descriptive error saying that the given value is not of the required type.obj
is the object to which the trait belongs.
-
For instance, here’s the definition of the TCPAddress
trait:
class TCPAddress(TraitType):
"""A trait for an (ip, port) tuple.
This allows for both IPv4 IP addresses as well as hostnames.
"""
default_value = ('127.0.0.1', 0)
info_text = 'an (ip, port) tuple'
def validate(self, obj, value):
if isinstance(value, tuple):
if len(value) == 2:
if isinstance(value[0], six.string_types) and isinstance(value[1], int):
port = value[1]
if port >= 0 and port <= 65535:
return value
self.error(obj, value)