TimeCache

Introduction

This class is a class that stores data to memory. The data is stored with a time to live (TTL) value. When the TTL expires, the data is removed from the cache.

Unlike Singleton TimeCache, this class is not a singleton class.

Examples

This example creates an instance of the TimeCache class with a TTL of 2 seconds.

import time
from ooodev.utils.cache import TimeCache

cache = TimeCache(seconds=2)  # 60 seconds
cache["key"] = "value"
assert "key" in cache # True
assert cache["key"] == "value"

time.sleep(1)
assert "key" in cache # True

time.sleep(3)
assert "key" not in cache # True

This example demonstrates the use of the cache_items_expired event. A callback function is called when the TTL expires.

import threading
from ooodev.utils.cache import TimeCache

LOCK = threading.Lock()

def on_items_expired(source, event):
    with LOCK:
        # event.event_data is a DotDict with an attribute keys
        # that contains a list of keys that have expired.
        keys = event.event_data.keys
        for key in keys:
            print(f"Expired: {key}")

cache = TimeCache(60.0)  # 60 seconds
cache.subscribe_event("cache_items_expired", on_items_expired)
cache["key"] = "value"
value = cache["key"]

Class

class ooodev.utils.cache.TimeCache(seconds, cleanup_interval=60.0)

Time based Cache.

Cached items expire after a specified time. If cleanup_interval is set, then the cache is cleaned up at regular intervals; Otherwise, the cache is only cleaned up when an item is accessed.

Each time an element is accessed, the timestamp is updated. If the element has expired, it is removed from the cache.

When an item expires, the event cache_items_expired is triggered. This event is called on a separate thread. for this reason it is important to make sure that the event handler is thread safe. See Also TimeCache

Parameters:

• seconds (float) –

• cleanup_interval (float) –

__contains__(key)

Return type:

bool

Parameters:

key (Any) –

__delitem__(key)

Remove key.

Parameters:

key (Any) – Any Hashable object.

Raises:

TypeError – If key is None.

Return type:

None

Note

Triggers the event cache_item_removing before removing the item. The Event is a CancelEventArgs and can be canceled.

Triggers the event cache_item_removed after removing the item. The Event is a EventArgs.

The event args event_data is a DotDict instance that contains the key of the item being removed.

Return type:

None

Parameters:

key (Any) –

__getitem__(key)

Return type:

Any

Parameters:

key (Any) –

__init__(seconds, cleanup_interval=60.0)

Time based Cache.

Parameters:

• seconds (float) – Cache expiration time in seconds.

• cleanup_interval (float, optional) – Cache cleanup interval in seconds. If set to 0 then the cleanup is disabled. Defaults to 60.0.

Return type:

None

__len__()

Return type:

int

__setitem__(key, value)

Set value by key.

Parameters:

• key (Any) – Any Hashable object.

• value (Any) – Any object.

Raises:

TypeError – If key or value is None.

Return type:

None

Note

Triggers the event cache_item_adding before adding the item. The Event is a CancelEventArgs and can be canceled.

Triggers the event cache_item_added after adding the item. The Event is a EventArgs.

Triggers the event cache_item_updating before updating the item. The Event is a CancelEventArgs and can be canceled.

Triggers the event cache_item_updated after updating the item. The Event is a EventArgs.

The event args event_data is a DotDict instance that contains the key, value and is_new of the item being added or updated.

Return type:

None

Parameters:

• key (Any) –

• value (Any) –

clear()

Clear cache.

Return type:

None

clear_expired()

Clear expired items from the cache.

Note

Triggers the event cache_items_expired, on a new thread.

The event args event_data is a DotDict instance that contains the keys as a list of the items that were removed.

Return type:

None

get(key)

Get value by key.

Parameters:

key (Any) – Any Hashable object.

Returns:

Value or None if not found.

Return type:

Any

Note

The get method is an alias for the __getitem__ method. So you can use cache_inst.get(key) or cache_inst[key] interchangeably.

put(key, value)

Put value by key.

Parameters:

• key (Any) – Any Hashable object.

• value (Any) – Any object.

Return type:

None

Note

The put method is an alias for the __setitem__ method. So you can use cache_inst.put(key, value) or cache_inst[key] = value interchangeably.

Return type:

None

Parameters:

• key (Any) –

• value (Any) –

remove(key)

Remove key.

Parameters:

key (Any) – Any Hashable object.

Return type:

None

Note

The remove method is an alias for the __delitem__ method. So you can use cache_inst.remove(key) or del cache_inst[key] interchangeably.

Return type:

None

Parameters:

key (Any) –

start_timer()

Start the timer.

This only applies if the cleanup interval is set.

Returns:

True if the timer is started, False if the timer is already running.

Return type:

bool

Note

Triggers the event time_cache_timer_started.

stop_timer()

Stop the timer.

This only applies if the cleanup interval is set.

Returns:

True if the timer is stopped, False if the timer was not running.

Return type:

bool

Note

Triggers the event time_cache_timer_stopped.

property cleanup_interval: float

Gets/Sets Cache cleanup interval in seconds.

Return type:

float

property hits: int

Hits count.

Returns:

Hits count.

Return type:

int

property seconds: float

Gets/Sets Cache expiration time in seconds.

Return type:

float