ramses-rf 0.22.40__py3-none-any.whl → 0.51.2__py3-none-any.whl

{ramses_rf/protocol → ramses_tx}/logger.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
 """RAMSES RF - a RAMSES-II protocol decoder & analyser.
 
 This module wraps logger to provide bespoke functionality, especially for timestamps.
 """
+
 from __future__ import annotations
 
 import logging
@@ -12,15 +11,14 @@ import os
 import re
 import shutil
 import sys
+from collections.abc import Callable, Mapping
 from datetime import datetime as dt
 from logging.handlers import TimedRotatingFileHandler as _TimedRotatingFileHandler
-from typing import Callable
+from typing import Any
 
-from .const import __dev_mode__
-from .schemas import SZ_FILE_NAME, SZ_ROTATE_BACKUPS, SZ_ROTATE_BYTES
 from .version import VERSION
 
-DEV_MODE = __dev_mode__ and False
+DEV_MODE = False
 
 _LOGGER = logging.getLogger(__name__)
 if DEV_MODE:
@@ -69,23 +67,23 @@ class _Logger(logging.Logger):  # use pkt.dtm for the log record timestamp
 
     def makeRecord(
         self,
-        name,
-        level,
-        fn,
-        lno,
-        msg,
-        args,
-        exc_info,
-        func=None,
-        extra=None,
-        sinfo=None,
-    ):
+        name: str,
+        level: int,
+        fn: str,
+        lno: int,
+        msg: object,
+        args: Any,
+        exc_info: Any,
+        func: str | None = None,
+        extra: Mapping[str, object] | None = None,
+        sinfo: str | None = None,
+    ) -> logging.LogRecord:
         """Create a specialized LogRecord with a bespoke timestamp.
 
         Will overwrite created and msecs (and thus asctime), but not relativeCreated.
         """
 
-        extra = dict(extra)  # work with a copy
+        extra = dict(extra or {})  # work with a copy
         extra["frame"] = extra.pop("_frame", "")
         if extra["frame"]:
             extra["frame"] = f" {extra['_rssi']} {extra['frame']}"
@@ -102,11 +100,11 @@ class _Logger(logging.Logger):  # use pkt.dtm for the log record timestamp
         if rv.msg:
             rv.msg = f" < {rv.msg}"
 
-        if getattr(rv, "error_text", None):
-            rv.error_text = f" * {rv.error_text}"
+        if value := getattr(rv, "error_text", None):  # HACK
+            rv.error_text = f" * {value}"
 
-        if getattr(rv, "comment", None):
-            rv.comment = f" # {rv.comment}"
+        if value := getattr(rv, "comment", None):  # HACK
+            rv.comment = f" # {value}"
 
         return rv
 
@@ -118,7 +116,7 @@ class _Formatter:  # format asctime with configurable precision
     default_time_format = "%Y-%m-%dT%H:%M:%S.%f"
     precision = 6
 
-    def formatTime(self, record, datefmt=None) -> str:
+    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
         """Return the creation time (asctime) of the LogRecord as formatted text.
 
         Allows for sub-millisecond precision, using datetime instead of time objects.
@@ -143,7 +141,7 @@ class Formatter(_Formatter, logging.Formatter):  # type: ignore[misc]
 class PktLogFilter(logging.Filter):  # record.levelno in (logging.INFO, logging.WARNING)
     """For packet log files, process only wanted packets."""
 
-    def filter(self, record) -> bool:
+    def filter(self, record: logging.LogRecord) -> bool:
         """Return True if the record is to be processed."""
         # if record._frame[4:] or record.comment or record.error_text:
         return record.levelno in (logging.INFO, logging.WARNING)
@@ -152,21 +150,21 @@ class PktLogFilter(logging.Filter):  # record.levelno in (logging.INFO, logging.
 class StdErrFilter(logging.Filter):  # record.levelno >= logging.WARNING
     """For sys.stderr, process only wanted packets."""
 
-    def filter(self, record) -> bool:
-        """Return True if the record is to be processed."""
-        return record.levelno >= logging.WARNING  # WARNING-30, ERROR-40
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Return True if the record is to be processed."""  # WARNING-30, ERROR-40
+        return record.levelno >= logging.WARNING
 
 
 class StdOutFilter(logging.Filter):  # record.levelno < logging.WARNING
     """For sys.stdout, process only wanted packets."""
 
-    def filter(self, record) -> bool:
-        """Return True if the record is to be processed."""
-        return record.levelno < logging.WARNING  # INFO-20, DEBUG-10
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Return True if the record is to be processed."""  # INFO-20, DEBUG-10
+        return record.levelno < logging.WARNING
 
 
 class TimedRotatingFileHandler(_TimedRotatingFileHandler):
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         assert self.when == "MIDNIGHT"
         self.extMatch = re.compile(r"^\d{4}-\d{2}-\d{2}$", re.ASCII)
@@ -176,10 +174,10 @@ class TimedRotatingFileHandler(_TimedRotatingFileHandler):
     #         self.doRollover()
     #     return super().emit(record)
 
-    def getFilesToDelete(self):  # zxdavb: my version
+    def getFilesToDelete(self) -> list[str]:  # zxdavb: my version
         """Determine the files to delete when rolling over.
 
