timedict 0.0.1

A self updating dictionary like structure

Time Dictionary

How to install

> pip install time_dict

Overview

This module implements self-updating structure that is able to handle updating and removing object based on age. Objects added to this structure are assigned timestamp at insertion, then when age of object is exceeded optional action function is called and object is removed from the structure.

NOTE

When using this structure you must explicitly delete it due to thread locking either by calling destroy() method or deleting it as del d or the interpreter will hang at exit

Example Usage

from time_dict import TimeDict
cache = TimeDict(action_time=2, poll_time=0.5)
key = '1'
cache[key] = 1
key in cache
del cache

---

Main parameters are:

action_time - which specifies age in second at which objects should be deleted - 
            time when actions should be performed and object will be deleted from structure

poll_time - frequency in seconds of polling the objects for age timeout,
            experimentally should be around 1/4 of the action_time or less. 
            Please not that too frequent polling
            may negatively affect you application performance

action  -   function that is called on object age timeout. 
            Signature is 'fn(key:Any, value:Any) -> None'

no_delete - do not delete objects when actions was called

Class PARTIALLY implements dictionary interface, implementations allows for:

d = TimeDict(action_time=2, poll_time=0.5)
insertion:
    d[key] = value
updating:
    NOTE: updating only changes the value, age remains unchanged
    d[key] = value
deletion:
      del d[key]
testing for membership:
    key in d
checking length:
    len(d)

All of the above method have optimistic time complexity of O(1) and pessimistic of O(n) due to thread locking except for del which always is O(n)

Rest of the dictionary interface is not implemented by design.

Methods are:

clear() → None

Safely clear all data in the structure :raises Exception

destroy() → None

Destroys the structure, must be called to properly deinitialize it

flush() → None

Flush all the objects by calling the action function, does not remove objects Does not respect object age, calls action method on all objects :raises Exception if updated thread died