import os import sys from io import TextIOWrapper from typing import TextIO, Union from collections import namedtuple from utils import common from utils.printfmt import * class Logger: ... # class delcaration class Logger: # class redeclaration & initialisation """A simple logging class to write messages directly to the console or to a log file. Class contains a variety of methods to perform logging, all of which invoke a private wrapper method over the built-in `print()` function, with enhanced features built into the class methods. Make use of pseudolog methods (`Logger` pseudonyms) to quickly, and effectively write a message to a log file. These pseudolog methods modify the class state to remember the last message logged out to a file, in addition to its formatting, which can then be written to the console using the `Logger.withConsole()` method. Example of using pseudolog methods: ```py >>> import clog >>> logger = clog.Logger() >>> >>> logger.debug("A debug message with stacktrace!") >>> logger.error("Whoops! This should not be here.").withConsole() \033[91mWhoops! This should not be here.\033[0m >>> >>> msg = "Checking if 1 + 1 = 2..." >>> logger.debug(msg, end="\r").withConsole() >>> if 1 + 1 != 2: ... logger.error(msg + "failed.").withConsole() ... else: ... logger.debug(msg + "ok.").withConsole() ``` Logger can output text to a console with colour, depending on its associated log level given. Different standard `PIPE`s can also be written to depending on the level of the log, or if a file redirect descriptor has been given. Note, colour is omitted when not writing to console on STDOUT or STDERR. """ ## set the PIPE to STDOUT by default __stdpipe: TextIO = sys.stdout ## detect if there's a redirect __IS_STDOUT_REDIR: bool = os.isatty(sys.stdout.fileno()) __IS_STDERR_REDIR: bool = os.isatty(sys.stderr.fileno()) ## the default log out file __DEFAULT_OUT_FILE: str = "dump.log" ## log info namedtuple for storing class states __LOG_INFO_TUPLE = namedtuple('LogInfo', ['isatty', 'lv', 'msg', 'sep', 'end']) ## create instance attribute for class singleton __instance__ = None ## create instance attribute as read-only for log location log = None def __new__(cls, *, out_f: str = ...) -> Logger: """Construct a new instance of the class and initialise it. Constructor method is used to establish the class as a Singleton+Factory pattern. A new instance is returned from the constructor, or if an existing instance is present, return the object of that instance. """ if cls.__instance__ is None: cls.__instance__ = super(Logger, cls).__new__(cls) # establish singleton instance cls.log = cls.__DEFAULT_OUT_FILE # initialise attribute to default ## handle if a custom file pathspec was given if out_f is not Ellipsis and isinstance(out_f, str): ## verify path and convert to real pathspec. if common.is_path_spec(out_f): ## redefine the default log out attribute and create ## public attribute for the currect log location cls.log = cls.__DEFAULT_OUT_FILE = \ os.path.realpath(out_f).strip('"') cls.__loginfo = None # default the namedtuple to None on first instance cls.printLog2File("----[New instance of script has been started]----", file=cls.__DEFAULT_OUT_FILE, mode='w') return cls.__instance__ @classmethod def debug(cls, *value: object, sep: Union[str, None] = None, end: Union[str, None] = None, wrapping: bool = True, strace: bool = True) -> Logger: """Pseudolog for writing to log file with level `LogLevel.DEBUG`. Method is invoked on a `Logger` instance and will directly write out to a log file using the built-in `printLog2File` helper method. The returned object is a modified instance of the `Logger` class which stores information regarding what was written to the log file, and what formatting was applied. The `Logger.withConsole()` method can be invoked directly afterwards (or later) to write the same message to the console. """ Logger.printLog2File(*value, sep=sep, end=end, wrapping=wrapping, strace=strace) Logger.__stdpipe = sys.stderr cls.__loginfo: namedtuple = Logger.__LOG_INFO_TUPLE( Logger.__IS_STDERR_REDIR, LogLevel.DEBUG, value, sep, end ) return cls @classmethod def warn(cls, *value: object, sep: Union[str, None] = None, end: Union[str, None] = None, wrapping: bool = True, strace: bool = True) -> Logger: """Pseudolog for writing to log file with level `LogLevel.WARN`. Method is invoked on a `Logger` instance and will directly write out to a log file using the built-in `printLog2File` helper method. The returned object is a modified instance of the `Logger` class which stores information regarding what was written to the log file, and what formatting was applied. The `Logger.withConsole()` method can be invoked directly afterwards (or later) to write the same message to the console. """ Logger.printLog2File(*value, level=LogLevel.WARN, sep=sep, end=end, wrapping=wrapping, strace=strace) Logger.__stdpipe = sys.stderr cls.__loginfo: namedtuple = Logger.__LOG_INFO_TUPLE( Logger.__IS_STDERR_REDIR, LogLevel.WARN, value, sep, end ) return cls @classmethod def error(cls, *value: object, sep: Union[str, None] = None, end: Union[str, None] = None, wrapping: bool = True, strace: bool = True) -> Logger: """Pseudolog for writing to log file with level `LogLevel.ERROR`. Method is invoked on a `Logger` instance and will directly write out to a log file using the built-in `printLog2File` helper method. The returned object is a modified instance of the `Logger` class which stores information regarding what was written to the log file, and what formatting was applied. The `Logger.withConsole()` method can be invoked directly afterwards (or later) to write the same message to the console. """ Logger.printLog2File(*value, level=LogLevel.ERROR, sep=sep, end=end, wrapping=wrapping, strace=strace) Logger.__stdpipe = sys.stderr cls.__loginfo: namedtuple = Logger.__LOG_INFO_TUPLE( Logger.__IS_STDERR_REDIR, LogLevel.ERROR, value, sep, end ) return cls @staticmethod def withConsole() -> None: """Write the last message logged to a file to the console as well. That is, any message written using a pseudolog method. The last message is determined by a pseudolog, which modifies the state of the class to remember information regarding what was recently written out to a log file. This method will write to the console according to the standard PIPE of each type of logging level. Colouring will be enabled for outputs in association to the log level. If PIPE is redirected to external file, colouring is disabled. Any other information regarding the formatting of the message is directly associated to the formatting used when writing to a log file. """ if not Logger.__loginfo is None: Logger.__printLog__(Logger.__loginfo.isatty, Logger.__loginfo.lv, Logger.__loginfo.msg, Logger.__loginfo.sep, Logger.__loginfo.end) @staticmethod def printLog2File(*value: object, level: Union[LogLevel, int] = LogLevel.DEBUG, mode: str = 'a', file: Union[TextIOWrapper, str] = ..., sep: Union[str, None] = None, end: Union[str, None] = None, wrapping: bool = True, strace: bool = True, header: bool = True) -> None: """Wrapper method over the built-in `print()` function defined using 3.x syntax. All Familiar functionality can be passed to the method as found when calling `print()`, but comes with added features. Method not to be confused with `Logger.printLog()`, `printLog2File` provides enhanced and guaranteed handling of file streams using the built-in `with` statement. `printLog()` can however write out to a file stream, but requires a `TextIOWrapper` object to be given, or omitted with `None` for output to the `STDOUT` stream. `printLog2File` can take a string pathspec as the location to a file and open the file stream to write into. This method is designed strictly to write messages to a log file with ehanced features, such as line-wrapping and stacktrace. By default, this method will generate a log entry header with `strace` and `wrapping` enabled. Optionally, these can be disabled when calling the method. If the `header` is disabled, it means the given `value` is written directly to the log file. This allows for process controlled messages to be written, i.e., a log might be written employing a process is about to be performed, and append the values 'ok' or 'failed', depending on the finishing state of the process. Examples of logging to file: ```py >>> import clog >>> >>> log_file = ".dump.log" >>> clog.Logger.printLog2File("Hello from log file!", file=log_file) >>> # note, we can still pass a TextIOWrapper object >>> with open(log_file, 'a') as f: ... clog.Logger.printLog2File("Using own wapper.", file=f) ... >>> # process controlled logging >>> clog.Logger.printLog2File("Establishing OS...", end="") >>> import os >>> clog.Logger.printLog2File(os.name, header=False) ``` NOTE: if `file` is omitted when invoking method, the default pathspec is used to write to file (defined as `__DEFAULT_OUT_FILE`). If a new `Logger` instance was established, when `file` is obmitted, the default pathspec used is defined by the `Logger` instance. """ ## handle if no file parameter was given if file is Ellipsis or not os.path.exists(file): file = Logger.__DEFAULT_OUT_FILE _frame = sys._getframe(2) if sys._getframe(1).f_code.co_name in \ dir(Logger) else sys._getframe(1) ## get the executing filename of where log was called _fname = _frame.f_code.co_filename.removeprefix( os.getcwd()).strip('\\\/') ## generate new header for log file and construct new message if header: msg = gen_log_header(level).format( " ".join(value), CALLER="{0}:{1}[{2}]".format( _fname, _frame.f_code.co_name, _frame.f_lineno ).replace("module", "global") if strace else "LOGGER" ) else: msg = " ".join(value) # perform wrapping of message and indent wrapped lines if wrapping: msg = wrap(msg).replace('\n', '\n\t') if isinstance(file, str): with open(file, mode, encoding="utf-8") as log: Logger.__stdpipe = log # pre-requisite to write PIPE to file Logger.__printLog__(False, level, (msg,), sep, end, False) elif isinstance(file, TextIOWrapper): Logger.__stdpipe = log Logger.__printLog__(False, level, (msg,), sep, end, False) @staticmethod def printLog(*value: object, level: Union[int, LogLevel] = LogLevel.NORMAL, sep: Union[str, None] = None, end: Union[str, None] = None, file: Union[TextIOWrapper, None] = None, flush: bool = True) -> None: """Wrapper method over the built-in `print()` function defined using 3.x syntax. All Familiar functionality can be passed to the method as found when calling `print()`, but comes with added features. `Logger.printLog` is designed for purpose of logging information to the console window or to a file, either via an explicit write by passing a compatible `SupportsWrite[str]` value to `file=`, or by redirecting the standard PIPE streams to an external file. In addition, different levels of logging will result in output to standard PIPE streams to have appropriate highlighting to the message displayed. If standard PIPE streams are to be redirected to an external file via a PIPE redirect, the highlighting syntax is dropped do prevent ANSI escape code sequences from being written to file. The standard log level is `NORMAL`, referring to standard formatted text to the standard stream. Log level can be elevated by either passing an integer to represent the log level, or pass an enum variable from `class LogLevel` from the `utils/common.py` module. Examples of logging: ``` >>> import clog >>> clog.Logger.printLog("Hello, World!") Hello, World! >>> clog.Logger.printLog("Hello,", "World" + "!", level=LogLevel.DEBUG) \033[94mHello, World!\033[0m >>> clog.Logger.printLog("Hello,", end=" ") ; clog.Logger.printLog("World!", level=1) Hello, \033[92mWorld!\033[0m >>> with open("dump.log", 'a') as log_file: ... clog.Logger.printLog("Hello, Log File!", file=log_file) ... >>> ``` """ ### :@Ethan: whilst `print` disables force flushing of the # stream, from testing, it's best to forcibly flush the stream # so the default behaviour is to do exactly this. ## configure PIPE to STDERR if logging is high enough if file is None: if level >= LogLevel.DEBUG: Logger.__stdpipe = sys.stderr else: Logger.__stdpipe = sys.stdout ## handle if the file is a TextIOWrapper elif isinstance(file, TextIOWrapper): Logger.__stdpipe = file # `print` will handle this as is. ## otherwise the method was given an invalid argument else: Logger.printLog("Warning: logging function was called with a", "file specifier parameter which is not a valid option.", level=LogLevel.WARN) return ## display message to console with appropriate colouring ### :@NOTE: if there's a PIPE redirect, don't use colour ### for that redirect PIPE if level < LogLevel.WARN: ## handle output for STDOUT Logger.__printLog__(Logger.__IS_STDOUT_REDIR, level, value, sep, end, flush) else: ## handle output for STDERR Logger.__printLog__(Logger.__IS_STDERR_REDIR, level, value, sep, end, flush) @staticmethod def __printLog__(isatty: bool, lv: LogLevel, msg: object, s: Union[str, None] = None, e: Union[str, None] = None, flsh: bool = True) -> None: """Private helper method responsible for invoking the built-in `print` function with appropriate keyword arugments. Method identifies the PIPE used and provide text highlighting accordingly. """ ## handle if we have a redirect if isatty and (Logger.__stdpipe is sys.stdout or \ Logger.__stdpipe is sys.stderr): ## write ANSI code to start coloured text print(log_as_col(lv), end="", file=Logger.__stdpipe, flush=flsh) ## unpack the object and pass to print print(*msg, sep=s, end="", file=Logger.__stdpipe, flush=flsh) ## reset the colour sequence back to normal print(Colours.NORMAL, end=e, file=Logger.__stdpipe, flush=flsh) else: print(*msg, sep=s, end=e, file=Logger.__stdpipe, flush=flsh)