Package: jk-simpleobjpersistency
jk_simpleobjpersistencyIntroductionThis python module provides a simple persistency for data objects.Information about this module can be found here:github.orgpypi.python.orgHow to use this moduleImport packageTo import the packagejk_simpleobjpersistencyuse the following code:importjk_simpleobjpersistencyImplement a class usable for persistencyIf you want to persist an object you have to consider a few minor aspects for your implementation:Your constructor must be parameterless.You require to implement a regular object method deserializingfroma dictionary:deserialize(self, dataObj:dict)You require to implement a regular object method serializingtoa dictionary:serialize(self) -> dictYou must not use any of these member identifiers:setChanged,store,storeIfChanged,isModified,destroy,isNew,isPersistentas well as_x_isModified._x_persisteer,_x_identifier,_x_isAutoStore.That's it.A quite minimum implementation of a serializing class might then look like this:classMyUserObj(object):def__init__(self):self.userName=Noneself.password=Noneself.eMail=Noneself.yearOfBirth=Nonedefdeserialize(self,jData:dict):self.userName=jData.get("userName")self.password=jData.get("password")self.eMail=jData.get("eMail")self.yearOfBirth=jData.get("yearOfBirth")defserialize(self):return{"userName":self.userName,"password":self.password,"eMail":self.eMail,"yearOfBirth":self.yearOfBirth,}This is just an example but it demonstrates the basic concept. Here: The object variables will hold the object's data, and the methodsdeserialize()andserialize()will be used by the framework to implement persistency.For persistency to work the class and the objects will be patched by the persistency framework. Additional methods are added:setChanged,store,storeIfChanged,isModified,destroy,isNew,isPersistentas well as_x_isModified._x_persisteer,_x_identifier,_x_isAutoStore. This is the reason why you must not use the specific identifiers listed above. (If you do they will get overridden by the framework and your implementation will likely break.)Instantiate and initialize the persistency layerIn order to work with this persistency layer you need a) to instantiate a persistency data manager first and b) register all classes that should be persistent before then c) working with instances of these classes.The most recommended way for isntantiation is something like this:pm=jk_simpleobjpersistency.PersistencyManager("/my/data/dir/path")The path argument is the root directory where data is stored (if not specified otherwise during registration of a class).After that you must register all classes that the persistency layer should deal with. This is done invokingregisterClass()for each class persistency should be active for.A class registration requires the following arguments:Argument nameArgument typRequired or optionalDescriptionclazzA class typerequiredThe class itselfdefaultsdictor an instance of the serialization typeoptionalEither the serialized data or an prototypical instance of the class type (that get serialized by invokingserialize()dirPathstroptionalThe directory to store the data. (By default the class name is used.)autoStorebooloptionalIftruemodified objects get stored automatically on delete if they have been changed. (Default:false)Example:ppdm=jk_simpleobjpersistency.PersistencyManager("testdata")ppdm.registerClass(clazz=MyUserObj,defaults={"eMail":"example@example.com"},dirPath="testdata/users",autoStore=True)As you can see in this example we use a dictionary for the defaults. The content of the dictionary must match expectations of the class implementation.Creating instancesAn instance of an object can be created like this:obj=pp.createObject(MyUserObj,"myUser")That's it.objnow contains a fresh instance ofMyUserObj.But let's have a look at the arguments:Argument nameArgument typRequired or optionalDescriptionclazzA class typerequiredThe class itselfidentifierstroptionalIf specified an instance is created that furtheron will be uniquely identified by this string. If no identifier is specified, a new one is generated.Please note that the object will not have been stored yet. If you throw it away without storing - andautoStoreis notTrue- then data you might have put into the object will be lost.Modifying instancesYou have two options:Either using the modified-flag that is provided by every instance orstore every modified object explicitely.Example:obj=pp.createObject(MyUserObj,"myUser")obj.userName="something"obj.password="somepwd123"obj.store()Or:obj=pp.createObject(MyUserObj,"myUser")obj.userName="something"obj.password="somepwd123"obj.setModified()And later on invokeobj.storeIfModified(). (This storing is performed automatically ifautoStoreis set toTrueduring registration of a class.CAUTION!Be aware that at the end of your program all objects should be stored already. Python defines no order in how objects get disposed: It might well be that
build in functions likeopen()used for writing a file might be disposed already at the time a modified object tries to store itself. It's remains your reponsibility
as programmer to take care that all objects have been properly saved when your program terminates. (Compare:https://stackoverflow.com/questions/23422188/why-am-i-getting-nameerror-global-name-open-is-not-defined-in-del) Have a look atstoreAllModified(clazz)which might
help you in this case.Destroying an instanceInstances can be destroyed by invokingdestroy()on the persistent object itself. Please be aware that this action isimmediate: If data is persistently stored on disk this
data is removed instantly.Example:obj=pp.getObject(MyUserObj,"myUser")obj.destroy()A note about cachingAll objects created or retrieved from backgroud storage are cached. That means that these objectsconsume memory. If this is a problem you can invoke any of these methods at any time:MethodDescriptionclearEntireCache()That will remove all cached intances.clearClassCache(clazz)Clear the cache for a specific class.Contact InformationThis is Open Source code. That not only gives you the possibility of freely using this code it also
allows you to contribute. Feel free to contact the author(s) of this software listed below, either
for comments, collaboration requests, suggestions for improvement or reporting bugs:Jürgen Knauth:pubsrc@binary-overflow.deLicenseThis software is provided under the following license:Apache Software License 2.0