ccpn.util.traits package

Submodules

ccpn.util.traits.CcpNmrDataFrame module

class ccpn.util.traits.CcpNmrDataFrame.CcpNmrDataFrame(**kwargs)

Bases: ccpn.util.traits.CcpNmrJson.CcpNmrJson

Class for json serialisable and easy Pandas DataFrame

addColumn(column, fmt=None, values=None, beforeColumn=None)

Add a column, optional beforeColumn (default at end), optionally setting values

allRows(sorted=True)

Iterate over each row, maintain the currently sorted order if sorted=True

appendRow(**kwds)

For append each (key,value) of kwds as new row

classVersion = 3.0

property columns

- None, immutable - Return columns of dataFrame as a list

dataFrame

A trait that defines a json serialisable Pandas DataFrame

deleteColumns(*columns)

Delete columns, retaining others

fromJson(string, **kwds)

Subclassed to execute _sortDataFrame

getRow(row)

Return row as a AttributeDict

insertRow(row, **kwds)

Insert (key, values) as row This will re-index (+1) all current rows >= row Also replaces dataFrame with new instance

property rows

- None, immutable - Return rows of dataFrame as a list

selectColumns(*columns)

Select columns, deleting others

setRow(row, **kwds)

For each (key,value) of kwds, set (row,key) to value

property sizes

- None, immutable - Return (numberOfRows, numberOfColumns) tuple

sort(sortColumn, ascending=True)

Sort dataFrame by sortColumn; use None to revert to row-sorted

sortRows()

Convience method to revert to ascending sorted rows

class ccpn.util.traits.CcpNmrDataFrame.DataFrameTrait(*args, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.Instance

A trait that defines a json serialisable Pandas DataFrame

default_value = Empty DataFrame Columns: [] Index: []

info_text = 'A json serialisable DataFrame'

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

Serialise DataFrame instance to be json compatible. Needs some complicated encoding/decoding as result of int64 rows encoding

decode(obj, trait, value)

uses value to generate and set the new (or modified) obj

encode(obj, trait)

returns a json serialisable object

ccpn.util.traits.CcpNmrJson module

class ccpn.util.traits.CcpNmrJson.CcpNmrJson(**kwargs)

Bases: ccpn.util.traits.TraitBase.TraitBase

Abstract base class to handle objects to and from json

Define attributes (traits) as traitlets instances (Import from util/traits/CcpNmrTraits).

Traits to be saved to json are tagged saveToJson=True.

Example: myint = Int().tag(saveToJson=True)

All traits can be saved by default setting the class attribute saveAllTraitsToJson to True

Example: saveAllTraitsToJson = True

Trait handlers are defined by hiarachy:

1) Traits can use jsonHandler tag key to define a specific jsonHandler class (typically defined outside the class) or use the jsonHandler(trait) decorator (typically inside a class definition).

Example:

myint = Int().tag(saveToJson=True, jsonHandler=myHandler) # myHandler defined elsewhere

or

myint = Int().tag(saveToJson=True)

@jsonHandler(myint) class myHandler(object): #myHandler defined inside the class

2) A custom traitlet class can have a traitlet-specific jsonHandler class defined inside its class definition (see Adict for example).

3) A TraitBase class can have a jsonHandler, which it would use for all traits. NB assure that the handler can deal with all trait types defined in the class

4. No explicit handler defined, json decoders are assumed be able to handle it.

A jsonHandler class must derive from TraitJsonHandlerBase and can subclass two methods:

encode(obj, trait) which returns a json serialisable object decode(obj, trait, value) which uses value to generate and set the new (or modified) obj

Example:

class myHandler(TraitJsonHandlerBase):

def encode(self, obj, trait):

“returns a json serialisable object” value = getattr(obj, trait) – some action on value – return value

def decode(self, obj, trait, value):

“uses value to generate and set the new (or modified) obj” newValue = — some action using value — setattr(obj, trait, newValue)

Any CcpNmrJson-derived class maintains metadata. Use the setJsonMetadata(), getJsonMetadata()

and hasJsonMetadata() methods to access

