kisa-utils 0.39.1__py3-none-any.whl → 0.40.0__py3-none-any.whl

kisa_utils/__init__.py

@@ -18,3 +18,4 @@ from kisa_utils import permissions
 from kisa_utils import functionUtils
 from kisa_utils import servers
 from kisa_utils import enqueue
+from kisa_utils import dataStructures

kisa_utils/dataStructures.py

@@ -0,0 +1,89 @@
+import copy
+import pprint
+
+class KDict(dict):
+    '''
+    A dict subclass that allows attribute access (obj.key)
+    and recursively converts nested dicts, lists, tuples, and sets.
+    '''
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._convert_nested()
+
+    def __getattr__(self, name):
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(f"`KDict` object has no attribute '{name}'")
+
+    def __setattr__(self, name, value):
+        self[name] = value
+
+    def __delattr__(self, name):
+        try:
+            del self[name]
+        except KeyError:
+            raise AttributeError(f"`KDict` object has no attribute '{name}'")
+
+    @staticmethod
+    def _wrap(value):
+        '''Recursively wrap any dicts inside nested structures.'''
+        if isinstance(value, dict) and not isinstance(value, KDict):
+            return KDict(value)
+        elif isinstance(value, list):
+            return [KDict._wrap(v) for v in value]
+        elif isinstance(value, tuple):
+            return tuple(KDict._wrap(v) for v in value)
+        elif isinstance(value, set):
+            return {KDict._wrap(v) for v in value}
+        else:
+            return value
+
+    def _convert_nested(self):
+        '''Convert all nested dicts/lists/tuples/sets in self.'''
+        for k, v in list(self.items()):
+            super().__setitem__(k, self._wrap(v))
+
+    def copy(self):
+        return KDict(copy.deepcopy(self))
+
+    def update(self, *args, **kwargs):
+        result = super().update(*args, **kwargs)
+        self._convert_nested()
+        return result
+
+    @classmethod
+    def fromkeys(cls, seq, value=None):
+        return cls({k: value for k in seq})
+
+    def __getitem__(self, key):
+        value = super().__getitem__(key)
+        wrapped = self._wrap(value)
+        if wrapped is not value:
+            super().__setitem__(key, wrapped)
+        return wrapped
+
+    def toDict(self):
+        '''
+        convert KDict to dict
+        '''
+        def unwrap(v):
+            if isinstance(v, KDict):
+                return {k: unwrap(x) for k, x in v.items()}
+            if isinstance(v, list):
+                return [unwrap(x) for x in v]
+            if isinstance(v, tuple):
+                return tuple(unwrap(x) for x in v)
+            if isinstance(v, set):
+                return {unwrap(x) for x in v}
+            return v
+        return unwrap(self)
+
+    def __repr__(self):
+        return repr(dict(self))
+
+# map the KDict type to pprint's dict pretty-printer
+try:
+    pprint.PrettyPrinter._dispatch[KDict.__repr__] = pprint.PrettyPrinter._pprint_dict
+except Exception: pass

kisa_utils/db.py

@@ -14,6 +14,7 @@ from .response import Error, Ok, Response
 from .functionUtils import enforceRequirements, Definition
 from .structures.utils import Value
 from . import structures
+from .dataStructures import KDict
 
 if sqlite3.sqlite_version_info[1]<38:
     sys.exit(f'we need sqlite3 v3.38.0+ to run this program. current version::{sqlite3.sqlite_version}')
@@ -395,7 +396,7 @@ class Api:
 
         return _data
 
