expresso-framework 0.0.1__py3-none-any.whl

expresso/__init__.py

@@ -0,0 +1,16 @@
+from .expresso import Expresso
+from .exposure import Exposure
+
+from .enums import (
+    ExposureCategory,
+    ExposureLevel,
+    ExposureTimeSource,
+)
+
+__all__ = [
+    "Expresso",
+    "Exposure",
+    "ExposureCategory",
+    "ExposureLevel",
+    "ExposureTimeSource",
+]

expresso/enums/__init__.py

@@ -0,0 +1,9 @@
+from .exposure_category import ExposureCategory
+from .exposure_level import ExposureLevel
+from .exposure_time_source import ExposureTimeSource
+
+__all__ = [
+    "ExposureCategory",
+    "ExposureLevel",
+    "ExposureTimeSource",
+]

expresso/enums/exposure_category.py

@@ -0,0 +1,24 @@
+class ExposureCategory:
+    def __init__(self, name): self.name = name
+
+    @staticmethod
+    def of(customName):
+        normalized = customName.strip().upper()
+        return ExposureCategory(normalized)
+
+    def __eq__(self, other):
+        if isinstance(other, ExposureCategory):
+            return self.name == other.name
+        return False
+
+    def __hash__(self): return hash(self.name)
+
+    def __str__(self): return self.name
+
+ExposureCategory.VANILLA = ExposureCategory("VANILLA")
+ExposureCategory.SYSTEMLOG = ExposureCategory("SYSTEMLOG")
+ExposureCategory.DEBUG = ExposureCategory("DEBUG")
+ExposureCategory.COMPONENTIAL = ExposureCategory("COMPONENTIAL")
+ExposureCategory.LOWERLEVEL = ExposureCategory("LOWERLEVEL")
+ExposureCategory.BITWISE = ExposureCategory("BITWISE")
+ExposureCategory.TEST = ExposureCategory("TEST")

expresso/enums/exposure_level.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+class ExposureLevel(Enum):
+    LEVEL1 = 1
+    LEVEL2 = 2
+    LEVEL3 = 3
+    LEVEL4 = 4
+    LEVEL5 = 5
+
+    def getLevel(self) -> int: return self.value

expresso/enums/exposure_time_source.py

@@ -0,0 +1,5 @@
+from abc import ABC, abstractmethod
+
+class ExposureTimeSource(ABC):
+    @abstractmethod
+    def getTime(self) -> str: pass

expresso/exposure.py

@@ -0,0 +1,69 @@
+from .expresso import Expresso
+from .enums.exposure_level import ExposureLevel
+
+class Exposure:
+
+    def __init__(self, identity = None): self.identity = identity
+
+    def enabled(self, category, level): return Expresso.isExposed(category, level)
+
+    def expose(self, category, level, formatString, *args):
+        if callable(formatString):
+            if not Expresso.isExposed(category, level):
+                return
+            Expresso.printf(self.identity, category, level, "%s", formatString())
+        else:
+            Expresso.printf(self.identity, category, level, formatString, *args)
+
+    def l1(self, category, formatString, *args):
+        if callable(formatString):
+            if not Expresso.isExposed(category, ExposureLevel.LEVEL1): return
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL1, "%s", formatString())
+        else:
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL1, formatString, *args)
+
+    def l2(self, category, formatString, *args):
+        if callable(formatString):
+            if not Expresso.isExposed(category, ExposureLevel.LEVEL2): return
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL2, "%s", formatString())
+        else:
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL2, formatString, *args)
+
+    def l3(self, category, formatString, *args):
+        if callable(formatString):
+            if not Expresso.isExposed(category, ExposureLevel.LEVEL3): return
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL3, "%s", formatString())
+        else:
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL3, formatString, *args)
+
+    def l4(self, category, formatString, *args):
+        if callable(formatString):
+            if not Expresso.isExposed(category, ExposureLevel.LEVEL4): return
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL4, "%s", formatString())
+        else:
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL4, formatString, *args)
+
+    def l5(self, category, formatString, *args):
+        if callable(formatString):
+            if not Expresso.isExposed(category, ExposureLevel.LEVEL5): return
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL5, "%s", formatString())
+        else:
+            Expresso.printf(self.identity, category, ExposureLevel.LEVEL5, formatString, *args)
+
+    def nl(self, category, requiredLevel):
+        Expresso.NEWLINE(category, requiredLevel)
+
+    def lbr(self, category, requiredLevel):
+        Expresso.LINEBREAK(category, requiredLevel)
+
+    def err(self, formatString, *args):
+        if self.identity is not None and str(self.identity).strip():
+            Expresso.error("[" + str(self.identity) + "] " + formatString, *args)
+        else:
+            Expresso.error(formatString, *args)
+
+    def here(self, label=None, customColor=None, customHeader=None):
+        Expresso.hereAnnounce(identity=self.identity, customColor=customColor, customHeader=customHeader, label=label)
+
+    def getIdentity(self):
+        return self.identity

