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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev1
+Version: 0.2.0.dev3
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT
@@ -54,18 +54,22 @@ 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=False) -> (host, port)`
-  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
-  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(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) -> (host, port)`
+  通过 `subprocess.Popen` 启动一个独立的日志服务子进程（不依赖
+  `multiprocessing`，因此**不会回头执行用户主脚本的任何顶层代码**）。
+  幂等。已通过 `atexit` 注册清理。`port=0` 让操作系统挑选空闲端口；返回
+  真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
-  默认**不动**主进程 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 该参数没有意义。
+  同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
+  `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
+  在用户用 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，
+  仅返回从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  `if __name__ == "__main__":` 包裹。
+- `getLogger(name=None) -> logging.Logger`
+  返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是
+  `logging.getLogger("kitty.foo")`，`getLogger()` 拿到的是 `kitty` 本身。
+  整个进程内只有 `kitty` 持有 `SocketHandler`，子 logger 通过标准库的祖先链
+  冒泡上来，无需重复挂载。
 - `shutdown_logging()` — 显式停止日志服务子进程。
 
 ## 为什么只支持 spawn
@@ -80,13 +84,12 @@ if __name__ == "__main__":
 
 ## 注意事项
 
-- 默认每个 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。
+- **所有 logger 名都带 `kitty.` 前缀**，这是有意保留的标记：日志记录里
+  `%(name)s` 字段一眼可以和第三方库（urllib3、httpx 等）的输出区分。
+  `getLogger(__name__)` 在模块 `myapp.svc` 下实际得到的是 `kitty.myapp.svc`。
+- `kitty` 子树**不向 root 冒泡**：第三方库挂在 root 上的 handler 不会收到
+  kitty_logger 的日志，反之 root 上输出的日志也不会被 kitty_logger 转发。
+  两条输出渠道互不干扰。
 - `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
   `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
   `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。

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

