release 1.3.4

Author: ClericPy

CHANGELOG.md

@@ -4,7 +4,12 @@
 1. fix `morebuiltins.utils.gen_id` wrong length issue.
 2. fix `morebuiltins.funcs.LineProfiler` to handle nested function calls correctly.
 3. update `morebuiltins.cmd.log_server` to support close idle file handlers after 300 seconds.
-4. add `get_logger` to `morebuiltins.cmd.log_server` to get a logger with `SocketHandler` to send logs to `LogServer`.
+4. add `get_logger` to `morebuiltins.cmd.log_server` to get a **singleton** logger with `SocketHandler` to send logs to `LogServer`.
+5. [**Compatibility Warnings**] Refactor of `morebuiltins.cmd.log_server`:
+   1. use `LogSetting` struct instead of untyped dict, client send dict with `LogSetting` structure.
+   2. add `level_specs` filter to specify log levels of files, like `[logging.ERROR, logging.CRITICAL]`.
+   3. add cache file for log settings, readable by both server and human.
+   4. THIS IS A BREAKING CHANGE, old clients may not work with new server.
 
 ### 1.3.3 (2025-09-01)
 1. add `morebuiltins.logs.LogHelper.handle_crash` to log uncaught exceptions.

README.md

@@ -17,9 +17,12 @@ This project enhances Python’s built-ins with extra functionality, prioritizin
 ibution.
 
 ## Compatibility Break Warnings
-1. **1.3.2 (2025-08-02)**
+
+1. **1.3.4 (2025-09-17)**
+   1. Refactor of `morebuiltins.cmd.log_server`
+2. **1.3.2 (2025-08-02)**
    1. move `async_logger`, `AsyncQueueListener`, `LogHelper`, `RotatingFileWriter`, and `SizedTimedRotatingFileHandler` from `morebuiltins.funcs` to `morebuiltins.logs`.
-2. **1.3.0 (2025-03-08)**
+3. **1.3.0 (2025-03-08)**
    1. rename `morebuiltins.functools` to `morebuiltins.funcs` to avoid conflict with `functools` in python standard library.
 
 ## Install
@@ -221,7 +224,7 @@ print(morebuiltins.__file__)
 
 ## 9. morebuiltins.cmd.log_server
 
-9.1 `LogServer` - Log Server for SocketHandler, create a socket server with asyncio.start_server. Update settings of rotation/formatter with extra: {"max_size": 1024**2, "formatter": logging.Formatter(fmt="%(asctime)s - %(filename)s - %(message)s")}
+9.1 `LogServer` - Log server for SocketHandler, create a socket server with asyncio.start_server. Custom formatter or rotation strategy with extra in log record.
 
 
 ## 10. morebuiltins.cmd.proxy_checker

doc.md

@@ -2260,23 +2260,29 @@ Demo::
 
 
 
-9.1 `LogServer` - Log Server for SocketHandler, create a socket server with asyncio.start_server. Update settings of rotation/formatter with extra: {"max_size": 1024**2, "formatter": logging.Formatter(fmt="%(asctime)s - %(filename)s - %(message)s")}
+9.1 `LogServer` - Log server for SocketHandler, create a socket server with asyncio.start_server. Custom formatter or rotation strategy with extra in log record.
 
 
 ```python
 
+[WARNING]: Ensure your log msg is "" if you only want to update settings, or the msg will be skipped.
+
+logger.info("", extra={"log_setting": {"formatter": formatter, "max_size": 1024**2, "level_specs": [logging.ERROR]}})
+
+
 ### Server demo1:
     start log server in terminal, only collect logs and print to console
     > python -m morebuiltins.cmd.log_server
 
 ### Server demo2:
-    custom options to log to "logs" directory, default rotates at 10MB with 5 backups
-    > python -m morebuiltins.cmd.log_server --log-dir=./logs --host 127.0.0.1 --port 8901
+    custom options to log to "logs" directory, default rotates at 10MB with 5 backups, no log_stream, enable compress
+    > python -m morebuiltins.cmd.log_server --log-dir=./logs --host 127.0.0.1 --port 8901 --log-stream=None --compress
 
 ### Server demo3:
     python code
 
 ```python
+# Server side
 import asyncio
 
 from morebuiltins.cmd.log_server import LogServer
@@ -2293,6 +2299,7 @@ asyncio.run(main())
 ### Client demo1:
 
 ```python
+# Client side(no dependency on morebuiltins)
 import logging
 import logging.handlers
 
@@ -2301,16 +2308,21 @@ logger.setLevel(logging.DEBUG)
 h = logging.handlers.SocketHandler("127.0.0.1", 8901)
 h.setLevel(logging.DEBUG)
 logger.addHandler(h)
-for _ in range(5):
-    logger.info(
-        "hello world!",
-        extra={
+logger.info(
+    "",
+    extra={
+        "log_setting": {
             "max_size": 1024**2,
             "formatter": logging.Formatter(
                 fmt="%(asctime)s - %(filename)s - %(message)s"
             ),
-        },
-    )
+            "level_specs": [logging.ERROR],
+        }
+    },
+)
+for _ in range(5):
+    logger.info("hello world!")
+
 # [client] 2024-08-10 19:30:07,113 - temp3.py - hello world!
 # [client] 2024-08-10 19:30:07,113 - temp3.py - hello world!
 # [client] 2024-08-10 19:30:07,113 - temp3.py - hello world!

morebuiltins/cmd/log_server.py

@@ -153,20 +153,26 @@ def __str__(self):
 
 
 class LogServer(SocketServer):
-    """Log Server for SocketHandler, create a socket server with asyncio.start_server. Update settings of rotation/formatter with extra: {"max_size": 1024**2, "formatter": logging.Formatter(fmt="%(asctime)s - %(filename)s - %(message)s")}
+    """Log server for SocketHandler, create a socket server with asyncio.start_server. Custom formatter or rotation strategy with extra in log record.
+
+    [WARNING]: Ensure your log msg is "" if you only want to update settings, or the msg will be skipped.
+
+    logger.info("", extra={"log_setting": {"formatter": formatter, "max_size": 1024**2, "level_specs": [logging.ERROR]}})
+
 
     ### Server demo1:
         start log server in terminal, only collect logs and print to console
         > python -m morebuiltins.cmd.log_server
 
     ### Server demo2:
-        custom options to log to "logs" directory, default rotates at 10MB with 5 backups
-        > python -m morebuiltins.cmd.log_server --log-dir=./logs --host 127.0.0.1 --port 8901
+        custom options to log to "logs" directory, default rotates at 10MB with 5 backups, no log_stream, enable compress
+        > python -m morebuiltins.cmd.log_server --log-dir=./logs --host 127.0.0.1 --port 8901 --log-stream=None --compress
 
     ### Server demo3:
         python code
 
     ```python