expresso/expresso.py

@@ -0,0 +1,393 @@
+import sys
+import time
+import traceback
+from datetime import datetime
+from enum import Enum
+from threading import Lock
+
+from .enums.exposure_category import ExposureCategory
+from .enums.exposure_level import ExposureLevel
+from .enums.exposure_time_source import ExposureTimeSource
+from . import variable_constants
+
+
+class Expresso:
+
+    globalEventCounter = 0
+    counterLock = Lock()
+
+    minIndex = 0
+    maxIndex = float("inf")
+    indexLock = Lock()
+
+    showIndexTag = True
+    showIdentityTag = True
+    showCategoryTag = True
+    showLevelTag = True
+
+    timeSource = None
+    showApplicationTimeTag = False
+    showTimestampTag = False
+    showElapsedTimeTag = False
+
+    DEFAULT_ERROR_PREFIX = "[ERROR]: "
+    DEFAULT_ERROR_COLOR = variable_constants.BOLD + variable_constants.FG_RED
+
+    DEFAULT_HERE_HEADER = "--> [EXPRESSO REPORT HERE]"
+    DEFAULT_HERE_COLOR = variable_constants.BOLD + variable_constants.FG_MAGENTA
+
+    errorPrefix = DEFAULT_ERROR_PREFIX
+    errorColor = DEFAULT_ERROR_COLOR
+
+    hereHeader = DEFAULT_HERE_HEADER
+    hereColor = DEFAULT_HERE_COLOR
+
+    showDiagnosticTags = False
+
+    enabledCategories = set()
+    categoriesLock = Lock()
+
+    enabledLevels = { ExposureLevel.LEVEL1 }
+    levelsLock = Lock()
+
+    externalBridge = None
+
+    runtimeStart = time.perf_counter()
+
+    RESET = variable_constants.RESET
+    BOLD = variable_constants.BOLD
+    DIM = variable_constants.DIM
+    UNDERLINE = variable_constants.UNDERLINE
+    LINEFEED = variable_constants.LINEFEED
+
+    FG_BLACK = variable_constants.FG_BLACK
+    FG_RED = variable_constants.FG_RED
+    FG_GREEN = variable_constants.FG_GREEN
+    FG_YELLOW = variable_constants.FG_YELLOW
+    FG_BLUE = variable_constants.FG_BLUE
+    FG_MAGENTA = variable_constants.FG_MAGENTA
+    FG_CYAN = variable_constants.FG_CYAN
+    FG_WHITE = variable_constants.FG_WHITE
+
+    BG_BLACK = variable_constants.BG_BLACK
+    BG_RED = variable_constants.BG_RED
+    BG_GREEN = variable_constants.BG_GREEN
+    BG_YELLOW = variable_constants.BG_YELLOW
+    BG_BLUE = variable_constants.BG_BLUE
+    BG_MAGENTA = variable_constants.BG_MAGENTA
+    BG_CYAN = variable_constants.BG_CYAN
+    BG_WHITE = variable_constants.BG_WHITE
+
+    @staticmethod
+    def FG_COLOR(id): return variable_constants.FG_COLOR(id)
+
+    @staticmethod
+    def BG_COLOR(id): return variable_constants.BG_COLOR(id)
+
+    @staticmethod
+    def exposure(identity = None): 
+        from .exposure import Exposure
+        return Exposure(identity)
+
+    @staticmethod
+    def enableIndexTag(enable): Expresso.showIndexTag = enable
+
+    @staticmethod
+    def enableIdentityTag(enable): Expresso.showIdentityTag = enable
+
+    @staticmethod
+    def enableCategoryTag(enable): Expresso.showCategoryTag = enable
+
+    @staticmethod
+    def enableLevelTag(enable): Expresso.showLevelTag = enable
+
+    @staticmethod
+    def enableTimestamp(enable): Expresso.showTimestampTag = enable
+
+    @staticmethod
+    def enableElapsedTime(enable): Expresso.showElapsedTimeTag = enable
+
+    @staticmethod
+    def setIndexRange(start, end = None):
+        if end is None:
+            nextMin = 0
+            nextMax = start
+        else:
+            nextMin = max(0, start)
+            nextMax = max(start, end)
+
+        with Expresso.indexLock:
+            Expresso.minIndex = nextMin
+            Expresso.maxIndex = nextMax
+
+    @staticmethod
+    def setSingleIndex(targetIndex): Expresso.setIndexRange(targetIndex, targetIndex)
+
+    @staticmethod
+    def setErrorStyle(color = None, prefix = None):
+        if color is not None: Expresso.errorColor = color
+        if prefix is not None: Expresso.errorPrefix = prefix
+
+    @staticmethod
+    def setHereStyle(color = None, header = None):
+        if color is not None: Expresso.hereColor = color
+        if header is not None: Expresso.hereHeader = header
+
+    @staticmethod
+    def resetErrorStyle():
+        Expresso.errorColor = Expresso.DEFAULT_ERROR_COLOR
+        Expresso.errorPrefix = Expresso.DEFAULT_ERROR_PREFIX
+
+    @staticmethod
+    def resetHereStyle():
+        Expresso.hereColor = Expresso.DEFAULT_HERE_COLOR
+        Expresso.hereHeader = Expresso.DEFAULT_HERE_HEADER
+
+    @staticmethod
+    def enableDiagnosticTags(enable): Expresso.showDiagnosticTags = enable
+
+    @staticmethod
+    def clearIndexFilter():
+        with Expresso.indexLock:
+            Expresso.minIndex = 0
+            Expresso.maxIndex = float("inf")
+
+    @staticmethod
+    def resetEventCounter():
+        with Expresso.counterLock: Expresso.globalEventCounter = 0
+
+    @staticmethod
+    def clearAllCategories(): 
+        with Expresso.categoriesLock: Expresso.enabledCategories = set()
+
+    @staticmethod
+    def enableCategory(category):
+        if category is not None: 
+            with Expresso.categoriesLock: Expresso.enabledCategories.add(category.name)
+
+    @staticmethod
+    def disableCategory(category):
+        if category is not None: 
+            with Expresso.categoriesLock: Expresso.enabledCategories.discard(category.name)
+
+    @staticmethod
+    def NEWLINE(category, requiredLevel):
+        if Expresso.isExposed(category, requiredLevel): Expresso.emit("\n\n")
+
+    @staticmethod
+    def LINEBREAK(category, requiredLevel):
+        if Expresso.isExposed(category, requiredLevel): Expresso.emit("\n--------------------------------\n")
+
+    @staticmethod
+    def setLevel(newLevel):
+        with Expresso.levelsLock:
+            Expresso.enabledLevels.clear()
+            if newLevel is not None: Expresso.enabledLevels.add(newLevel)
+
+    @staticmethod
+    def setLevels(*handPickedLevels):
+        with Expresso.levelsLock:
+            Expresso.enabledLevels.clear()
+            if handPickedLevels is not None:
+                for level in handPickedLevels:
+                    if level is not None:
+                        Expresso.enabledLevels.add(level)
+
+    @staticmethod
+    def setCategory(category):
+        nextSet = set()
+        if category is not None: nextSet.add(category.name)
+        with Expresso.categoriesLock: Expresso.enabledCategories = nextSet
+
+    @staticmethod
+    def setCategories(*handPickedCategories):
+        nextSet = set()
+        if handPickedCategories is not None:
+            for category in handPickedCategories:
+                if category is not None: nextSet.add(category.name)
+        with Expresso.categoriesLock: Expresso.enabledCategories = nextSet
+
+    @staticmethod
+    def getCurrentEventCount():
+        with Expresso.counterLock: return Expresso.globalEventCounter
+
+    @staticmethod
+    def getCategories(): 
+        with Expresso.categoriesLock: return frozenset(Expresso.enabledCategories)
+
+    @staticmethod
+    def getLevels(): 
+        with Expresso.levelsLock: return frozenset(Expresso.enabledLevels)
+
+    @staticmethod
+    def setTimeSource(source): Expresso.timeSource = source
+
+    @staticmethod
+    def enableApplicationTime(enable): Expresso.showApplicationTimeTag = enable
+
+    @staticmethod
+    def setBridge(outsideSystem): Expresso.externalBridge = outsideSystem
+
+    @staticmethod
+    def reset():
+        Expresso.clearAllCategories()
+        Expresso.setLevel(ExposureLevel.LEVEL1)
+        Expresso.clearIndexFilter()
+        Expresso.resetEventCounter()
+        Expresso.enableTimestamp(False)
+        Expresso.enableElapsedTime(False)
+        Expresso.enableApplicationTime(False)
+        Expresso.setBridge(None)
+
+    @staticmethod
+    def isExposed(category, requiredLevel):
+        if category is None or requiredLevel is None: return False
+        with Expresso.categoriesLock:
+            activeCategories = Expresso.enabledCategories
+            if activeCategories and category.name not in activeCategories:
+                return False
+
+        with Expresso.levelsLock:
+            activeLevels = Expresso.enabledLevels
+
+            if not activeLevels: return False
+
+            if len(activeLevels) == 1:
+                activeLevel = next(iter(activeLevels))
+                if activeLevel.getLevel() < requiredLevel.getLevel(): return False
+            else:
+                if requiredLevel not in activeLevels: return False
+
+        return True
+
+    @staticmethod
+    def printf(*args):
+        if len(args) < 3:
+            raise TypeError("printf requires at least category, requiredLevel and format")
+
+        if isinstance(args[0], ExposureCategory):
+            identity = ""
+            category = args[0]
+            requiredLevel = args[1]
+            formatString = args[2]
+            formatArgs = args[3:]
+        else:
+            identity = args[0]
+            category = args[1]
+            requiredLevel = args[2]
+            formatString = args[3]
+            formatArgs = args[4:]
+
+        if not Expresso.isExposed(category, requiredLevel): return
+
+        with Expresso.counterLock:
+            Expresso.globalEventCounter += 1
+            currentIndex = Expresso.globalEventCounter
+
+        with Expresso.indexLock:
+            minIndex = Expresso.minIndex
+            maxIndex = Expresso.maxIndex
+
+        if currentIndex < minIndex or currentIndex > maxIndex: return
+
+        output = ""
+
+        if Expresso.showApplicationTimeTag:
+            source = Expresso.timeSource
+            if source is not None:
+                applicationTime = source.getTime()
+                if applicationTime is not None and str(applicationTime).strip():
+                    output += Expresso.DIM + "[" + str(applicationTime) + "] " + Expresso.RESET
+
+        if Expresso.showTimestampTag:
+            timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+            output += Expresso.DIM + "[" + timestamp + "] " + Expresso.RESET
+
+        if Expresso.showElapsedTimeTag:
+            elapsedMillis = (time.perf_counter() - Expresso.runtimeStart) * 1000.0
+            output += Expresso.DIM + f"[+{elapsedMillis:.3f}ms] " + Expresso.RESET
+
+        if Expresso.showIndexTag:
+            output += Expresso.DIM + f"[#{currentIndex}] " + Expresso.RESET
+
+        if Expresso.showIdentityTag and identity is not None and str(identity).strip():
+            output += Expresso.DIM + f"[{identity}] " + Expresso.RESET
+
+        if Expresso.showCategoryTag:
+            output += Expresso.DIM + f"[{category.name}] " + Expresso.RESET
+
+        if Expresso.showLevelTag:
+            output += Expresso.DIM + f"[{requiredLevel.name}] " + Expresso.RESET
+
+        if formatArgs:
+            try:  output += formatString % formatArgs
+            except TypeError: output += formatString.format(*formatArgs)
+        else: output += formatString
+
+        Expresso.emit(output)
+
+    @staticmethod
+    def emit(text):
+        bridge = Expresso.externalBridge
+        if bridge is not None:
+            bridge(text)
+        else:
+            print(text, end="")
+
+    @staticmethod
+    def appendDiagnosticTags():
+        output = ""
+        if not Expresso.showDiagnosticTags: return output
+
+        if Expresso.showApplicationTimeTag and Expresso.timeSource is not None:
+            appTime = Expresso.timeSource.getTime()
+            if appTime is not None and str(appTime).strip():
+                output += Expresso.DIM + f"[{appTime}] " + Expresso.RESET
+
+        if Expresso.showTimestampTag:
+            timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+            output += Expresso.DIM + f"[{timestamp}] " + Expresso.RESET
+
+        if Expresso.showElapsedTimeTag:
+            elapsedMillis = (time.perf_counter() - Expresso.runtimeStart) * 1000.0
+            output += Expresso.DIM + f"[+{elapsedMillis:.3f}ms] " + Expresso.RESET
+
+        return output
+
+    @staticmethod
+    def error(formatString, *args):
+        exception = None
+        formattingArgs = list(args)
+
+        if formattingArgs and isinstance(formattingArgs[-1], BaseException):
+            exception = formattingArgs.pop()
+
+        output = Expresso.appendDiagnosticTags()
+        output += Expresso.errorColor + Expresso.errorPrefix + Expresso.RESET
+
+        if formattingArgs:
+            try: output += formatString % tuple(formattingArgs)
+            except TypeError: output += formatString.format(*formattingArgs)
+        else: 
+            output += formatString
+
+        if exception is not None:
+            output += "\n"
+            output += "".join(traceback.format_exception(type(exception), exception, exception.__traceback__))
+
+        Expresso.emit(output)
+
+    @staticmethod
+    def hereAnnounce(identity=None, customColor = None, customHeader = None, label = None):
+        output = Expresso.appendDiagnosticTags()
+        color = customColor if customColor is not None else Expresso.hereColor
+        header = customHeader if customHeader is not None else Expresso.hereHeader
+
+        if identity is not None and str(identity).strip(): output += "[" + str(identity) + "] "
+
+        output += color + header + Expresso.RESET
+
+        if label is not None and str(label).strip(): output += ": " + str(label)
+        output += "\n"
+            
+        Expresso.emit(output)

