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

{kitty_logger-0.2.0.dev3/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.dev3
+Version: 0.2.0.dev4
 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.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kitty_logger"
-version = "0.2.0.dev3"
+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.dev3 → 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.dev3"
+__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.dev3 → kitty_logger-0.2.0.dev4}/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.dev4}/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.dev4}/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.dev4/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.dev4
 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.dev4}/tests/test_kitty_logger.py

@@ -333,3 +333,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/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 颜色码。"""