Concepts behind pcsg

Immutable Objects

A basic concept behind the pcsg tree are immutable objects. Once an immubtable object is created it can not be modified anymore.

class pcsg.immutable.Object

Base class for immutable objects: only allows attributes to be assigned from the constructor. Assigment of attributes outside the constructor will be prohibited.

Data objects

class pcsg.immutable.DataObject

Base class implementing copy construction, hash and comparison functions for immutable data structures.

Each derived class must define a static method _copyConstructorAttributes () returning a tuple containing base classes and field names. The returned tuple defines which attributes are supplied to the constructor when using the copy () function.

Each derived class could implement a static method _compareAttributes () to select the fields used for hash and comparision functions. When this method is not implemented, _copyConstructorAttributes () will be used instead.

__hash__()

Returns the hash code of this object.

copy(**assignments)

Creates a copy of this object with altered parameters. All named parameters of the constructor can be applied to this method, when a parameter of the constructor is not supplied, the parameter will be inherited from the current instance.

static restore(file, noException: bool = True)

Restore DataObject from file, calls the copy constructor after deserialization. When noException is True, None will be returned on failed restoration, othwerwise an exception will be thrown. Restoration will fail if the implementation has been changed.

store(file)

Store DataObject to file, serializes all attributes defined by _compareAttributes ().

Implementing own data objects

class MyBaseObject (immutable.DataObject):
    """
    Example for implementing a simple DataObject class.
    """
    def __init__ (self, value = 1):
        super ().__init__ ()
        self.value = value

    # List attributes for copy construction
    @staticmethod
    def _copyConstructorAttributes ():
        return (
            'value',        #< add field for copy construction
        )

    # List attributes for hash and comparision functions,
    # when not defined _copyConstructorAttributes will be used
    @staticmethod
    def _compareAttributes ():
        return (
            'value',        #< add field for comparision
        )



class MyObject (MyBaseObject):
    """
    Example for implementing a derived DataObject class.
    """
    def __init__ (self, value = 1, other = 2, noCompare = 3):
        super ().__init__ (value = value)
        self.other = other
        self.noCompare = noCompare

    @staticmethod
    def _copyConstructorAttributes ():
        return (
            MyBaseObject,   #< also copy values of base class
            'other',        #< add field for copy construction
            'noCompare'     #< add field for copy construction
        )

    @staticmethod
    def _compareAttributes ():
        return (
            MyBaseObject,   #< also compare values of base class
            'other'         #< add field for comparision
        )

Hash

The hash module generates hashcodes for values by deep inspection.

A hashcode is guaranteed to be the same for equal values, but equal hashcodes do not guarantee that the values are equal. The hashcode algorithms are designed to minimize the probability of a hash collision, but nevertheless different values may have the same hashcode.

For primitive types like booleans, strings, floats the value will be converted to a hashcode. Lists, Tuples and dictionaries are hashed by deep inspection. The hashcode of an object will be calculated via deep inspection by default. When an object implements its own __hash__() method, the result of __hash__() will used to calculate the returned hashcode and no deep inspection will not be performed.

util.hash()

Calculates a hash code for a list of arguments with arbirtary types, returns an unsigned 64 bit number.

Cache

The cache stores already computed items by a hash value. It is also used to provide a temporary directory for generating temporary files.

cache.setup(tempPrefix: Optional[str] = None, noPersistence: bool = False, ignoreIfAlreadySetup: bool = False)

Setup the cache module. The cache will operate on the directories specified by cachePrefix and tempPrefix. Setup must only be called once, when calling a second time with other parameters, an exception will be thrown.

cache.temporary()

Creates a temporary file name and returns it’s absolute path.

cache.load(suffix: str = '')

Load data object by fingerprint.

cache.store(fingerprint, suffix: str = '')

Store data object by fingerprint.

cache.persistentPath(suffix: str = '', create: bool = False)

Get persistent absolute path of item by fingerprint.