Commit 19de1651 authored by eric pellegrini's avatar eric pellegrini
Browse files

Fully docstringed MDANSE.Core.UserDefinitions module

parent 3264c6c9
......@@ -38,11 +38,26 @@ from MDANSE.Core.Error import Error
from MDANSE.Core.Singleton import Singleton
class UserDefinitionsError(Error):
pass
'''
This class handles exception related to UserDefinitions
'''
class UnicodeDict(dict):
'''
This class implements a specification of python dict that converts automatically any string key in unicode.
This kind of object is useful when exposed to package such as wxPython that implements string as unicode.
'''
def __contains__(self, item):
'''
Returns True if a given key is found in the dictionary.
If the key is basestring then it will be searched as a unicode string.
:param item: the key to search in the dictionary
:type item: any valid key
'''
if isinstance(item,basestring):
return super(UnicodeDict,self).__contains__(unicode(item))
......@@ -51,6 +66,16 @@ class UnicodeDict(dict):
return super(UnicodeDict,self).__contains__(item)
def __setitem__(self, item, value):
'''
Sets the value of a given key.
If the key is a basestirng, it will be converted internally in a unicode objet.
:param item: the key to set in the dictionary
:type item: any valid key
:param value: the value to associate with the key
:type value: any python object
'''
if isinstance(item,basestring):
......@@ -59,21 +84,28 @@ class UnicodeDict(dict):
else:
super(UnicodeDict,self).__setitem__(item,value)
class UserDefinitions(UnicodeDict):
class UserDefinitions(object):
'''
This class is used to register, save and delete UD (UD for User Definition).
This class is used to register, save and delete MDANSE user definitions (a.k.a. UD).
Basically a UD file is a cPickle file that must store a dictionary of definitions related to a target file.
The target file can be any kind of file on which some extra information should be attached.
For instance, if the target file is a trajectory, the UD file may contains selected atoms,
center or axis that can be used for further analysis in new MDANSE sessions.
Basically, user definitions are used to keep track of definitions made on a given target. The target can
be a file or any kind of object that has to be associated with the user definitions.
This definitions can be selections of atoms, Q vectors definitions, axis definitions ... The
user definitions are loaded when MDANSE starts through a cPickle file that will store these definitions.
They are stored internally as MDANSE.Framework.UserDefinables.IUserDefinable derived objects in a nested
dictionary whose primary key is the target name, secondary key is the category of the user definition and
tertiary key is the name of the user definition.
'''
__metaclass__ = Singleton
_path = os.path.join(PLATFORM.application_directory(),"user_definitions.ud")
def restore_state(self):
def load(self):
'''
Load the user definitions.
'''
if not os.path.exists(UserDefinitions._path):
return
......@@ -92,6 +124,12 @@ class UserDefinitions(UnicodeDict):
f.close()
def save(self, path=None):
'''
Save the user definitions.
:param path: the path of the user definitions file.
:type path: str
'''
if path is None:
path = self._path
......@@ -104,34 +142,52 @@ class UserDefinitions(UnicodeDict):
cPickle.dump(self, f, protocol=2)
f.close()
def check_and_get(self, target, typ, name):
def get(self, target, category, name):
'''
Returns a user definition given its target, category and its name.
:param target: the target related to the user definition
:type target: str
:param category: the category of the user definition
:type category: str
:param name: the name of the user definition
:type name: str
'''
try:
ud = self[name]
except (KeyError,TypeError):
ud = self[target][category][name]
# Any kind of error should be caught here.
except:
raise UserDefinitionsError('The item %r is not registered in the user definition' % str(name))
else:
else:
if ud.target != target:
raise UserDefinitionsError('Target mismatch between %r and %r' % (target,ud.target))
if ud.type != typ:
raise UserDefinitionsError('Type mismatch between %r and %r' % (typ,ud.type))
if ud.type != category:
raise UserDefinitionsError('Type mismatch between %r and %r' % (category,ud.type))
return ud
def __setitem__(self, item, value):
from MDANSE.Framework.UserDefinables.IUserDefinable import IUserDefinable
if not isinstance(value,IUserDefinable):
raise UserDefinitionsError("Invalid value for user definition: must be a user definable object")
def set(self, target, category, name, ud):
'''
Sets a new user definition.
super(UserDefinitions,self).__setitem__(item,value)
def filter(self, basename,typ):
:param target: the name of the user definition to set
:type target: str
:param category: the category of the user definition to set
:type category: str
:param name: the name of the user definition to set
:type name: str
:param ud: the user definition to set
:type ud: MDANSE.Framework.UserDefinables.IUserDefinable derived object
'''
targets = self.setdefault(unicode(target),{})
return [k for k,v in self.iteritems() if (v.target==basename and v.type==typ)]
categories = targets.setdefault(unicode(category),{})
categories[unicode(name)] = ud
USER_DEFINITIONS = UserDefinitions()
\ No newline at end of file
......@@ -88,7 +88,7 @@ class IUserDefinable(dict):
return self._creationTime
def __setitem__(self, item,value):
def __setitem__(self, item, value):
# It is not possible to set directly a key of a user definable object
if item in self._keywords:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment