python-backpack 1.0.4__py3-none-any.whl → 1.1.4__py3-none-any.whl

backpack/cache.py

@@ -0,0 +1,68 @@
+# ----------------------------------------------------------------------------------------
+# Python-Backpack - Pattern Utilities
+# Maximiliano Rocamora / maxirocamora@gmail.com
+# https://github.com/MaxRocamora/python-backpack
+# ----------------------------------------------------------------------------------------
+from datetime import datetime, timedelta, timezone
+from functools import lru_cache, wraps
+
+from backpack.logger import get_logger
+
+log = get_logger('Python Backpack - Cache')
+
+
+def timed_lru_cache(seconds: int, maxsize: int = 128):
+    """Lru_cache with expiration time.
+
+    Args:
+        seconds (int): expiration time in seconds
+        maxsize (int): maxsize for lru_cache
+    Note:
+        Wrapped function can be forced to clear cache with: force_clear=True
+        Wrapped function can show log on clear with: show_log=True
+    Returns:
+        function result
+
+    # * Usage:
+
+        # * Add the decorator to your function
+
+        @timed_lru_cache(seconds=60)
+        def my_function():
+            return 'Hello World'
+
+        # * to clear the cache, use force_clear=True on the function call
+        my_function(force_clear=True)
+
+    """
+
+    def wrapper_cache(func):
+        func = lru_cache(maxsize=maxsize)(func)
+        func.lifetime = timedelta(seconds=seconds)
+        func.expiration = datetime.now(timezone.utc) + func.lifetime
+
+        @wraps(func)
+        def wrapped_func(*args, force_clear: bool = False, show_log: bool = False, **kwargs):
+            """Wrapper function for lru_cache with expiration time.
+
+            Args:
+                *args: function arguments
+                force_clear (bool): forces a clear cache
+                show_log (bool): show log on clear
+                **kwargs: function keyword arguments
+            Returns:
+                function result
+            """
+
+            if force_clear or datetime.now(timezone.utc) >= func.expiration:
+                if show_log:
+                    log.debug(f'Cache cleared for {func.__name__}')
+
+                func.cache_clear()
+                func.expiration = datetime.now(timezone.utc) + func.lifetime
+
+            return func(*args, **kwargs)
+
+        return wrapped_func
+
+    return wrapper_cache

backpack/custom_errors.py

@@ -4,33 +4,34 @@
 # https://github.com/MaxRocamora/python-backpack
 # ----------------------------------------------------------------------------------------
 
-class EnvironmentVariableNotFound(Exception):
 
+class EnvironmentVariableNotFoundError(Exception):
     def __init__(self, var_name: str) -> None:
-        '''Error Raised when a required environment variable is missing from os.
+        """Error Raised when a required environment variable is missing from os.
 
         Args:
             var_name (str): name of the required variable missing
-        '''
+        """
         self.var_name = var_name
-        self.message = f'System required ({var_name}) Environment Variable not found.'
+        self.message = f'Required Environment Variable [{var_name}] not found.'
         super().__init__(self.message)
 
     def __str__(self):
+        """Return the error message."""
         return self.message
 
 
-class ApplicationNotFound(Exception):
-
+class ApplicationNotFoundError(Exception):
     def __init__(self, app_name: str) -> None:
-        '''Error Raised when an Application Name required is not found.
+        """Error Raised when an Application Name required is not found.
 
         Args:
             app_name (str): name of the required application missing
-        '''
+        """
         self.app_name = app_name
         self.message = f'Application ({app_name}) not found.'
         super().__init__(self.message)
 
     def __str__(self):
+        """Return the error message."""
         return self.message

backpack/file_utils.py

@@ -8,23 +8,25 @@ import contextlib
 
 from backpack.logger import get_logger
 
-log = get_logger('FileUtils')
+log = get_logger('Python Backpack - FileUtils')
 
 
-def replace_strings_in_file(ascii_file: str, strings: list, new_string: str):
-    ''' Opens ascii file and replaces all occurrences from strings into new_string.
+def replace_strings_in_file(ascii_file: str, strings: list, new_string: str) -> None:
+    """Opens ascii file and replaces all occurrences from strings into new_string.
+
     In this class we use a full path to avoid use of os.dirname, which
     causes string encode problems.
+
     Args:
-        ascii_file (fullpath) file to open
-        strings (list) strings to replace
-        new_string (string) new string or path to set
-    '''
+        ascii_file: (fullpath string) file to open
+        strings: (list) strings to replace
+        new_string: (string) new string or path to set
+    """
 
     # force forward slashes