-        Overriden as old log files not being deleted.
+        Overridden as old log files not being deleted.
         """
         # See bpo-44753 (this code is as was before that commit), bpo45628, bpo-46063
         dirName, baseName = os.path.split(self.baseFilename)
@@ -200,7 +198,9 @@ class TimedRotatingFileHandler(_TimedRotatingFileHandler):
         return result
 
 
-def getLogger(name=None, pkt_log=None):  # permits a bespoke Logger class
+def getLogger(  # permits a bespoke Logger class
+    name: str | None = None, pkt_log: bool = False
+) -> logging.Logger:
     """Return a logger with the specified name, creating it if necessary.
 
     Used to set record timestamps to its packet timestamp instead of the current time.
@@ -208,25 +208,34 @@ def getLogger(name=None, pkt_log=None):  # permits a bespoke Logger class
     if name is None or not pkt_log:
         return logging.getLogger(name)
 
-    logging._acquireLock()  # So no-one else uses our Logger class
+    # Acquire lock, so no-one else uses our Logger class
+    try:  # TODO: remove this ASAP
+        logging._acquireLock()  # type: ignore[attr-defined]
+    except AttributeError:  # Python 3.13+
+        logging._lock.acquire()  # type: ignore[attr-defined]
+
     klass = logging.getLoggerClass()
     logging.setLoggerClass(_Logger)
 
     logger = logging.getLogger(name)
 
     logging.setLoggerClass(klass)
-    logging._releaseLock()
+
+    try:  # TODO: remove this ASAP
+        logging._releaseLock()  # type: ignore[attr-defined]
+    except AttributeError:  # Python 3.13+
+        logging._lock.release()  # type: ignore[attr-defined]
 
     return logger
 
 
-def set_logger_timesource(dtm_now: Callable):
+def set_logger_timesource(dtm_now: Callable[..., dt]) -> None:
     """Set a custom record factory, with a bespoke source of timestamps.
 
     Used to have records with the same datetime as the most recent packet log record.
     """
 
-    def record_factory(*args, **kwargs):
+    def record_factory(*args: Any, **kwargs: Any) -> logging.LogRecord:
         record = old_factory(*args, **kwargs)
 
         ct = dtm_now().timestamp()
@@ -240,12 +249,19 @@ def set_logger_timesource(dtm_now: Callable):
     logging.setLogRecordFactory(record_factory)
 
 
-def set_pkt_logging(logger, dt_now=None, cc_console: bool = False, **kwargs) -> None:
+def set_pkt_logging(
+    logger: logging.Logger,
+    cc_console: bool = False,
+    file_name: str | None = None,
+    rotate_backups: int = 0,
+    rotate_bytes: int | None = None,
+) -> None:
     """Create/configure handlers, formatters, etc.
 
     Parameters:
-    - backup_count: keep this many copies, and rotate at midnight unless:
-    - max_bytes:    rotate log files when log > rotate_size
+    - file_name:      base of file to store packet logs in, from root
+    - rotate_backups: keep this many copies, and rotate at midnight unless:
+    - rotate_bytes:   rotate log files when log > rotate_size
     """
 
     logger.propagate = False  # log file is distinct from any app/debug logging
@@ -255,18 +271,15 @@ def set_pkt_logging(logger, dt_now=None, cc_console: bool = False, **kwargs) ->
     for handler in logger.handlers:  # dont use logger.hasHandlers() as not propagating
         logger.removeHandler(handler)
 
-    if file_name := kwargs.get(SZ_FILE_NAME):
-        bkp_count = kwargs.get(SZ_ROTATE_BACKUPS, 0)
-        max_bytes = kwargs.get(SZ_ROTATE_BYTES)
-
-        if max_bytes:
-            bkp_count = bkp_count or 2
+    if file_name:  # note: this opens the packet_log file IO and may block
+        if rotate_bytes:
+            rotate_backups = rotate_backups or 2
             handler = logging.handlers.RotatingFileHandler(
-                file_name, maxBytes=max_bytes, backupCount=bkp_count
+                file_name, maxBytes=rotate_bytes, backupCount=rotate_backups
             )
-        elif bkp_count:
+        elif rotate_backups:
             handler = TimedRotatingFileHandler(
-                file_name, when="MIDNIGHT", backupCount=bkp_count
+                file_name, when="MIDNIGHT", backupCount=rotate_backups
             )
         else:
             handler = logging.FileHandler(file_name)
@@ -285,7 +298,8 @@ def set_pkt_logging(logger, dt_now=None, cc_console: bool = False, **kwargs) ->
         logger.setLevel(logging.CRITICAL)
         return
 
-    if cc_console:
+    if cc_console:  # CC: output to stdout/stderr
+        console_fmt: ColoredFormatter | Formatter
         if _use_color_:
             console_fmt = ColoredFormatter(
                 fmt=f"%(log_color)s{CONSOLE_FMT + COLOR_SUFFIX}",
@@ -310,6 +324,6 @@ def set_pkt_logging(logger, dt_now=None, cc_console: bool = False, **kwargs) ->
     extras = {
         "_frame": "",
         "error_text": "",
-        "comment": f"ramses_rf {VERSION}",
+        "comment": f"ramses_tx {VERSION}",
     }
-    logger.warning("", extra=extras)
+    logger.warning("", extra=extras)  # initial log line