-    def __decodeOutgoingData(self, data:list[tuple]) -> list[tuple]:
+    def __decodeOutgoingData(self, data:list[tuple], dictType:dict|KDict = dict) -> list[tuple]:
         '''
         attempt to decode json objects to python list/dict where applicable. 
         Args:
@@ -408,6 +409,8 @@ class Api:
                 if value and isinstance(value,str) and (value[0] in '[{'):
                     try:
                         value = storage.decodeJSON(value)
+                        if dictType==KDict:
+                            value = KDict._wrap(value)
                     except:
                         pass
 
@@ -613,7 +616,8 @@ class Api:
             table:str, columns:list, condition:str, conditionData:list, 
             limit:int=MAX_FETCH_ITEMS, returnDicts:bool=False, 
             returnNamespaces:bool=False, parseJson:bool=False, 
-            returnGenerator:bool=False
+            returnGenerator:bool=False,
+            useKDicts:bool=True,
         ) -> list|Response:
         '''
         attempt to fetch from the database
@@ -624,11 +628,12 @@ class Api:
             condition(str): a string indicating the SQL condition for the fetch eg `userId=? and dateCreated<?`. all values a represented with the `?` placeholder
             conditionData(list): a list containing the values for each `?` placeholder in the condition
             limit(int): number indicating the maximum number of results to fetch
-            returnDicts(bool): if `True`, we shall return a list of dictionaries as opposed to a list of tuples
+            returnDicts(bool): if `True`, we shall return a list of dictionaries(KDict if `useKDicts`=`True`) as opposed to a list of tuples
             returnNamespaces(bool): if `True`, we shall return a list of named-tuples as opposed to a list of tuples
                 ** if both `returnDicts` and `returnNamespaces` are set, `returnDicts` is effected
             parseJson(bool):if `True`, we shall parse json objects to python lists and dictionaries where possible
             returnGenerator(bool): if True, a generator will be returned instead of the list of tuple|dict|SimpleNamespace. this is especially recommended for large data
+            useKDicts(bool): if True, all dicts returned are `KDicts` ie dicts that support the dot notation, just like JS objects
         '''
         if not (limit>0 and limit<=MAX_FETCH_ITEMS):
             err = f'please set a limit on the returned rows. maximum should be {MAX_FETCH_ITEMS}'
@@ -666,18 +671,23 @@ class Api:
             except Exception as e:
                 return Error(str(e))
 
+        dictType = KDict if useKDicts else dict
+
         fetchedData = self.cursor
         if parseJson and not returnGenerator:
-            fetchedData = self.__decodeOutgoingData(fetchedData)
+            fetchedData = self.__decodeOutgoingData(fetchedData, dictType=dictType)
 
         cols = [_[0] for _ in self.cursor.description]
 
         if not (returnDicts or returnNamespaces):
-            returnData = [_ for _ in fetchedData] if not returnGenerator else self.__createFetchResultsGenerator(fetchedData, cols, parseJson, 'plain')
+            if fetchedData == self.cursor:
+                fetchedData = [_ for _ in fetchedData]
+
+            returnData = fetchedData if not returnGenerator else self.__createFetchResultsGenerator(fetchedData, cols, parseJson, 'plain')
             return returnData if not self.__returnKISAResponse else Ok(returnData)
 
         if returnDicts:
-            returnData = [dict(zip(cols,_)) for _ in fetchedData] if not returnGenerator else self.__createFetchResultsGenerator(fetchedData, cols, parseJson, 'dicts')
+            returnData = [dictType(zip(cols,_)) for _ in fetchedData] if not returnGenerator else self.__createFetchResultsGenerator(fetchedData, cols, parseJson, 'dicts')
             return returnData if not self.__returnKISAResponse else Ok(returnData)
 
         # namepsaces...

kisa_utils/response.py

@@ -1,4 +1,4 @@
-from kisa_utils.storage import encodeJSON
+import json as _j; encodeJSON = _j.JSONEncoder().encode
 from typing import Any
 import inspect
 
@@ -57,10 +57,16 @@ class Response(tuple):
             'status': self.__status,
             'log': self.__log,
             'data': self.__data,
-        }.get(index, self)) == self:
-            raise ValueError(f'invalid accessor given `{index}`')
+        }.get(index, self)) != self:
+            return value
+
+        if not isinstance(self.__data, dict) or (index not in self.__data):
+            return self.__data
+
+        return self.__data[index]
         
-        return value
+    def __getattr__(self, attr):
+        return self[attr]
 
     def __iter__(self):
         return iter([self[0], self[1]])
@@ -137,4 +143,9 @@ def Error(log:str) -> Response:
     Args:
         log(str): the log to pass to the Response object
     '''
