kitty-logger 0.2.0.dev0__tar.gz → 0.2.0.dev1__tar.gz

{kitty_logger-0.2.0.dev0/src/kitty_logger.egg-info → kitty_logger-0.2.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev0
+Version: 0.2.0.dev1
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT
@@ -54,12 +54,18 @@ if __name__ == "__main__":
 
 ## API
 
-- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=True) -> (host, port)`
+- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=False) -> (host, port)`
   启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
   `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
-- `getLogger(name=None) -> logging.Logger`
+  默认**不动**主进程 root logger；想让某个 logger 走 kitty_logger，请显式
+  `kitty_logger.getLogger(...)`。如果希望主进程 root 也自动挂上 SocketHandler，
+  传 `attach_main_logger=True`。
+- `getLogger(name=None, *, propagate=False) -> logging.Logger`
   返回一个挂好 `SocketHandler`、指向日志服务的 logger。
+  默认 **`propagate=False`**：每个 logger 独立挂载，互不干扰；想让子 logger
+  通过祖先链冒泡到这个 logger 时（`getLogger("myapp")` 接住 `myapp.svc.x` 等），
+  传 `propagate=True`。对 root logger 该参数没有意义。
 - `shutdown_logging()` — 显式停止日志服务子进程。
 
 ## 为什么只支持 spawn
@@ -74,11 +80,13 @@ if __name__ == "__main__":
 
 ## 注意事项
 
-- **不要**在 `setup_logging(attach_main_logger=True)` 之前调用
-  `logging.basicConfig()`（或自行给 root logger 挂 `StreamHandler`）——
-  否则主进程会把每条记录输出两次：一次走本地 root handler，一次走日志
-  服务。要么让 kitty_logger 做唯一的配置入口，要么传
-  `attach_main_logger=False` 自行管理主进程的 handler。
+- 默认每个 logger 都是**显式加入、互不传播**的：业务代码里 `kitty_logger.getLogger(__name__)`
+  得到的 logger 自带 `SocketHandler` 且 `propagate=False`，第三方库（urllib3、httpx 等）
+  的日志不会被卷入。如果你更喜欢"包级挂一次、子模块走 stdlib + propagate"的传统模式，
+  调 `kitty_logger.getLogger("myapp", propagate=True)` 即可。
+- 如果传了 `attach_main_logger=True` 让主进程 root 也挂上 SocketHandler，请**不要**
+  在此之前调用 `logging.basicConfig()` 或自行给 root 挂 `StreamHandler`，否则会出现
+  双倍输出。要么让 kitty_logger 做唯一入口，要么保持默认 `False` 自行管理 root。
 - `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
   `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
   `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev1}/README.md

@@ -41,12 +41,18 @@ if __name__ == "__main__":
 
 ## API
 
-- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=True) -> (host, port)`
+- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=False) -> (host, port)`
   启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
   `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
-- `getLogger(name=None) -> logging.Logger`
+  默认**不动**主进程 root logger；想让某个 logger 走 kitty_logger，请显式
+  `kitty_logger.getLogger(...)`。如果希望主进程 root 也自动挂上 SocketHandler，
+  传 `attach_main_logger=True`。
+- `getLogger(name=None, *, propagate=False) -> logging.Logger`
   返回一个挂好 `SocketHandler`、指向日志服务的 logger。
+  默认 **`propagate=False`**：每个 logger 独立挂载，互不干扰；想让子 logger
+  通过祖先链冒泡到这个 logger 时（`getLogger("myapp")` 接住 `myapp.svc.x` 等），
+  传 `propagate=True`。对 root logger 该参数没有意义。
 - `shutdown_logging()` — 显式停止日志服务子进程。
 
 ## 为什么只支持 spawn
@@ -61,11 +67,13 @@ if __name__ == "__main__":
 
 ## 注意事项
 
-- **不要**在 `setup_logging(attach_main_logger=True)` 之前调用
-  `logging.basicConfig()`（或自行给 root logger 挂 `StreamHandler`）——
-  否则主进程会把每条记录输出两次：一次走本地 root handler，一次走日志
-  服务。要么让 kitty_logger 做唯一的配置入口，要么传
-  `attach_main_logger=False` 自行管理主进程的 handler。
+- 默认每个 logger 都是**显式加入、互不传播**的：业务代码里 `kitty_logger.getLogger(__name__)`
+  得到的 logger 自带 `SocketHandler` 且 `propagate=False`，第三方库（urllib3、httpx 等）
+  的日志不会被卷入。如果你更喜欢"包级挂一次、子模块走 stdlib + propagate"的传统模式，
+  调 `kitty_logger.getLogger("myapp", propagate=True)` 即可。
+- 如果传了 `attach_main_logger=True` 让主进程 root 也挂上 SocketHandler，请**不要**
+  在此之前调用 `logging.basicConfig()` 或自行给 root 挂 `StreamHandler`，否则会出现
+  双倍输出。要么让 kitty_logger 做唯一入口，要么保持默认 `False` 自行管理 root。
 - `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
   `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
   `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kitty_logger"