@@ -41,18 +41,22 @@ 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=False) -> (host, port)`
-  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
-  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(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) -> (host, port)`
+  通过 `subprocess.Popen` 启动一个独立的日志服务子进程（不依赖
+  `multiprocessing`，因此**不会回头执行用户主脚本的任何顶层代码**）。
+  幂等。已通过 `atexit` 注册清理。`port=0` 让操作系统挑选空闲端口；返回
+  真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
-  默认**不动**主进程 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 该参数没有意义。
+  同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
+  `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
+  在用户用 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，
+  仅返回从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  `if __name__ == "__main__":` 包裹。
+- `getLogger(name=None) -> logging.Logger`
+  返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是
+  `logging.getLogger("kitty.foo")`，`getLogger()` 拿到的是 `kitty` 本身。
+  整个进程内只有 `kitty` 持有 `SocketHandler`，子 logger 通过标准库的祖先链
+  冒泡上来，无需重复挂载。
 - `shutdown_logging()` — 显式停止日志服务子进程。
 
 ## 为什么只支持 spawn
@@ -67,13 +71,12 @@ if __name__ == "__main__":
 
 ## 注意事项
 
-- 默认每个 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。
+- **所有 logger 名都带 `kitty.` 前缀**，这是有意保留的标记：日志记录里
+  `%(name)s` 字段一眼可以和第三方库（urllib3、httpx 等）的输出区分。
+  `getLogger(__name__)` 在模块 `myapp.svc` 下实际得到的是 `kitty.myapp.svc`。
+- `kitty` 子树**不向 root 冒泡**：第三方库挂在 root 上的 handler 不会收到
+  kitty_logger 的日志，反之 root 上输出的日志也不会被 kitty_logger 转发。
+  两条输出渠道互不干扰。
 - `shutdown_logging()` 会卸载本进程内 kitty_logger 自己挂的
   `SocketHandler`，并清理 `KITTY_LOGGER_*` 环境变量，确保进程状态与
   `setup_logging` 对称。如果你额外挂了别的 handler，仍由你自己负责清理。

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

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

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

@@ -6,6 +6,11 @@
 日志收敛到主进程指定的文件 / ``stderr`` 中，不会因多进程并发写文件而
 错行或丢失。
 
+命名空间：所有由本库返回的 logger 都挂在 ``kitty`` 这棵子树下。
+``getLogger("foo")`` 实际拿到的是 ``logging.getLogger("kitty.foo")``，
+日志记录里 ``%(name)s`` 会带 ``kitty.`` 前缀，便于和第三方库的日志区分。
+``kitty`` 子树独立运行，不会向 root 冒泡，也不会被 root 上的 handler 干扰。
+
 典型用法::
 
     # main.py
@@ -28,4 +33,4 @@ from ._client import getLogger
 from ._setup import setup_logging, shutdown_logging
 
 __all__ = ["setup_logging", "shutdown_logging", "getLogger"]
-__version__ = "0.2.0.dev1"
+__version__ = "0.2.0.dev3"

kitty_logger-0.2.0.dev3/src/kitty_logger/_client.py

@@ -0,0 +1,112 @@
+"""子进程侧 API：:func:`getLogger`。
+
+子进程通过环境变量
+``KITTY_LOGGER_HOST`` / ``KITTY_LOGGER_PORT`` / ``KITTY_LOGGER_LEVEL``
+找到日志服务地址；这些环境变量是父进程在 :func:`setup_logging` 时写入的，
+``spawn`` 出来的后代进程会自动继承。
+
+命名空间约定
+------------
+
+所有由本库返回的 logger 都挂在 ``kitty`` 这棵子树下：
+
+- ``getLogger()`` → ``logging.getLogger("kitty")``
+- ``getLogger("foo.bar")`` → ``logging.getLogger("kitty.foo.bar")``
+
+整个进程内只有 ``kitty`` 这一个 logger 持有指向日志服务的
+:class:`SocketHandler`，子 logger 通过标准库的祖先链冒泡上来。
+``kitty`` 自身的 ``propagate`` 被关闭，与 root 上的第三方库日志互不干扰。
+"""
+
+import logging
+import logging.handlers
+import os
+import threading
+
+from ._env import ENV_HOST, ENV_LEVEL, ENV_PORT
+
+# 本库使用的 logger 命名空间根。所有用户拿到的 logger 都在这棵子树下。
+KITTY_NAMESPACE = "kitty"
+
+# 保护 ``kitty`` logger 上的 handler 初始化。
+_lock = threading.Lock()
+
+
+def _read_endpoint() -> tuple[str, int]:
+    """从环境变量读出 ``(host, port)``；未设置则抛出友好错误。"""
+    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 host, int(port)
+
+
+def _read_level() -> int:
+    """从环境变量解析默认 level。优先按整数解析，失败则按级别名解析。"""
+    raw = os.environ.get(ENV_LEVEL)
+    if raw is None:
+        return logging.INFO
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    return logging.getLevelNamesMapping().get(raw.upper(), logging.INFO)
+
+
+def _ensure_kitty_handler() -> logging.Logger:
+    """保证本进程内 ``kitty`` logger 已挂上指向日志服务的 SocketHandler。
+
+    幂等：已挂过则直接返回；``spawn`` 出来的全新解释器里第一次调用时
+    才会真正去读 ENV、建 SocketHandler。
+
+    .. note::
+       :class:`logging.handlers.SocketHandler` 直接 pickle ``LogRecord``
+       发送，由接收端格式化；在这里给 handler 设置 ``formatter`` 没有
+       任何效果，会被服务端忽略。
+    """
+    SocketHandler = logging.handlers.SocketHandler
+    kitty = logging.getLogger(KITTY_NAMESPACE)
+
+    with _lock:
+        for h in kitty.handlers:
+            if isinstance(h, SocketHandler):
+                return kitty
+
+        host, port = _read_endpoint()
+        level = _read_level()
+
+        kitty.addHandler(SocketHandler(host, port))
+
+        # 仅在仍是默认 ``NOTSET`` 时才设置 level，避免悄悄覆盖
+        # 用户已经显式设置过的级别。
+        if kitty.level == logging.NOTSET:
+            kitty.setLevel(level)
+
+        # ``kitty`` 子树自成一系，不向 root 冒泡：这样和第三方库挂在 root
+        # 上的 handler 互不串扰；用户控制 root 的输出渠道时也不会无意中
+        # 把 kitty_logger 的日志带过去（反之亦然）。
+        kitty.propagate = False
+
+    return kitty
+
+
+def getLogger(name: str | None = None) -> logging.Logger:
+    """返回挂在 ``kitty`` 命名空间下的 logger，自动连到日志服务。
+
+    必须在父进程已经调用过 :func:`kitty_logger.setup_logging` 之后才能
+    使用。本库只支持 ``spawn`` 启动方式；spawn 出来的子进程模块级状态
+    天然为空，第一次调用时会按需完成初始化。
+
+    :param name: 业务名；``None`` 表示直接返回 ``kitty`` 本身。``"foo"``
+        会被转换为 ``logging.getLogger("kitty.foo")``——日志记录里
+        ``%(name)s`` 字段会带 ``kitty.`` 前缀，这是有意保留的标记，方便
+        和第三方库日志区分。
+    :raises RuntimeError: 当前进程树尚未调用 ``setup_logging``。
+    """
+    _ensure_kitty_handler()
+    full = KITTY_NAMESPACE if not name else f"{KITTY_NAMESPACE}.{name}"
+    return logging.getLogger(full)

{kitty_logger-0.2.0.dev1 → kitty_logger-0.2.0.dev3}/src/kitty_logger/_server.py

@@ -1,13 +1,12 @@
-"""日志服务子进程实现。
+"""日志服务子进程的核心组件（与启动方式无关）。
 
-工作模型：
+服务进程通过 ``python -m kitty_logger._server_main`` 由 :func:`kitty_logger.setup_logging`
+间接拉起，本模块只提供与"具体如何起进程"无关的纯逻辑：
 
-1. 父进程在 :func:`kitty_logger.setup_logging` 中先 ``bind`` 一个 TCP
-   监听 socket，再连同其他参数一起传给一个 ``spawn`` 启动的子进程。
-2. 子进程在 :func:`run_server` 里基于这个 socket 跑 ``ThreadingTCPServer``，
-   反序列化客户端通过 :class:`logging.handlers.SocketHandler` 发来的
-   ``LogRecord`` 字节流，再用本进程里配置的 handler（FileHandler /
-   StreamHandler）落地。
+- :func:`_bind_loopback`：在 loopback 地址上绑定一个 ``AF_INET`` 监听 socket。
+- :class:`_LogRecordSocketReceiver`：基于 :class:`socketserver.ThreadingTCPServer`
+  的接收器，复用外部已 ``bind`` 好的 socket。
+- :func:`_build_handlers`：根据用户参数组装落地用的 handler 列表。
 """
 
 import logging
@@ -16,19 +15,39 @@ import socket
 import socketserver
 import struct
 import sys
-import threading
 from logging.handlers import TimedRotatingFileHandler
-from multiprocessing.synchronize import Event as MpEvent
 from typing import cast, final, override
 
 from ._formatters import ColorFormatter, FileFormatter
 
+# 这三个符号由同包内的 ``_server_main`` 模块导入复用；以下划线开头是因为它们
+# 不属于库的公共 API（仅 kitty_logger 内部使用）。pyright 对下划线名默认按
+# "模块内私有"处理，看不到跨模块引用，因此显式通过 ``__all__`` 声明为本模块
+# 的对外导出，避免 reportUnusedFunction / reportUnusedClass 误报。
+__all__ = ["_bind_loopback", "_LogRecordSocketReceiver", "_build_handlers"]
+
 # 单条 LogRecord 序列化后字节数上限。任何正常 LogRecord 都远小于此值；
 # 超过即视为协议错位或异常流量，直接断开连接，避免一次性分配巨大缓冲区
 # 触发 OOM。
 _MAX_RECORD_BYTES = 16 * 1024 * 1024
 
 
+def _bind_loopback(
+    host: str, port: int, backlog: int = 128
+) -> tuple[socket.socket, str, int]:
+    """创建并绑定一个 ``AF_INET`` TCP 监听 socket，返回 ``(sock, bound_host, bound_port)``。
+
+    把"AF_INET 的 ``getsockname`` 一定返回 ``tuple[str, int]``"这个静态
+    事实集中收敛在这里，调用方不必再写 ``cast``。
+    """
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind((host, port))
+    sock.listen(backlog)
+    bound_host, bound_port = cast(tuple[str, int], sock.getsockname())
+    return sock, bound_host, bound_port
+
+
 def _recv_exact(conn: socket.socket, n: int) -> bytes | None:
     """从 ``conn`` 上读满 ``n`` 字节；对端已关闭则返回 ``None``。
 
@@ -84,7 +103,7 @@ class _LogRecordStreamHandler(socketserver.StreamRequestHandler):
 class _LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
     """基于 :class:`socketserver.ThreadingTCPServer` 的接收器。
 
-    复用父进程已 ``bind`` 好的监听 socket，本类不再自己 ``bind``/``listen``。
+    复用外部已 ``bind`` 好的监听 socket，本类不再自己 ``bind``/``listen``。
     """
 
     allow_reuse_address: bool = True
@@ -95,7 +114,7 @@ class _LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
         addr = cast(tuple[str, int], listening_sock.getsockname()[:2])
         # 走父类正常流程以建立 BaseServer 内部状态（shutdown 标志等），
         # 但通过 ``bind_and_activate=False`` 跳过它自己的 bind/listen——
-        # 这个 socket 已经由父进程绑好。
+        # 这个 socket 已经由调用方绑好。
         super().__init__(addr, _LogRecordStreamHandler, bind_and_activate=False)
         # 父类构造时仍会 ``self.socket = socket.socket(...)`` 占坑，
         # 这里替换成真正复用的 socket，并把临时占位关闭掉。
@@ -132,75 +151,3 @@ def _build_handlers(
         sh.setFormatter(ColorFormatter(fmt=console_fmt, datefmt=datefmt))
         handlers.append(sh)
     return handlers
-
-
-def run_server(
-    listening_sock: socket.socket,
-    shutdown_event: MpEvent,
-    parent_alive_recv: socket.socket,
-    level: int,
-    log_file: str | None,
-    stream: bool,
-    console_fmt: str,
-    file_fmt: str,
-    datefmt: str | None,
-) -> None:
-    """日志服务子进程入口函数。
-
-    通过 :mod:`multiprocessing` 在 ``spawn`` 出来的全新解释器里运行；
-    所有依赖参数显式从 ``kwargs`` 进入，不依赖父进程的全局状态。
-
-    :param listening_sock: 已经由父进程 ``bind`` + ``listen`` 好的 socket。
-    :param shutdown_event: 父进程通知子进程正常退出用的事件。
-    :param parent_alive_recv: ``socketpair`` 的接收端，用来侦测父进程死亡。
-    :param level: 服务端 root logger 级别。
-    :param log_file: 日志文件路径；``None`` 表示不落盘。
-    :param stream: 是否同时输出到 ``stderr``。
-    :param console_fmt: 控制台 handler 的 format 字符串。
-    :param file_fmt: 文件 handler 的 format 字符串。
-    :param datefmt: 时间戳的 ``strftime`` 格式；``None`` 走默认值。
-    """
-    # 子进程是 ``spawn`` 出来的全新解释器，root logger 默认无 handler；
-    # 但仍保险地清掉一遍以便重复初始化场景下的幂等性。
-    root = logging.getLogger()
-    for h in list(root.handlers):
-        root.removeHandler(h)
-    for h in _build_handlers(log_file, stream, console_fmt, file_fmt, datefmt):
-        root.addHandler(h)
-    root.setLevel(level)
-
-    server = _LogRecordSocketReceiver(listening_sock)
-
-    def _wait_shutdown() -> None:
-        _ = shutdown_event.wait()
-        server.shutdown()
-
-    def _watch_parent_alive() -> None:
-        # 父进程持有 socketpair 的发送端；任意原因（正常退出 / SIGKILL /
-        # 段错误）使父进程消失，内核都会关闭它的 fd，本端 ``recv`` 会立刻
-        # 返回空字节（EOF）。借此触发自我退出，避免变成孤儿进程。
-        try:
-            while True:
-                data = parent_alive_recv.recv(64)
-                if not data:
-                    break
-        except OSError:
-            pass
-        finally:
-            try:
-                parent_alive_recv.close()
-            except OSError:
-                pass
-        shutdown_event.set()
-
-    threading.Thread(target=_wait_shutdown, daemon=True).start()
-    threading.Thread(target=_watch_parent_alive, daemon=True).start()
-
-    try:
-        server.serve_forever()
-    finally:
-        try:
-            server.server_close()
-        except OSError:
-            pass
-        logging.shutdown()

kitty_logger-0.2.0.dev3/src/kitty_logger/_server_main.py

@@ -0,0 +1,129 @@
+"""kitty_logger 服务子进程入口。
+
+通过 ``python -m kitty_logger._server_main`` 启动，由
+:func:`kitty_logger.setup_logging` 内部用 :class:`subprocess.Popen` 拉起。
+本模块不是给最终用户的接口。
+
+握手 / 生命周期协议
+--------------------
+
+整套机制只用三条标准管道，不需要 ``pass_fds``，所以天然跨平台：
+
+* ``stdin``  — 父→子，**parent-alive**：父进程保持 write 端打开但不写。
+  父进程任何原因退出（``exit`` / ``kill -9`` / 段错误），内核会关掉它持有
+  的写端 fd，子进程在本端 ``read()`` 立刻返回 ``b""`` → 触发优雅退出。
+* ``stdout`` — 子→父，**启动握手**：子进程 ``bind+listen`` 成功后写出
+  ``"PORT <port>\\n"`` 然后 ``close``，握手即结束；之后不再使用 stdout
+  以避免后续误用 ``print`` 污染父进程的读端。
+* ``stderr`` — 子→父，**日志落地**：直接继承父进程的 stderr/tty。
+  ``--stream`` 控制是否给 root logger 挂上 :class:`logging.StreamHandler`。
+
+命令行参数对应 :func:`kitty_logger.setup_logging` 的同名参数。
+"""
+
+import argparse
+import logging
+import sys
+import threading
+
+from ._server import _LogRecordSocketReceiver, _bind_loopback, _build_handlers
+
+
+def _parse_args() -> argparse.Namespace:
+    ap = argparse.ArgumentParser(prog="kitty_logger._server_main", add_help=False)
+    ap.add_argument("--host", required=True)
+    ap.add_argument("--port", type=int, required=True)
+    ap.add_argument("--level", type=int, required=True)
+    ap.add_argument("--log-file", default=None)
+    ap.add_argument("--stream", action="store_true")
+    ap.add_argument("--console-fmt", required=True)
+    ap.add_argument("--file-fmt", required=True)
+    ap.add_argument("--datefmt", default=None)
+    return ap.parse_args()
+
+
+def _emit_handshake(port: int) -> None:
+    """把 ``"PORT <port>\\n"`` 写到 stdout 并主动 close。
+
+    主动 close 等于显式宣告"握手结束"——之后任何对 ``sys.stdout`` 的
+    误用都不会再污染父进程的读端，父进程的 ``readline()`` 也只会看到
+    我们刚写的这一行。
+    """
+    sys.stdout.write(f"PORT {port}\n")
+    sys.stdout.flush()
+    try:
+        sys.stdout.close()
+    except OSError:
+        pass
+
+
+def _emit_handshake_error(msg: str) -> None:
+    """启动失败时通过 stdout 报错，让父端 ``readline()`` 看到非 ``PORT`` 行。"""
+    try:
+        sys.stdout.write(f"ERROR {msg}\n")
+        sys.stdout.flush()
+        sys.stdout.close()
+    except OSError:
+        pass
+
+
+def main() -> None:
+    args = _parse_args()
+
+    # 先 bind+listen，这一步任何失败都通过 stdout 上报给父进程，让 setup_logging
+    # 能在主进程线程中以 ``RuntimeError`` 形式抛出，而不是父子双方各自卡住。
+    try:
+        sock, _bound_host, bound_port = _bind_loopback(args.host, args.port)
+    except OSError as e:
+        _emit_handshake_error(f"bind failed: {e}")
+        sys.exit(2)
+
+    _emit_handshake(bound_port)
+
+    # spawn 出来的全新解释器，root logger 默认无 handler；保险起见仍清一遍
+    # 以便重复初始化场景下保持幂等。
+    root = logging.getLogger()
+    for h in list(root.handlers):
+        root.removeHandler(h)
+    for h in _build_handlers(
+        args.log_file, args.stream, args.console_fmt, args.file_fmt, args.datefmt
+    ):
+        root.addHandler(h)
+    root.setLevel(args.level)
+
+    server = _LogRecordSocketReceiver(sock)
+
+    def _watch_parent_alive() -> None:
+        """父进程持有 stdin 的写端；任何原因（正常退出 / SIGKILL / 段错误）
+        让父进程消失，内核都会关掉它的 fd，本端 ``read()`` 会立刻返回
+        ``b""``（EOF）。借此触发自我退出，避免变成孤儿进程。
+
+        正常生命周期下父进程也通过 ``proc.stdin.close()`` 主动触发同一
+        条 EOF 路径，把"父退出 / 父主动 shutdown" 收敛为同一种处理。
+        """
+        try:
+            while True:
+                data = sys.stdin.buffer.read(64)
+                if not data:
+                    break
+        except (OSError, ValueError):
+            pass
+        finally:
+            server.shutdown()
+
+    threading.Thread(
+        target=_watch_parent_alive, name="kitty-logger-parent-watch", daemon=True
+    ).start()
+
+    try:
+        server.serve_forever()
+    finally:
+        try:
+            server.server_close()
+        except OSError:
+            pass
+        logging.shutdown()
+
+
+if __name__ == "__main__":
+    main()