+    # Server side
     import asyncio
 
     from morebuiltins.cmd.log_server import LogServer
@@ -183,6 +189,7 @@ async def main():
     ### Client demo1:
 
     ```python
+    # Client side(no dependency on morebuiltins)
     import logging
     import logging.handlers
 
@@ -191,16 +198,21 @@ async def main():
     h = logging.handlers.SocketHandler("127.0.0.1", 8901)
     h.setLevel(logging.DEBUG)
     logger.addHandler(h)
-    for _ in range(5):
-        logger.info(
-            "hello world!",
-            extra={
+    logger.info(
+        "",
+        extra={
+            "log_setting": {
                 "max_size": 1024**2,
                 "formatter": logging.Formatter(
                     fmt="%(asctime)s - %(filename)s - %(message)s"
                 ),
-            },
-        )
+                "level_specs": [logging.ERROR],
+            }
+        },
+    )
+    for _ in range(5):
+        logger.info("hello world!")
+
     # [client] 2024-08-10 19:30:07,113 - temp3.py - hello world!
     # [client] 2024-08-10 19:30:07,113 - temp3.py - hello world!
     # [client] 2024-08-10 19:30:07,113 - temp3.py - hello world!
@@ -308,10 +320,13 @@ def _init_settings(
         for sig in self.handle_signals:
             signal.signal(sig, self.handle_signal)
         self._log_settings = self.load_settings()
+        if self.name in self._log_settings:
+            self._log_settings[self.name] = self._server_log_setting
+        self.send_log("", init_setting=True)
 
     def load_settings(self):
         result = typing.cast(typing.Dict[str, LogSetting], {})
-        if not self.setting_path:
+        if not (self.setting_path and self.setting_path.is_file()):
             return result
         try:
             with self.setting_path.open("r", encoding="utf-8") as f:
@@ -358,7 +373,6 @@ async def end_callback(self):
     def start_callback(self):
         self.send_log(
             f"started log server on {self.host}:{self.port}, handle_signals={self.handle_signals}, max_queue_size={self.max_queue_size}, max_queue_buffer={self.max_queue_buffer}, log_stream={getattr(self.log_stream, 'name', None)}, compress={self.compress}, log_dir={self.log_dir}, setting={self._server_log_setting}",
-            init_setting=True,
         )
 
     def send_log(
@@ -660,7 +674,7 @@ def close_opened_files(self):
             _, fw = self._opened_files.popitem()
             try:
                 fw.close()
-            except Exception as e:
+            except Exception:
                 pass
 
     async def run_wrapper(self):
@@ -723,10 +737,9 @@ def get_logger(
     log_level: int = logging.DEBUG,
     socket_handler_level: int = logging.DEBUG,
     shorten_level: bool = True,
-    # sys.stderr, sys.stdout, None
-    streaming: typing.Optional[typing.TextIO] = None,
+    streaming: typing.Optional[typing.TextIO] = None,  # sys.stderr, sys.stdout, None
     streaming_level: int = logging.DEBUG,
-    # custom settings
+    # custom settings for log files
     formatter: typing.Optional[logging.Formatter] = LogHelper.DEFAULT_FORMATTER,
     max_size: int = DefaultLogSetting.max_size,
     max_backups: int = DefaultLogSetting.max_backups,
@@ -736,20 +749,25 @@ def get_logger(
     For easy use, you can use original logging.handlers.SocketHandler, but you need to manage the handler yourself.
 
     Demo::
-        # python -m morebuiltins.cmd.log_server --host localhost --port 8901
+
+        # python -m morebuiltins.cmd.log_server --host localhost --port 8901 --log-dir logs
         import logging
         import logging.handlers
         logger = logging.getLogger("client")
         logger.setLevel(logging.DEBUG)
         h = logging.handlers.SocketHandler("localhost", 8901)
         h.setLevel(logging.DEBUG)
         logger.addHandler(h)
-        # add custom settings
+        # Add custom settings
+        # Add error log to a specific log file; use a custom formatter and max_size; set msg to ""
         formatter = logging.Formatter(fmt="%(asctime)s - %(filename)s - %(message)s")
-        # add error log to specific log file
-        logger.info("", extra={"max_size": 1024**2, "formatter": formatter, "level_specs": [logging.ERROR]})
+        logger.info("", extra={"log_setting": {"formatter": formatter, "max_size": 1024**2, "level_specs": [logging.ERROR]}})
         for _ in range(5):
             logger.info("hello world!")
+        # Send some error logs
+        logger.error("this is an error!")
+        # The remote log server will create a "client_error.log" file in log_dir if settings are applied
+
     """
     if shorten_level:
         LogHelper.shorten_level()