NB: Need to register the class for proper restoring from the json data Example:

class MyClass(CcpNmrJson):

#end class MyClass.register()

classVersion = None

duplicate(**metadata)

Convenience method to return a duplicate of self, using toJson and fromJson methods and a ad-hoc json conversion for those traits that were not included. Method will fail if attributes cannot be serialised

fromJson(string)

Populate/update self with data from json string; a list of (trait, value) tuples Return self

getJsonMetadata(*keys) → list

get values for keys from metadata; get value for all keys if len(keys) == 0

hasJsonMetadata(key) → bool

Return: True if metadata has key

static isRegistered(className)

Return True if className is registered

keys(**metadata)

Return the keys; excluding the json.METADATA trait; optionally filter for trait metadata; NB these are different from the json METADATA. The latter store information regarding the class, version, user, path, etc of the json representation of the object.

static newObjectFromJson(path=None, jsonString=None, **kwds)

Create a new object defined by either the: - json-file path; reading the jsonString or - jsonString The jsonString should be a json encoded dict with valid metadata needed for restoring the objects kwds are passed to the class instantiation of the object

:return the object restored from the Json data

objectInfo = None

classmethod register()

Register the class

restore(path, **kwds)

Restore from file using appropriate handlers depending on extension; return self Non-functional unless a handler is added by fileHandler decorator. **kwds do get passed on to the ‘fromX’ method defined by the fileHandler decorator. :return self

save(path, **kwds)

Save using appropriate handlers depending on extension. Non-functional unless a handler is added by fileHandler decorator. **kwds do get passed on to the ‘toX’ method defined by the fileHandler decorator.

saveAllTraitsToJson = False

setJsonMetadata(key, value, force=False)

Update Json metadata with kwds (key,value) pairs; guard for any json-related keys that should not be changed this way :param key: the key of the metadata to be updated :param value: the value of the metadata to be updated; must be json serialisable

toJson(**kwds)

Return self as list of (trait, value) tuples represented in a json string

class ccpn.util.traits.CcpNmrJson.CcpnJsonDirectoryABC

Bases: collections.OrderedDict

An Abstract base class that restores objects (type CcpNmrJson) from the json files in a directory as (key, object) pairs

attributeName = None

directory = None

extension = '.json'

restoreFromJson()

restore all records from directory; populate the ordered-dict

saveToJson()

Save all records to json

sorted = False

class ccpn.util.traits.CcpNmrJson.Constants

Bases: object

CLASSNAME = 'className'

CLASSVERSION = 'classVersion'

FILEHANDLERS = '_fileHandlers'

JSONHANDLER = 'jsonHandler'

JSONVERSION = 'jsonVersion'

LASTPATH = 'lastPath'

METADATA = '_metadata'

METADATA_KEYS = ('jsonVersion', 'className', 'classVersion', 'user', 'lastPath', 'timestamp')

RECURSION = 'recursion'

TIMESTAMP = 'timestamp'

UPDATEHANDLERS = '_updateHandlers'

USER = 'user'

ccpn.util.traits.CcpNmrJson.fileHandler(extension, toString, fromString)

Decorator to define toString, fromString methods for a file with extension. It defines the _fileHandler dict for the class, used to store the various fileHandlers (for each extension type).

ccpn.util.traits.CcpNmrJson.jsonHandler(trait)

decorator for defining a json handler class on a trait

ccpn.util.traits.CcpNmrJson.update(updateHandler, push=False)

Decorator to register updateHandler function It also defines the _update method and _updateHandlers list for the class.

Parameters

• updateHandler –

  a function to update the dataDict with profile:

  updateHandler(obj, dataDict) -> dataDict

  obj: object that is being restored dataDict: original dict with (attribute, value) pairs returns: dataDict consistent with obj

• push – push to the front of the _updateHandlersList (i.e executed first)

ccpn.util.traits.CcpNmrTraits module

