bittensor.btlogging refactoring

bittensor/btlogging/__init__.py

@@ -1,7 +1,3 @@
-""" 
-Standardized logging for Bittensor.
-"""
-
 # The MIT License (MIT)
 # Copyright © 2021 Yuma Rao
 
@@ -19,10 +15,13 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 # DEALINGS IN THE SOFTWARE.
 
-import os
-import argparse
+"""
+btlogging sub-package standardized logging for Bittensor.
+
+This module provides logging functionality for the Bittensor package. It includes custom loggers, handlers, and
+formatters to ensure consistent logging throughout the project.
+"""
 
-import bittensor.config
 from bittensor.btlogging.loggingmachine import LoggingMachine
 
 

bittensor/btlogging/defines.py

@@ -1,3 +1,22 @@
+# The MIT License (MIT)
+# Copyright © 2023 OpenTensor Foundation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the “Software”), to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+# and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+# the Software.
+
+# THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+# THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+"""Btlogging constant definition module."""
+
 BASE_LOG_FORMAT = "%(asctime)s | %(levelname)s | %(message)s"
 TRACE_LOG_FORMAT = (
     f"%(asctime)s | %(levelname)s | %(name)s:%(filename)s:%(lineno)s | %(message)s"

bittensor/btlogging/format.py

@@ -1,40 +1,65 @@
-import time
+# The MIT License (MIT)
+# Copyright © 2023 OpenTensor Foundation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the “Software”), to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+# and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+# the Software.
+
+# THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+# THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+"""
+btlogging.format module
+
+This module defines custom logging formatters for the Bittensor project.
+"""
+
 import logging
+import time
+from typing import Dict
+
 from colorama import init, Fore, Back, Style
 
 
 init(autoreset=True)
 
-TRACE_LEVEL_NUM = 5
-SUCCESS_LEVEL_NUM = 21
+TRACE_LEVEL_NUM: int = 5
+SUCCESS_LEVEL_NUM: int = 21
 
 
-def trace(self, message, *args, **kws):
+def _trace(self, message: str, *args, **kws):
     if self.isEnabledFor(TRACE_LEVEL_NUM):
         self._log(TRACE_LEVEL_NUM, message, args, **kws)
 
 
-def success(self, message, *args, **kws):
+def _success(self, message: str, *args, **kws):
     if self.isEnabledFor(SUCCESS_LEVEL_NUM):
         self._log(SUCCESS_LEVEL_NUM, message, args, **kws)
 
 
 logging.SUCCESS = SUCCESS_LEVEL_NUM
 logging.addLevelName(SUCCESS_LEVEL_NUM, "SUCCESS")
-logging.Logger.success = success
+logging.Logger.success = _success
 
 logging.TRACE = TRACE_LEVEL_NUM
 logging.addLevelName(TRACE_LEVEL_NUM, "TRACE")
-logging.Logger.trace = trace
+logging.Logger.trace = _trace
 
-emoji_map = {
+emoji_map: Dict[str, str] = {
     ":white_heavy_check_mark:": "✅",
     ":cross_mark:": "❌",
     ":satellite:": "🛰️",
 }
 
 
-color_map = {
+color_map: Dict[str, str] = {
     "<red>": Fore.RED,
     "</red>": Style.RESET_ALL,
     "<blue>": Fore.BLUE,
@@ -44,7 +69,7 @@ def success(self, message, *args, **kws):
 }
 
 
-log_level_color_prefix = {
+log_level_color_prefix: Dict[int, str] = {
     logging.NOTSET: Fore.RESET,
     logging.TRACE: Fore.MAGENTA,
     logging.DEBUG: Fore.BLUE,
@@ -56,41 +81,54 @@ def success(self, message, *args, **kws):
 }
 
 
-LOG_FORMATS = {
+LOG_FORMATS: Dict[int, str] = {
     level: f"{Fore.BLUE}%(asctime)s{Fore.RESET} | {Style.BRIGHT}{color}%(levelname)s\033[0m | %(message)s"
     for level, color in log_level_color_prefix.items()
 }
 
-LOG_TRACE_FORMATS = {
+LOG_TRACE_FORMATS: Dict[int, str] = {
     level: f"{Fore.BLUE}%(asctime)s{Fore.RESET}"
     f" | {Style.BRIGHT}{color}%(levelname)s{Fore.RESET}{Back.RESET}{Style.RESET_ALL}"
     f" | %(name)s:%(filename)s:%(lineno)s"
     f" | %(message)s"
     for level, color in log_level_color_prefix.items()
 }
 
-DEFAULT_LOG_FORMAT = (
+DEFAULT_LOG_FORMAT: str = (
     f"{Fore.BLUE}%(asctime)s{Fore.RESET} | "
     f"{Style.BRIGHT}{Fore.WHITE}%(levelname)s{Style.RESET_ALL} | "
     f"%(name)s:%(filename)s:%(lineno)s | %(message)s"
 )
 
-DEFAULT_TRACE_FORMAT = (
+DEFAULT_TRACE_FORMAT: str = (
     f"{Fore.BLUE}%(asctime)s{Fore.RESET} | "
     f"{Style.BRIGHT}{Fore.WHITE}%(levelname)s{Style.RESET_ALL} | "
     f"%(name)s:%(filename)s:%(lineno)s | %(message)s"
 )
 
 
 class BtStreamFormatter(logging.Formatter):
+    """
+    A custom logging formatter for the Bittensor project that overrides the time formatting to include milliseconds,
+    centers the level name, and applies custom log formats, emojis, and colors.
+    """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.trace = False
 
-    def formatTime(self, record, datefmt=None):
+    def formatTime(self, record, datefmt=None) -> str:
         """
         Override formatTime to add milliseconds.
+
+        Args:
+            record (logging.LogRecord): The log record.
+            datefmt (str, optional): The date format string.
+
+        Returns:
+            s (str): The formatted time string with milliseconds.
         """
+
         created = self.converter(record.created)
         if datefmt:
             s = time.strftime(datefmt, created)
@@ -99,9 +137,20 @@ def formatTime(self, record, datefmt=None):
         s += ".{:03d}".format(int(record.msecs))
         return s
 
-    def format(self, record):
-        # Save the original format configured by the user
-        # when the logger formatter was instantiated
+    def format(self, record) -> str:
+        """
+        Override format to apply custom formatting including emojis and colors.
+
+        This method saves the original format, applies custom formatting based on the log level and trace flag, replaces
+        text with emojis and colors, and then returns the formatted log record.
+
+        Args:
+            record (logging.LogRecord): The log record.
+
+        Returns:
+            result (str): The formatted log record.
+        """
+
         format_orig = self._style._fmt
         record.levelname = f"{record.levelname:^16}"
 
@@ -127,14 +176,30 @@ def format(self, record):
         return result
 
     def set_trace(self, state: bool = True):
+        """Change formatter state."""
         self.trace = state
 
 
 class BtFileFormatter(logging.Formatter):
-    def formatTime(self, record, datefmt=None):
+    """
+    BtFileFormatter
+
+    A custom logging formatter for the Bittensor project that overrides the time formatting to include milliseconds and
+    centers the level name.
+    """
+
+    def formatTime(self, record, datefmt=None) -> str:
         """
         Override formatTime to add milliseconds.
+
+        Args:
+            record (logging.LogRecord): The log record.
+            datefmt (str, optional): The date format string.
+
+        Returns:
+            s (str): The formatted time string with milliseconds.
         """
+
         created = self.converter(record.created)
         if datefmt:
             s = time.strftime(datefmt, created)
@@ -143,6 +208,15 @@ def formatTime(self, record, datefmt=None):
         s += ".{:03d}".format(int(record.msecs))
         return s
 
-    def format(self, record):
+    def format(self, record) -> str:
+        """
+        Override format to center the level name.
+
+        Args:
+            record (logging.LogRecord): The log record.
+
+        Returns:
+            formated record (str): The formatted log record.
+        """
         record.levelname = f"{record.levelname:^16}"
         return super().format(record)

bittensor/btlogging/helpers.py

@@ -1,9 +1,36 @@
+# The MIT License (MIT)
+# Copyright © 2023 OpenTensor Foundation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the “Software”), to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+# and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+# the Software.
+
+# THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+# THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+"""
+btlogging.helpers module provides helper functions for the Bittensor logging system.
+"""
+
 import logging
+from typing import Generator
 
 
-def all_loggers():
-    """
-    Generator that yields all logger instances in the application.
+def all_loggers() -> Generator[logging.Logger, None, None]:
+    """Generator that yields all logger instances in the application.
+
+    Iterates through the logging root manager's logger dictionary and yields all active `Logger` instances. It skips
+    placeholders and other types that are not instances of `Logger`.
+
+    Yields:
+        logger (logging.Logger): An active logger instance.
     """
     for logger in logging.root.manager.loggerDict.values():
         if isinstance(logger, logging.PlaceHolder):
@@ -20,7 +47,16 @@ def all_loggers():
             pass
 
 
-def all_logger_names():
+def all_logger_names() -> Generator[str, None, None]:
+    """
+    Generate the names of all active loggers.
+
+    This function iterates through the logging root manager's logger dictionary and yields the names of all active
+    `Logger` instances. It skips placeholders and other types that are not instances of `Logger`.
+
+    Yields:
+        name (str): The name of an active logger.
+    """
     for name, logger in logging.root.manager.loggerDict.items():
         if isinstance(logger, logging.PlaceHolder):
             continue
@@ -36,7 +72,15 @@ def all_logger_names():
             pass
 
 
-def get_max_logger_name_length():
+def get_max_logger_name_length() -> int:
+    """
+    Calculate and return the length of the longest logger name.
+
+    This function iterates through all active logger names and determines the length of the longest name.
+
+    Returns:
+        max_length (int): The length of the longest logger name.
+    """
     max_length = 0
     for name in all_logger_names():
         if len(name) > max_length: