421 lines
16 KiB
Python
421 lines
16 KiB
Python
"""
|
|
|
|
AUTHOR:
|
|
|
|
Khushal P Soonderji
|
|
|
|
DATE:
|
|
|
|
CREATED: Tue, 25th Nov, 2025
|
|
UPDATED: Thu, 27th Nov, 2025
|
|
|
|
OBJECTIVE:
|
|
|
|
To define a caching class that uses in-RAM dicts to hold cached data.
|
|
This is a good way to cache data for a single-machine, single-process service. The cached data is rapidly
|
|
available (since it's held in RAM), but it cannot be shared across various instances.
|
|
|
|
WARNING:
|
|
--------
|
|
THIS IS A STRONGLY STATEFUL WAY OF IMPLEMENTING CACHING. THE USER'S REQUEST WILL HAVE TO HIT EXACTLY THE SAME
|
|
MACHINE AND EXACTLY THE SAME PROCESS ON THAT MACHINE FOR THE CACHE TO BE ANY GOOD.
|
|
|
|
The idea is simple:
|
|
-------------------
|
|
Everything that needs to be cached should have a key (identifier) and a value (the actual data). We hold the
|
|
cache in a dictionary in Python where the identifier becomes the key of the dict, and the value is the cached
|
|
data.
|
|
|
|
REFERENCES:
|
|
|
|
N/A
|
|
|
|
DOWNLOADS:
|
|
|
|
N/A
|
|
|
|
"""
|
|
|
|
|
|
# *****************************************************************************************************************
|
|
# ***** ****
|
|
# *** IMPORT ***
|
|
# ***** ****
|
|
# *****************************************************************************************************************
|
|
|
|
|
|
# To make sibling directories accessible for imports:
|
|
import sys
|
|
sys.path.append(".")
|
|
sys.path.append("..")
|
|
|
|
# Other utils:
|
|
from utils_v2.date_time import date_time
|
|
from utils_v2.string import regex
|
|
from utils_v2.cache_v2.async_base import AsyncCachingBase
|
|
|
|
# To work with datatypes:
|
|
from typing import List, Any
|
|
|
|
|
|
# *****************************************************************************************************************
|
|
# ***** ****
|
|
# *** MACROS / ONE-TIME INIT ***
|
|
# ***** ****
|
|
# *****************************************************************************************************************
|
|
|
|
|
|
# --- Nothing Yet
|
|
|
|
|
|
# *****************************************************************************************************************
|
|
# ***** ****
|
|
# *** VARIABLES ***
|
|
# ***** ****
|
|
# *****************************************************************************************************************
|
|
|
|
|
|
# --- Nothing Yet
|
|
|
|
|
|
# *****************************************************************************************************************
|
|
# ***** ****
|
|
# *** CLASSES ***
|
|
# ***** ****
|
|
# *****************************************************************************************************************
|
|
|
|
|
|
class AsyncMemCache(AsyncCachingBase):
|
|
|
|
def __init__(
|
|
self,
|
|
expiry_check_interval: int | float = 60.0,
|
|
debug = True,
|
|
debug_prefix = "AMemCache | "
|
|
):
|
|
|
|
"""
|
|
Implements a simple cache in RAM that holds and returns all native datatypes. This is good for single-process
|
|
implementations that run on a single machine because the cached data will not be accessible to other processes
|
|
even when running on the same machine. Also, all timestamps are normalized to UTC.
|
|
NOTE: It is NOT async, actually. It has been built on top of an async class so it has been declared as if it is.
|
|
:param expiry_check_interval: How frequently to check for expiry of all the cached data. When you request very
|
|
specific data, its expiry will be checked before serving; but this interval defines a general cleanup to
|
|
release memory.
|
|
:param debug: Whether, or not, you want to show debugging messages from the start.
|
|
:param debug_prefix: The prefix text to show with the debugging messages.
|
|
"""
|
|
|
|
# Invoke the parent class's constructor:
|
|
super().__init__(
|
|
debug = debug,
|
|
debug_prefix = debug_prefix
|
|
)
|
|
|
|
# Create a local dict that will hold the cached data:
|
|
self.__cached_data = {}
|
|
self.__expiry_check_interval = expiry_check_interval
|
|
self.__last_expiry_check_ts = date_time.get_current_utc_date_time(as_string = False).timestamp()
|
|
|
|
# ┓┏ ┓
|
|
# ┣┫┏┓┃┏┓┏┓┏┓┏
|
|
# ┛┗┗ ┗┣┛┗ ┛ ┛
|
|
# ┛
|
|
|
|
async def __expired(
|
|
self,
|
|
key: str
|
|
) -> bool:
|
|
|
|
"""
|
|
Tells you if a key has expired.
|
|
:param key: The key that you want to identify.
|
|
:return: True if expired, False if valid.
|
|
"""
|
|
|
|
# If the key doesn't exist, it has expired:
|
|
if key not in self.__cached_data: return True
|
|
|
|
# If the key exists, but the current timestamp has crossed the expiry timestamp;
|
|
# we also try to delete the key in that case:
|
|
elif self.now_utc >= self.__cached_data[key]["exp"]:
|
|
await self.delete(key, raise_exception = False)
|
|
return True
|
|
|
|
# Otherwise it is yet valid (not expired):
|
|
else: return False
|
|
|
|
async def __clear_expired_keys(self) -> None:
|
|
|
|
"""
|
|
Clears all the expired cached data.
|
|
:return: None.
|
|
"""
|
|
|
|
# If the expiry check interval has not been crossed,
|
|
# we need not go through the process:
|
|
ref_utc = self.now_utc
|
|
if ref_utc - self.__last_expiry_check_ts < self.__expiry_check_interval: return
|
|
|
|
# Otherwise, we note down the current timestamp and proceed:
|
|
self.__last_expiry_check_ts = ref_utc
|
|
|
|
# Enlist all the keys that need to be deleted:
|
|
to_del = [k for k in self.__cached_data.keys() if self.__expired(k)]
|
|
|
|
# Delete the expired keys:
|
|
for k in to_del: await self.delete(k, raise_exception = False)
|
|
|
|
# ┏┓
|
|
# ┃ ┏┓┏┓┏┓
|
|
# ┗┛┗┛┛ ┗
|
|
|
|
async def list_keys(
|
|
self,
|
|
match: str | None = None,
|
|
raise_exception: bool = False
|
|
) -> List[str] | None:
|
|
|
|
"""
|
|
To get a list of all the keys that match the pattern.
|
|
:param match: To match a glob-style pattern. THIS IS NOT FULL-FLEDGED REGEX.
|
|
:param raise_exception: Whether to raise or suppress exceptions.
|
|
:return: The list of keys if successful, else None.
|
|
"""
|
|
|
|
# Clear the expired keys:
|
|
await self.__clear_expired_keys()
|
|
|
|
# Start with an empty list:
|
|
keys_list = []
|
|
|
|
try:
|
|
|
|
# Enlist all the keys,
|
|
# test the pattern against all the keys and keep only those that match:
|
|
for k, v in self.__cached_data.items():
|
|
if not await self.__expired(k):
|
|
if match is None: keys_list.append(k)
|
|
elif regex.match(text = str(k), pattern = match):
|
|
keys_list.append(k)
|
|
|
|
# Done here:
|
|
return list(set(keys_list)) if keys_list else None
|
|
|
|
# If an exception occurs in the process:
|
|
except Exception as exception:
|
|
self._printer("LIST ERR!", exception)
|
|
if raise_exception: raise
|
|
else: return None
|
|
|
|
async def ttl(
|
|
self,
|
|
key: str | bytes,
|
|
raise_exception: bool = False
|
|
) -> int | float | None:
|
|
|
|
"""
|
|
To get the no. of seconds till the expiry of some key.
|
|
:param key: The key to check the expiry of.
|
|
:param raise_exception: Whether to raise or suppress exceptions.
|
|
:return: -1 if the key is persistent (i.e., no expiry time set), -2 if the key does not exist, or the time left
|
|
in seconds if the key exists and is not persistent. If something goes wrong, you will get a null value.
|
|
"""
|
|
|
|
# Clear the expired keys:
|
|
await self.__clear_expired_keys()
|
|
|
|
# Start by assuming failure:
|
|
ttl = None
|
|
|
|
try:
|
|
|
|
# Get the expiry:
|
|
exp_utc = self.__cached_data.get(key, {}).get("exp", None)
|
|
if exp_utc is None: ttl = -2
|
|
else: ttl = exp_utc - self.now_utc
|
|
return ttl
|
|
|
|
# If an exception occurs in the process:
|
|
except Exception as exception:
|
|
self._printer("TTL ERR!", key, exception)
|
|
if raise_exception: raise
|
|
else: return None
|
|
|
|
async def set(
|
|
self,
|
|
key: str | bytes,
|
|
value: Any,
|
|
expiry: float = None,
|
|
raise_exception: bool = False
|
|
) -> bool:
|
|
|
|
"""
|
|
Saves some value to the cache. If an expiry is specified, the data will be deleted after that many seconds.
|
|
:param key: The key with which the data will be stored and retrieved.
|
|
:param value: The value to store.
|
|
:param expiry: The time in seconds after which the data will expire. Must be a positive number.
|
|
:param raise_exception: Whether to raise or suppress exceptions.
|
|
:return: True if cached, else False.
|
|
"""
|
|
|
|
# Clear the expired keys:
|
|
await self.__clear_expired_keys()
|
|
|
|
try:
|
|
|
|
# If the expiry is not specified,
|
|
# make it an unreasonably far off future date:
|
|
if expiry is None: expiry = self.now_utc + self.LONG_EXPIRY
|
|
|
|
# Here we actually try to set the data:
|
|
self.__cached_data[key] = {
|
|
"val": value,
|
|
"exp": self.now_utc + expiry
|
|
}
|
|
|
|
# Done here:
|
|
return True
|
|
|
|
# If an exception occurs in the process:
|
|
except Exception as exception:
|
|
self._printer("SET ERR!", key, exception)
|
|
if raise_exception: raise
|
|
else: return False
|
|
|
|
async def get(
|
|
self,
|
|
key: str | bytes,
|
|
raise_exception: bool = False,
|
|
on_fail: Any = None
|
|
) -> Any:
|
|
|
|
"""
|
|
Retrieve the cached value.
|
|
:param key: The key with which the data was saved.
|
|
:param raise_exception: Whether to raise or suppress exceptions.
|
|
:param on_fail: What to return if the process fails due to an exception.
|
|
:return: The retrieved data or null if not found.
|
|
"""
|
|
|
|
# Clear the expired keys:
|
|
await self.__clear_expired_keys()
|
|
|
|
try:
|
|
|
|
# Here we try to fetch the data:
|
|
data = on_fail
|
|
raw = self.__cached_data[key]
|
|
|
|
# Check for expiry if it was a cache hit:
|
|
if await self.__expired(key) and raise_exception: raise RuntimeError(f"Key '{key}' not found.")
|
|
else: data = raw["val"]
|
|
|
|
# if self.now_utc >= raw["exp"]: await self.delete(key, raise_exception = True)
|
|
# else: data = raw["val"]
|
|
|
|
# Done here:
|
|
return data
|
|
|
|
# If an exception occurs in the process:
|
|
except Exception as exception:
|
|
self._printer("CACHE MISS!", key, exception)
|
|
if raise_exception: raise
|
|
else: return on_fail
|
|
|
|
async def delete(
|
|
self,
|
|
key: str | bytes,
|
|
raise_exception: bool = False
|
|
) -> bool:
|
|
|
|
"""
|
|
Prematurely delete the value from the cache before it expires.
|
|
:param key: The key with which the data was saved.
|
|
:param raise_exception: Whether to raise or suppress exceptions.
|
|
:return: True if deleted, else False.
|
|
"""
|
|
|
|
# Clear the expired keys:
|
|
await self.__clear_expired_keys()
|
|
|
|
try:
|
|
|
|
# Try to manually delete the key before expiry:
|
|
response = self.__cached_data.pop(key, None)
|
|
return True if response else False
|
|
|
|
# If an exception occurs in the process:
|
|
except Exception as exception:
|
|
self._printer("DEL ERR!", key, exception)
|
|
if raise_exception: raise
|
|
else: return False
|
|
|
|
async def count(
|
|
self,
|
|
key: str | bytes,
|
|
value: int = 1,
|
|
expiry: float = None,
|
|
raise_exception: bool = False
|
|
) -> int | None:
|
|
|
|
"""
|
|
To use simple counters. If the counter (identified by the 'key') exists, it will be incremented, else the
|
|
counter will be created and the value will be incremented from 0.
|
|
:param key: The name of the counter.
|
|
:param value: The amount to increment the value by. Send negative values to count backwards.
|
|
:param expiry: The time (in seconds) in which the counter expires. Starts from the time the counter is created.
|
|
This value has to be an integer. If a float is passed, the value will be rounded off.
|
|
:param raise_exception: Whether to raise or suppress exceptions.
|
|
:return: The latest value of the counter. Will be null if something went wrong and the exception was suppressed.
|
|
"""
|
|
|
|
# Clear the expired keys:
|
|
await self.__clear_expired_keys()
|
|
|
|
try:
|
|
|
|
# If the key already exists and hasn't expired yet:
|
|
if not await self.__expired(key):
|
|
self.__cached_data[key]["val"] = self.__cached_data[key]["val"] + value
|
|
|
|
# If the key has expired or if it is new:
|
|
else:
|
|
await self.set(
|
|
key = key,
|
|
value = value,
|
|
expiry = expiry,
|
|
raise_exception = True
|
|
)
|
|
|
|
# Return the new value:
|
|
return await self.get(key, raise_exception = True)
|
|
|
|
# If an exception occurs in the process:
|
|
except Exception as exception:
|
|
self._printer("COUNT ERR!", key, value, exception)
|
|
if raise_exception: raise
|
|
else: return None
|
|
|
|
|
|
# *****************************************************************************************************************
|
|
# ***** ****
|
|
# *** FUNCTIONS ***
|
|
# ***** ****
|
|
# *****************************************************************************************************************
|
|
|
|
|
|
# --- Nothing Yet
|
|
|
|
|
|
# *****************************************************************************************************************
|
|
# ***** ****
|
|
# *** MAIN PROGRAM ***
|
|
# ***** ****
|
|
# *****************************************************************************************************************
|
|
|
|
|
|
if __name__ == "__main__":
|
|
|
|
pass
|