kitty-logger 0.2.0.dev4__tar.gz → 0.2.0.dev6__tar.gz

kitty_logger-0.2.0.dev6/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Kitty
+
+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.

{kitty_logger-0.2.0.dev4/src/kitty_logger.egg-info → kitty_logger-0.2.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev4
+Version: 0.2.0.dev6
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT

{kitty_logger-0.2.0.dev4 → kitty_logger-0.2.0.dev6}/pyproject.toml

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

{kitty_logger-0.2.0.dev4 → kitty_logger-0.2.0.dev6}/src/kitty_logger/__init__.py

@@ -42,4 +42,4 @@ __all__ = [
     "PRESETS",
     "get_preset",
 ]
-__version__ = "0.2.0.dev4"
+__version__ = "0.2.0.dev6"

{kitty_logger-0.2.0.dev4 → kitty_logger-0.2.0.dev6}/src/kitty_logger/_client.py

@@ -32,16 +32,18 @@ KITTY_NAMESPACE = "kitty"
 _lock = threading.Lock()
 
 
-def _read_endpoint() -> tuple[str, int]:
-    """从环境变量读出 ``(host, port)``；未设置则抛出友好错误。"""
+def _read_endpoint() -> tuple[str, int] | None:
+    """从环境变量读出 ``(host, port)``；未设置则返回 ``None``。
+
+    返回 ``None`` 表示当前进程树尚未调用 :func:`setup_logging`。这是
+    合法状态——用户可能在模块顶层先 ``log = getLogger(__name__)``、
+    后续才调 ``setup_logging``，期间发出的日志按"无 handler"处理，
+    不强制报错。
+    """
     host = os.environ.get(ENV_HOST)
     port = os.environ.get(ENV_PORT)
     if not host or not port:
-        raise RuntimeError(
-            "kitty_logger 尚未在当前进程树中初始化。"
-            + "请先在主进程调用 kitty_logger.setup_logging()，"
-            + "再创建（spawn）子进程或调用 getLogger()。"
-        )
+        return None
     return host, int(port)
 
 
@@ -58,10 +60,17 @@ def _read_level() -> int:
 
 
 def _ensure_kitty_handler() -> logging.Logger:
-    """保证本进程内 ``kitty`` logger 已挂上指向日志服务的 SocketHandler。
+    """尽力保证本进程内 ``kitty`` logger 已挂上指向日志服务的 SocketHandler。
+
+    幂等且容忍未初始化：
 
-    幂等：已挂过则直接返回；``spawn`` 出来的全新解释器里第一次调用时
-    才会真正去读 ENV、建 SocketHandler。
+    - 已经挂过 SocketHandler：直接返回。
+    - ENV 中没有端点（尚未 ``setup_logging``）：返回未挂 handler 的
+      ``kitty`` logger。此时 ``kitty`` 仍保持默认 ``propagate=True``，
+      用户在 ``setup_logging`` 之前发出的日志会冒到 root（沿用标准
+      库行为），等到 ``setup_logging`` 真正调用时再来一次本函数完成
+      挂载与 ``propagate=False`` 的切换。
+    - ENV 存在：装 SocketHandler、按需设置 level、关闭 propagate。
 
     .. note::
        :class:`logging.handlers.SocketHandler` 直接 pickle ``LogRecord``
@@ -76,7 +85,14 @@ def _ensure_kitty_handler() -> logging.Logger:
             if isinstance(h, SocketHandler):
                 return kitty
 
-        host, port = _read_endpoint()
+        endpoint = _read_endpoint()
+        if endpoint is None:
+            # 尚未 setup_logging：保持 ``kitty`` 处于"无 handler、向 root
+            # 冒泡"的标准状态，让用户即使在 setup 之前调 getLogger 也不
+            # 会炸。后续调 setup_logging 时会再次进入本函数完成真正挂载。
+            return kitty
+
+        host, port = endpoint
         level = _read_level()
 
         kitty.addHandler(SocketHandler(host, port))
@@ -94,19 +110,34 @@ def _ensure_kitty_handler() -> logging.Logger:
     return kitty
 
 
-def getLogger(name: str | None = None) -> logging.Logger:
-    """返回挂在 ``kitty`` 命名空间下的 logger，自动连到日志服务。
+def getLogger(
+    name: str | None = None,
+    *,
+    level: int | str | None = None,
+) -> logging.Logger:
+    """返回挂在 ``kitty`` 命名空间下的 logger。
+
+    可在 :func:`kitty_logger.setup_logging` 之前调用——例如在模块顶层
+    写 ``log = getLogger(__name__)``。此时拿到的 logger 还没有连上日志
+    服务，等 ``setup_logging`` 实际执行后会自动生效（通过 ``kitty``
+    祖先 logger 上的 SocketHandler）。
 
-    必须在父进程已经调用过 :func:`kitty_logger.setup_logging` 之后才能
-    使用。本库只支持 ``spawn`` 启动方式；spawn 出来的子进程模块级状态
-    天然为空，第一次调用时会按需完成初始化。
+    本库只支持 ``spawn`` 启动方式；spawn 出来的子进程模块级状态天然为
+    空，第一次调用 ``getLogger`` 时会按需完成 SocketHandler 挂载（依赖
+    父进程通过 ENV 传入的端点）。
 
     :param name: 业务名；``None`` 表示直接返回 ``kitty`` 本身。``"foo"``
         会被转换为 ``logging.getLogger("kitty.foo")``——日志记录里
         ``%(name)s`` 字段会带 ``kitty.`` 前缀，这是有意保留的标记，方便
         和第三方库日志区分。
-    :raises RuntimeError: 当前进程树尚未调用 ``setup_logging``。
+    :param level: 可选；为该 logger 设置 level。等价于 ``getLogger(name)``
+        之后再调 ``.setLevel(level)``。``None`` 表示保持默认 ``NOTSET``，
+        向上沿用 ``kitty`` 根 logger 的级别。支持 ``logging.DEBUG`` 这样
+        的整数，也支持 ``"DEBUG"`` 这样的级别名（大小写不敏感）。
     """
     _ensure_kitty_handler()
     full = KITTY_NAMESPACE if not name else f"{KITTY_NAMESPACE}.{name}"
-    return logging.getLogger(full)
+    logger = logging.getLogger(full)
+    if level is not None:
+        logger.setLevel(level)
+    return logger

{kitty_logger-0.2.0.dev4 → kitty_logger-0.2.0.dev6/src/kitty_logger.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev4
+Version: 0.2.0.dev6
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT

{kitty_logger-0.2.0.dev4 → kitty_logger-0.2.0.dev6}/tests/test_kitty_logger.py

@@ -111,12 +111,38 @@ def test_shutdown_logging_idempotent(tmp_path: Path):
     kitty_logger.shutdown_logging()
 
 
-def test_get_logger_without_setup_raises():
+def test_get_logger_before_setup_works(tmp_path: Path):
+    """允许在 ``setup_logging`` 之前 ``getLogger``——典型用法是模块顶层
+    ``log = getLogger(__name__)``。setup 之后日志应能正常落到服务端。"""
     # 必须没有环境变量。
     for k in ("KITTY_LOGGER_HOST", "KITTY_LOGGER_PORT"):
         os.environ.pop(k, None)
-    with pytest.raises(RuntimeError, match="setup_logging"):
-        kitty_logger.getLogger("x")
+
+    # 还没 setup 就 getLogger：不应抛错，拿到的 logger 暂无 SocketHandler。
+    log = kitty_logger.getLogger("early")
+    assert not any(
+        isinstance(h, logging.handlers.SocketHandler)
+        for h in logging.getLogger("kitty").handlers
+    )
+
+    # setup 之后再用同一个 logger 写日志：应当落到文件。
+    log_path = tmp_path / "app.log"
+    kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+    log.info("late-binding-ok")
+    _wait_for_lines(log_path, lambda t: "late-binding-ok" in t)
+
+
+def test_get_logger_level_param():
+    """``level=`` 参数等价于 ``.setLevel(level)``，支持整数与级别名。"""
+    log_int = kitty_logger.getLogger("lvl.int", level=logging.DEBUG)
+    assert log_int.level == logging.DEBUG
+
+    log_str = kitty_logger.getLogger("lvl.str", level="WARNING")
+    assert log_str.level == logging.WARNING
+
+    # 不传 level：保持默认 NOTSET，沿用祖先级别。
+    log_default = kitty_logger.getLogger("lvl.default")
+    assert log_default.level == logging.NOTSET
 
 
 def test_non_loopback_raises(tmp_path: Path):

kitty_logger-0.2.0.dev4/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Kitty
-
-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.