kitty-logger 0.1.0__tar.gz

kitty_logger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.1
+Name: kitty_logger
+Version: 0.1.0
+Summary: Cross-process logging via a dedicated log server process and SocketHandler.
+Author: Kitty
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# kitty_logger
+
+Cross-process Python logger. The main process starts a dedicated log-server
+subprocess; every other process (forked or spawned) ships `LogRecord`s to it
+via `logging.handlers.SocketHandler`, so all log lines end up in one place
+with no interleaving or file-locking issues.
+
+## Install
+
+```bash
+pip install .
+```
+
+## Usage
+
+```python
+# main.py
+import multiprocessing as mp
+import kitty_logger
+
+def worker(i):
+    log = kitty_logger.getLogger(f"worker.{i}")
+    log.info("hello from worker %d", i)
+
+if __name__ == "__main__":
+    kitty_logger.setup_logging(log_file="app.log")
+    log = kitty_logger.getLogger("main")
+    log.info("starting")
+
+    with mp.get_context("spawn").Pool(4) as pool:
+        pool.map(worker, range(4))
+```
+
+`setup_logging` sets the env vars `KITTY_LOGGER_HOST` / `KITTY_LOGGER_PORT`,
+which child processes inherit and use to connect.
+
+## 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)`
+  Starts the log-server subprocess (always uses the `spawn` start method).
+  Idempotent. Registered with `atexit`. `port=0` lets the OS pick a free port;
+  the actual `(host, port)` is returned.
+- `getLogger(name=None) -> logging.Logger`
+  Returns a logger with a `SocketHandler` pointing at the server.
+- `shutdown_logging()` — stop the server subprocess explicitly.
+
+## Why spawn-only
+
+Child processes started with `fork` inherit the parent's already-connected
+`SocketHandler` (and its TCP fd). Parent and child would then interleave
+pickled-record bytes on the same connection, which corrupts every record on
+the wire. `fork` is also unsafe in multi-threaded parents and unavailable on
+Windows. KittyLogger therefore only supports `spawn`. Use
+`multiprocessing.get_context("spawn")` (or just rely on Python's defaults
+under `if __name__ == "__main__":`).
+
+## Security
+
+The server uses `pickle` to deserialize incoming `LogRecord`s. **Only ever bind
+to a loopback address** (the default `127.0.0.1`). Binding to `0.0.0.0` or any
+externally reachable interface exposes a remote-code-execution surface to anyone
+who can reach the port.
+
+## Caveats
+
+- Do **not** call `logging.basicConfig()` (or otherwise attach a `StreamHandler`
+  to the root logger) before `setup_logging(attach_main_logger=True)` — the main
+  process would emit each record twice: once via the local root handler and
+  once via the log-server. Either let kitty_logger be the only configurer, or
+  pass `attach_main_logger=False` and manage main-process handlers yourself.
+- After `shutdown_logging()`, kitty_logger removes its own `SocketHandler`s
+  from this process's loggers and clears `KITTY_LOGGER_*` env vars, so the
+  process state is symmetric with `setup_logging`. If you attach extra handlers
+  yourself, you remain responsible for cleaning them up.

kitty_logger-0.1.0/README.md

@@ -0,0 +1,74 @@
+# kitty_logger
+
+Cross-process Python logger. The main process starts a dedicated log-server
+subprocess; every other process (forked or spawned) ships `LogRecord`s to it
+via `logging.handlers.SocketHandler`, so all log lines end up in one place
+with no interleaving or file-locking issues.
+
+## Install
+
+```bash
+pip install .
+```
+
+## Usage
+
+```python
+# main.py
+import multiprocessing as mp
+import kitty_logger
+
+def worker(i):
+    log = kitty_logger.getLogger(f"worker.{i}")
+    log.info("hello from worker %d", i)
+
+if __name__ == "__main__":
+    kitty_logger.setup_logging(log_file="app.log")
+    log = kitty_logger.getLogger("main")
+    log.info("starting")
+
+    with mp.get_context("spawn").Pool(4) as pool:
+        pool.map(worker, range(4))
+```
+
+`setup_logging` sets the env vars `KITTY_LOGGER_HOST` / `KITTY_LOGGER_PORT`,
+which child processes inherit and use to connect.
+
+## 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)`
+  Starts the log-server subprocess (always uses the `spawn` start method).
+  Idempotent. Registered with `atexit`. `port=0` lets the OS pick a free port;
+  the actual `(host, port)` is returned.
+- `getLogger(name=None) -> logging.Logger`
+  Returns a logger with a `SocketHandler` pointing at the server.
+- `shutdown_logging()` — stop the server subprocess explicitly.
+
+## Why spawn-only
+
+Child processes started with `fork` inherit the parent's already-connected
+`SocketHandler` (and its TCP fd). Parent and child would then interleave
+pickled-record bytes on the same connection, which corrupts every record on
+the wire. `fork` is also unsafe in multi-threaded parents and unavailable on
+Windows. KittyLogger therefore only supports `spawn`. Use
+`multiprocessing.get_context("spawn")` (or just rely on Python's defaults
+under `if __name__ == "__main__":`).
+
+## Security
+
+The server uses `pickle` to deserialize incoming `LogRecord`s. **Only ever bind
+to a loopback address** (the default `127.0.0.1`). Binding to `0.0.0.0` or any
+externally reachable interface exposes a remote-code-execution surface to anyone
+who can reach the port.
+
+## Caveats
+
+- Do **not** call `logging.basicConfig()` (or otherwise attach a `StreamHandler`
+  to the root logger) before `setup_logging(attach_main_logger=True)` — the main
+  process would emit each record twice: once via the local root handler and
+  once via the log-server. Either let kitty_logger be the only configurer, or
+  pass `attach_main_logger=False` and manage main-process handlers yourself.
+- After `shutdown_logging()`, kitty_logger removes its own `SocketHandler`s
+  from this process's loggers and clears `KITTY_LOGGER_*` env vars, so the
+  process state is symmetric with `setup_logging`. If you attach extra handlers
+  yourself, you remain responsible for cleaning them up.

