neotraits Package

Neotraits is a framework that lets you declare class attributes with type checking and introspection abilities. The public api is in the neotraits.api module

_attr

This private module implements concrete declarative attributes

class tvb.basic.neotraits._attr.Attr(field_type: type, default: Any | None = None, doc: str = '', label: str = '', required: bool = True, final: bool = False, choices: tuple | None = None)

Bases: _Attr

An Attr declares the following about the attribute it describes: * the type * a default value shared by all instances * if the value might be missing * documentation It will resolve to attributes on the instance.

class tvb.basic.neotraits._attr.Dim(doc='')

Bases: Final

A symbol that defines a dimension in a numpy array shape. It can only be set once. It is an int. Dimensions have to be set before any NArrays that reference them are used.

any = <object object>

class tvb.basic.neotraits._attr.EnumAttr(field_type=None, default=None, doc='', label='', required=True)

Bases: Attr

class tvb.basic.neotraits._attr.Final(default=None, field_type=None, doc='', label='')

Bases: Attr

An attribute that can only be set once. If a default is provided it counts as a set, so it cannot be written to. Note that if the default is a mutable type, the value is shared with all instances of the owning class. We cannot enforce true constancy in python

class tvb.basic.neotraits._attr.Float(field_type=<class 'float'>, default=0, doc='', label='', required=True, final=False, choices=None)

Bases: _Number

Declares a float. This is different from Attr(field_type=float). The former enforces float subtypes. This allows any type that can be safely cast to the declared float type according to numpy rules.

Reading and writing this attribute is slower than a plain python attribute. In performance sensitive code you might want to use plain python attributes or even better local variables.

class tvb.basic.neotraits._attr.Int(field_type=<class 'int'>, default=0, doc='', label='', required=True, final=False, choices=None)

Bases: _Number

Declares an integer This is different from Attr(field_type=int). The former enforces int subtypes This allows all integer types, including numpy ones that can be safely cast to the declared type according to numpy rules

class tvb.basic.neotraits._attr.LinspaceRange(lo, hi, npoints=50)

Bases: object

Defines a domain with precise endpoints but the points are not precisely equidistant Similar to numpy.linspace

to_array()

class tvb.basic.neotraits._attr.List(of: type = <class 'object'>, default: tuple = (), doc: str = '', label: str = '', final: bool = False, choices: tuple | None = None)

Bases: Attr

The attribute is a list of values. Choices and type are reinterpreted as applying not to the list but to the elements of it

class tvb.basic.neotraits._attr.NArray(default: ~numpy.ndarray | None = None, required: bool = True, doc: str = '', label: str = '', dtype: ~numpy.dtype | type | str = <class 'numpy.float64'>, shape: ~typing.Tuple[~tvb.basic.neotraits._attr.Dim, ...] | None = None, dim_names: ~typing.Tuple[str, ...] = (), domain: ~typing.Container | None = None)

Bases: Attr

Declares a numpy array. dtype enforces the dtype. The default dtype is float64. An optional symbolic shape can be given, as a tuple of Dim attributes from the owning class. The shape will be enforced, but no broadcasting will be done. domain declares what values are allowed in this array. It can be any object that can be checked for membership Defaults are checked if they are in the declared domain. For performance reasons this does not happen on every attribute set.

class tvb.basic.neotraits._attr.Range(lo, hi, step=1.0)

Bases: object

Defines a domain like the one that numpy.arange generates Points are precisely equidistant but the largest point is <= hi

to_array()

_core

This module implements neotraits. It is private only to shield public usage of the imports and logger.

class tvb.basic.neotraits._core.CachedTraitProperty(fget: Callable, attr: _Attr, fset: Callable | None = None)

Bases: _Property

class tvb.basic.neotraits._core.HasTraits(**kwargs)

Bases: object

Traited class [tvb.basic.neotraits._core.HasTraits]

Attributes declared

gid : tvb.basic.neotraits._core.HasTraits.gid = Attr(field_type=<class ‘uuid.UUID’>, default=None, required=True)

TYPES_TO_DEEPCOPY = (<class 'numpy.random.mtrand.RandomState'>, <class 'scipy.sparse._csc.csc_matrix'>, <class 'scipy.sparse._base.spmatrix'>, <class 'list'>, <class 'tuple'>)

configure(*args, **kwargs)

Ensures that invariant of the class are satisfied. Override to compute uninitialized state of the class.

duplicate()

gid

gid identifies a specific instance of the hastraits it is used by serializers as an identifier. For non-datatype HasTraits this is less usefull but still provides a unique id for example for a model configuration

set_title()

summary_info() → Dict[str, str]

