kisa-utils 0.37.3__py3-none-any.whl → 0.37.4__py3-none-any.whl

kisa_utils/cache.py

@@ -8,6 +8,7 @@ import time
 from . import threads
 from . import queues
 from . import db
+from typing import Callable
 
 class CacheException(Exception):
     pass
@@ -17,7 +18,12 @@ class _EmptyCacheValue:
 
 class Cache:
     __ACTIVE_CACHES = {}
-    def __init__(self, name:str):
+    def __init__(self, name:str) -> None:
+        '''
+        create a cache instance
+        Args:
+            name(str): the cache name
+        '''
         self.__cache = {
             # key: {
             #     'lastUpdated': int, 
@@ -75,23 +81,30 @@ class Cache:
         self.__cache[key]['value'] = value
         self.__cache[key]['lastUpdated'] = now
 
-    def addKey(self, name:str, updator:callable, autoUpdateAfter:int=3600, duplicateUpdateThreshold:float=30) -> dict:
+    def addKey(self, name:str, updator:Callable, autoUpdateAfter:int=3600, duplicateUpdateThreshold:float=30) -> dict:
         '''
         create a new cache key
 
-        @param `name`: the name of the key
-        @param `updator`: the function to call everytime we need to update the key. 
-                          The value of the key is whatever the function returns.
-                          Also, the `updator` should not take any arguments or keywords
-        @param `autoUpdateAfter`: how many SECONDS to wait before we automatically call the `updator` function
-        @param `duplicateUpdateThreshold`: SECONDS within which if multiple requests to update the key will be ignored as long as one is already activated.
-            say we have 20 calls to update a key in 1 minute, only 1 request will be obeyed to avoid strange deadlocks and database contension-resources
+        Args:
+            name(str): the name of the key
+            updator(Callable): the function to call everytime we need to update the key. 
+                            The value of the key is whatever the function returns.
+                            Also, the `updator` should not take any arguments or keywords
+            autoUpdateAfter(int): how many SECONDS to wait before we automatically call the `updator` function
+            duplicateUpdateThreshold(float): SECONDS within which if multiple requests to update the key will be ignored as long as one is already activated.
+                say we have 20 calls to update a key in 1 minute, only 1 request will be obeyed to avoid strange deadlocks and database contension-resources
         
-        @returns {'status':BOOL, 'log':STR}
-
+        Returns:
+            ```
+            {
+                'status':bool,
+                'log':str
+            }
+            ```
+            
         NB: the result of the `updator` will be ignored if;
             - its `None`
-            - its a `dict` with `status=False`
+            - its a `dict` with `status` set to `False`
             - the `updator` raised an exception
         '''
         reply = {'status':False, 'log':''}
@@ -131,10 +144,16 @@ class Cache:
     def triggerKeyUpdate(self, key:str) -> dict:
         '''
         trigger update value of a key
-
-        @param `key`: name of the cache key
-
-        @returns {'status':BOOL, 'log':STR}
+        Args:
+            key(str): name of the cache key
+
+        Returns:
+        ```
+        {
+            'status':bool, 
+            'log':str
+        }
+        ```
         '''
         reply = {'status':False, 'log':''}
 
@@ -147,10 +166,17 @@ class Cache:
     def getValue(self, key:str) -> dict:
         '''
         attempt to get the value of a key set in the cache
-
-        @param `key`: name of the cache key
-
-        @returns {'status':BOOL, 'log':STR, 'value':Any}
+        Args:
+            key(str): name of the cache key
+
+        Returns:
+        ```
+        {
+            'status':bool, 
+            'log':str, 
+            'value':Any
+        }
+        ```
         '''
         
         reply = {'status':False, 'log':'', 'value':None}
@@ -170,10 +196,17 @@ class Cache:
 def create(name:str) -> dict:
     '''
     create a new cache object
-
-    @param `name`: the name of the cache
-
-    @returns {'status':BOOL, 'log':STR, 'cache':CACHE_OBJECT}
+    Args:
+        name(str): the name of the cache
+
+    Returns:
+    ```
+    {
+        'status':bool,
+        'log':str,
+        'cache': Cache
+    }
+    ```
     '''
     reply = {'status':False, 'log':'', 'cache':None}
 
@@ -190,6 +223,11 @@ def create(name:str) -> dict:
     return reply
 
 def get(name:str) -> Cache | None:
+    '''
+    get cache by its name
+    Args:
+        name(str): the cache name
+    '''
     return Cache._Cache__ACTIVE_CACHES.get(name,None)
 
 if __name__=='__main__':

kisa_utils/codes.py

@@ -7,7 +7,15 @@ __MAX_CODE_LENGTH = 32
 __ID_SPACE = string.ascii_lowercase + string.ascii_uppercase + string.digits
 
 def new(length:int=12, useSeparator:bool=False, xterSet:str=__ID_SPACE) -> str:
-    'compexity of the code will be len(__ID_SPACE)^length'
+    '''
+    generate a new code
+    Args:
+        length(int): length of the code to generate
+        useSeparator(bool): include a separator ('-') in the code
+        xterSet(str): the chatacters to use eg '0123456789' ensures the code only has numbers in it
+    Note:
+        compexity of the code will be len(xterSet)^length
+    '''
     
     assert(length>0 and length<=__MAX_CODE_LENGTH)
     code = ''

kisa_utils/config.py

@@ -32,7 +32,9 @@ def _getTopicAndKey(path:str) -> list[str,str]:
 
 def getValue(path:str) -> Any|None:
     '''
-    path: topicName/keyName eg 'topic1/key1'
+    get the value of a set topic-key path
+    Args:
+        path(str): topicName/keyName eg 'topic1/key1'
     '''
 
     topic, key = _getTopicAndKey(path)
@@ -41,7 +43,9 @@ def getValue(path:str) -> Any|None:
     
 def setValue(path:str, value:Any) -> bool:
     '''
-    path: topicName/keyName eg 'topic1/key1'
+    set the value of a set topic-key path
+    Args:
+        path(str): topicName/keyName eg 'topic1/key1'
     '''
     topic, key = _getTopicAndKey(path)
 
@@ -58,6 +62,11 @@ def setValue(path:str, value:Any) -> bool:
     return True
 
 def getTopic(topic:str) -> dict|None:
+    '''
+    get topic data
+    Args:
+        topic(str): the topic name
+    '''
     topic,_ = _getTopicAndKey(f'{topic}/_')
     data = None
 
@@ -72,9 +81,10 @@ def getTopic(topic:str) -> dict|None:
     return data
 
 def getConfigPath() -> str:
+    '''get path to the config files root directory'''
     return __config_root_path
 
-def init():
+def __init__() -> None:
     global __config_root_path
     _rootPath = getValue('_sys_/configPath')
     if _rootPath:
@@ -82,4 +92,4 @@ def init():
     else:
         setValue('_sys_/configPath', __config_root_path)
 
-init()
+__init__()

kisa_utils/dates.py

@@ -1,6 +1,5 @@
 import datetime
 import time
-from typing import Tuple
 
 WEEK_DAYS = {
     1:'Monday', 2:'Tuesday', 3:'Wednesday',
@@ -8,8 +7,16 @@ WEEK_DAYS = {
     7: 'Sunday'
 }
 
-def weekRange(date:str|datetime.datetime) -> Tuple[str,str]: # assumes standardizedDates to be given
-    'return week range (monday-sunday) in thich a date(YYYY-MM-DD) belongs'
+def weekRange(date:str|datetime.datetime) -> tuple[str,str]: # assumes standardizedDates to be given
+    '''
+    return a list containing the monday and sunday that belong to the week
+    Args:
+        date(str|datetime.datetime): the date whose week-range we need to get
+    Returns:
+        ```
+        (monday:str, sunday:str) # each date is in format "YYYY-MM-DD"
+        ```
+    '''
     
     if isinstance(date,(str,bytes)):
         date = datetime.datetime.strptime(date, '%Y-%m-%d')
@@ -22,8 +29,17 @@ def weekRange(date:str|datetime.datetime) -> Tuple[str,str]: # assumes standardi
  # assumes standardizedDates to be given
 def humanizeDate(date:str, includeWeekDay:bool=False) -> str:
     '''
-    convert 'YYYY-MM-DD' to 'DD MonthCode YYYY' eg
-    2021-09-23 - > '23 Sep 2021' || ''Thu 23 Sep 2021''
+    convert date into a human-friendly format
+    Args:
+        date(str): the date to humanize. its in the `YYYY-MM-DD` format
+        includeWeekDay(bool): wheather or not to include the week-day
+    Returns:
+        `str` in format `DD MonthCode YYYY`
+    Examples:
+        ```
+        humanizeDate('2021-09-23') -> '23 Sep 2021'
+        humanizeDate('2021-09-23', True) -> 'Thu 23 Sep 2021'
+        ```    
     '''
         
     if includeWeekDay:
@@ -35,20 +51,67 @@ def humanizeDate(date:str, includeWeekDay:bool=False) -> str:
     #return f'{date[2]} {MONTH_CODES[date[1]]} {date[0]}'
 
 def dehumanizeDate(date:str) -> str:
+    '''
+    convert date from human-friendly format to YYYY-MM-DD
+    Args:
+        date(str): the humanized date to dehumanize
+    Examples:
+        ```
+        dehumanizeDate('23 Sep 2021') -> '2021-09-23'
+        dehumanizeDate('Thu 23 Sep 2021') -> '2021-09-23'
+        ```    
+
+    '''
     if 2==date.count(' '):
         return datetime.datetime.strptime(date, '%d %b %Y').strftime('%Y-%m-%d')
 
     return datetime.datetime.strptime(date, '%a %d %b %Y').strftime('%Y-%m-%d')
 
-def daysBetweenDates(dateFrom, dateTo):  # assumes standardizedDates to be given
-    'dates given are in format YYYY-MM-DD'
+def daysBetweenDates(dateFrom:str, dateTo:str) -> int:  # assumes standardizedDates to be given
+    '''
+    get the number of days between dates, not inclusive
+    Args:
+        dateFrom(str): the start date in `YYYY-MM-DD` format
+        dateTo(str): end date in `YYYY-MM-DD` format
+    Note:
+        the days are not inclusive in the count
+    Examples:
+        ```
+        daysBetweenDates(monday, tuesday) -> 1 # both days in the same week
+        ```
+    '''
+
     return (datetime.datetime.strptime(dateTo, '%Y-%m-%d') - datetime.datetime.strptime(dateFrom, '%Y-%m-%d')).days
 
-def daysBetweenDatesInlusive(dateFrom:str, dateTo:str):  # assumes standardizedDates to be given
+def daysBetweenDatesInlusive(dateFrom:str, dateTo:str) -> str:  # assumes standardizedDates to be given
+    '''
+    get the number of days between dates, inclusive
+    Args:
+        dateFrom(str): the start date in `YYYY-MM-DD` format
+        dateTo(str): end date in `YYYY-MM-DD` format
+    Note:
+        the days are not inclusive in the count
+    Examples:
+        ```
+        daysBetweenDatesInlusive(monday, tuesday) -> 2 # both days in the same week, monday is included in the count
+        ```
+    '''
     days = daysBetweenDates(dateFrom, dateTo)
     return (abs(days)+1) * (-1 if days<0 else +1)
 
-def howLongAgo(dateFrom, dateTo, shortestVersion:bool=True):
+def howLongAgo(dateFrom:str, dateTo:str, shortestVersion:bool=True) -> str:
+    '''
+    get a human-friendly how-long-ago eg '3 days', '1 week, 4 days', '3 months, 1 week, 6 days', etc
+    Args:
+        dateFrom(str): the start date in the YYYY-MM-DD format
+        dateTo(str): the end date in the YYYY-MM-DD format
+        shortestVersion(bool): return the shorted possible version
+    Examples:
+        ```
+        howLongAgo('2025-01-01', '2025-05-18') -> '4 months, 2 weeks'
+        howLongAgo('2025-01-01', '2025-05-18', False) -> '4 months, 2 weeks, 3 days'
+        ```
+    '''
     days = daysBetweenDates(dateFrom, dateTo)
 
     return_str = ''
@@ -82,28 +145,78 @@ def howLongAgo(dateFrom, dateTo, shortestVersion:bool=True):
         
     return return_str
 
-def currentTimestamp():
+def currentTimestamp() -> str:
     '''
-    get current timestamp in EAT, YYYY-MM-DD HH:MM:SS
+    get current timestamp in EAT
+    Returns:
+        string in format `YYYY-MM-DD HH:MM:SS`
     '''
     now = datetime.datetime.utcnow() + datetime.timedelta(hours=3.00)
     return str(now)[:19]
 
-def dateFrom(date,days,hours=0):
-    'date: YYYY-MM-DD'
-    date = datetime.datetime.strptime(date, '%Y-%m-%d')
-    return str(date+datetime.timedelta(days=days, hours=hours))[:10]
+def dateFrom(date:str, days:int, hours:int=0) -> str:
+    '''
+    get the date thats `days` + `hours` from `date`
+    Args:
+        date(str): the reference date to use format is `YYYY-MM-DD`
+        days(int): days from the reference date
+        hours(int): hours to include to the days to ge tthe new date
+    Examples:
+        ```
+        dateFrom('2025-06-18', 1) -> '2025-06-19'
+        dateFrom('2025-01-01', -2) -> '2024-12-30'
+        ```
+    '''
+    _date = datetime.datetime.strptime(date, '%Y-%m-%d')
+    return str(_date + datetime.timedelta(days=days, hours=hours))[:10]
 
-def dateFromNow(days=0,hours=0):
+def dateFromNow(days=0,hours=0) -> str:
     '''
-    get current timestamp in EAT, YYYY-MM-DD HH:MM:SS
+    get the timestamp(not date) thats `days` + `hours` from the current time
+    Args:
+        days(int): days from the reference date
+        hours(int): hours to include to the days to ge tthe new date
+    Examples:
+        ```
+        # assuming the current time is '2025-06-18 10:53:54'
+        dateFromNow(1) -> '2025-06-19 10:53:54'
+        dateFromNow(-2) -> '2025-06-16 10:53:54'
+        ```
     '''
     now = datetime.datetime.utcnow() + datetime.timedelta(hours=3.00)
     return str(now+datetime.timedelta(days=days, hours=hours))[:19]
 
 # thanks to airtel & MTN strange date formats, we have this
-def standardizedDate(date:str, fmt=''):
-    'return "YYYY-MM-DD HH:MM:SS"'
+def standardizedDate(date:str, fmt:str=''):
+    '''
+    standardize date/timestamp into the `YYYY-MM-DD HH:MM:SS` standard
+    Args:
+        date(str): the date to standardize
+        fmt(str): the format in which the date/timestamp is currently in
+    Note:
+        Supported formats;
+        - DD-MM-YYYY HH:MM:SS
+        - MM-DD-YYYY HH:MM:SS
+        
+        - DD-MM-YYYY HH:MM:SS AM
+        - MM-DD-YYYY HH:MM:SS AM
+
+        - DD-MM-YYYY HH:MM
+        - MM-DD-YYYY HH:MM
+        
+        - DD-MM-YYYY HH:MM AM
+        - MM-DD-YYYY HH:MM AM
+        
+        - YYYY-MM-DD
+        - DD-MM-YYYY
+        - MM-DD-YYYY
+        
+        - YYYY-MM-DD HH:MM:SS
+        - YYYY-MM-DD HH:MM:SS AM
+
+        - YYYY-MM-DD HH:MM
+        - YYYY-MM-DD HH:MM AM
+    '''
     _date = None
 
     date = date.replace('/','-').replace('"','').replace("'",'')
@@ -112,7 +225,7 @@ def standardizedDate(date:str, fmt=''):
     if len(date)<len('YYYY-MM-DD'): raise ValueError('invalid date given')
     if not fmt: raise ValueError('no format given')
 
-    fmt = fmt.upper().replace('PM','AM')
+    fmt:str|None = fmt.upper().replace('PM','AM')
 
     fmt = {
         'DD-MM-YYYY HH:MM:SS':'%d-%m-%Y %H:%M:%S',
@@ -167,10 +280,18 @@ def _testStandardizeTime():
     ]:
         print(date,'->',standardizedDate(date,fmt))
 
-def lastWeekOn(day:int, humanize:bool=False):
+def lastWeekOn(day:int, humanize:bool=False) -> str:
     '''
-        day: 1=Monday, 7=Sunday
-        get date of day in last week eg lastWeekOn(1) -> date of monday, last week
+    get the date(YYYY-MM-DD) on `day`, last week
+    Args:
+        day(int): the week day; Mon=1, Tue=2, ..., Sun=7
+        humanize(bool): humanize the date
+    Examples:
+        ```
+        # assuming the current date is '2025-06-18'
+        lastWeekOn(3) -> '2025-06-11'
+        lastWeekOn(3, True) -> '11 Jun 2025'
+        ```
     '''
     assert isinstance(day,int) and 1<=day<=7
 
@@ -185,25 +306,36 @@ def lastWeekOn(day:int, humanize:bool=False):
     return strDate
 
 def secondsSinceEpoch()->int:
+    '''get the seconds since epoch'''
     return int(time.time())
 
 def minutesSinceEpoch()->int:
+    '''get minutes since epoch'''
     return secondsSinceEpoch() // 60
 
 def today() -> str:
+    '''get current date in YYYY-MM-DD format'''
     return currentTimestamp()[:10]
 
 def tomorrow() -> str:
+    '''get tomorrow's date in YYYY-MM-DD format'''
     return dateFromNow(days=+1)[:10]
 
 def yesterday() -> str:
+    '''get yesterday's date in YYYY-MM-DD format'''
     return dateFromNow(days=-1)[:10]
 
 def endOfMonth(year:str|int, month:str|int) -> str:
     '''
-    get the last date of the given month
-    @arg `year`: str|int, 4 characters representing the year
-    @arg `month`: str|int, 1|2 characters representing the month
+    get the last date(YYYY-MM-DD) of the given month
+    Args:
+        year(str|int): 4 characters representing the year
+        month(str|int): 1|2 characters representing the month
+    Examples:
+        ```
+        endOfMonth(2025, 6) -> '2025-06-30'
+        endOfMonth(2025, 2) -> '2025-02-28'
+        ```
     '''
 
     year = f'{year}'
@@ -228,7 +360,7 @@ def endOfMonth(year:str|int, month:str|int) -> str:
 
 def endOfCurrentMonth() -> str:
     '''
-    get last date of the current month
+    get last date(YYYY-MM-DD) of the current month
     '''
 
     dateToday = today()
@@ -239,8 +371,8 @@ def endOfCurrentMonth() -> str:
 def dateIsValid(date:str) -> bool:
     '''
     check if a date is valid in the format 'YYYY-MM-DD'
-    @arg `date:str`: the date to check
-    @return `bool`. True=date is valid, False = date is invalid
+    Args:
+        date(str): the date to check
     '''
     try:
         standardizedDate(date, 'YYYY-MM-DD')
@@ -250,12 +382,27 @@ def dateIsValid(date:str) -> bool:
     return True
 
 def isWeekend(date:str) -> bool:
+    '''
+    check if `date` is in a weekend (Saturday or Sunday)
+    Args:
+        date(str): the date to check
+    '''
     return humanizeDate(date, includeWeekDay=True).split(' ')[0] in ['Sat','Sun']
 
 def isSunday(date:str) -> bool:
+    '''
+    check if `date` is a Sunday
+    Args:
+        date(str): the date to check
+    '''
     return humanizeDate(date, includeWeekDay=True).split(' ')[0] in ['Sun']
 
 def isSaturday(date:str) -> bool:
+    '''
+    check if `date` is a Saturday
+    Args:
+        date(str): the date to check
+    '''
     return humanizeDate(date, includeWeekDay=True).split(' ')[0] in ['Sat']
 
 if __name__=='__main__':