Note
This documentation is for a development version of IPython. There may be significant differences from the latest stable release (1.2.1).
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:
We don’t support:
There are also some important difference in our design:
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.
Inheritance diagram:
Authors:
Bases: exceptions.Exception
Bases: object
Link traits from different objects together so they remain in sync.
| Parameters: | obj : pairs of objects/attributes |
|---|
Examples
>>> c = link((obj1, 'value'), (obj2, 'value'), (obj3, 'value'))
>>> obj1.value = 5 # updates other objects as well
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:
Create a TraitType.
Create a new instance of the default value.
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
|
|---|
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.
Bases: type
A metaclass for HasTraits.
This metaclass makes sure that any TraitType class attributes are instantiated and sets their name attribute.
Finish initializing the HasTraits class.
This sets the this_class attribute of each TraitType in the class dict to the newly created class cls.
Bases: IPython.utils.traitlets._NewBase
Get a list of all the names of this class’ traits.
This method is just like the trait_names() method, but is unbound.
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.
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
name : list, str, None
remove : bool
|
|---|
Get metadata values for trait by key.
Get a list of all the names of this class’ traits.
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.
Bases: IPython.utils.traitlets.TraitType
A trait with error reporting for Type, Instance and This.
Bases: IPython.utils.traitlets.ClassBasedTraitType
A trait whose value must be a subclass of a specified class.
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
klass : class, str, None
allow_none : boolean
|
|---|
Returns a description of the trait.
Validates that the value is a valid object instance.
Bases: object
A class for generating new default value instances.
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.
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
args : tuple
kw : dict
allow_none : bool
|
|---|
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 either args or kw is not (but not both), None is replace by () or {}.
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.
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.
Bases: IPython.utils.traitlets.TraitType
An int trait.
Bases: IPython.utils.traitlets.Int
A casting version of the int trait.
Bases: IPython.utils.traitlets.TraitType
A long integer trait.
Bases: IPython.utils.traitlets.Long
A casting version of the long integer trait.
Bases: IPython.utils.traitlets.TraitType
An integer trait.
Longs that are unnecessary (<= sys.maxint) are cast to ints.
Bases: IPython.utils.traitlets.TraitType
A float trait.
Bases: IPython.utils.traitlets.Float
A casting version of the float trait.
Bases: IPython.utils.traitlets.TraitType
A trait for complex numbers.
Bases: IPython.utils.traitlets.Complex
A casting version of the complex number trait.
Bases: IPython.utils.traitlets.TraitType
A trait for byte strings.
Bases: IPython.utils.traitlets.Bytes
A casting version of the byte string trait.
Bases: IPython.utils.traitlets.TraitType
A trait for unicode strings.
Bases: IPython.utils.traitlets.Unicode
A casting version of the unicode trait.
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.
In Python 2, coerce ascii-only unicode to str
Bases: IPython.utils.traitlets.ObjectName
A string holding a valid dotted object name in Python, such as A.b3._c
Bases: IPython.utils.traitlets.TraitType
A boolean (True, False) trait.
Bases: IPython.utils.traitlets.Bool
A casting version of the boolean trait.
Bases: IPython.utils.traitlets.TraitType
An enum that whose value must be in a given sequence.
Returns a description of the trait.
Bases: IPython.utils.traitlets.Enum
An enum of strings that are caseless in validate.
Bases: IPython.utils.traitlets.Instance
An instance of a container (list, set, etc.)
To be subclassed by overriding klass.
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 ]
default_value : SequenceType [ optional ]
allow_none : Bool [ default True ]
**metadata : any
|
|---|
Bases: IPython.utils.traitlets.Container
An instance of a Python list.
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 ]
default_value : SequenceType [ optional ]
minlen : Int [ default 0 ]
maxlen : Int [ default sys.maxsize ]
allow_none : Bool [ default True ]
**metadata : any
|
|---|
alias of list
Bases: IPython.utils.traitlets.List
An instance of a Python set.
Bases: IPython.utils.traitlets.Container
An instance of a Python tuple.
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 ]
default_value : SequenceType [ optional ]
allow_none : Bool [ default True ]
**metadata : any
|
|---|
alias of tuple
Bases: IPython.utils.traitlets.Instance
An instance of a Python dict.
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.
Bases: IPython.utils.traitlets.TraitType
A trait for an (ip, port) tuple.
This allows for both IPv4 IP addresses as well as hostnames.
Bases: IPython.utils.traitlets.TraitType
A casting compiled regular expression trait.
Accepts both strings and compiled regular expressions. The resulting attribute will be a compiled regular expression.
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’).
Returns a string containing the correct indefinite article (‘a’ or ‘an’) prefixed to the specified string.
Return a string representation of a value and its type for readable error messages.
Returns whether the given value is an instance or subclass of TraitType.
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']
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.