kitty_logger-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kitty_logger"
+version = "0.1.0"
+description = "Cross-process logging via a dedicated log server process and SocketHandler."
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Kitty" }]
+license = { text = "MIT" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 2048

kitty_logger-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kitty_logger-0.1.0/src/kitty_logger/__init__.py

@@ -0,0 +1,19 @@
+"""kitty_logger：通过专用日志服务子进程实现的跨进程日志记录。
+
+典型用法::
+
+    # 主进程
+    import kitty_logger
+    kitty_logger.setup_logging(log_file="app.log")
+
+    # 之后用 spawn 启动子进程（本库不支持 fork），在子进程中：
+    import kitty_logger
+    log = kitty_logger.getLogger(__name__)
+    log.info("hello from child")
+"""
+
+from ._client import getLogger
+from ._setup import setup_logging, shutdown_logging
+
+__all__ = ["setup_logging", "shutdown_logging", "getLogger"]
+__version__ = "0.1.0"

kitty_logger-0.1.0/src/kitty_logger/_client.py

@@ -0,0 +1,83 @@
+"""子进程侧 API：``getLogger`` 返回一个连接到日志服务进程的 logger。"""
+
+import logging
+import logging.handlers
+import os
+import threading
+
+from ._env import ENV_HOST, ENV_LEVEL, ENV_PORT
+
+_lock = threading.Lock()
+_configured_loggers: set[str] = set()
+
+
+def _read_endpoint() -> tuple[str, int]:
+    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()，再创建子进程。"
+        )
+    return host, int(port)
+
+
+def _read_level() -> int:
+    raw = os.environ.get(ENV_LEVEL)
+    if raw is None:
+        return logging.INFO
+    # 优先按整数解析；解析失败再当作 ``"INFO"`` 这类名字处理。
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    name_to_level = logging.getLevelNamesMapping()
+    return name_to_level.get(raw.upper(), logging.INFO)
+
+
+def _attach_socket_handler(
+    logger: logging.Logger, host: str, port: int, level: int
+) -> None:
+    # 避免在同一个 logger 上重复挂 SocketHandler（例如模块被重新 import 时）。
+    for h in logger.handlers:
+        if isinstance(h, logging.handlers.SocketHandler) and (h.host, h.port) == (
+            host,
+            port,
+        ):
+            return
+    handler = logging.handlers.SocketHandler(host, port)
+    # SocketHandler 直接 pickle LogRecord，由接收端负责格式化。
+    # 在这里设置 formatter 没有效果，会被忽略。
+    logger.addHandler(handler)
+    # 仅当 logger 还是默认的 NOTSET 时才设置 level，不要悄悄覆盖用户已经
+    # 显式设置过的级别（例如用户在 setup_logging 之前已经
+    # ``logging.getLogger().setLevel(DEBUG)``）。
+    if logger.level == logging.NOTSET:
+        logger.setLevel(level)
+    # 关闭向 root 的传播，避免子进程恰好已经有默认 StreamHandler
+    # （比如调用过 basicConfig）时出现重复输出。root logger 没有父级，
+    # 设置 propagate 没有意义，跳过。
+    if logger is not logging.getLogger():
+        logger.propagate = False
+
+
+def getLogger(name: str | None = None) -> logging.Logger:
+    """返回一个会把日志记录发送到 kitty_logger 服务进程的 logger。
+
+    必须在祖先进程已经调用过 :func:`setup_logging` 之后才能使用
+    （子进程通过继承的环境变量 ``KITTY_LOGGER_HOST`` / ``KITTY_LOGGER_PORT``
+    定位服务地址）。
+
+    本库只支持 ``spawn`` 启动方式，因此模块级状态在子进程里天然是空的，
+    无需处理"继承自父进程的 SocketHandler"问题。
+    """
+    host, port = _read_endpoint()
+    level = _read_level()
+    logger = logging.getLogger(name)
+    with _lock:
+        # ``logging.getLogger("")`` 与 ``logging.getLogger(None)`` 都是 root，
+        # 在本集合里共用 ""；与 root 真正的别名一致，不需要单独区分。
+        key = name or ""
+        if key not in _configured_loggers:
+            _attach_socket_handler(logger, host, port, level)
+            _configured_loggers.add(key)
+    return logger