-    return Response(False, log=log)
+    return Response(False, log=log)
+
+if __name__=='__main__':
+    r = Ok(74); print(r['xx'], r.xx, r['xy'], r.data, r)
+    r = Ok({'xx':50}); print(r['xx'], r.xx, r['xy'], r['data'], r)
+    r = Ok({'xx':{'a':13}}); print(r['xx']['a'], r.xx['a'], r['data'], r)

kisa_utils/storage.py

@@ -1,5 +1,6 @@
 import os, glob, json
 import inspect
+from kisa_utils.response import Response, Error, Ok
 
 encodeJSON = json.JSONEncoder().encode
 decodeJSON = json.JSONDecoder().decode
@@ -22,7 +23,7 @@ class Path:
         return os.path.isfile(path)
 
     @staticmethod
-    def createDirectory(path:str) -> dict[str,bool|str]:
+    def createDirectory(path:str) -> Response:
         '''
         attempt to create a directory provided in `path`. 
         Args:
@@ -31,159 +32,91 @@ class Path:
         Note:
             if any intermediate directories dont exist, they will be created as well
 
-        Returns:
-            the standard dict in the form
-            ```
-            {
-                'status': bool, 
-                'log': str
-            }
-            ```
         '''
-        reply = {'status':False, 'log':''}
         if os.system(f"mkdir -p '{path}' 2> /dev/null"):
-            reply['log'] = 'failed to create directory. please review your permissions'
-            return reply
+            return Error('failed to create directory. please review your permissions')
         
-        reply['status'] = True
-        return reply
+        return Ok()
     
     @staticmethod
-    def createShortcut(source:str, destination:str) -> dict[str,bool|str]:
+    def createShortcut(source:str, destination:str) -> Response:
         '''
         attempt to create a shortcut.
         Args:
             source(str): the path we want to create a shortcut to
             destination(str): the path to the shortcut 
-
-        Returns:
-            the standard dict in the form of
-            ```
-            {
-                'status': bool, 
-                'log': str
-            }
-            ```
         '''
-        reply = {'status':False, 'log':''}
 
         if not Path.exists(source):
-            reply['log'] = 'the source path does not exist'
-            return reply
+            return Error('the source path does not exist')
 
         if Path.exists(destination):
-            reply['log'] = 'the destination path already exists'
-            return reply
+            return Error('the destination path already exists')
 
         if os.system(f"ln -s -T '{source}' '{destination}' 2> /dev/null"):
-            reply['log'] = 'failed to create the shortcut. please confirm that all necessary paths are valid and exist'
-            return reply
+            return Error('failed to create the shortcut. please confirm that all necessary paths are valid and exist')
         
-        reply['status'] = True
-        return reply
+        return Ok()
 
     @staticmethod
-    def delete(path:str) -> dict[str,bool|str]:
+    def delete(path:str) -> Response:
         '''
         attempt to delete `path`.
 
         Note:
             if the path is a directory, it will NOT be deleted if its empty 
-
-        Returns:
-            the standard dict in the form
-            ```
-            {
-                'status': bool, 
-                'log': str
-            }
-            ```
         '''
-        reply = {'status':False, 'log':''}
 
         if not Path.exists(path):
-            reply['log'] = 'path does not exist'
-            return reply
+            return Error('path does not exist')
 
         if Path.isDirectory(path) and os.listdir(path):
-            reply['log'] = 'can not delete a non-empty directory'
-            return reply
+            return Error('can not delete a non-empty directory')
 
         if Path.isFile(path):
             if os.system(f"rm '{path}' 2> /dev/null"):