-    new_string = new_string.replace("\\", "/")
+    new_string = new_string.replace('\\', '/')
 
-    log.info(f"Replacing Strings, Opening File: {ascii_file}")
+    log.info(f'Replacing Strings, Opening File: {ascii_file}')
 
     with open(ascii_file) as f:
         file_data = f.read()
@@ -37,41 +39,48 @@ def replace_strings_in_file(ascii_file: str, strings: list, new_string: str):
     with open(ascii_file, 'w') as f:
         f.write(file_data)
         f.close()
-        log.info(f"Closing File: {ascii_file}")
+        log.info(f'Closing File: {ascii_file}')
+
 
+def remove_line_from_file(ascii_file: str, strings: list, verbose: bool = False) -> None:
+    """Removes given lines from ascii file.
 
-def remove_line_from_file(ascii_file: str, strings: str):
-    ''' removes given lines from ascii file.
     Args:
-        ascii_file (path) ASCII file to process
-        strings (list) match lines to remove
-    '''
+        ascii_file: (string path) ASCII file to process
+        strings: (list) match lines to remove
+        verbose: (bool) if true, prints removed lines
+    """
 
     with open(ascii_file) as f:
         file_content = f.read().splitlines()
 
     for line in file_content:
-        print('file line', line)
+        if verbose:
+            log.info(f'Checking line: {line}')
         with contextlib.suppress(ValueError):
             if line in strings:
+                if verbose:
+                    log.info(f'Removing line: {line}')
                 file_content.pop(file_content.index(line))
 
-    with open(ascii_file, "w") as f:
-        contents = "\n".join(file_content)
+    with open(ascii_file, 'w') as f:
+        contents = '\n'.join(file_content)
         f.write(contents)
 
 
 def file_is_writeable(filepath: str) -> bool:
-    ''' checks if a file is locked and can be overwritten
+    """Checks if a file is locked and can be overwritten.
+
     Args:
-        filepath (str)) file to check
+        filepath: (str) file to check
     Returns:
         bool : true if file is writeable
-    '''
+    """
     try:
         with open(filepath, 'r+') as _:
             return True
     except OSError as x:
         log.warning(f'{filepath} is locked ')
         log.info(x.strerror)
+
     return False

backpack/folder_utils.py

@@ -10,42 +10,43 @@ import subprocess
 
 from backpack.logger import get_logger
 
-log = get_logger('FolderUtils')
+log = get_logger('Python Backpack - FolderUtils')
 
 
 def browse_folder(folder: str) -> bool:
-    ''' Open windows explorer on folder
+    """Open windows explorer on folder.
+
     Args:
-        folder (path) folder to open
-    '''
+        folder: (string path) folder to open
+    """
     if folder and os.path.isdir(folder):
-        subprocess.Popen(f"explorer {os.path.abspath(folder)}")
+        subprocess.Popen(f'explorer {os.path.abspath(folder)}')
         return True
 
-    log.warning(f"Unable to open folder {folder}")
+    log.warning(f'Unable to open folder {folder}')
     return False
 
 
 def create_folders(folders: list, force_empty: bool = False, verbose: bool = False):
-    ''' Creates multiple folders on disc.
+    """Creates multiple folders on disc.
 
     Args:
         folders (list): folder list
         force_empty (bool, optional): forces clearing folder content. Defaults to False.
         verbose (bool, optional):shows log. Defaults to False.
-    '''
+    """
     for folder in folders:
         create_folder(folder, force_empty=force_empty, verbose=verbose)
 
 
 def create_folder(path: str, force_empty: bool = False, verbose: bool = True):
