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

kitty_logger-0.2.0.dev5/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.dev3/src/kitty_logger.egg-info → kitty_logger-0.2.0.dev5}/PKG-INFO

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

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

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

{kitty_logger-0.2.0.dev3 → kitty_logger-0.2.0.dev5}/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.dev3"
+__all__ = [
+    "setup_logging",
+    "shutdown_logging",
+    "getLogger",
+    "FormatPreset",
+    "FormatSpec",
+    "PRESETS",
+    "get_preset",
+]
+__version__ = "0.2.0.dev5"

{kitty_logger-0.2.0.dev3 → kitty_logger-0.2.0.dev5}/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))
@@ -95,17 +111,21 @@ def _ensure_kitty_handler() -> logging.Logger:
 
 
 def getLogger(name: str | None = None) -> logging.Logger:
-    """返回挂在 ``kitty`` 命名空间下的 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``。
     """
     _ensure_kitty_handler()
     full = KITTY_NAMESPACE if not name else f"{KITTY_NAMESPACE}.{name}"

kitty_logger-0.2.0.dev5/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.dev3 → kitty_logger-0.2.0.dev5}/src/kitty_logger/_server.py

@@ -131,9 +131,26 @@ def _build_handlers(
     stream: bool,
     console_fmt: str,
     file_fmt: str,
-    datefmt: str | None,
+    console_datefmt: str | None,
+    file_datefmt: str | None,
+    console_show_msec: bool,
+    file_show_msec: bool,
 ) -> list[logging.Handler]:
-    """根据用户传入的参数组合出落地用的 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 天历史。
@@ -144,10 +161,18 @@ def _build_handlers(
             backupCount=365,
             encoding="utf-8",
         )
-        fh.setFormatter(FileFormatter(fmt=file_fmt, datefmt=datefmt))
+        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=datefmt))
+        sh.setFormatter(
+            ColorFormatter(
+                fmt=console_fmt,
+                datefmt=console_datefmt,
+                show_msec=console_show_msec,
+            )
+        )
         handlers.append(sh)
     return handlers

{kitty_logger-0.2.0.dev3 → kitty_logger-0.2.0.dev5}/src/kitty_logger/_server_main.py

@@ -38,7 +38,10 @@ def _parse_args() -> argparse.Namespace:
     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)
+    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()
 
 
@@ -86,7 +89,14 @@ def main() -> None:
     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
+        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)

{kitty_logger-0.2.0.dev3 → kitty_logger-0.2.0.dev5}/src/kitty_logger/_setup.py

@@ -8,10 +8,11 @@ import os
 import socket
 import subprocess
 import sys
+from dataclasses import replace
 from typing import IO, Literal, TypedDict, TypeGuard, cast
 
 from ._env import ENV_HOST, ENV_LEVEL, ENV_PORT
-from ._formatters import DEFAULT_CONSOLE_FMT, DEFAULT_FILE_FMT
+from ._formatters import FormatPreset, FormatSpec, get_preset
 
 
 class _NotRunningState(TypedDict):
@@ -128,9 +129,8 @@ def _build_server_argv(
     level: int,
     log_file: str | None,
     stream: bool,
-    console_fmt: str,
-    file_fmt: str,
-    datefmt: str | None,
+    console_spec: FormatSpec,
+    file_spec: FormatSpec,
 ) -> list[str]:
     """把 ``setup_logging`` 的参数翻译成服务子进程的命令行参数。"""
     argv = [
@@ -144,16 +144,22 @@ def _build_server_argv(
         "--level",
         str(level),
         "--console-fmt",
-        console_fmt,
+        console_spec.console_fmt,
         "--file-fmt",
-        file_fmt,
+        file_spec.file_fmt,
+        "--console-datefmt",
+        console_spec.datefmt,
+        "--file-datefmt",
+        file_spec.datefmt,
     ]
     if log_file is not None:
         argv += ["--log-file", log_file]
     if stream:
         argv += ["--stream"]
-    if datefmt is not None:
-        argv += ["--datefmt", datefmt]
+    if console_spec.show_msec:
+        argv += ["--console-show-msec"]
+    if file_spec.show_msec:
+        argv += ["--file-show-msec"]
     return argv
 
 
@@ -163,8 +169,11 @@ def setup_logging(
     host: str = "127.0.0.1",
     port: int = 0,
     stream: bool = True,
-    console_fmt: str = DEFAULT_CONSOLE_FMT,
-    file_fmt: str = DEFAULT_FILE_FMT,
+    preset: FormatPreset = "verbose",
+    console_preset: FormatPreset | None = None,
+    file_preset: FormatPreset | None = None,
+    console_fmt: str | None = None,
+    file_fmt: str | None = None,
     datefmt: str | None = None,
 ) -> tuple[str, int]:
     """在主进程里启动跨进程日志服务，返回服务真实绑定到的 ``(host, port)``。