CcpNmr version of the Trailets; all subclassed for added functionalities: - _traitOrder - fixing of default_value issues (see also https://github.com/ipython/traitlets/issues/165) - json handlers

class ccpn.util.traits.CcpNmrTraits.Adict(default_value={}, allow_none=False, read_only=None, **kwargs)

Bases: traitlets.traitlets.TraitType, ccpn.util.traits.CcpNmrTraits._Ordered

A trait that defines a json serialisable AttributeDict; dicts or (key,value) iterables are automatically cast into AttributeDict Recursion is not active

default_value = {}

info_text = "'an AttributeDict'"

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.RecursiveDictHandlerABC

klass

alias of ccpn.util.AttributeDict.AttributeDict

recursion = False

validate(obj, value)

Assure a AttributeDict instance

class ccpn.util.traits.CcpNmrTraits.Any(*args, **kwargs)

Bases: traitlets.traitlets.Any, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.Bool(*args, **kwargs)

Bases: traitlets.traitlets.Bool, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.CBool(*args, **kwargs)

Bases: traitlets.traitlets.CBool, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.CFloat(*args, **kwargs)

Bases: traitlets.traitlets.CFloat, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.CInt(*args, **kwargs)

Bases: traitlets.traitlets.CInt, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.CList(trait=None, default_value=[], minlen=0, maxlen=9223372036854775807, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.List, ccpn.util.traits.CcpNmrTraits._Ordered

Casting list, any iterable

validate(obj, values)

class ccpn.util.traits.CcpNmrTraits.CPath(default_value='', allow_none=False, read_only=False, **kwargs)

Bases: traitlets.traitlets.TraitType, ccpn.util.traits.CcpNmrTraits._Ordered

A trait that defines a casting Path object and is json serialisable

default_value = Path('.')

info_text = "'an Path object'"

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

Serialise Path to be json compatible.

decode(obj, trait, value)

uses value to generate and set the new (or modified) obj

encode(obj, trait)

returns a json serialisable object

validate(obj, value)

Assure a Path instance

class ccpn.util.traits.CcpNmrTraits.CString(default_value='', encoding='utf8', allow_none=False, read_only=None, **kwargs)

Bases: traitlets.traitlets.TraitType, ccpn.util.traits.CcpNmrTraits._Ordered

A trait that defines a string object, casts from bytes object and is json serialisable

NONE_VALUE = '__CSTRING_NONE_VALUE__'

asBytes(value)

Return value encoded as a bytes object; encode None

default_value = ''

fromBytes(value)

Return value decoded from bytes object; decode NONE_VALUE to None

info_text = "'an string'"

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

json compatible;

validate(obj, value)

Assure a str instance

class ccpn.util.traits.CcpNmrTraits.CTuple(*traits, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.Tuple

Casting tuple, any iterable

validate(obj, values)

class ccpn.util.traits.CcpNmrTraits.CUnicode(*args, **kwargs)

Bases: traitlets.traitlets.CUnicode, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.Dict(trait=None, traits=None, default_value={}, **kwargs)

Bases: traitlets.traitlets.Dict, ccpn.util.traits.CcpNmrTraits._Ordered

Fixing default_value problem

class ccpn.util.traits.CcpNmrTraits.Float(*args, **kwargs)

Bases: traitlets.traitlets.Float, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.Immutable(value)

Bases: ccpn.util.traits.CcpNmrTraits.Any, ccpn.util.traits.CcpNmrTraits._Ordered

info_text = 'an immutable object, intended to be used as constant'

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

Serialise Immutable to be json compatible.

decode(obj, trait, value)

uses value to generate and set the new (or modified) obj

class ccpn.util.traits.CcpNmrTraits.Instance(*args, **kwargs)

Bases: traitlets.traitlets.Instance, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.Int(*args, **kwargs)

Bases: traitlets.traitlets.Int, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.List(trait=None, default_value=[], minlen=0, maxlen=9223372036854775807, **kwargs)

Bases: traitlets.traitlets.List, ccpn.util.traits.CcpNmrTraits._Ordered

Fixing default_value problem

class ccpn.util.traits.CcpNmrTraits.Odict(default_value={}, allow_none=False, read_only=False, **kwargs)

Bases: traitlets.traitlets.TraitType, ccpn.util.traits.CcpNmrTraits._Ordered

A trait that defines a json serialisable OrderedDict; dicts are automatically cast into OrderedDict Recursion is not active

default_value = {}

info_text = "'an OrderedDict'"

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.RecursiveDictHandlerABC

klass

alias of collections.OrderedDict

recursion = False

validate(obj, value)

Assure a OrderedDict instance

class ccpn.util.traits.CcpNmrTraits.RecursiveAdict(default_value={}, allow_none=False, read_only=None, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.Adict

A trait that defines a json serialisable AttributeDict; dicts or (key,value) iterables are automatically cast into AttributeDict Recursion is active

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.RecursiveDictHandlerABC

klass

alias of ccpn.util.AttributeDict.AttributeDict

recursion = True

class ccpn.util.traits.CcpNmrTraits.RecursiveDict(trait=None, traits=None, default_value={}, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.Dict

A dict trait that implements recursion of any of the values that are a CcpNmrJson (sub)type Recursion is active by default, unless tagged with .tag(recursion=False)

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.RecursiveDictHandlerABC

klass

alias of dict

class ccpn.util.traits.CcpNmrTraits.RecursiveList(trait=None, default_value=[], minlen=0, maxlen=9223372036854775807, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.List

A list trait that implements recursion of any of the values that are a CcpNmrJson (sub)type

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.RecursiveListHandlerABC

klass

alias of list

recursion = True

class ccpn.util.traits.CcpNmrTraits.RecursiveOdict(default_value={}, allow_none=False, read_only=False, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.Odict

A trait that defines a json serialisable OrderedDict; dicts are automatically cast into OrderedDict Recursion is active

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.RecursiveDictHandlerABC

klass

alias of collections.OrderedDict

recursion = True

class ccpn.util.traits.CcpNmrTraits.RecursiveSet(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.Set

A Set trait that implements recursion of any of the values that are a CcpNmrJson (sub)type

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.RecursiveListHandlerABC

klass

alias of set

recursion = True

class ccpn.util.traits.CcpNmrTraits.RecursiveTuple(*traits, **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.Tuple

A tuple trait that implements recursion of any of the values that are a CcpNmrJson (sub)type

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.RecursiveListHandlerABC

klass

alias of tuple

recursion = True

class ccpn.util.traits.CcpNmrTraits.Set(trait=None, default_value=None, minlen=0, maxlen=9223372036854775807, **kwargs)

Bases: traitlets.traitlets.Set, ccpn.util.traits.CcpNmrTraits._Ordered

Fixing default_value problem

class ccpn.util.traits.CcpNmrTraits.Tuple(*traits, **kwargs)

Bases: traitlets.traitlets.Tuple, ccpn.util.traits.CcpNmrTraits._Ordered

Fixing default_value problem

class ccpn.util.traits.CcpNmrTraits.Unicode(*args, **kwargs)

Bases: traitlets.traitlets.Unicode, ccpn.util.traits.CcpNmrTraits._Ordered

class ccpn.util.traits.CcpNmrTraits.V3Object(default_value=None, allow_none=True, **kwargs)

Bases: traitlets.traitlets.TraitType, ccpn.util.traits.CcpNmrTraits._Ordered

A trait that defines a V3-object, json serialisable through its Pid

default_value = None

info_text = 'A V3-Object'

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

json compatible;

decode(obj, trait, value)

uses value to generate and set the new (or modified) obj

encode(obj, trait)

returns a json serialisable object

validate(obj, value)

Assure a str instance

class ccpn.util.traits.CcpNmrTraits.V3ObjectList(default_value=[], **kwargs)

Bases: ccpn.util.traits.CcpNmrTraits.List

A trait that defines a list of V3-objects, json serialisable through their Pid’s

default_value = []

info_text = 'A V3-ObjectList'

class jsonHandler

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

json compatible;

decode(obj, trait, value)

uses value to generate and set the new (or modified) obj

encode(obj, trait)

returns a json serialisable object

ccpn.util.traits.TraitBase module

class ccpn.util.traits.TraitBase.TraitBase(**kwargs)

Bases: traitlets.traitlets.HasTraits

Class to give HasTraits dict-like methods keys, values, update, items and iteration

asDict(**metadata)

return trait, value pairs as dict, optionally filtering for metadata

getAllTraitObjects(objectOnly=False, **metadata) → dict

Return a dict of (traitName, trait object) key,value pairs, optionally filtering for metadata. If objectOnly is True, only traits defined for this object are included; if False, also include any inherited traits.

getInfo(noDoc=False, noTraits=False, noValues=False, maxLen=50, **traits)

Extract information from: - Class docstring - .metadata[‘info’] (if metadata is present) - all traits tagged with ‘info’

Modify what is included using the noDoc, noTraits or **traits. For the latter, setting a trait True or False will switch its inclusion in the output.

Example: print(a.info(noDoc=True, noTraits=True, maxLen=50, mydict=True))

==> does not print the doc-string, does not print any traits (noTraits=True) except trait ‘mydict’ (mydict=True). The output of the trait values is limited to 50 characters.

return string, optionally limited to maxLen if maxLen is not None

getItemTrait(trait)

Return the trait object corresponding to trait for items of an iterable, i.e. used for validate_items or None if does not exists

getMetadata(trait, key, default=None)

convenience for trait_metadata

getTrait(trait)

Return the trait object corresponding to trait, or None if does not exists

getTraitDefaultValue(trait)

convenience: return default value of trait

getTraitObject(trait)

get the trait object or None if trait does not exist

getTraitValue(trait)

convenience (to complement setTraitValue): return value of trait

hasTrait(trait)

Convenience, Return True if self has trait

isMutableTrait(trait)

Return True is trait is mutable

items(**metadata)

iterable over key, value pairs, optionally filtering for metadata

keys(**metadata)

get keys (object only), optionally filtering for metadata

keysInOrder = True

print(printInfo=False)

Print all traits

setTraitDefaultValue(trait)

convenience: set trait to default value

setTraitValue(trait, value, force=False)

Convenience: set value of trait, optionally overwriting immutable ones

update(other, **metadata)

update self with values from other (dict-like), optionally filtering for metadata

values(**metadata)

get values, optionally filtering for metadata

ccpn.util.traits.TraitJsonHandlerBase module

class ccpn.util.traits.TraitJsonHandlerBase.CcpNmrJsonClassHandlerABC

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

Abstract base class to handle class-like traits of the CcpNmrJson (sub-)type

decode(obj, trait, value)

uses value to generate and set the new (or modified) obj

encode(obj, trait)

returns a json serialisable object

class ccpn.util.traits.TraitJsonHandlerBase.RecursiveDictHandlerABC

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

Abstract base class to handle (optionally) recursion of dict-like traits Each value of the (key,value) pairs must of CcpNmrJson (sub-)type

decode(obj, trait, theList)

uses value to generate and set the new (or modified) obj

encode(obj, trait)

returns a json serialisable object

klass = None

recursion = True

class ccpn.util.traits.TraitJsonHandlerBase.RecursiveListHandlerABC

Bases: ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

Abstract base class to handle recursion of list-like traits Each value of the (list must of CcpNmrJson (sub-)type

decode(obj, trait, theList)

uses value to generate and set the new (or modified) obj

encode(obj, trait)

returns a json serialisable object

klass = None

recursion = True

class ccpn.util.traits.TraitJsonHandlerBase.TraitJsonHandlerBase

Bases: object

Base class for all Trait json handlers;

Any jsonHandler class must derive from TraitJsonHandlerBase and can subclass two methods:

encode(obj, trait) which returns a json serialisable object decode(obj, trait, value) which uses value to generate and set the new (or modified) obj

Example:

class myHandler(TraitJsonHandlerBase):

def encode(self, obj, trait):

“returns a json serialisable object” value = getattr(obj, trait) – some action on value – return value

def decode(self, obj, trait, value):

“uses value to generate and set the new (or modified) obj” newValue = — some action using value — setattr(obj, trait, newValue)

decode(obj, trait, value)

uses value to generate and set the new (or modified) obj

encode(obj, trait)

returns a json serialisable object