kitty_logger-0.1.0/src/kitty_logger/_env.py

@@ -0,0 +1,8 @@
+"""共享常量：环境变量名。
+
+放在独立模块以避免 ``_setup`` 与 ``_client`` 互相导入造成循环。
+"""
+
+ENV_HOST = "KITTY_LOGGER_HOST"
+ENV_PORT = "KITTY_LOGGER_PORT"
+ENV_LEVEL = "KITTY_LOGGER_LEVEL"

kitty_logger-0.1.0/src/kitty_logger/_formatters.py

@@ -0,0 +1,60 @@
+"""日志格式化器：彩色控制台 + 毫秒时间戳文件。
+
+移植自 llm_engine.log；保留原本的 ANSI 配色与 ``formatTime`` 的毫秒精度。
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import override
+
+
+class _MillisecondTimeFormatter(logging.Formatter):
+    """``formatTime`` 输出 ``YYYY-MM-DD HH:MM:SS.mmm``（毫秒精度）。"""
+
+    @override
+    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
+        ct = self.converter(record.created)
+        s = time.strftime(datefmt or "%Y-%m-%d %H:%M:%S", ct)
+        return f"{s}.{int(record.msecs):03d}"
+
+
+class ColorFormatter(_MillisecondTimeFormatter):
+    """为控制台输出添加 ANSI 彩色的日志格式化器。
+
+    在格式串里可以使用以下额外字段：``%(color)s``、``%(name_color)s``、
+    ``%(file_color)s``、``%(func_color)s``，以及对应的 ``%(reset)s``。
+    """
+
+    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",
+    }
+    name_color: str = "\033[38;5;36m"
+    file_color: str = "\033[38;5;45m"
+    func_color: str = "\033[38;5;208m"
+    reset: str = "\033[0m"
+
+    @override
+    def format(self, record: logging.LogRecord) -> str:
+        record.color = self.colors.get(record.levelname, "")  # type: ignore[attr-defined]
+        record.name_color = self.name_color  # type: ignore[attr-defined]
+        record.file_color = self.file_color  # type: ignore[attr-defined]
+        record.func_color = self.func_color  # type: ignore[attr-defined]
+        record.reset = self.reset  # type: ignore[attr-defined]
+        return super().format(record)
+
+
+class FileFormatter(_MillisecondTimeFormatter):
+    """用于日志文件的格式化器，无颜色，含毫秒时间戳。"""
+
+
+# 默认格式：在 llm_engine 原版基础上加入 ``processName[process]``，
+# 以便跨进程日志能区分来源进程。
+DEFAULT_CONSOLE_FMT = "%(asctime)s | %(name_color)s%(name)s%(reset)s | %(processName)s[%(process)d] | %(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 | %(name)s | %(processName)s[%(process)d] | %(filename)s:%(lineno)d | %(funcName)s | %(levelname)s | %(message)s"

kitty_logger-0.1.0/src/kitty_logger/_server.py

@@ -0,0 +1,171 @@
+"""日志记录接收进程。
+
+运行在一个独立的子进程中。接收父进程预先 bind 好的监听 socket，
+反序列化客户端进程通过 ``logging.handlers.SocketHandler`` 发来的
+``logging.LogRecord``，然后交给本进程内配置的日志 handler（文件、
+stderr 等）输出。
+
+实现参考自 Python ``logging`` cookbook。
+"""
+
+import logging
+import pickle
+import socket
+import socketserver
+import struct
+import sys
+import threading
+from typing import cast, final, override
+
+from multiprocessing.synchronize import Event as MpEvent
+
+from ._formatters import ColorFormatter, FileFormatter
+
+# 单条 LogRecord 序列化后的最大字节数。超过即视为协议错乱或恶意流量，
+# 直接断开连接，避免 ``recv`` 一口气分配几个 GB 的 buffer 把进程打爆。
+# 16 MiB 已经远大于任何正常的 ``LogRecord``（含 traceback / extra）。
+_MAX_RECORD_BYTES = 16 * 1024 * 1024
+
+
+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):
+    """处理一个客户端连接上的流式日志请求。"""
+
+    @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:
+                # 长度异常的请求多半是协议不匹配或恶意流量，直接断连而不是
+                # 试图继续读，避免被诱导分配巨大 buffer。
+                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))
+            logger = logging.getLogger(record.name)
+            logger.handle(record)
+
+
+@final
+class _LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
+    allow_reuse_address: bool = True
+    daemon_threads: bool = True
+
+    @override
+    def __init__(self, listening_sock: socket.socket) -> None:
+        # 父类正常初始化（含 _BaseServer 的 shutdown 标志位等内部状态），
+        # 但跳过 bind/listen——监听 socket 是父进程已经绑好的。
+        addr = cast(tuple[str, int], listening_sock.getsockname()[:2])
+        super().__init__(addr, _LogRecordStreamHandler, bind_and_activate=False)
+        # 关闭 ``TCPServer.__init__`` 默认创建的那个空 socket，再换成外部传入的。
+        try:
+            self.socket.close()
+        except Exception:
+            pass
+        self.socket = listening_sock
+        self.server_address = addr
+
+
+def _build_handlers(
+    log_file: str | None,
+    stream: bool,
+    console_fmt: str,
+    file_fmt: str,
+    datefmt: str | None,
+) -> list[logging.Handler]:
+    handlers: list[logging.Handler] = []
+    if log_file:
+        fh = logging.FileHandler(log_file, encoding="utf-8")
+        fh.setFormatter(FileFormatter(fmt=file_fmt, datefmt=datefmt))
+        handlers.append(fh)
+    if stream:
+        sh = logging.StreamHandler(stream=sys.stderr)
+        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:
+    """日志服务子进程的入口函数。"""
+    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 的 send 端；任何原因导致父进程消失（正常退出、
+        # 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 Exception:
+                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 Exception:
+            pass
+        logging.shutdown()

kitty_logger-0.1.0/src/kitty_logger/_setup.py

@@ -0,0 +1,282 @@
+import atexit
+import ipaddress
+import logging
+import multiprocessing as mp
+import os
+import socket
+import warnings
+
+from multiprocessing.process import BaseProcess
+from multiprocessing.synchronize import Event as MpEvent
+from typing import Literal, TypedDict, TypeGuard, cast
+
+
+from ._env import ENV_HOST, ENV_LEVEL, ENV_PORT
+from ._formatters import DEFAULT_CONSOLE_FMT, DEFAULT_FILE_FMT
+from ._server import run_server
+
+
+class _NotRunningState(TypedDict):
+    running: Literal[False]
+    host: None
+    port: None
+    proc: None
+    shutdown_event: None
+    parent_alive_send: None
+
+
+class _RunningState(TypedDict):
+    running: Literal[True]
+    host: str
+    port: int
+    proc: BaseProcess
+    shutdown_event: MpEvent
+    # 父进程持有的 socketpair 一端；只要父进程活着这个 fd 就开着，
+    # 父进程一旦消失（包括 SIGKILL/段错误），内核会自动关闭它，
+    # 子进程的另一端会读到 EOF 从而触发自我退出。
+    parent_alive_send: socket.socket
+
+
+type _ServerState = _NotRunningState | _RunningState
+
+
+def _make_not_running_state() -> _NotRunningState:
+    return {
+        "running": False,
+        "host": None,
+        "port": None,
+        "proc": None,
+        "shutdown_event": None,
+        "parent_alive_send": None,
+    }
+
+
+_state: _ServerState = _make_not_running_state()
+
+
+def _is_running(state: _ServerState) -> TypeGuard[_RunningState]:
+    return state["running"] is True
+
+
+def _warn_if_non_loopback(host: str) -> None:
+    """非 loopback 地址会把 ``pickle.loads`` 暴露给可达端口的任何人，等于 RCE。"""
+    try:
+        addr = ipaddress.ip_address(host)
+        addrs: list[ipaddress.IPv4Address | ipaddress.IPv6Address] = [addr]
+    except ValueError:
+        # 主机名（例如 "localhost" / "my-host.example.com"）：尽力解析后判断。
+        try:
+            infos = socket.getaddrinfo(host, None)
+        except OSError:
+            warnings.warn(
+                f"kitty_logger 无法解析 host={host!r}，无法判断是否为 loopback；服务端使用 pickle 反序列化，请确认绑定地址不可被外部访问。",
+                stacklevel=3,
+            )
+            return
+        addrs = []
+        for info in infos:
+            sockaddr = info[4]
+            ip_str = sockaddr[0] if isinstance(sockaddr, tuple) else None
+            if not ip_str:
+                continue
+            try:
+                addrs.append(ipaddress.ip_address(ip_str))
+            except ValueError:
+                continue
+        if not addrs:
+            return
+    if any(not a.is_loopback for a in addrs):
+        warnings.warn(
+            f"kitty_logger 绑定到非 loopback 地址 {host!r}：服务端使用 pickle 反序列化，等同于把远程代码执行能力暴露给可达该端口的任何主机。请仅在 127.0.0.1 / ::1 上使用。",
+            stacklevel=3,
+        )
+
+
+def _bind_ipv4_listener(
+    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 setup_logging(
+    log_file: str | None = None,
+    level: int = logging.INFO,
+    host: str = "127.0.0.1",
+    port: int = 0,
+    stream: bool = True,
+    console_fmt: str = DEFAULT_CONSOLE_FMT,
+    file_fmt: str = DEFAULT_FILE_FMT,
+    datefmt: str | None = None,
+    attach_main_logger: bool = True,
+) -> tuple[str, int]:
+    """初始化跨进程日志服务。
+
+    启动一个专用子进程（始终使用 ``spawn`` 启动方式），通过 TCP 接收
+    ``LogRecord`` 并写入 ``log_file`` 和/或 stderr。同时设置环境变量
+    ``KITTY_LOGGER_HOST`` 和 ``KITTY_LOGGER_PORT``，让本次调用之后
+    spawn 出来的子进程可以通过 :func:`kitty_logger.getLogger` 连接到
+    该服务。
+
+    控制台输出使用 ``ColorFormatter``（带 ANSI 颜色），文件输出使用
+    ``FileFormatter``（无颜色）；两者都使用毫秒级时间戳。
+
+    返回服务实际绑定到的 ``(host, port)``（当 ``port=0`` 由 OS 自动
+    分配端口时，调用方可以从这里拿到真实端口）。
+
+    幂等：重复调用直接返回已经记录的 ``(host, port)``。
+
+    .. note::
+       本库**不支持** ``fork`` 启动方式。原因：
+       (1) ``fork`` 会让子进程继承父进程已建立的 ``SocketHandler`` 和
+       底层 TCP 连接，父子两个进程往同一个 socket 上交叉写 pickle 字节流，
+       服务端反序列化必然失败；
+       (2) 多线程程序里 ``fork`` 本身就不安全（其他线程持有的锁会原样
+       留在子进程里）；
+       (3) 跨平台一致性：macOS / Windows 都不能用 ``fork``。
+       请始终使用 ``multiprocessing.get_context("spawn")`` 或顶层守卫
+       ``if __name__ == "__main__":`` 配合默认 ``spawn``。
+    """
+    global _state
+    if _is_running(state=_state):
+        return _state["host"], _state["port"]
+
+    _warn_if_non_loopback(host)
+
+    # 在父进程里直接 bind，使 ``port=0`` 时也能同步拿到真实端口；
+    # 然后把已绑定的 socket 交给服务子进程使用。
+    listening_sock, bound_host, bound_port = _bind_ipv4_listener(host, port)
+
+    # 父进程存活监测：父进程持有 send 端，子进程持有 recv 端。
+    # 父进程哪怕被 ``kill -9`` 也会让内核 close 它的 fd，子进程会读到 EOF。
+    parent_alive_send, parent_alive_recv = socket.socketpair()
+
+    # 始终使用 spawn：见上面 docstring 的解释。
+    ctx = mp.get_context("spawn")
+    shutdown_event = ctx.Event()
+    proc = ctx.Process(
+        target=run_server,
+        kwargs=dict(
+            listening_sock=listening_sock,
+            shutdown_event=shutdown_event,
+            parent_alive_recv=parent_alive_recv,
+            level=level,
+            log_file=log_file,
+            stream=stream,
+            console_fmt=console_fmt,
+            file_fmt=file_fmt,
+            datefmt=datefmt,
+        ),
+        name="kitty-logger-server",
+        daemon=False,
+    )
+    proc.start()
+    # 父进程不再需要这两个 socket 副本：listening_sock 完全交给子进程；
+    # parent_alive_recv 只能由子进程持有，否则 EOF 永远不会到来。
+    listening_sock.close()
+    parent_alive_recv.close()
+
+    # 这些 ENV 是给"日后由本进程 spawn 出来的工作子进程"用的（它们靠 ENV
+    # 找到服务地址）；服务子进程本身已经通过 kwargs 拿到全部参数，所以
+    # 在 ``proc.start()`` 之后再写 ENV 没有竞态问题。
+    os.environ[ENV_HOST] = bound_host
+    os.environ[ENV_PORT] = str(bound_port)
+    os.environ[ENV_LEVEL] = str(level)
+
+    new_state: _RunningState = {
+        "running": True,
+        "host": bound_host,
+        "port": bound_port,
+        "proc": proc,
+        "shutdown_event": shutdown_event,
+        "parent_alive_send": parent_alive_send,
+    }
+    _state = new_state
+
+    if attach_main_logger:
+        # 让主进程自己产生的日志也走同一个服务，避免输出渠道分裂。
+        from ._client import _attach_socket_handler
+
+        _attach_socket_handler(logging.getLogger(), bound_host, bound_port, level)
+
+    _ = atexit.register(shutdown_logging)
+    return bound_host, bound_port
+
+
+def _detach_all_socket_handlers(host: str, port: int) -> None:
+    """卸载本进程内所有指向 ``(host, port)`` 的 ``SocketHandler``。
+
+    ``shutdown_logging`` 之后服务子进程已死，留在 logger 上的 handler 会让
+    后续 ``logging.xxx`` 调用打到一个不存在的端口（``logging`` 会静默吞掉
+    socket 错误，外部表现为日志凭空消失）。在 shutdown 时主动卸载它们，
+    保证状态对称：``setup_logging`` 装上去什么，``shutdown_logging`` 全部
+    取下来。
+    """
+    from logging.handlers import SocketHandler
+
+    loggers: list[logging.Logger] = [logging.getLogger()]
+    for obj in logging.Logger.manager.loggerDict.values():
+        if isinstance(obj, logging.Logger):
+            loggers.append(obj)
+    for lg in loggers:
+        for h in list(lg.handlers):
+            if isinstance(h, SocketHandler) and (h.host, h.port) == (host, port):
+                lg.removeHandler(h)
+                try:
+                    h.close()
+                except Exception:
+                    pass
+
+
+def shutdown_logging(timeout: float = 5.0) -> None:
+    """停止日志服务子进程并清理本进程内残留的 ``SocketHandler``。可被重复调用。"""
+    global _state
+    if not _is_running(state=_state):
+        return
+    event: MpEvent = _state["shutdown_event"]
+    proc: BaseProcess = _state["proc"]
+    parent_alive_send: socket.socket = _state["parent_alive_send"]
+    host: str = _state["host"]
+    port: int = _state["port"]
+    _state = _make_not_running_state()
+    try:
+        event.set()
+    except Exception:
+        pass
+    # 主动关闭父端 socket，作为 mp.Event 的兜底关闭信号。
+    try:
+        parent_alive_send.close()
+    except Exception:
+        pass
+    proc.join(timeout)
+    if proc.is_alive():
+        proc.terminate()
+        proc.join(1.0)
+    if proc.is_alive():
+        # ``terminate`` 没杀掉（被磁盘 IO 等阻塞在不可中断状态），最后兜底 kill。
+        try:
+            proc.kill()
+        except Exception:
+            pass
+        proc.join(1.0)
+
+    # 服务进程已经死了，本进程里指向它的 SocketHandler 必须全部取下，
+    # 否则后续 logging 调用会向一个失效端口发送，触发静默丢日志。
+    _detach_all_socket_handlers(host, port)
+
+    # 同步清理 _client 的 dedup 集合与 ENV，让"二次 setup"能真正回到干净状态。
+    from . import _client
+
+    with _client._lock:
+        _client._configured_loggers.clear()
+    for k in (ENV_HOST, ENV_PORT, ENV_LEVEL):
+        os.environ.pop(k, None)

kitty_logger-0.1.0/src/kitty_logger.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.1
+Name: kitty_logger
+Version: 0.1.0
+Summary: Cross-process logging via a dedicated log server process and SocketHandler.
+Author: Kitty
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# kitty_logger
+
+Cross-process Python logger. The main process starts a dedicated log-server
+subprocess; every other process (forked or spawned) ships `LogRecord`s to it
+via `logging.handlers.SocketHandler`, so all log lines end up in one place
+with no interleaving or file-locking issues.
+
+## Install
+
+```bash
+pip install .
+```
+
+## Usage
+
+```python
+# main.py
+import multiprocessing as mp
+import kitty_logger
+
+def worker(i):
+    log = kitty_logger.getLogger(f"worker.{i}")
+    log.info("hello from worker %d", i)
+
+if __name__ == "__main__":
+    kitty_logger.setup_logging(log_file="app.log")
+    log = kitty_logger.getLogger("main")
+    log.info("starting")
+
+    with mp.get_context("spawn").Pool(4) as pool:
+        pool.map(worker, range(4))
+```
+
+`setup_logging` sets the env vars `KITTY_LOGGER_HOST` / `KITTY_LOGGER_PORT`,
+which child processes inherit and use to connect.
+
+## 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)`
+  Starts the log-server subprocess (always uses the `spawn` start method).
+  Idempotent. Registered with `atexit`. `port=0` lets the OS pick a free port;
+  the actual `(host, port)` is returned.
+- `getLogger(name=None) -> logging.Logger`
+  Returns a logger with a `SocketHandler` pointing at the server.
+- `shutdown_logging()` — stop the server subprocess explicitly.
+
+## Why spawn-only
+
+Child processes started with `fork` inherit the parent's already-connected
+`SocketHandler` (and its TCP fd). Parent and child would then interleave
+pickled-record bytes on the same connection, which corrupts every record on
+the wire. `fork` is also unsafe in multi-threaded parents and unavailable on
+Windows. KittyLogger therefore only supports `spawn`. Use
+`multiprocessing.get_context("spawn")` (or just rely on Python's defaults
+under `if __name__ == "__main__":`).
+
+## Security
+
+The server uses `pickle` to deserialize incoming `LogRecord`s. **Only ever bind
+to a loopback address** (the default `127.0.0.1`). Binding to `0.0.0.0` or any
+externally reachable interface exposes a remote-code-execution surface to anyone
+who can reach the port.
+
+## Caveats
+
+- Do **not** call `logging.basicConfig()` (or otherwise attach a `StreamHandler`
+  to the root logger) before `setup_logging(attach_main_logger=True)` — the main
+  process would emit each record twice: once via the local root handler and
+  once via the log-server. Either let kitty_logger be the only configurer, or
+  pass `attach_main_logger=False` and manage main-process handlers yourself.
+- After `shutdown_logging()`, kitty_logger removes its own `SocketHandler`s
+  from this process's loggers and clears `KITTY_LOGGER_*` env vars, so the
+  process state is symmetric with `setup_logging`. If you attach extra handlers
+  yourself, you remain responsible for cleaning them up.

kitty_logger-0.1.0/src/kitty_logger.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/kitty_logger/__init__.py
+src/kitty_logger/_client.py
+src/kitty_logger/_env.py
+src/kitty_logger/_formatters.py
+src/kitty_logger/_server.py
+src/kitty_logger/_setup.py
+src/kitty_logger.egg-info/PKG-INFO
+src/kitty_logger.egg-info/SOURCES.txt
+src/kitty_logger.egg-info/dependency_links.txt
+src/kitty_logger.egg-info/requires.txt
+src/kitty_logger.egg-info/top_level.txt
+tests/test_kitty_logger.py

kitty_logger-0.1.0/src/kitty_logger.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kitty_logger-0.1.0/src/kitty_logger.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=7

kitty_logger-0.1.0/src/kitty_logger.egg-info/top_level.txt

@@ -0,0 +1 @@
+kitty_logger

kitty_logger-0.1.0/tests/test_kitty_logger.py

@@ -0,0 +1,247 @@
+"""kitty_logger 端到端冒烟与回归测试。
+
+- 主进程 + spawn 子进程的端到端写入。
+- 半包 / 中途断连不会导致服务端死循环或丢失后续记录。
+- 重复调用 ``setup_logging`` / ``shutdown_logging`` 是幂等的。
+- ``setup_logging`` 绑定非 loopback 地址会触发 ``UserWarning``。
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import multiprocessing as mp
+import os
+import pickle
+import socket
+import struct
+import time
+import warnings
+from pathlib import Path
+
+import pytest
+
+import kitty_logger
+from kitty_logger import _client
+
+
+def _wait_for_lines(path: Path, predicate, timeout: float = 5.0) -> str:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if path.exists():
+            text = path.read_text(encoding="utf-8")
+            if predicate(text):
+                return text
+        time.sleep(0.05)
+    raise AssertionError(f"timed out waiting for log file: existing={path.exists()}")
+
+
+def _spawn_worker(idx: int) -> None:
+    log = kitty_logger.getLogger(f"worker.{idx}")
+    log.info("hello from worker %d", idx)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_state(monkeypatch):
+    """确保每个用例都从干净的全局状态出发。"""
+    # setup_logging 是模块级单例，跑完后必须 shutdown 干净。
+    yield
+    try:
+        kitty_logger.shutdown_logging()
+    except Exception:
+        pass
+    # 重置 _client 模块状态，避免集合泄漏到下一个用例。
+    _client._configured_loggers = set()
+    # 清掉测试期间挂上去的 SocketHandler。
+    for lg in [logging.getLogger()] + [
+        obj for obj in logging.Logger.manager.loggerDict.values() if isinstance(obj, logging.Logger)
+    ]:
+        for h in list(lg.handlers):
+            if isinstance(h, logging.handlers.SocketHandler):
+                lg.removeHandler(h)
+    # 清环境变量。
+    for k in ("KITTY_LOGGER_HOST", "KITTY_LOGGER_PORT", "KITTY_LOGGER_LEVEL"):
+        os.environ.pop(k, None)
+
+
+def test_end_to_end_spawn(tmp_path: Path):
+    log_path = tmp_path / "app.log"
+    host, port = kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+    assert host == "127.0.0.1"
+    assert port > 0
+
+    main_log = kitty_logger.getLogger("main")
+    main_log.info("hello from main")
+
+    ctx = mp.get_context("spawn")
+    procs = [ctx.Process(target=_spawn_worker, args=(i,)) for i in range(3)]
+    for p in procs:
+        p.start()
+    for p in procs:
+        p.join(timeout=10)
+        assert p.exitcode == 0, f"worker exited with {p.exitcode}"
+
+    text = _wait_for_lines(
+        log_path,
+        lambda t: "hello from main" in t and all(f"hello from worker {i}" in t for i in range(3)),
+    )
+    # 进程名应当出现在每行里，便于跨进程定位。
+    assert "[" in text and "]" in text
+
+
+def test_setup_logging_idempotent(tmp_path: Path):
+    log_path = tmp_path / "app.log"
+    h1, p1 = kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+    h2, p2 = kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+    assert (h1, p1) == (h2, p2)
+
+
+def test_shutdown_logging_idempotent(tmp_path: Path):
+    kitty_logger.setup_logging(log_file=str(tmp_path / "app.log"), stream=False)
+    kitty_logger.shutdown_logging()
+    # 再调用一次不应抛错。
+    kitty_logger.shutdown_logging()
+
+
+def test_get_logger_without_setup_raises():
+    # 必须没有环境变量。
+    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")
+
+
+def test_non_loopback_warns(tmp_path: Path):
+    # 用一个本机存在但不是 loopback 的地址：0.0.0.0 在大多数系统都能 bind。
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        kitty_logger.setup_logging(host="0.0.0.0", port=0, log_file=str(tmp_path / "x.log"), stream=False)
+    assert any("loopback" in str(w.message) for w in caught)
+
+
+def _send_pickled_record(sock: socket.socket, name: str, msg: str) -> None:
+    record = logging.LogRecord(
+        name=name, level=logging.INFO, pathname=__file__, lineno=1, msg=msg, args=None, exc_info=None
+    )
+    payload = pickle.dumps(record.__dict__)
+    sock.sendall(struct.pack(">L", len(payload)) + payload)
+
+
+def test_partial_send_and_abrupt_close_does_not_hang(tmp_path: Path):
+    """
+    回归测试 P0-1：服务端必须能处理
+      (a) 头部分多次 send；
+      (b) body 中途断连（recv 返回 b""）。
+
+    断连后再开新连接发送的下一条记录应能正常落盘。
+    """
+    log_path = tmp_path / "app.log"
+    host, port = kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+
+    # 1) 头部分两次 send，body 完整 —— 应当成功。
+    s = socket.create_connection((host, port))
+    record = logging.LogRecord(
+        name="split", level=logging.INFO, pathname=__file__, lineno=1, msg="split-header-ok", args=None, exc_info=None
+    )
+    payload = pickle.dumps(record.__dict__)
+    header = struct.pack(">L", len(payload))
+    s.sendall(header[:2])
+    time.sleep(0.05)
+    s.sendall(header[2:] + payload)
+    s.close()
+
+    # 2) 半个 body 后强行 close —— 服务端不应死循环、不应崩溃。
+    s2 = socket.create_connection((host, port))
+    record2 = logging.LogRecord(
+        name="split", level=logging.INFO, pathname=__file__, lineno=1, msg="will-be-truncated", args=None, exc_info=None
+    )
+    payload2 = pickle.dumps(record2.__dict__)
+    s2.sendall(struct.pack(">L", len(payload2)) + payload2[: len(payload2) // 2])
+    s2.close()
+
+    # 3) 新连接里发一条完整记录，应当依旧能落盘（说明服务端没卡住）。
+    s3 = socket.create_connection((host, port))
+    _send_pickled_record(s3, "split", "after-truncation")
+    s3.close()
+
+    text = _wait_for_lines(
+        log_path,
+        lambda t: "split-header-ok" in t and "after-truncation" in t,
+    )
+    assert "will-be-truncated" not in text
+
+
+def test_level_env_accepts_name(tmp_path: Path):
+    # 直接复用 _read_level：不必启服务。
+    os.environ["KITTY_LOGGER_LEVEL"] = "WARNING"
+    assert _client._read_level() == logging.WARNING
+    os.environ["KITTY_LOGGER_LEVEL"] = "warning"
+    assert _client._read_level() == logging.WARNING
+    os.environ["KITTY_LOGGER_LEVEL"] = "30"
+    assert _client._read_level() == logging.WARNING
+    os.environ["KITTY_LOGGER_LEVEL"] = "not-a-level"
+    assert _client._read_level() == logging.INFO
+
+
+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.getLogger("svc.a")
+
+    assert os.environ.get("KITTY_LOGGER_HOST")
+    assert any(
+        isinstance(h, logging.handlers.SocketHandler) for h in logging.getLogger().handlers
+    )
+    assert _client._configured_loggers  # 至少包含 "svc.a"
+
+    kitty_logger.shutdown_logging()
+
+    assert not any(
+        isinstance(h, logging.handlers.SocketHandler) for h in logging.getLogger().handlers
+    )
+    for k in ("KITTY_LOGGER_HOST", "KITTY_LOGGER_PORT", "KITTY_LOGGER_LEVEL"):
+        assert k not in os.environ
+    assert not _client._configured_loggers
+
+
+def test_setup_after_shutdown_uses_new_port(tmp_path: Path):
+    """shutdown 之后再 setup，新端口必须真正生效（旧 dedup 不能阻止重新挂 handler）。"""
+    log_path = tmp_path / "app.log"
+    h1, p1 = kitty_logger.setup_logging(log_file=str(log_path), stream=False)
+    _ = kitty_logger.getLogger("svc.b")
+    kitty_logger.shutdown_logging()
+
+    log_path2 = tmp_path / "app2.log"
+    h2, p2 = kitty_logger.setup_logging(log_file=str(log_path2), stream=False)
+    log = kitty_logger.getLogger("svc.b")
+    log.info("after-restart")
+
+    # 新 logger 的 SocketHandler 必须指向新端口，不能还指向旧端口。
+    sock_handlers = [h for h in log.handlers if isinstance(h, logging.handlers.SocketHandler)]
+    assert sock_handlers, "expected a SocketHandler attached to svc.b after restart"
+    assert all(h.port == p2 for h in sock_handlers)
+    assert p1 != p2 or h1 == h2  # 端口可能被 OS 复用，只要 handler 指向当前端口即可
+
+    _wait_for_lines(log_path2, lambda t: "after-restart" in t)
+
+
+def test_attach_main_logger_false_leaves_root_alone(tmp_path: Path):
+    root = logging.getLogger()
+    before = list(root.handlers)
+    kitty_logger.setup_logging(
+        log_file=str(tmp_path / "app.log"), stream=False, attach_main_logger=False
+    )
+    after = list(root.handlers)
+    assert after == before, "attach_main_logger=False 不应改动 root logger 的 handlers"
+
+
+def test_attach_does_not_override_explicit_level(tmp_path: Path):
+    """用户已显式设置的 level 不应被悄悄覆盖。"""
+    custom = logging.getLogger("explicit-level-user")
+    custom.setLevel(logging.DEBUG)
+    kitty_logger.setup_logging(
+        log_file=str(tmp_path / "app.log"), level=logging.WARNING, stream=False
+    )
+    _ = kitty_logger.getLogger("explicit-level-user")
+    assert custom.level == logging.DEBUG