-                reply['log'] = 'failed to delete the file. please ensure you have the right permissions'
-                return reply
+                return Error('failed to delete the file. please ensure you have the right permissions')
         else:
             if os.system(f"rmdir '{path}' 2> /dev/null"):
-                reply['log'] = 'failed to delete the directory. please ensure you have the right permissions'
-                return reply
+                return Error('failed to delete the directory. please ensure you have the right permissions')
         
-        reply['status'] = True
-        return reply
+        return Ok()
 
     @staticmethod
-    def copy(source:str, destination:str) -> dict[str,bool|str]:
+    def copy(source:str, destination:str) -> Response:
         '''
         attempt to copy a file/directory
         Args:
             source(str): the path we want to copy
             destination(str): the path to the new copy of the file/directory 
-
-        Returns:
-            the standard dict in the form
-            ```
-            {
-                'status': bool, 
-                'log': str
-            }
-            ```
         '''
-        reply = {'status':False, 'log':''}
 
         if not Path.exists(source):
-            reply['log'] = 'the source path does not exist'
-            return reply
+            return Error('the source path does not exist')
 
         if Path.exists(destination):
-            reply['log'] = 'the destination path already exists'
-            return reply
+            return Error('the destination path already exists')
 
         if os.system(f"cp -rfHpu '{source}' '{destination}' 2> /dev/null"):
-            reply['log'] = 'failed to copy the source. please confirm that all necessary paths are valid and exist'
-            return reply
+            return Error('failed to copy the source. please confirm that all necessary paths are valid and exist')
         
-        reply['status'] = True
-        return reply
+        return Ok()
 
     @staticmethod
-    def listDirectory(path:str) -> dict[str,bool|str|list[str]]:
+    def listDirectory(path:str) -> Response:
         '''
         attempt to list the contents of a directory
         Args:
             path(str): the path to the directory we want to list
-
-        Returns:
-            the standard dict in the form
-            ```
-            {
-                'status': bool, 
-                'log': str,
-                'contents': list[str] # list of ABSOLUTE paths
-            }
-            ```
         '''
-        reply = {'status':False, 'log':'', 'contents':[]}
 
         if not Path.isDirectory(path):
-            reply['log'] = 'the path given is not a directory'
-            return reply
+            return Error('the path given is not a directory')
 
         path += '/*'
         contents = [os.path.abspath(f) for f in glob.glob(path)]
 
-        reply['contents'] = contents
-        reply['status'] = True
-        return reply
+        return Ok(contents)
 
     @staticmethod
     def getMyAbsolutePath() -> str:
@@ -206,7 +139,7 @@ class Path:
         return os.path.abspath(caller_file)
 
     @staticmethod
-    def directoryBackAt(path:str, howFarBack:int=0) -> dict[str,bool|str]:
+    def directoryBackAt(path:str, howFarBack:int=0) -> Response:
         '''
         get directory thats `howFarBack` steps from `path`
         Args:
@@ -223,36 +156,30 @@ class Path:
             
             if `howFarBack` = 4, then final directory = '/a/b'
             ```
-                    
-        Returns:
-            dict in form
-            ```
-            {
-                'status': bool,
-                'log': str,
-                'directory': str
-            }
-            ```
         '''
-        reply = {'status':False, 'log':'', 'directory':''}
 
         if not Path.exists(path):
-            reply['log'] = 'could not find the given path'
-            return reply
+            return Error('could not find the given path')
 
         if howFarBack<0:
-            reply['log'] = 'invalid value given for `howFarBack`'
-            return reply
+            return Error('invalid value given for `howFarBack`')
 
         parent = os.path.dirname(path)
 
         if howFarBack >= parent.count('/'):