-    '''creates a folder
+    """Creates a folder.
 
     Args:
         path (str): folder path
         force_empty (bool, optional): forces clearing folder content. Defaults to False.
         verbose (bool, optional): show log. Defaults to True.
-    '''
+    """
     abspath = os.path.abspath(path)
     if verbose:
         log.info(f'Creating Folder {abspath}')
@@ -56,14 +57,14 @@ def create_folder(path: str, force_empty: bool = False, verbose: bool = True):
         elif force_empty:
             remove_files_in_dir(abspath)
     except OSError as e:
-        log.warning(f"Unable to create folder: {path}")
+        log.warning(f'Unable to create folder: {path}')
         log.error(str(e))
 
     return True
 
 
 def remove_files_in_dir(path: str):
-    ''' clears all content in given directory '''
+    """Clears all content in given directory."""
     for root, dirs, files in os.walk(path):
         for f in files:
             os.unlink(os.path.join(root, f))
@@ -72,12 +73,12 @@ def remove_files_in_dir(path: str):
 
 
 def recursive_dir_copy(source_path: str, target_path: str):
-    ''' Copy all files src dir to dest dir, including sub-directories.
+    """Copy all files src dir to dest dir, including sub-directories.
 
     Args:
         source_path (str): source path
         target_path (str): destination path
-    '''
+    """
 
     create_folder(source_path)
     create_folder(target_path)

backpack/json_metadata.py

@@ -3,153 +3,130 @@
 # Maximiliano Rocamora / maxirocamora@gmail.com
 # https://github.com/MaxRocamora/python-backpack
 # ----------------------------------------------------------------------------------------
-import sys
+import inspect
 import os
+import platform
+import sys
 import time
-import inspect
 from datetime import datetime
-import platform
+from typing import Any
 
 from backpack.json_utils import json_load, json_save
 from backpack.version import version
 
 
-class JsonMetaFile():
+class JsonMetaFile:
+    PREFIX = 'MD_'
 
-    def __init__(self, name: str, path: str):
-        '''saves/load a class/dict as a json metadata file
+    def __init__(self, name: str, path: str) -> None:
+        """saves/load a class/dict as a json metadata file.
 
         Args:
             name (str): name of the file/class
             path (str, optional): filepath. Defaults to None.
-        '''
+        """
         self._name = name
         self._path = path
-        self._data = {}
-        self._data["_about"] = {'package': 'python-backpack',
-                                'version': self.version}
-
-    # ------------------------------------------------------------------------------------
-    # PROPERTIES
-    # ------------------------------------------------------------------------------------
+        self._data = {'_about': {'package': 'python-backpack', 'version': self.version}}
 
     @property
-    def name(self):
-        ''' name of this metadata class'''
+    def name(self) -> str:
+        """Name of this metadata class."""
         return self._name
 
     @property
-    def version(self):
-        ''' version of this metadata class'''
+    def version(self) -> str:
+        """Version of this metadata class."""
         return version
 
     @property
-    def data(self):
-        ''' stored metadata dict '''
-        return self._data
-
-    @data.setter
-    def data(self, val):
-        self._data = val
-
-    @property
-    def prefix(self):
-        ''' file prefix, is auto-included on the filename '''
-        return "MD_"
-
-    @property
-    def filename(self):
-        ''' Returns default filename with prefix and extension '''
-        return self.prefix + self.name + '.json'
+    def filename(self) -> str:
+        """Returns default filename with prefix and extension."""
+        return self.PREFIX + self.name + '.json'
 
     @property
-    def filepath(self):
-        ''' full json metadata filepath '''
+    def filepath(self) -> str:
+        """Full json metadata filepath."""
         return os.path.join(self.path, self.filename)
 
     @property
-    def path(self):
-        ''' base path location of metadata json file '''
+    def path(self) -> str:
+        """Base path location of metadata json file."""
         return self._path
 
-    def has_file(self):
+    def has_file(self) -> bool:
+        """Returns true if file exists."""
         return os.path.exists(self.filepath)
 
     # ------------------------------------------------------------------------------------
     # LOAD/INSERT/REMOVE/SAVE
     # ------------------------------------------------------------------------------------
 