-version = "0.2.0.dev0"
+version = "0.2.0.dev1"
 description = "Cross-process logging via a dedicated log server process and SocketHandler."
 readme = "README.md"
 requires-python = ">=3.12"

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev1}/src/kitty_logger/__init__.py

@@ -28,4 +28,4 @@ from ._client import getLogger
 from ._setup import setup_logging, shutdown_logging
 
 __all__ = ["setup_logging", "shutdown_logging", "getLogger"]
-__version__ = "0.2.0.dev0"
+__version__ = "0.2.0.dev1"

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev1}/src/kitty_logger/_client.py

@@ -51,6 +51,7 @@ def _attach_socket_handler(
     host: str,
     port: int,
     level: int,
+    propagate: bool,
 ) -> None:
     """给 ``logger`` 挂上指向日志服务的 :class:`SocketHandler`。
 
@@ -74,13 +75,14 @@ def _attach_socket_handler(
     if logger.level == logging.NOTSET:
         logger.setLevel(level)
 
-    # 关闭向 root 的传播，避免与已存在的 root handler（比如调用过
-    # ``basicConfig``）造成重复输出。root 自身没有父级，跳过此项。
+    # 默认关闭向上传播：每个 logger 独立挂 SocketHandler，互不干扰，
+    # 也避免与第三方库共用 root handler 时的串扰。root 自身没有父级，
+    # 跳过此项。需要让子 logger 通过祖先链冒泡上来时显式 propagate=True。
     if logger is not logging.getLogger():
-        logger.propagate = False
+        logger.propagate = propagate
 
 
-def getLogger(name: str | None = None) -> logging.Logger:
+def getLogger(name: str | None = None, *, propagate: bool = False) -> logging.Logger:
     """返回一个会把日志通过 :class:`SocketHandler` 发送到日志服务的 logger。
 
     必须在父进程已经调用过 :func:`kitty_logger.setup_logging` 之后才能
@@ -88,6 +90,10 @@ def getLogger(name: str | None = None) -> logging.Logger:
     天然为空，因此不需要处理"继承自父进程的 SocketHandler"问题。
 
     :param name: logger 名；``None`` 表示 root logger。
+    :param propagate: 是否允许该 logger 把记录继续向上传播给父级 logger。
+        默认 ``False``——每个 logger 独立挂 SocketHandler，互不干扰；
+        想让子 logger 通过祖先链冒泡到这个 logger 时设为 ``True``。
+        对 root logger 该参数没有意义（root 没有父级），会被忽略。
     :raises RuntimeError: 当前进程树尚未调用 ``setup_logging``。
     """
     host, port = _read_endpoint()
@@ -97,6 +103,6 @@ def getLogger(name: str | None = None) -> logging.Logger:
     with _lock:
         key = name or ""
         if key not in _configured_loggers:
-            _attach_socket_handler(logger, host, port, level)
+            _attach_socket_handler(logger, host, port, level, propagate)
             _configured_loggers.add(key)
     return logger

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev1}/src/kitty_logger/_setup.py

@@ -128,7 +128,7 @@ def setup_logging(
     console_fmt: str = DEFAULT_CONSOLE_FMT,
     file_fmt: str = DEFAULT_FILE_FMT,
     datefmt: str | None = None,
-    attach_main_logger: bool = True,
+    attach_main_logger: bool = False,
 ) -> tuple[str, int]:
     """在主进程里启动跨进程日志服务，返回服务真实绑定到的 ``(host, port)``。
 