@@ -176,7 +185,9 @@ def setup_logging(
     通过 :func:`kitty_logger.getLogger` 连上来。
 
     控制台输出使用带 ANSI 颜色的 :class:`ColorFormatter`，文件输出使用
-    无颜色的 :class:`FileFormatter`，两者均使用毫秒级时间戳。
+    无颜色的 :class:`FileFormatter`。两侧的格式由四档预置之一决定：
+    ``minimal`` / ``standard`` / ``verbose`` / ``debug``，每档同时封装
+    format 字符串、``datefmt`` 与是否显示毫秒。
 
     幂等：重复调用直接返回已记录的 ``(host, port)``，不会重复启动子进程。
 
@@ -187,9 +198,12 @@ def setup_logging(
                  绑定非 loopback 地址会直接 :class:`ValueError`。
     :param port: 监听端口；``0`` 让 OS 自动选择空闲端口。
     :param stream: 是否同时输出到 ``stderr``。
-    :param console_fmt: 控制台 handler 的 format 字符串。
-    :param file_fmt: 文件 handler 的 format 字符串。
-    :param datefmt: 时间戳的 ``strftime`` 格式；``None`` 走默认值。
+    :param preset: 同时作用于控制台与文件两侧的预置档位。
+    :param console_preset: 仅覆盖控制台侧的档位；不传则沿用 ``preset``。
+    :param file_preset: 仅覆盖文件侧的档位；不传则沿用 ``preset``。
+    :param console_fmt: 进一步覆盖控制台 handler 的 format 字符串。
+    :param file_fmt: 进一步覆盖文件 handler 的 format 字符串。
+    :param datefmt: 进一步覆盖时间戳的 ``strftime`` 格式（同时作用于两侧）。
     :return: 服务真实绑定到的 ``(host, port)``。
 
     .. note::
@@ -229,15 +243,26 @@ def setup_logging(
 
     _check_loopback_only(host)
 
+    # 解析每侧的 preset：单侧 preset 优先于全局 preset；具体的 fmt/datefmt
+    # 参数则在 preset 选定后再做字段级覆盖。
+    console_spec = get_preset(console_preset or preset)
+    file_spec = get_preset(file_preset or preset)
+    if console_fmt is not None:
+        console_spec = replace(console_spec, console_fmt=console_fmt)
+    if file_fmt is not None:
+        file_spec = replace(file_spec, file_fmt=file_fmt)
+    if datefmt is not None:
+        console_spec = replace(console_spec, datefmt=datefmt)
+        file_spec = replace(file_spec, datefmt=datefmt)
+
     argv = _build_server_argv(
         host=host,
         port=port,
         level=level,
         log_file=log_file,
         stream=stream,
-        console_fmt=console_fmt,
-        file_fmt=file_fmt,
-        datefmt=datefmt,
+        console_spec=console_spec,
+        file_spec=file_spec,
     )
     # 把本包所在目录拼进子进程的 ``PYTHONPATH``，保证子进程的解释器能
     # ``import`` 到 ``kitty_logger._server_main``。已经 ``pip install`` 装到

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

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

{kitty_logger-0.2.0.dev3 → kitty_logger-0.2.0.dev5}/tests/test_kitty_logger.py

@@ -111,12 +111,25 @@ 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_non_loopback_raises(tmp_path: Path):
@@ -333,3 +346,44 @@ def test_setup_logging_in_child_is_noop(tmp_path: Path):
         lambda t: f"host={host} port={port}" in t and "kitty.child.0" in t,
     )
     assert "SpawnProcess" in text
+
+
+def test_preset_minimal_writes_short_format(tmp_path: Path):
+    """``minimal`` 档：时间戳到秒、字段只剩 level + message。"""
+    log_path = tmp_path / "app.log"
+    kitty_logger.setup_logging(log_file=str(log_path), stream=False, preset="minimal")
+    kitty_logger.getLogger("m").info("hi-minimal")
+
+    text = _wait_for_lines(log_path, lambda t: "hi-minimal" in t)
+    line = next(line for line in text.splitlines() if "hi-minimal" in line)
+    # minimal 不带毫秒（无 ``.\d{3}``）也不带管道分隔符。
+    assert "|" not in line
+    assert "INFO hi-minimal" in line
+    # 形如 ``HH:MM:SS INFO hi-minimal``，前 8 个字符是时间戳。
+    assert line[2] == ":" and line[5] == ":"
+
+
+def test_preset_debug_includes_thread_name(tmp_path: Path):
+    """``debug`` 档：在 verbose 字段基础上额外带 ``threadName``。"""
+    log_path = tmp_path / "app.log"
+    kitty_logger.setup_logging(log_file=str(log_path), stream=False, preset="debug")
+    kitty_logger.getLogger("d").info("hi-debug")
+
+    _wait_for_lines(log_path, lambda t: "hi-debug" in t and "MainThread" in t)
+
+
+def test_independent_console_and_file_presets(tmp_path: Path):
+    """``console_preset`` / ``file_preset`` 可以分别选档。"""
+    log_path = tmp_path / "app.log"
+    # 控制台 minimal、文件 debug：只校验文件这侧拿到 debug 字段。
+    kitty_logger.setup_logging(
+        log_file=str(log_path),
+        stream=False,
+        console_preset="minimal",
+        file_preset="debug",
+    )
+    kitty_logger.getLogger("ind").info("hi-ind")
+
+    text = _wait_for_lines(log_path, lambda t: "hi-ind" in t and "MainThread" in t)
+    # 文件侧是 debug 档，必含进程名与线程名。
+    assert "MainProcess" in text

kitty_logger-0.2.0.dev3/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.

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

@@ -1,82 +0,0 @@
-"""日志格式化器：控制台版（按字段着色 ANSI）与文件版（无颜色）。
-
-控制台格式化器把不同字段染成不同颜色，便于在终端里快速分辨；
-文件格式化器保持纯文本，避免日志文件被颜色码污染。两者都通过
-:class:`_MillisecondTimeFormatter` 共享毫秒精度的时间戳实现。
-"""
-
-import logging
-import time
-from typing import 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"
-_NAME_COLOR = "\033[38;5;36m"
-_FILE_COLOR = "\033[38;5;45m"
-_FUNC_COLOR = "\033[38;5;208m"
-_RESET = "\033[0m"
-
-# 控制台格式：每个字段独立着色，进程信息排在最前以契合 kitty_logger 的跨进程定位。
-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"
-)
-
-# 文件格式：字段一致，但不带任何 ANSI 颜色码。
-DEFAULT_FILE_FMT = (
-    "%(asctime)s | %(processName)s(%(process)d) | %(name)s | "
-    "%(filename)s:%(lineno)d | %(funcName)s | %(levelname)s | %(message)s"
-)
-
-
-class _MillisecondTimeFormatter(logging.Formatter):
-    """带毫秒精度的时间格式化基类。
-
-    标准库 :meth:`logging.Formatter.formatTime` 在传入 ``datefmt`` 时
-    不会自动拼接毫秒，这里覆写以始终带上 ``.毫秒`` 后缀。
-    """
-
-    @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 颜色。
-
-    实现思路是把颜色码作为属性挂到 ``record`` 上，再在格式串里通过
-    ``%(xxx_color)s ... %(reset)s`` 占位符把颜色串入对应字段，从而让
-    进程名、logger 名、文件位置、函数名、级别各自拥有独立的配色。
-    """
-
-    @override
-    def format(self, record: logging.LogRecord) -> str:
-        record.color = _LEVEL_COLORS.get(record.levelname, "")  # type: ignore[attr-defined]
-        record.proc_color = _PROC_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 颜色码。"""