-            reply['log'] = 'value of `howFarBack` goes beyond the root directory `/`'
-            return reply
+            return Error('value of `howFarBack` goes beyond the root directory `/`')
+
+        return Ok('/'.join(parent.split('/')[:-howFarBack]) if howFarBack else parent)
+
+    @staticmethod
+    def getAbsolutePath(path:str) -> str:
+        '''
+        get absolute path to file
+        Args:
+            path(str): path, relative or otherwise whose absolute path we need
+        '''
+        return os.path.abspath(path)
 
-        reply['directory'] = '/'.join(parent.split('/')[:-howFarBack]) if howFarBack else parent
-        reply['status'] = True
-        return reply
 
 if __name__=='__main__':
-    pass
+    print(Path.getAbsolutePath('.'))

kisa_utils/structures/validator.py

@@ -7,6 +7,7 @@ from typing import Any, get_args, get_origin
 from types import UnionType
 from kisa_utils.structures.utils import Value
 from kisa_utils.response import Response, Ok, Error
+from kisa_utils.dataStructures import KDict
 
 def validate(instance:Any, structure:Any, path:str='$') -> dict:
     '''
@@ -53,11 +54,13 @@ def validate(instance:Any, structure:Any, path:str='$') -> dict:
         result['status'] = True
         return result
     else:
-        if not isinstance(instance,type(structure)):
+        # checking in both directions as dict and KDict can fail when you check 
+        # `isinstance(dict, KDict)` but will pass when the arguments switch positions
+        if (not isinstance(instance,type(structure))) and (not isinstance(structure, type(instance))):
             result['log'] = f'E02: types not similar:: {path}, expected {str(type(structure))[7:-1]} but got {str(type(instance))[7:-1]}'
             return result
 
-        if isinstance(structure,dict):
+        if isinstance(structure,(dict, KDict)):
             _path = path
             for key in structure:
                 path = f'{_path}->{key}'

{kisa_utils-0.39.1.dist-info → kisa_utils-0.40.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kisa-utils
-Version: 0.39.1
+Version: 0.40.0
 Summary: Utility functions and modules for KISA Developers
 Author: Tom Bukenya
 Author-email: glayn2bukman@gmail.com

{kisa_utils-0.39.1.dist-info → kisa_utils-0.40.0.dist-info}/RECORD

@@ -1,9 +1,10 @@
-kisa_utils/__init__.py,sha256=iXjGTol3UxJkh_cyISYEAY_yWC5ZlNvIRXFuuiHx76Q,621
+kisa_utils/__init__.py,sha256=z2vCa2O3W1vOFhW4K0_hkpyEuy_H05WUTzdCPHldCyI,659
 kisa_utils/cache.py,sha256=4Ue5G3QhHSQAmIfQKYgWKWjNL4rA4wLLd_RdBLb2ABY,7345
 kisa_utils/codes.py,sha256=PV_S53Skggf4XetOdYoIKtEmM8cpN5wZwUlxje70WZY,904
 kisa_utils/config.py,sha256=NfluzGKTh66qfNtC-Ae0zNb1XzMTgU2Me9Vi82R9c1E,2285
+kisa_utils/dataStructures.py,sha256=ZgLpttJ66jfpU1NWzLDD1Czqxzj6sWereffgTQWhlV8,2679
 kisa_utils/dates.py,sha256=zxe4n0PdKReZjK5ZkvnCZtJ55lk5oqu9oS8VX_nLozw,13966
-kisa_utils/db.py,sha256=tVNMV-hc-oPxR4iRSX-d82Gi4fQwI5Cga1eP8SLvHFs,49202
+kisa_utils/db.py,sha256=oUpqpew3a1a69Ow1xSydfB1S_QhiUrCtba_7dbK0XBs,49715
 kisa_utils/encryption.py,sha256=nFzNpzWV_D9uSEq4FsgCnlS7FQtqWP9fvM_81rsfcLo,4218
 kisa_utils/enqueue.py,sha256=VIliaMvw4MUdOqts0dXdZCYNxs-QrOVjIRAR3scGrRM,11786
 kisa_utils/figures.py,sha256=pYIpQzu1OXRSsY1d98GhgPifnIRmgl-r7S32ai-Ms0c,3731
@@ -11,9 +12,9 @@ kisa_utils/functionUtils.py,sha256=PlXjnmU1uJWNdISlJJ3SCgavTsgNBoebaa9dtWSFhRA,6
 kisa_utils/log.py,sha256=0TYdxcIBts026RCSuVIQBcZ-CW1ES7n3M1nEIjmeLTM,2295
 kisa_utils/queues.py,sha256=9QqPtDujw6tbWk7uUiXrsd0rVBTIkzeQw9b45l5Fo3k,6502
 kisa_utils/remote.py,sha256=0RDrfC4RUW4m6JLziC0_EXJYqzWp38Rw8NDroJ0MuqI,2149
-kisa_utils/response.py,sha256=FusfDTBn7gOMqt34XkiUf4d1lWn42_c1n_61wJoPKYU,4182
+kisa_utils/response.py,sha256=asETUBkeF5OlSTwa-coa7lZDCKmQlHCmHf6eaZFl8CU,4560
 kisa_utils/standardize.py,sha256=nt-uzHQFoKxGscD_MpDYXw65Teg3724whAqa6Kh_zhE,2231
-kisa_utils/storage.py,sha256=8-NgrY6BpIo-B9IJNTd-TqMB0m9BY1PuQgZ9WL1z8SM,7683
+kisa_utils/storage.py,sha256=waHLmrf19QxvEQZlWlC2qQvEYFFhDeJHc7MMNbcmj7c,5823
 kisa_utils/threads.py,sha256=qQqsf64YHMyLpboq5AEXKxYqf3iXUhxiJe6Ymg-vlxI,12840
 kisa_utils/token.py,sha256=Y2qglWYWpmHxoXBh-TH0r1as0uPV5LLqMNcunLvM4vM,7850
 kisa_utils/permissions/__config__.py,sha256=i3ELkOydDnjKx2ozQTxLZdZ8DXSeUncnl2kRxANjFmM,613
@@ -22,8 +23,8 @@ kisa_utils/servers/__init__.py,sha256=lPqDyGTrFo0qwPZ2WA9Xtcpc5D8AIU4huqgFx1iZf6
 kisa_utils/servers/flask.py,sha256=XZYY1pWnP1mSvaS5Uv8G3EFJV5BJBQtU2gDbO8suvLc,40422
 kisa_utils/structures/__init__.py,sha256=JBU1j3A42jQ62ALKnsS1Hav9YXcYwjDw1wQJtohXPbU,83
 kisa_utils/structures/utils.py,sha256=665rXIapGwFqejizeJwy3DryeskCQOdgP25BCdLkGvk,2898
-kisa_utils/structures/validator.py,sha256=Y4UmB4TH7N-GkK22EV1WOsPWjTeqxVWLTentl1keZD4,4053
-kisa_utils-0.39.1.dist-info/METADATA,sha256=_lCvaoHUhJMTWCKO93XOLW-uqssorWIkxc9wB5Ifr7E,477
-kisa_utils-0.39.1.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-kisa_utils-0.39.1.dist-info/top_level.txt,sha256=URxY4sRuqmirOxWtztpVmPoGQdksEMYO6hmYsEDGz2Y,75
-kisa_utils-0.39.1.dist-info/RECORD,,
+kisa_utils/structures/validator.py,sha256=JhD9jcfbjTwBr_7OfuNaJd_cYr7wR2emFhsCEo5MCHQ,4323
+kisa_utils-0.40.0.dist-info/METADATA,sha256=OxeJF4Wb_Yk5x5spw-v8bdERToTAICfPzHPs9ntEyhg,477
+kisa_utils-0.40.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+kisa_utils-0.40.0.dist-info/top_level.txt,sha256=URxY4sRuqmirOxWtztpVmPoGQdksEMYO6hmYsEDGz2Y,75
+kisa_utils-0.40.0.dist-info/RECORD,,