A more structured __str__ A 2 column table represented as a dict of str->str The default __str__ and html representations of this object are derived from this table. Override this method and return such a table filled with instance information that informs the user about your instance

tag(tag_name: str, tag_value: str | None = None) → None

Add a tag to this trait instance. The tags are for user to recognize and categorize the instances They should never influence the behaviour of the program :param tag_name: an arbitrary tag :param tag_value: an optional tag value

tags

a generic collections of tags. The trait system is not using them nor should any other code. They should not alter behaviour They should describe the instance for the user

validate()

Check that the internal invariants of this class are satisfied. Not meant to ensure that that is the case. Use configure for that. The default configure calls this before it returns. It complains about missing required attrs Can be overridden in subclasses

class tvb.basic.neotraits._core.SubformEnum(value)

Bases: TupleEnum

An enumeration.

classmethod get_enum_members()

class tvb.basic.neotraits._core.TVBEnum(value)

Bases: Enum

Super class for all enums used in TVB

static string_to_enum(choices, data)

class tvb.basic.neotraits._core.TraitProperty(fget: Callable, attr: _Attr, fset: Callable | None = None)

Bases: _Property

setter(fset)

class tvb.basic.neotraits._core.TupleEnum(value)

Bases: TVBEnum

Super class for all enums which represent classes. The values of these enums are tuples of two elements, where the first element is a class and the second is a string representing how the parameter is displayed in the UI.

property instance

property value

tvb.basic.neotraits._core.cached_trait_property(attr: Attr) → Callable[[Callable], CachedTraitProperty]

A lazy evaluated attribute. Transforms the decorated method into a cached property. The method will be called once to compute a value. The value will be stored in an instance attribute with the same name as the decorated function. :param attr: the declarative attribute that describes this property

tvb.basic.neotraits._core.trait_property(attr: Attr) → Callable[[Callable], TraitProperty]

A read only property that has a declarative attribute associated with. :param attr: the declarative attribute that describes this property

_declarative_base

This private module implements the neotraits declarative machinery. The basic Attribute Property and their automatic discovery by the Metaclass.

class tvb.basic.neotraits._declarative_base.MetaType(type_name, bases, namespace)

Bases: ABCMeta

Metaclass for the declarative traits. We inherit ABCMeta so that the users may use @abstractmethod without having to deal with 2 meta-classes. Even though we do this we don’t support the dynamic registration of subtypes to these abc’s

property declarative_attrs: Tuple[str, ...]

Gathers all the declared attributes, including the ones declared in superclasses. This is a meta-property common to all classes with this metatype

property declarative_props: Tuple[str, ...]

Gathers all the declared props, including the ones declared in superclasses. This is a meta-property common to all classes with this metatype

get_known_subclasses(include_abstract: bool = False, include_itself: bool = False) → Dict[str, Type[MetaType]]

Returns all subclasses that exist now. New subclasses can be created after this call, after importing a new module or dynamically creating subclasses. Use with care. Use after most relevant modules have been imported.

property own_declarative_attrs

api

The public api of the neotraits package.

ex

exception tvb.basic.neotraits.ex.TraitAttributeError(msg='', trait=None, attr=None)

Bases: TraitError, AttributeError

exception tvb.basic.neotraits.ex.TraitError(msg='', trait=None, attr=None)

Bases: Exception

exception tvb.basic.neotraits.ex.TraitFinalAttributeError(msg='', trait=None, attr=None)

Bases: TraitAttributeError, AttributeError

exception tvb.basic.neotraits.ex.TraitTypeError(msg='', trait=None, attr=None)

Bases: TraitError, TypeError

exception tvb.basic.neotraits.ex.TraitValueError(msg='', trait=None, attr=None)

Bases: TraitError, ValueError

info

Functions that inform a user about the state of a traited class or object.

Some of these functions are here so that they won’t clutter the core trait implementation.

tvb.basic.neotraits.info.auto_docstring(cls)

generate a docstring for the new class in which the Attrs are documented

tvb.basic.neotraits.info.convert_rst_to_html(doc)

Convert from rst to html that can be rendered by Mathjax

tvb.basic.neotraits.info.narray_describe(ar: ndarray) → str

tvb.basic.neotraits.info.narray_summary_info(ar: ndarray, ar_name: str = '', condensed: bool = False) → Dict[str, str]

A 2 column table represented as a dict of str->str

tvb.basic.neotraits.info.prepare_html(doc: str) → str

Create html (that can be further enhanced by MathJax) from the description received as parameter

tvb.basic.neotraits.info.trait_object_repr_html(self)

tvb.basic.neotraits.info.trait_object_str(self)