expresso/variable_constants.py

@@ -0,0 +1,71 @@
+
+RESET          = "\033[0m"
+BOLD           = "\033[1m"
+DIM            = "\033[2m"
+UNDERLINE      = "\033[4m"
+BLINK          = "\033[5m"
+INVERT         = "\033[7m"
+STRIKETHROUGH  = "\033[9m"
+
+FG_BLACK       = "\033[30m"
+FG_RED         = "\033[31m"
+FG_GREEN       = "\033[32m"
+FG_YELLOW      = "\033[33m"
+FG_BLUE        = "\033[34m"
+FG_MAGENTA     = "\033[35m"
+FG_CYAN        = "\033[36m"
+FG_WHITE       = "\033[37m"
+
+BG_BLACK       = "\033[40m"
+BG_RED         = "\033[41m"
+BG_GREEN       = "\033[42m"
+BG_YELLOW      = "\033[43m"
+BG_BLUE        = "\033[44m"
+BG_MAGENTA     = "\033[45m"
+BG_CYAN        = "\033[46m"
+BG_WHITE       = "\033[47m"
+
+FG_COLOR = lambda id: f"\033[38;5;{id}m"
+BG_COLOR = lambda id: f"\033[48;5;{id}m" 
+
+CLEAR_LINE     = "\033[2K\r"
+
+ENDOFSTRING    = 0     
+BELL           = 7            
+BACKSPACE      = 8       
+HORIZONTALTAB  = 9   
+LINEFEED       = 10   
+CARRIAGERETURN = 13
+ESCAPE         = 27         
+
+STARTOFHEADING = 1      
+STARTOFTEXT    = 2         
+ENDOFTEXT      = 3           
+ENDOFTRANSMISSION = 4   
+ENQUIRY = 5             
+ACKNOWLEDGE = 6         
+NEGATIVEACKNOWLEDGE = 21
+SYNCHRONOUSIDLE = 22    
+ENDOFTRANSMITBLOCK = 23  
+
+VERTICALTAB = 11     
+FORMFEED = 12        
+SHIFTIN = 15         
+DATALINKESCAPE = 16  
+DEVICECONTROL1 = 17  
+DEVICECONTROL2 = 18  
+DEVICECONTROL3 = 19  
+DEVICECONTROL4 = 20  
+CANCEL = 24          
+ENDOFMEDIUM = 25     
+SUBSTITUTE = 26      
+
+FILESEPARATOR = 28    
+GROUPSEPARATOR = 29    
+RECORDSEPARATOR = 30    
+UNITSEPARATOR = 31    
+DELETECHAR = 127      
+
+SPINNER = "|/-\\" 
+NEWLINE = lambda: print(RESET + "\n\n")
+LINEBREAK = lambda: print(RESET + "\n--------------------------------\n")