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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kitty_logger
-Version: 0.2.0.dev2
+Version: 0.2.0.dev4
 Summary: Cross-process logging via a dedicated log server process and SocketHandler.
 Author: Kitty
 License: MIT
@@ -55,13 +55,15 @@ 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) -> (host, port)`
-  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
-  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
+  通过 `subprocess.Popen` 启动一个独立的日志服务子进程（不依赖
+  `multiprocessing`，因此**不会回头执行用户主脚本的任何顶层代码**）。
+  幂等。已通过 `atexit` 注册清理。`port=0` 让操作系统挑选空闲端口；返回
+  真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
   同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
   `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
-  在 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，仅返回
-  从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  在用户用 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，
+  仅返回从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
   `if __name__ == "__main__":` 包裹。
 - `getLogger(name=None) -> logging.Logger`
   返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是

{kitty_logger-0.2.0.dev2 → kitty_logger-0.2.0.dev4}/README.md

@@ -42,13 +42,15 @@ 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) -> (host, port)`
-  启动日志服务子进程（始终使用 `spawn`）。幂等。已通过 `atexit` 注册清理。
-  `port=0` 让操作系统挑选空闲端口；返回真实绑定到的 `(host, port)`。
+  通过 `subprocess.Popen` 启动一个独立的日志服务子进程（不依赖
+  `multiprocessing`，因此**不会回头执行用户主脚本的任何顶层代码**）。
+  幂等。已通过 `atexit` 注册清理。`port=0` 让操作系统挑选空闲端口；返回
+  真实绑定到的 `(host, port)`。
   **`host` 必须是 loopback**——绑定非 loopback 地址会直接 `ValueError`。
   同时把主进程内 `logging.getLogger("kitty")` 这一个 logger 初始化好——挂上
   `SocketHandler`、设置 level、关闭 `propagate`。**不动 root logger**。
-  在 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，仅返回
-  从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
+  在用户用 `multiprocessing` 启动的子进程里再次调用本函数会自动 no-op，
+  仅返回从父进程继承的 `(host, port)`，因此可以直接放在模块顶层而不必用
   `if __name__ == "__main__":` 包裹。
 - `getLogger(name=None) -> logging.Logger`
   返回挂在 `kitty` 命名空间下的 logger：`getLogger("foo")` 实际拿到的是

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

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

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

@@ -30,7 +30,16 @@
 """
 
 from ._client import getLogger
+from ._formatters import PRESETS, FormatPreset, FormatSpec, get_preset
 from ._setup import setup_logging, shutdown_logging
 
-__all__ = ["setup_logging", "shutdown_logging", "getLogger"]
-__version__ = "0.2.0.dev2"
+__all__ = [
+    "setup_logging",
+    "shutdown_logging",
+    "getLogger",
+    "FormatPreset",
+    "FormatSpec",
+    "PRESETS",
+    "get_preset",
+]
+__version__ = "0.2.0.dev4"

kitty_logger-0.2.0.dev4/src/kitty_logger/_formatters.py

@@ -0,0 +1,211 @@
+"""日志格式化器：控制台版（按字段着色 ANSI）与文件版（无颜色）。
+
+控制台格式化器把不同字段染成不同颜色，便于在终端里快速分辨；
+文件格式化器保持纯文本，避免日志文件被颜色码污染。两者都通过
+:class:`_MillisecondTimeFormatter` 共享毫秒精度的时间戳实现，
+可通过 ``show_msec=False`` 切换为秒级精度。
+
+模块同时提供四档预置格式 :data:`PRESETS`：``minimal`` / ``standard``
+/ ``verbose`` / ``debug``，每档封装好 ``console_fmt`` / ``file_fmt``
+/ ``datefmt`` / ``show_msec``，由 :func:`kitty_logger.setup_logging`
+通过 ``preset=`` 参数选用。
+"""
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Literal, override
+
+# 256 色调色板，在深色终端下不刺眼。
+_LEVEL_COLORS: dict[str, str] = {
+    "DEBUG": "\033[38;5;32m",
+    "INFO": "\033[38;5;70m",
+    "WARNING": "\033[38;5;186m",
+    "ERROR": "\033[38;5;206m",
+    "CRITICAL": "\033[1;38;5;196m",
+}
+_PROC_COLOR = "\033[38;5;141m"
+_THREAD_COLOR = "\033[38;5;177m"
+_NAME_COLOR = "\033[38;5;36m"
+_FILE_COLOR = "\033[38;5;45m"
+_FUNC_COLOR = "\033[38;5;208m"
+_RESET = "\033[0m"
+
+# ---------------------------------------------------------------------------
+# minimal：仅时间 + 级别 + 消息，时间戳到秒，适合脚本类小工具或交互式调试。
+# ---------------------------------------------------------------------------
+_MINIMAL_CONSOLE_FMT = "%(asctime)s %(color)s%(levelname)s%(reset)s %(message)s"
+_MINIMAL_FILE_FMT = "%(asctime)s %(levelname)s %(message)s"
+
+# ---------------------------------------------------------------------------
+# standard：时间 + 级别 + logger 名 + 消息，毫秒精度，足够定位大部分问题。
+# ---------------------------------------------------------------------------
+_STANDARD_CONSOLE_FMT = (
+    "%(asctime)s | "
+    "%(color)s%(levelname)-8s%(reset)s | "
+    "%(name_color)s%(name)s%(reset)s | "
+    "%(message)s"
+)
+_STANDARD_FILE_FMT = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+
+# ---------------------------------------------------------------------------
+# verbose：进程信息 + 文件位置 + 函数名，毫秒精度。本库的历史默认值。
+# ---------------------------------------------------------------------------
+DEFAULT_CONSOLE_FMT = (
+    "%(asctime)s | "
+    "%(proc_color)s%(processName)s(%(process)d)%(reset)s | "
+    "%(name_color)s%(name)s%(reset)s | "
+    "%(file_color)s%(filename)s:%(lineno)d%(reset)s | "
+    "%(func_color)s%(funcName)s%(reset)s | "
+    "%(color)s%(levelname)s%(reset)s | "
+    "%(message)s"
+)
+DEFAULT_FILE_FMT = (
+    "%(asctime)s | %(processName)s(%(process)d) | %(name)s | "
+    "%(filename)s:%(lineno)d | %(funcName)s | %(levelname)s | %(message)s"
+)
+
+# ---------------------------------------------------------------------------
+# debug：在 verbose 基础上加入线程名，便于排查多线程时序问题。
+# ---------------------------------------------------------------------------
+_DEBUG_CONSOLE_FMT = (
+    "%(asctime)s | "
+    "%(proc_color)s%(processName)s(%(process)d)%(reset)s | "
+    "%(thread_color)s%(threadName)s%(reset)s | "
+    "%(name_color)s%(name)s%(reset)s | "
+    "%(file_color)s%(filename)s:%(lineno)d%(reset)s | "
+    "%(func_color)s%(funcName)s%(reset)s | "
+    "%(color)s%(levelname)s%(reset)s | "
+    "%(message)s"
+)
+_DEBUG_FILE_FMT = (
+    "%(asctime)s | %(processName)s(%(process)d) | %(threadName)s | %(name)s | "
+    "%(filename)s:%(lineno)d | %(funcName)s | %(levelname)s | %(message)s"
+)
+
+
+FormatPreset = Literal["minimal", "standard", "verbose", "debug"]
+
+
+@dataclass(frozen=True)
+class FormatSpec:
+    """单档预置格式的完整规格。
+
+    :param console_fmt: 控制台 handler 的 format 字符串（含 ANSI 占位符）。
+    :param file_fmt: 文件 handler 的 format 字符串（无 ANSI）。
+    :param datefmt: ``strftime`` 格式串。
+    :param show_msec: 是否在时间戳尾部追加 ``.毫秒``。
+    """
+
+    console_fmt: str
+    file_fmt: str
+    datefmt: str
+    show_msec: bool
+
+
+PRESETS: dict[FormatPreset, FormatSpec] = {
+    "minimal": FormatSpec(
+        console_fmt=_MINIMAL_CONSOLE_FMT,
+        file_fmt=_MINIMAL_FILE_FMT,
+        datefmt="%H:%M:%S",
+        show_msec=False,
+    ),
+    "standard": FormatSpec(
+        console_fmt=_STANDARD_CONSOLE_FMT,
+        file_fmt=_STANDARD_FILE_FMT,
+        datefmt="%Y-%m-%d %H:%M:%S",
+        show_msec=True,
+    ),
+    "verbose": FormatSpec(
+        console_fmt=DEFAULT_CONSOLE_FMT,
+        file_fmt=DEFAULT_FILE_FMT,
+        datefmt="%Y-%m-%d %H:%M:%S",
+        show_msec=True,
+    ),
+    "debug": FormatSpec(
+        console_fmt=_DEBUG_CONSOLE_FMT,
+        file_fmt=_DEBUG_FILE_FMT,
+        datefmt="%Y-%m-%d %H:%M:%S",
+        show_msec=True,
+    ),
+}
+
+
+def get_preset(name: FormatPreset) -> FormatSpec:
+    """返回 ``name`` 档预置格式规格；未知名抛 :class:`ValueError`。"""
+    try:
+        return PRESETS[name]
+    except KeyError:
+        raise ValueError(
+            f"未知的 format preset: {name!r}，可选: {list(PRESETS)}"
+        ) from None
+
+
+class _MillisecondTimeFormatter(logging.Formatter):
+    """带可选毫秒精度的时间格式化基类。
+
+    标准库 :meth:`logging.Formatter.formatTime` 在传入 ``datefmt`` 时
+    不会自动拼接毫秒，这里覆写以按 ``show_msec`` 决定是否追加 ``.毫秒``。
+    """
+
+    def __init__(
+        self,
+        fmt: str | None = None,
+        datefmt: str | None = None,
+        *,
+        show_msec: bool = True,
+    ) -> None:
+        """
+        :param fmt: 透传给 :class:`logging.Formatter` 的 format 字符串。
+        :param datefmt: 透传给 :class:`logging.Formatter` 的 ``strftime`` 格式。
+        :param show_msec: 是否在时间戳尾部追加 ``.毫秒``。
+            ``minimal`` 档为秒级精度，因此传入 ``False``；其余档位均为 ``True``。
+        """
+        super().__init__(fmt=fmt, datefmt=datefmt)
+        self._show_msec = show_msec
+
+    @override
+    def formatTime(
+        self,
+        record: logging.LogRecord,
+        datefmt: str | None = None,
+    ) -> str:
+        """格式化时间戳；按 ``self._show_msec`` 决定是否追加 ``.毫秒``。"""
+        ct = self.converter(record.created)
+        s = time.strftime(datefmt or "%Y-%m-%d %H:%M:%S", ct)
+        if self._show_msec:
+            return f"{s}.{int(record.msecs):03d}"
+        return s
+
+
+class ColorFormatter(_MillisecondTimeFormatter):
+    """控制台格式化器：按字段分别添加 ANSI 颜色。
+
+    实现思路是把颜色码作为属性挂到 ``record`` 上，再在格式串里通过
+    ``%(xxx_color)s ... %(reset)s`` 占位符把颜色串入对应字段，从而让
+    进程名、线程名、logger 名、文件位置、函数名、级别各自拥有独立的配色。
+    未在格式串中引用的占位符会被忽略，因此各 preset 共用同一份属性注入。
+    """
+
+    @override
+    def format(self, record: logging.LogRecord) -> str:
+        """把各字段对应的 ANSI 颜色码作为属性挂到 ``record`` 上再走父类格式化。
+
+        注入的属性涵盖 level / 进程 / 线程 / logger 名 / 文件位置 / 函数名
+        各自的颜色，以及统一的 ``reset``。具体格式串引用其中哪几个由 preset
+        决定（例如 ``debug`` 档会用到 ``thread_color``，``minimal`` 档则只
+        用到 ``color`` / ``reset``）；未被引用的属性由标准库
+        :class:`logging.Formatter` 自动忽略。
+        """
+        record.color = _LEVEL_COLORS.get(record.levelname, "")  # type: ignore[attr-defined]
+        record.proc_color = _PROC_COLOR  # type: ignore[attr-defined]
+        record.thread_color = _THREAD_COLOR  # type: ignore[attr-defined]
+        record.name_color = _NAME_COLOR  # type: ignore[attr-defined]
+        record.file_color = _FILE_COLOR  # type: ignore[attr-defined]
+        record.func_color = _FUNC_COLOR  # type: ignore[attr-defined]
+        record.reset = _RESET  # type: ignore[attr-defined]
+        return super().format(record)
+
+
+class FileFormatter(_MillisecondTimeFormatter):
+    """文件格式化器：与控制台版字段一致但不带任何 ANSI 颜色码。"""

kitty_logger-0.2.0.dev4/src/kitty_logger/_server.py

@@ -0,0 +1,178 @@
+"""日志服务子进程的核心组件（与启动方式无关）。
+
+服务进程通过 ``python -m kitty_logger._server_main`` 由 :func:`kitty_logger.setup_logging`
+间接拉起，本模块只提供与"具体如何起进程"无关的纯逻辑：
+
+- :func:`_bind_loopback`：在 loopback 地址上绑定一个 ``AF_INET`` 监听 socket。
+- :class:`_LogRecordSocketReceiver`：基于 :class:`socketserver.ThreadingTCPServer`
+  的接收器，复用外部已 ``bind`` 好的 socket。
+- :func:`_build_handlers`：根据用户参数组装落地用的 handler 列表。
+"""
+
+import logging
+import pickle
+import socket
+import socketserver
+import struct
+import sys
+from logging.handlers import TimedRotatingFileHandler
+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``。
+
+    单次 ``recv`` 不保证读够请求长度（TCP 半包），且对端关闭时
+    ``recv`` 会立刻返回 ``b""``。任何"按长度循环 recv"的实现都必须显式
+    处理 EOF，否则在客户端中途断连时会陷入死循环。
+    """
+    buf = bytearray()
+    while len(buf) < n:
+        try:
+            chunk = conn.recv(n - len(buf))
+        except (ConnectionError, OSError):
+            return None
+        if not chunk:
+            return None
+        buf.extend(chunk)
+    return bytes(buf)
+
+
+@final
+class _LogRecordStreamHandler(socketserver.StreamRequestHandler):
+    """处理一个客户端连接上的连续 LogRecord 流。
+
+    协议沿用标准库 :class:`logging.handlers.SocketHandler`：
+    ``[uint32 大端长度][pickle 字节]``，可在同一连接上重复出现。
+    """
+
+    @override
+    def handle(self) -> None:
+        conn = cast(socket.socket, self.connection)
+        while True:
+            header = _recv_exact(conn, 4)
+            if header is None:
+                break
+            slen = cast(int, struct.unpack(">L", header)[0])
+            if slen == 0 or slen > _MAX_RECORD_BYTES:
+                break
+            body = _recv_exact(conn, slen)
+            if body is None:
+                break
+            try:
+                obj = cast(object, pickle.loads(body))
+            except Exception:
+                # 单条记录损坏不应连累整条连接；继续读下一条。
+                continue
+            if not isinstance(obj, dict):
+                continue
+            record = logging.makeLogRecord(cast(dict[str, object], obj))
+            logging.getLogger(record.name).handle(record)
+
+
+@final
+class _LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
+    """基于 :class:`socketserver.ThreadingTCPServer` 的接收器。
+
+    复用外部已 ``bind`` 好的监听 socket，本类不再自己 ``bind``/``listen``。
+    """
+
+    allow_reuse_address: bool = True
+    daemon_threads: bool = True
+
+    @override
+    def __init__(self, listening_sock: socket.socket) -> None:
+        addr = cast(tuple[str, int], listening_sock.getsockname()[:2])
+        # 走父类正常流程以建立 BaseServer 内部状态（shutdown 标志等），
+        # 但通过 ``bind_and_activate=False`` 跳过它自己的 bind/listen——
+        # 这个 socket 已经由调用方绑好。
+        super().__init__(addr, _LogRecordStreamHandler, bind_and_activate=False)
+        # 父类构造时仍会 ``self.socket = socket.socket(...)`` 占坑，
+        # 这里替换成真正复用的 socket，并把临时占位关闭掉。
+        try:
+            self.socket.close()
+        except OSError:
+            pass
+        self.socket = listening_sock
+        self.server_address = addr
+
+
+def _build_handlers(
+    log_file: str | None,
+    stream: bool,
+    console_fmt: str,
+    file_fmt: str,
+    console_datefmt: str | None,
+    file_datefmt: str | None,
+    console_show_msec: bool,
+    file_show_msec: bool,
+) -> list[logging.Handler]:
+    """根据用户传入的参数组合出落地用的 handler 列表。
+
+    控制台与文件两侧的 ``datefmt`` / ``show_msec`` 各自独立——上层允许
+    分别选择不同的 preset，因此服务端不再共用同一份时间设置。
+
+    :param log_file: 日志文件路径；``None`` 表示不挂文件 handler。
+    :param stream: 是否同时挂上指向 ``sys.stderr`` 的 :class:`StreamHandler`。
+    :param console_fmt: 控制台 handler 的 format 字符串（含 ANSI 占位符）。
+    :param file_fmt: 文件 handler 的 format 字符串（无 ANSI）。
+    :param console_datefmt: 控制台时间戳的 ``strftime`` 格式；``None`` 走默认值。
+    :param file_datefmt: 文件时间戳的 ``strftime`` 格式；``None`` 走默认值。
+    :param console_show_msec: 控制台时间戳是否在尾部追加 ``.毫秒``。
+    :param file_show_msec: 文件时间戳是否在尾部追加 ``.毫秒``。
+    :return: 顺序为 ``[file?, stream?]`` 的 handler 列表，调用方按需挂载。
+    """
+    handlers: list[logging.Handler] = []
+    if log_file:
+        # 按天轮转，每天 0 点切一份，最多保留 365 天历史。
+        fh = TimedRotatingFileHandler(
+            log_file,
+            when="midnight",
+            interval=1,
+            backupCount=365,
+            encoding="utf-8",
+        )
+        fh.setFormatter(
+            FileFormatter(fmt=file_fmt, datefmt=file_datefmt, show_msec=file_show_msec)
+        )
+        handlers.append(fh)
+    if stream:
+        sh = logging.StreamHandler(stream=sys.stderr)
+        sh.setFormatter(
+            ColorFormatter(
+                fmt=console_fmt,
+                datefmt=console_datefmt,
+                show_msec=console_show_msec,
+            )
+        )
+        handlers.append(sh)
+    return handlers

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

@@ -0,0 +1,139 @@
+"""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("--console-datefmt", default=None)
+    ap.add_argument("--file-datefmt", default=None)
+    ap.add_argument("--console-show-msec", action="store_true")
+    ap.add_argument("--file-show-msec", action="store_true")
+    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.console_datefmt,
+        args.file_datefmt,
+        args.console_show_msec,
+        args.file_show_msec,
+    ):
+        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()