-    def load(self):
-        ''' loads metadata from disk '''
+    def load(self) -> None:
+        """Loads metadata from disk."""
         self._data = json_load(self.filepath) if self.has_file() else {}
 
-    def insert(self, key, value):
-        ''' inserts value into metadata '''
+    def insert(self, key: str, value: Any) -> None:
+        """Inserts value into metadata."""
         self._data[key] = value
 
-    def remove(self, key):
-        ''' remove key from metadata '''
+    def remove(self, key: str) -> None:
+        """Remove key from metadata."""
         if key in self._data.keys():
             del self._data[key]
 
-    def save(self, path: str = None):
-        ''' Save current metadata into json file.
-        Args:
-            path (str) sets target path for json file. Optional. Defaults to None
-        '''
+    def save(self) -> None:
+        """Save current metadata into json file."""
         if not os.path.exists(self.path):
             os.makedirs(self.path)
 
-        self.data['system'] = self._system_data()
-        json_save(self.data, self.filepath)
+        self._data['system'] = self._system_data()
+        json_save(self._data, self.filepath)
 
     # ------------------------------------------------------------------------------------
     # CLASS MODE METHODS
     # ------------------------------------------------------------------------------------
 
-    def load_as_class(self):
-        ''' returns the metadata dict as a class obj '''
-        metadataClass = type(self.name, (), self._data)
-        return metadataClass
-
-    def insert_class(self, _class):
-        ''' set class dict to data, data is cleared '''
-        self.data = self._attributes_from_class(_class)
+    def load_as_class(self) -> type:
+        """Returns the metadata dict as a class obj."""
+        metadata_class = type(self.name, (), self._data)
+        return metadata_class
 
-    def _attributes_from_class(self, _class):
+    def insert_class(self, _class: type) -> None:
+        """Load all attributes from  a  given class into this class metadata."""
         attributes = {}
         for name in dir(_class):
             value = getattr(_class, name)
             if not name.startswith('__') and not inspect.ismethod(value):
                 attributes[name] = value
-        return attributes
+
+        self._data = attributes
 
     # ------------------------------------------------------------------------------------
     # SYSTEM METADATA OS/USER/TIME
     # ------------------------------------------------------------------------------------
 
-    def _system_data(self):
-        ''' add system metadata to the default data before save '''
+    def _system_data(self) -> dict:
+        """Add system metadata to the default data before save."""
         return {
             'name': self.name,
             'app': os.path.basename(sys.executable),
             'PC': str(platform.node()),
             'python_version': sys.version,
             'User': str(os.getenv('username')),
-            'time': self._get_time_metadata,
+            'time': self._current_time_metadata(),
         }
 
-    @property
-    def _get_time_metadata(self):
-        ''' Get export time info. '''
-        ftime = time.strftime("%Y,%b,%d,%j,%H:%M", time.localtime())
-        times = ftime.split(",")
+    def _current_time_metadata(self) -> dict:
+        """Get export time info."""
+        ftime = time.strftime('%Y,%b,%d,%j,%H:%M', time.localtime())
+        times = ftime.split(',')
         td = {
-            "year": times[0],
-            "month": times[1],
-            "day": times[2],
-            "year_day": times[3],
-            "time": times[4],
-            'save_time': datetime.now().ctime()
+            'year': times[0],
+            'month': times[1],
+            'day': times[2],
+            'year_day': times[3],
+            'time': times[4],
+            'save_time': datetime.now().ctime(),
         }
         return td

backpack/json_user_settings.py

@@ -1,68 +1,71 @@
-# -*- coding: utf-8 -*-
-# --------------------------------------------------------------------------------------------
+# ----------------------------------------------------------------------------------------
 # Json Settings Class
 # This class handle load/save json files on win/linux local user folder
-''' Usage:
+
+"""Usage.
+
 us = JsonUserSettings('my_app')
 us.save(someDict)
 data = us.load()
 
-'''
-# --------------------------------------------------------------------------------------------
+"""
+# ----------------------------------------------------------------------------------------
 import os
 
+from backpack.json_utils import json_load, json_save
 from backpack.logger import get_logger
-from backpack.json_utils import json_save, json_load
 
-log = get_logger('UserSettings')
+log = get_logger('Python Backpack - UserSettings')
 
 
-class JsonUserSettings():
-    def __init__(self, folder: str, name: str):
-        '''Manages saving/loading json file on local user folder
+class JsonUserSettings:
+    def __init__(self, folder: str, name: str) -> None:
+        """Manages saving/loading json file on local user folder.
 
         Args:
             folder (str): name of sub folder inside user path. Defaults to 'json_settings'.