@@ -154,6 +154,8 @@ def setup_logging(
     :param datefmt: 时间戳的 ``strftime`` 格式；``None`` 走默认值。
     :param attach_main_logger: 是否给主进程的 root logger 也挂一个
         :class:`SocketHandler`，让主进程自身的日志走同一个服务。
+        默认 ``False``——主进程 root 保持不动；想让某个 logger 走
+        kitty_logger，请显式调用 :func:`kitty_logger.getLogger`。
     :return: 服务真实绑定到的 ``(host, port)``。
 
     .. note::
@@ -230,7 +232,9 @@ def setup_logging(
         # 让主进程自身的日志也走同一个服务，避免输出渠道分裂。
         from ._client import _attach_socket_handler
 
-        _attach_socket_handler(logging.getLogger(), bound_host, bound_port, level)
+        _attach_socket_handler(
+            logging.getLogger(), bound_host, bound_port, level, propagate=False
+        )
 
     _ = atexit.register(shutdown_logging)
     return bound_host, bound_port

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev1/src/kitty_logger.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev0
+Version: 0.2.0.dev1
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT
@@ -54,12 +54,18 @@ if __name__ == "__main__":
 
 ## API
 
-- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=True) -> (host, port)`
+- `setup_logging(log_file=None, level=logging.INFO, host="127.0.0.1", port=0, stream=True, console_fmt=..., file_fmt=..., datefmt=None, attach_main_logger=False) -> (host, port)`
   启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
   `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
-- `getLogger(name=None) -> logging.Logger`
+  默认**不动**主进程 root logger；想让某个 logger 走 kitty_logger，请显式
+  `kitty_logger.getLogger(...)`。如果希望主进程 root 也自动挂上 SocketHandler，
+  传 `attach_main_logger=True`。
+- `getLogger(name=None, *, propagate=False) -> logging.Logger`
   返回一个挂好 `SocketHandler`、指向日志服务的 logger。
+  默认 **`propagate=False`**：每个 logger 独立挂载，互不干扰；想让子 logger
+  通过祖先链冒泡到这个 logger 时（`getLogger("myapp")` 接住 `myapp.svc.x` 等），
+  传 `propagate=True`。对 root logger 该参数没有意义。
 - `shutdown_logging()` — 显式停止日志服务子进程。
 
 ## 为什么只支持 spawn
@@ -74,11 +80,13 @@ if __name__ == "__main__":
 
 ## 注意事项
 
-- **不要**在 `setup_logging(attach_main_logger=True)` 之前调用
-  `logging.basicConfig()`（或自行给 root logger 挂 `StreamHandler`）——
-  否则主进程会把每条记录输出两次：一次走本地 root handler，一次走日志
-  服务。要么让 kitty_logger 做唯一的配置入口，要么传
-  `attach_main_logger=False` 自行管理主进程的 handler。
+- 默认每个 logger 都是**显式加入、互不传播**的：业务代码里 `kitty_logger.getLogger(__name__)`
+  得到的 logger 自带 `SocketHandler` 且 `propagate=False`，第三方库（urllib3、httpx 等）
+  的日志不会被卷入。如果你更喜欢"包级挂一次、子模块走 stdlib + propagate"的传统模式，
+  调 `kitty_logger.getLogger("myapp", propagate=True)` 即可。
+- 如果传了 `attach_main_logger=True` 让主进程 root 也挂上 SocketHandler，请**不要**
+  在此之前调用 `logging.basicConfig()` 或自行给 root 挂 `StreamHandler`，否则会出现
+  双倍输出。要么让 kitty_logger 做唯一入口，要么保持默认 `False` 自行管理 root。
 - `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
   `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
   `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。

{kitty_logger-0.2.0.dev0 → kitty_logger-0.2.0.dev1}/tests/test_kitty_logger.py

@@ -218,7 +218,9 @@ def test_level_env_accepts_name(tmp_path: Path):
 def test_shutdown_cleans_state(tmp_path: Path):
     """shutdown 后：root 上的 SocketHandler 被卸载、ENV 被清、_configured_loggers 清空。"""
     log_path = tmp_path / "app.log"
-    kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+    kitty_logger.setup_logging(
+        log_file=str(log_path), stream=False, attach_main_logger=True
+    )
     _ = kitty_logger.getLogger("svc.a")
 
     assert os.environ.get("KITTY_LOGGER_HOST")