-            filename (str): name used for the json file. Defaults to 'user_data'.
-        '''
+            name (str): name used for the json file. Defaults to 'user_data'.
+        """
         self.name = name
         self.folder = folder
         self._user_data = {}
         self._verify_path()
 
     @property
-    def filepath(self):
-        ''' Returns user filepath '''
-        path = os.path.join(self.os_user_folder, self.folder, self.name + '.json')
+    def filepath(self) -> str:
+        """Returns user filepath."""
+        path = os.path.join(self.os_user_folder, self.folder, f'{self.name}.json')
         return os.path.abspath(path)
 
     @property
-    def os_user_folder(self):
-        ''' returns os users home directory '''
+    def os_user_folder(self) -> str:
+        """Returns os users home directory."""
         return os.path.expanduser('~')
 
     @property
-    def user_data(self):
-        ''' override this property to modify saving dict '''
+    def user_data(self) -> dict:
+        """Override this property to modify saving dict."""
         return self._user_data
 
     @user_data.setter
-    def user_data(self, v):
+    def user_data(self, v: dict) -> None:
         self._user_data = v
 
-    def _verify_path(self):
-        ''' Checks for target directory or make it '''
+    def _verify_path(self) -> bool:
+        """Checks for target directory or make it."""
         path = os.path.dirname(self.filepath)
         if not os.path.exists(path):
             os.makedirs(path)
+
         return True
 
-    def save_settings(self, data=False):
-        ''' Saves a dictionary into a json file (os user path)
+    def save_settings(self, data=False) -> bool:
+        """Saves a dictionary into a json file (os user path).
+
         Args:
             data (dictionary) : info dictionary to save, if set to False,
                 saves instead local self.user_data property
-        '''
+        """
         if not data:
             data = self.user_data
 
@@ -71,8 +74,8 @@ class JsonUserSettings():
             log.info('json settings file saved! [%s]', self.filepath)
         return r
 
-    def load_settings(self):
-        ''' Load json file from path and returns its contents '''
+    def load_settings(self) -> dict:
+        """Load json file from path and returns its contents."""
         try:
             return json_load(self.filepath)
         except OSError:

backpack/json_utils.py

@@ -1,36 +1,43 @@
-import os
 import json
+import os
 
 from backpack.logger import get_logger
 
-log = get_logger('JsonUtils')
+log = get_logger('Python Backpack - JsonUtils')
 
 
 def json_load(json_file: str) -> dict:
-    ''' Reads a json file
+    """Reads a json file.
+
     Args:
-        json_file (filepath) json file to read data.
+        json_file: (string filepath) json file to read data.
+
     Returns:
         dict (file content)
-    '''
+    """
     if not os.path.exists(json_file):
-        raise OSError(f"json_load: File not found: {json_file}.")
+        raise OSError(f'json_load: File not found: {json_file}.')
 
     with open(json_file) as json_file_opened:
         try:
             value = json.load(json_file_opened)
         except ValueError as e:
             json_file_opened.close()
-            raise OSError(f"{json_file} \n JSON File issue: {str(e)}") from e
+            raise OSError(f'{json_file} \n JSON File issue: {str(e)}') from e
+
     return value
 
 
-def json_save(data: dict, json_file: str):
-    ''' Saves a dictionary into a json file
+def json_save(data: dict, json_file: str) -> bool:
+    """Saves a dictionary into a json file.
+
     Args:
-        data (dict) : dictionary to save
-        json_file (filepath) json file to save data.
-    '''
+        data: (dict) dictionary to save
+        json_file: (string filepath) json file to save data.
+
+    Returns:
+        bool (True if success)
+    """
 
     if not os.path.exists(os.path.dirname(json_file)):
         os.makedirs(os.path.dirname(json_file))