sc92-lib 0.1.0__py3-none-any.whl

sc92_lib/__init__.py

@@ -0,0 +1,39 @@
+"""sc92_lib：单实例文件锁、轮转日志、全局异常钩子（主线程+子线程）、
+一次性 MQTT 发布、YAML 配置文件读写、值转 YAML 文本、工作时段判断。"""
+
+from .check_running_lock import check_running_lock, default_lock_file
+from .init_logging_config import default_log_file, init_logging_config
+from .enable_exception_logging import (
+    enable_exception_logging,
+    handle_global_exception,
+    handle_thread_exception,
+)
+from .mqtt_publisher import MqttPublisher
+from .yaml_config import default_yaml_file, read_yaml, write_yaml
+from .to_yaml import to_yaml
+from .is_worktime import is_worktime
+from .paths import script_dir, script_name
+
+__version__ = "0.1.0"
+# 每次更新功能后，手动把这里改成当时的日期时间（YYYY-MM-DD HH:MM:SS）
+__build_time__ = "2026-11-12 10:55:10"
+
+__all__ = [
+    "__version__",               # 当前包版本号
+    "__build_time__",            # 本版构建时间：YYYY-MM-DD HH:MM:SS（更新功能后手动改）
+    "script_dir",                # 入口脚本所在目录（兼容 exe 与 python -m）
+    "script_name",               # 入口脚本名（不含扩展名，兼容 exe 与 python -m）
+    "init_logging_config",       # 初始化轮转文件日志（debug/info）+ 控制台输出
+    "default_log_file",          # 推导默认日志路径前缀 <脚本目录>/logs/<脚本名>
+    "check_running_lock",        # 单实例文件锁：抢不到锁按策略退出或返回 False
+    "default_lock_file",         # 推导默认锁文件路径 <脚本目录>/<脚本名>.running.lock
+    "handle_global_exception",   # sys.excepthook 实现：主线程未捕获异常写日志
+    "handle_thread_exception",   # threading.excepthook 实现：子线程未捕获异常写日志
+    "enable_exception_logging",  # 一键挂载主线程 + 子线程的全局异常钩子
+    "MqttPublisher",             # 一次性 MQTT 发布器：连接、发一条、断开
+    "read_yaml",                 # 读 YAML 原样返回(不校验顶层类型)，仅文件缺失时写模板并退出
+    "write_yaml",                # 把 dict/list/str/int/float/bool/None 写成 YAML 文件（config 在前，路径可选）
+    "default_yaml_file",         # 推导默认配置文件路径 <脚本目录>/configs/<脚本名>.config.yaml
+    "to_yaml",                   # 把值尽量转成 YAML 文本，失败则原样返回
+    "is_worktime",               # 按星期几 + HHMM 时段判断当前时间是否在工作时间内
+]

sc92_lib/check_running_lock.py

@@ -0,0 +1,73 @@
+"""基于 filelock 的单实例运行检查。"""
+
+import logging
+import sys
+
+from .paths import script_dir, script_name
+
+_held_locks: dict = {}
+
+
+def default_lock_file() -> str:
+    """<脚本目录>/<脚本名>.running.lock
+
+    换目录跑、或者把脚本改名/复制一份，推导出来的就是另一个文件（另一把锁），
+    细节见 check_running_lock 的「单实例的确切含义」。
+    """
+    return str(script_dir() / f"{script_name()}.running.lock")
+
+
+def check_running_lock(lock_file: str | None = None, on_conflict: str = "exit") -> bool:
+    """尝试抢到"本脚本已在运行"这把独占锁。
+
+    lock_file   默认为入口脚本旁边的 <脚本名>.running.lock。
+    on_conflict "exit"（默认）：锁被别人占着时，本进程以退出码 1 结束；
+                "return"：返回 False，由调用方自己决定怎么善后。
+
+    抢到锁返回 True；on_conflict="return" 且被别人占用时返回 False。
+
+    ── 只在脚本开头调用一次 ──
+    锁是"文件"级别的：操作系统认的就是那个文件，跟你写绝对路径、加 ".\\" 前缀还是改
+    大小写都无关。所以同一个进程里第二次抢同一个 lock_file 必然 Timeout —— 会被自己
+    上一次留下的锁当成"别人在跑"，on_conflict="exit" 时当场把自己杀掉。
+    因此：只在 main 开头调一次，别塞进函数/类里，也别对同一个锁文件混用 "exit" 和
+    "return" 两种写法。（抢到的锁靠模块级 _held_locks 留住引用，FileLock 实例被回收
+    就等于解锁，所以必须留住。）
+
+    ── "单实例"的确切含义 ──
+    是"这个目录下的这个脚本名"只允许跑一份：改名、复制一份、挪去别的目录跑，
+    推导出来的默认锁文件名就变了，那是另一把锁，检查绕得过去 —— 这是设计。
+    确实要跨目录/跨脚本名互斥，就显式传同一个绝对 lock_file。
+
+    ── 副作用：锁文件的父目录会被创建 ──
+    filelock 在 acquire() 内部对锁文件所在目录做 mkdir(parents=True, exist_ok=True)
+    （构造 FileLock 对象时不建，实测确认）。传一个不存在的目录不会报错，而是把目录
+    顺手建出来；目录建了就不回收，锁文件本身释放后一般会被删掉。
+
+    锁文件是空文件、纯占位，抢锁失败的一方不会破坏正在持锁的那一份（实测确认）。
+    进程退出时锁由操作系统自动释放。filelock 4.x 以 DELETE_ON_CLOSE 方式打开锁
+    文件，最后一个持有者关闭句柄后文件一般就没了（还有别的线程持着句柄时可能残留；
+    残留与否都别依赖：残留的锁文件不影响下次抢锁）。
+    """
+    from filelock import FileLock, Timeout
+
+    if on_conflict not in ("exit", "return"):
+        raise ValueError(f'on_conflict must be "exit" or "return", got {on_conflict!r}')
+
+    if lock_file is None:
+        lock_file = default_lock_file()
+
+    lock = FileLock(str(lock_file), timeout=0)
+    try:
+        lock.acquire(blocking=False)
+    except Timeout:
+        logging.error(f"脚本正在运行，本次运行退出（锁文件：{lock_file}）")
+        if on_conflict == "exit":
+            sys.exit(1)
+        return False
+
+    # 留住引用，让锁在整个进程存活期间一直被持有（局部变量退出就会被释放），
+    # 设置一个全局字典，将lock作为值放到字典里。字典不释放，lock就不会被释放
+    _held_locks[str(lock_file)] = lock
+    logging.info(f"脚本未运行，继续执行（锁文件：{lock_file}）")
+    return True

sc92_lib/enable_exception_logging.py

@@ -0,0 +1,30 @@
+"""全局未捕获异常钩子：主线程 + 子线程都写进日志。"""
+
+import logging
+import sys
+import threading
+import traceback
+
+
+def handle_global_exception(exc_type, exc_value, exc_traceback) -> None:
+    """sys.excepthook 的实现：把未捕获异常写进日志。"""
+    tb_str = "".join(traceback.format_exception(exc_type, exc_value, exc_traceback))
+    logging.error(f"全局异常捕获：\n{tb_str}")
+
+
+def handle_thread_exception(args) -> None:
+    """threading.excepthook 的实现。
+
+    子线程不受 sys.excepthook 管辖，不挂这个钩子的话，线程里的 traceback 只会打到
+    stderr，永远进不了日志文件。
+    """
+    tb_str = "".join(traceback.format_exception(
+        args.exc_type, args.exc_value, args.exc_traceback))
+    thread_name = getattr(args.thread, "name", "<unknown>")
+    logging.error(f"子线程未捕获异常（线程：{thread_name}）：\n{tb_str}")
+
+
+def enable_exception_logging() -> None:
+    """快捷写法，等价于：sys.excepthook / threading.excepthook = 上面两个钩子。"""
+    sys.excepthook = handle_global_exception
+    threading.excepthook = handle_thread_exception

sc92_lib/init_logging_config.py

@@ -0,0 +1,69 @@
+"""轮转文件日志 + 控制台日志的初始化。"""
+
+import logging
+import logging.handlers
+import pathlib
+import sys
+
+from .paths import script_dir, script_name
+
+_FORMAT = "%(asctime)s [%(levelname)-8s] %(filename)12s:%(lineno)-4d %(funcName)-12s: %(message)s"
+
+
+def default_log_file() -> str:
+    """<脚本目录>/logs/<脚本名>（_debug.log / _info.log 后缀自动加）。"""
+    return str(script_dir() / "logs" / script_name())
+
+
+def init_logging_config(
+    log_file: str | None = None,
+    max_bytes: int = 10 * 1024 * 1024,
+    backup_count: int = 7,
+    force: bool = False,
+) -> None:
+    """配置根日志器：*_debug.log + *_info.log（轮转）+ 控制台。
+
+    log_file 默认为入口脚本旁边的 logs/<脚本名>。
+    如果根日志器已经有 handler（pytest、Jupyter，或别的库先配置过日志），
+    本函数不做任何事，并在 stderr 明确提示一句 —— 以前静默跳过等于
+    "日志一个都没落盘，还不知道为什么"。
+    确实要接管，就传 force=True，会先移除已有的 handler。
+    没有控制台时（pythonw.exe、PyInstaller --noconsole，此时 sys.stderr 为 None），
+    跳过控制台 handler，只留文件日志。
+    """
+    if logging.root.handlers and not force:
+        if sys.stderr is not None:
+            print(
+                "[sc92_lib] 根日志器已有 handler，init_logging_config() 没有生效，"
+                "日志不会写到文件；确认要接管请传 force=True。",
+                file=sys.stderr,
+            )
+        return
+
+    for handler in logging.root.handlers[:]:
+        logging.root.removeHandler(handler)
+
+    if log_file is None:
+        log_file = default_log_file()
+
+    debug_path = pathlib.Path(f"{log_file}_debug.log")
+    info_path = pathlib.Path(f"{log_file}_info.log")
+    debug_path.parent.mkdir(parents=True, exist_ok=True)
+
+    debug_handler = logging.handlers.RotatingFileHandler(
+        debug_path, maxBytes=max_bytes, backupCount=backup_count, encoding="utf-8"
+    )
+    debug_handler.setLevel(logging.DEBUG)
+
+    info_handler = logging.handlers.RotatingFileHandler(
+        info_path, maxBytes=max_bytes, backupCount=backup_count, encoding="utf-8"
+    )
+    info_handler.setLevel(logging.INFO)
+
+    handlers = [debug_handler, info_handler]
+    if sys.stderr is not None:
+        console_handler = logging.StreamHandler(sys.stderr)
+        console_handler.setLevel(logging.INFO)
+        handlers.append(console_handler)
+
+    logging.basicConfig(level=logging.DEBUG, format=_FORMAT, handlers=handlers)

sc92_lib/is_worktime.py

@@ -0,0 +1,129 @@
+"""工作时段判断：按星期几 + HHMM 时段判断当前时间是否在工作时间内。"""
+
+import logging
+import re
+import sys
+from datetime import datetime
+
+_DAY_RE = re.compile(r"[1-7]")  # 单个星期数字：1=周一 … 7=周日
+_PERIOD_RE = re.compile(r"([0-9]{4})-([0-9]{4})")  # 时段："0900-1200"，两端各 4 位数字
+
+
+def is_worktime(worktime_config: dict | None = None) -> bool:
+    """判断当前时间是否在工作时间内。
+
+    1=周一, 7=周日。键只能写单个数字（"3"），或 "起-止" 区间（"1-5"）：区间两端都必须是
+    1-7 且 起 <= 止，不支持跨周（"6-2" 报错退出，请拆成 "6-7" 和 "1" 两行）；
+    同一个星期写多次时以最后一次为准。
+    值是 "HHMM-HHMM" 字符串列表：两端各必须是 4 位数字且 起 <= 止，左闭右开 [起, 止)，
+    所以 "0900-1300" 在 13:00 整就算下班；不支持跨零点（"2200-0200" 报错退出，
+    请拆成 "2200-2400" 和 "0000-0200"）；这天不上班写空列表 []。
+    键或值的格式不合法：logging.error 说清是哪个键、哪个时段、错在哪里，然后 sys.exit(1)，
+    不做任何猜测、不自动补全（整个配置都会校验，不是只校验今天那一行）。
+    配置为空、或者今天没有排班，都返回 False。
+
+    日志：每次调用只写一条 INFO 结论（星期几、几点、命中哪个时段 / 为什么不算）；
+    逐时段的比较细节和时段列表写在 DEBUG，只在 *_debug.log 里，不会刷屏。
+    """
+    weekday_names = {1: "一", 2: "二", 3: "三", 4: "四", 5: "五", 6: "六", 7: "日"}
+
+    if not worktime_config:
+        logging.warning("工作时段配置为空 → False")
+        return False
+
+    if not isinstance(worktime_config, dict):
+        logging.error(
+            f"is_worktime 配置格式错误：worktime_config 是 {type(worktime_config).__name__}，"
+            f"要求形如 {{星期: [\"HHMM-HHMM\", …]}} 的字典，脚本退出"
+        )
+        sys.exit(1)
+
+    expanded = {}
+    for key, periods in worktime_config.items():
+        key_text = str(key).strip()
+
+        # —— 校验键：单个 1-7，或 "起-止" 区间（起 <= 止）——
+        if "-" in key_text:  # 区间写法，例如 "3-5" 表示星期三到星期五
+            head, _, tail = (part.strip() for part in key_text.partition("-"))
+            if not _DAY_RE.fullmatch(head) or not _DAY_RE.fullmatch(tail):
+                logging.error(
+                    f"is_worktime 星期键格式错误：{key_text!r}，区间写法必须是 \"起-止\"，"
+                    f"两端都是 1-7 的单个数字（1=周一 … 7=周日），例如 \"1-5\"，脚本退出"
+                )
+                sys.exit(1)
+            first_day, last_day = int(head), int(tail)
+            if first_day > last_day:
+                logging.error(
+                    f"is_worktime 星期键格式错误：{key_text!r}，起 {first_day} 大于止 {last_day}，"
+                    f"不支持跨周——周六日再加周一请拆成 \"6-7\" 和 \"1\" 两行，脚本退出"
+                )
+                sys.exit(1)
+            days = [str(day) for day in range(first_day, last_day + 1)]
+        elif _DAY_RE.fullmatch(key_text):
+            days = [key_text]
+        else:
+            logging.error(
+                f"is_worktime 星期键格式错误：{key_text!r}，键只能是 1-7 的单个数字"
+                f"（1=周一 … 7=周日），或 \"1-5\" 这种起不大于止的区间，脚本退出"
+            )
+            sys.exit(1)
+
+        # —— 校验值：空列表，或 "HHMM-HHMM" 字符串列表（起 <= 止）——
+        if not isinstance(periods, (list, tuple)):
+            logging.error(
+                f"is_worktime 时段格式错误：{key_text!r} 的值是 {type(periods).__name__}，"
+                f"必须是 \"HHMM-HHMM\" 字符串组成的列表，这天不上班写空列表 []，脚本退出"
+            )
+            sys.exit(1)
+
+        for period in periods:
+            matched = _PERIOD_RE.fullmatch(period) if isinstance(period, str) else None
+            if matched is None:
+                logging.error(
+                    f"is_worktime 时段格式错误：{key_text!r} 里的 {period!r}"
+                    f"{'' if isinstance(period, str) else f'（{type(period).__name__}）'}，"
+                    f"时段必须是 \"HHMM-HHMM\"，两端各 4 位数字，例如 \"0900-1200\"，脚本退出"
+                )
+                sys.exit(1)
+            if int(matched.group(1)) > int(matched.group(2)):
+                logging.error(
+                    f"is_worktime 时段格式错误：{key_text!r} 里的 {period!r}，"
+                    f"起 {matched.group(1)} 大于止 {matched.group(2)}，不支持跨零点——"
+                    f"22:00 上到次日 02:00 请拆成 \"2200-2400\" 和 \"0000-0200\"，脚本退出"
+                )
+                sys.exit(1)
+
+        for day in days:
+            expanded[day] = periods
+
+    now = datetime.now()
+    weekday = str(now.weekday() + 1)
+    current = now.hour * 100 + now.minute
+    today_periods = expanded.get(weekday, [])
+    day_label = f"星期{weekday_names[int(weekday)]} {now:%H:%M}"
+
+    if not today_periods:
+        logging.info(f"{day_label} 今天没有排班 → False")
+        return False
+
+    logging.debug(f"{day_label} 时段列表 = {today_periods}")
+
+    for period in today_periods:
+        # 能走到这里说明上面已整体校验通过，period 必定是 "HHMM-HHMM"，可以放心拆
+        start, end = period.split("-")
+        start_value, end_value = int(start), int(end)
+        hit = start_value <= current < end_value
+        logging.debug(
+            f"{day_label} 检查时段 {period} → "
+            f"{start_value:04d} <= {current:04d} < {end_value:04d} → "
+            f"{'命中' if hit else '未命中'}"
+        )
+        if hit:
+            logging.info(f"{day_label} 命中时段 {period} → True")
+            return True
+
+    logging.info(
+        f"{day_label} 未命中任何时段 → False"
+        f"（今天排班：{'、'.join(today_periods)}）"
+    )
+    return False

sc92_lib/mqtt_publisher.py

@@ -0,0 +1,92 @@
+"""MQTT 发布器。凭据只能来自构造函数的显式参数。
+
+绝不要把 host / username / password / topic 硬编码进这个源文件（本包会发布到
+PyPI，源码里的任何真实凭据都会公开）。推荐做法：放在你自己的 YAML 配置文件里
+（见 read_yaml），再把读到的值传进 MqttPublisher(...)。
+"""
+
+import logging
+
+import paho.mqtt.client as mqtt
+
+
+class MqttPublisher:
+    """一次性 MQTT 发布器：连接、发一条消息、断开。
+
+    逻辑保持朴素：connect -> loop_start -> publish -> wait_for_publish -> 收尾。
+    connect_timeout / publish_timeout 直接用 paho 自带的超时属性，不再自己开线程。
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int = 1883,
+        username: str | None = None,
+        password: str | None = None,
+        topic: str | None = None,
+        qos: int = 2,
+        client_id: str | None = None,
+        connect_timeout: float = 5,
+        publish_timeout: float = 10,
+    ):
+        self.host = host
+        self.port = int(port)
+        self.username = username
+        self.password = password
+        self.topic = topic
+        self.qos = int(qos)
+        self.client_id = client_id
+        self.connect_timeout = connect_timeout
+        self.publish_timeout = publish_timeout
+
+        missing = [n for n, v in (("host", self.host), ("topic", self.topic)) if not v]
+        if missing:
+            raise ValueError(
+                f"缺少 MQTT 参数: {', '.join(missing)}。请在调用脚本中显式传入，"
+                "凭据建议存放在本地 YAML 配置文件里用 read_yaml() 读取"
+                "（本库源码与 PyPI 发布物中不包含任何真实凭据）。"
+            )
+
+    def publish(self, msg, topic: str | None = None, qos: int | None = None) -> bool:
+        """发布一条消息；只有 broker 真的收下了才返回 True。
+
+        QoS 1/2：True 表示 broker 已确认收到。
+        QoS 0 本身没有确认机制：True 只表示已写入 socket。
+        任何连接失败、超时、异常都记 logging.error 并返回 False，不抛出。
+        """
+        topic = topic or self.topic
+        qos = self.qos if qos is None else int(qos)
+        payload = msg if isinstance(msg, (bytes, bytearray)) else str(msg)
+
+        client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=self.client_id)
+        if self.username is not None:
+            client.username_pw_set(self.username, self.password)
+        # paho 内部的 socket.create_connection 用的就是这个属性，能真正限制 TCP 连接耗时
+        client.connect_timeout = self.connect_timeout
+
+        try:
+            logging.info(f"正在连接 MQTT Broker {self.host}:{self.port} ...")
+            client.connect(self.host, self.port, keepalive=60)
+            client.loop_start()
+
+            info = client.publish(topic, payload=payload, qos=qos)
+            info.wait_for_publish(timeout=self.publish_timeout)
+            if info.rc == mqtt.MQTT_ERR_SUCCESS and info.is_published():
+                logging.info(f"消息已发布到主题 '{topic}' (QoS {qos}): {payload}")
+                return True
+            logging.error(
+                f"发布未被 broker 确认（超时 {self.publish_timeout}s）：rc={info.rc} 主题={topic}"
+            )
+            return False
+        except Exception as e:
+            logging.error(f"MQTT 发布发生异常: {e}")
+            return False
+        finally:
+            try:
+                client.disconnect()
+            except Exception:
+                pass
+            try:
+                client.loop_stop()
+            except Exception:
+                pass

sc92_lib/paths.py

@@ -0,0 +1,57 @@
+"""解析当前运行脚本所在目录与文件名，兼容 PyInstaller 打包后的 exe。"""
+
+import pathlib
+import sys
+
+
+def _is_frozen() -> bool:
+    return getattr(sys, "frozen", False)
+
+
+def _module_entry() -> str | None:
+    """以模块方式启动时返回模块入口名，普通独立脚本返回 None。
+
+    `python -m pkg[.mod]`（以及手动去跑某个包的 __main__.py）没有自己的入口脚本
+    名：sys.argv[0] 只会给到一个 "__main__.py"，而真正的模块通常躺在 site-packages
+    里 —— 那里不该被写日志/锁/配置文件。所以这些情况下返回模块名 / 包名。
+    """
+    if _is_frozen():
+        return None
+    spec = getattr(sys.modules.get("__main__"), "__spec__", None)
+    name = getattr(spec, "name", None)
+    if name and name != "__main__":
+        suffix = ".__main__"
+        return name[: -len(suffix)] if name.endswith(suffix) else name
+    first = pathlib.Path(sys.argv[0])
+    if first.stem == "__main__" and first.parent != pathlib.Path():
+        return first.resolve().parent.name
+    return None
+
+
+def script_dir() -> pathlib.Path:
+    """入口脚本所在目录（被 PyInstaller 打包后是 exe 所在目录）。
+
+    `python -m ...` 跑的是模块不是脚本，所以用当前工作目录：模块自己的目录
+    往往就是 site-packages。
+    """
+    if _is_frozen():
+        return pathlib.Path(sys.executable).parent
+    if _module_entry() is not None:
+        return pathlib.Path.cwd()
+    first = pathlib.Path(sys.argv[0])
+    if not first.name or first.name == "-c":
+        return pathlib.Path.cwd()
+    return first.resolve().parent
+
+
+def script_name() -> str:
+    """入口脚本的文件名（不含扩展名）：打包后取 exe 名，`python -m` 取模块/包名。"""
+    if _is_frozen():
+        return pathlib.Path(sys.executable).stem
+    module = _module_entry()
+    if module is not None:
+        return module
+    stem = pathlib.Path(sys.argv[0]).stem
+    if not stem or stem == "-c":
+        return pathlib.Path.cwd().name
+    return stem

sc92_lib/to_yaml.py

@@ -0,0 +1,91 @@
+"""把值转成 YAML 文本；转换失败就原样返回。"""
+
+import json
+import logging
+
+import yaml
+
+
+def _safe_repr(value: object) -> str:
+    """尽量把原值转成可读文本，repr/str 都失败时给一个占位说明。"""
+    try:
+        return repr(value)
+    except Exception:
+        pass
+    try:
+        return str(value)
+    except Exception:
+        return f"<{type(value).__name__} 对象，repr/str 均失败>"
+
+
+def to_yaml(value: object) -> object:
+    """尽可能输出 YAML 字符串，失败则原样返回。
+
+    只处理两类输入：
+
+    - dict / list：直接 safe_dump。
+    - 其它类型：先 str(value)，再 json.loads；只有解析结果是 dict / list
+      才 safe_dump。
+
+    任何一步失败都返回原值，不抛异常。成功和失败都写 logging.debug。
+    """
+
+    # 字典、列表直接转，对于特殊的字典（例如字典内嵌套对象），依旧无法转换为yaml。转失败直接return
+    if isinstance(value, (dict, list)):
+        try:
+            result = yaml.safe_dump(
+                value,
+                allow_unicode=True,
+                sort_keys=False,
+                default_flow_style=False,
+            )
+        except Exception as exc:
+            logging.debug(
+                f"to_yaml 无法转换 {type(value).__name__} 对象，"
+                f"原样返回（{type(exc).__name__}: {exc}）：{_safe_repr(value)}"
+            )
+            return value
+        log_text = result.rstrip("\n")
+        logging.debug(f"to_yaml 转换结果：\n{log_text}")
+        return result
+
+    # 其他类型先转字符串，失败直接原样返回
+    try:
+        text = str(value)
+    except Exception as exc:
+        logging.debug(
+            f"to_yaml 无法把 {type(value).__name__} 对象转成字符串，"
+            f"原样返回（{type(exc).__name__}: {exc}）：{_safe_repr(value)}"
+        )
+        return value
+    # 其他类型转字符串再用json解析，失败直接原样返回
+    try:
+        parsed = json.loads(text)
+    except Exception:
+        logging.debug(f"to_yaml JSON 解析字符串失败，原样返回：{_safe_repr(value)}")
+        return value
+
+    if not isinstance(parsed, (dict, list)):
+        logging.debug(
+            f"to_yaml JSON 结果不是 dict/list（{type(parsed).__name__}），"
+            f"原样返回：{_safe_repr(value)}"
+        )
+        return value
+    # 其他类型转字符串再用json解析再用yaml解析，失败直接原样返回
+    try:
+        result = yaml.safe_dump(
+            parsed,
+            allow_unicode=True,
+            sort_keys=False,
+            default_flow_style=False,
+        )
+    except Exception as exc:
+        logging.debug(
+            f"to_yaml 无法转换 JSON 结果，"
+            f"原样返回（{type(exc).__name__}: {exc}）：{_safe_repr(value)}"
+        )
+        return value
+
+    log_text = result.rstrip("\n")
+    logging.debug(f"to_yaml 转换结果：\n{log_text}")
+    return result

sc92_lib/yaml_config.py

@@ -0,0 +1,141 @@
+"""YAML 配置文件读写。
+
+原则：只有两种情况会停下等人工，其余一律原样返回。
+文件不存在           -> 按 default_config 写出模板后 exit(1)，让用户检查修改再重跑。
+文件损坏（非 UTF-8 / -> logging.error 后 exit(1)，坏文件原样保留交人工处置。
+ YAML 语法坏）
+其余情况             -> 直接返回 yaml.safe_load 的结果，不校验顶层是不是 dict
+                       （可以是 dict / list / 标量 / None / {}）。
+写文件               -> 原子落盘：先写同目录 .tmp 再 os.replace 换名，
+                        崩溃/断电都不会把已有配置截断成半个 YAML。
+"""
+
+import logging
+import os
+import pathlib
+import sys
+
+import yaml
+
+from .paths import script_dir, script_name
+
+
+def default_yaml_file() -> str:
+    """<脚本目录>/configs/<脚本名>.config.yaml（和日志一样各自归到子目录里）。"""
+    return str(script_dir() / "configs" / f"{script_name()}.config.yaml")
+
+
+def write_yaml(config: object,
+               config_file: str | pathlib.Path | None = None) -> None:
+    """把 config 写成 YAML 文件（utf-8，中文与插入顺序保留）。
+
+    config 必填、位置在前，只接受这几种类型，直接 safe_dump：
+        dict / list / str / int / float / bool / None
+    其它类型（如 tuple / set / 自定义对象）视为格式不正确，logging.error 后 exit(1)，
+    交人工处理；safe_dump 本身抛异常也同样记错误后 exit(1)。
+
+    config_file 可省略，默认为 <脚本目录>/configs/<脚本名>.config.yaml。
+    用 safe_dump：保证写出的文件 read_yaml()（safe_load）一定能读回。
+
+    落盘是原子的：先写同目录的 <文件名>.tmp 并 fsync，再用 os.replace 换成正式名字。
+    所以就算写到一半被强杀、崩溃或断电，目标文件仍是上一次的完整内容，不会出现
+    "截断的半个 YAML 把原配置毁掉"；中途失败留下的 .tmp 由 finally 清掉（被强杀或断电
+    来不及跑 finally 时会残留一个 .tmp，下次写入直接覆盖，不影响正确性）。
+    tmp 必须和目标同目录 —— 跨盘符的 replace 不保证原子，所以不复用系统临时目录。
+
+    Windows 特例：目标文件被别的程序以"不共享删除"的方式开着时（实测记事本、
+    PowerShell 都不挡，只有另一个 python 进程 open() 挂着句柄才挡），os.replace 会抛
+    PermissionError。这时记一条 WARNING 并退回直接覆盖写：这一趟没有原子保护，
+    但保证配置照样存得下去。连直接写也失败（真没权限/磁盘问题）则异常照常抛出。
+    """
+    if not isinstance(config, (dict, list, str, int, float, bool, type(None))):
+        logging.error(
+            f"write_yaml 的 config 类型不支持：{type(config).__name__}，"
+            f"只接受 dict/list/str/int/float/bool/None，请人工介入后重新运行，脚本退出"
+        )
+        sys.exit(1)
+
+    try:
+        text = yaml.safe_dump(
+            config, allow_unicode=True, sort_keys=False, default_flow_style=False
+        )
+    except Exception as exc:
+        logging.error(
+            f"write_yaml 转成 YAML 失败：{type(exc).__name__}: {exc}，"
+            f"请人工介入后重新运行，脚本退出"
+        )
+        sys.exit(1)
+
+    # 顶层是裸标量时 safe_dump 会在结尾补 "..."+换行 结束标记，去掉让文件更干净
+    if text.endswith("\n...\n"):
+        text = text[: -len("\n...\n")] + "\n"
+
+    if config_file is None:
+        config_file = default_yaml_file()
+    path = pathlib.Path(config_file)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # 原子落盘：写同目录临时文件 -> flush + fsync -> os.replace 换名。
+    # 中途被强杀/断电时，目标文件保持上一次的完整内容，不会留下半截 YAML。
+    tmp = path.with_name(path.name + ".tmp")
+    try:
+        with tmp.open("w", encoding="utf-8") as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        try:
+            os.replace(tmp, path)
+        except PermissionError as exc:
+            # Windows 上目标文件被别的程序以"不共享删除"的方式打开时，改名会被拒
+            # （实测：记事本、PowerShell 连 -Wait 都不挡；只有另一个 python open() 挂着句柄才挡）。
+            # 保存这件事还得继续，所以退回改前的直接覆盖写 —— 这一趟没有原子保护，但功能不丢。
+            logging.warning(
+                f"配置文件被占用，原子替换失败（WinError {exc.winerror}），"
+                f"退回直接覆盖写入: {path}"
+            )
+            with path.open("w", encoding="utf-8") as f:
+                f.write(text)
+                f.flush()
+                os.fsync(f.fileno())
+    finally:
+        tmp.unlink(missing_ok=True)  # 成功时 tmp 已被 replace 走，这步是空操作
+    logging.info(f"配置已写入: {path}")
+
+
+def read_yaml(config_file: str | pathlib.Path | None = None,
+              default_config: dict = {}) -> object:
+    """把 YAML 配置文件读成 Python 值。只有「文件不存在」和「文件损坏」会停下等人工，
+    其余一律把 yaml.safe_load 的结果原样返回，不校验顶层类型。
+
+    config_file      默认为 <脚本目录>/configs/<脚本名>.config.yaml。
+    文件不存在       -> 按 default_config 写出模板，logging.error，exit(1) 等人工复核。
+    加载 / 解析失败  -> logging.error（坏文件原样留着交人工处置），exit(1)。
+    其余             -> 原样返回 safe_load 的结果：dict / list / str / int / float /
+                       bool / None / {}（空文件、纯注释、null 都归这里）。
+
+    default_config 默认 {}，仅在「文件不存在」写模板时用到。写模板后脚本立刻退出，
+    所以直接把 default_config 交给 write_yaml，无需深拷贝。
+    """
+    if config_file is None:
+        config_file = default_yaml_file()
+    path = pathlib.Path(config_file)
+
+    if not path.is_file():
+        write_yaml(default_config, path)
+        logging.error(
+            f"配置文件不存在: {path}，已按默认配置生成模板，请检查修改后重新运行本脚本"
+        )
+        sys.exit(1)
+
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            loaded = yaml.safe_load(f)
+    except (UnicodeDecodeError, yaml.YAMLError) as exc:
+        logging.error(
+            f"配置文件加载/解析失败: {path}，错误信息: {exc}，"
+            f"坏文件原样保留，请人工处置后重新运行，脚本退出"
+        )
+        sys.exit(1)
+
+    logging.info(f"配置已加载: {path}")
+    return loaded

sc92_lib-0.1.0.dist-info/METADATA

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: sc92-lib
+Version: 0.1.0
+Summary: 个人自用工具箱：单实例文件锁、轮转日志、全局异常钩子、MQTT 发布、YAML 配置读写、值转 YAML 文本、工作时段判断
+Author: sc92
+License-Expression: MIT
+Keywords: filelock,logging,mqtt,yaml,worktime,utility
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: filelock>=4.0
+Requires-Dist: paho-mqtt>=2.0
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# sc92-lib
+
+从日常脚本里抽出来的个人自用工具箱：**单实例文件锁、轮转日志、全局异常钩子（主线程 +
+子线程）、一次性 MQTT 发布、YAML 配置读写、值转 YAML 文本、工作时段判断**。
+
+默认路径全部从入口脚本推导，所以典型用法**一个参数都不用传**；打包成 exe 之后照样写在
+exe 旁边，不会往 `site-packages` 里丢文件。
+
+出错风格是**大声停住等人工**，不静默兜底：绝大多数失败都是 `logging.error` 之后
+`sys.exit(1)`，只有 `to_yaml()` 和 `MqttPublisher.publish()` 这两个刻意做成"永不抛异常"。
+
+- 版本 `0.1.0`，构建时间 `2026-11-12 10:55:10`（对应 `__version__` / `__build_time__`）
+- Python >= 3.11；依赖 `filelock>=4.0`、`paho-mqtt>=2.0`、`PyYAML>=6.0`
+
+## 安装
+
+```bash
+pip install sc92-lib
+```
+
+用国内镜像时注意：清华源可能比官方 PyPI 慢一两个版本，装不到就先切官方源
+（`pip install -i https://pypi.org/simple sc92-lib`）。
+
+## 快速开始（放在任意脚本开头）
+
+```python
+import logging
+from sc92_lib import (
+    init_logging_config,        # ① 轮转日志 + 控制台
+    check_running_lock,         # ② 单实例锁
+    enable_exception_logging,   # ③ 未捕获异常 -> 写日志
+)
+
+init_logging_config()       # logs/<脚本名>_debug.log / _info.log
+check_running_lock()        # 脚本旁边的 <脚本名>.running.lock；别人在跑就退出码 1
+enable_exception_logging()
+
+logging.info("main started")
+```
+
+顺序必须是 ①→②→③：锁和 YAML 都用 `logging.info/error` 汇报结果，日志没先初始化，
+INFO 会被根日志器的默认级别丢掉（只有 ERROR 还能靠 `logging.lastResort` 兜到 stderr）。
+
+上面这些片段就是本包的全部对外用法；我自己在用的全流程演示脚本（每个功能、每种写法都
+跑一遍）**不随 wheel/sdist 发布**，装完的包里找不到它，是正常的。
+
+## 什么情况下脚本会 `exit(1)`
+
+| 触发点 | 日志 |
+|---|---|
+| `check_running_lock()` 没抢到锁（`on_conflict="exit"`，默认） | ERROR |
+| `read_yaml()` 配置文件不存在（先写模板再退） | ERROR |
+| `read_yaml()` 配置文件非 UTF-8 / YAML 语法坏 | ERROR |
+| `write_yaml()` 的 config 类型不支持、或 `safe_dump` 失败 | ERROR |
+| `is_worktime()` 的键或值写法不合法（不猜、不补全） | ERROR |
+| 未捕获异常 | ERROR（钩子只记日志，退出码 1 是解释器给的） |
+
+`to_yaml()`、`MqttPublisher.publish()` 不参与这个约定：它们只返回原值 / `False`，绝不退出。
+
+## 模块结构
+
+文件名按该模块的**核心功能**命名，公开 API 一律从包根 `sc92_lib` 导入。
+
+| 文件 | 导出 |
+|---|---|
+| `paths.py` | `script_dir()` `script_name()`（其它模块的默认路径都靠它俩） |
+| `init_logging_config.py` | `init_logging_config()` `default_log_file()` |
+| `check_running_lock.py` | `check_running_lock()` `default_lock_file()` |
+| `enable_exception_logging.py` | `enable_exception_logging()` `handle_global_exception` `handle_thread_exception` |
+| `yaml_config.py` | `read_yaml()` `write_yaml()` `default_yaml_file()` |
+| `to_yaml.py` | `to_yaml()` |
+| `is_worktime.py` | `is_worktime()` |
+| `mqtt_publisher.py` | `MqttPublisher` |
+
+## 1. 默认路径怎么来的：`script_dir()` / `script_name()`
+
+锁、日志、配置三样的默认位置都是 `<script_dir()>/<子目录>/<script_name()>.…`。
+
+| 启动方式 | `script_name()` | `script_dir()` |
+|---|---|---|
+| `python D:\a\b\tool.py` | `tool` | `D:\a\b` |
+| PyInstaller 打包的 `tool.exe` | `tool` | exe 所在目录 |
+| `python -m pkg`（跑的是 `pkg/__main__.py`） | `pkg`（自动去掉 `.__main__`） | **当前工作目录**（不往 `site-packages` 写） |
+| `python -m pkg.mod`（模块自己带 `if __name__ == "__main__"`） | `pkg.mod`（原样，带点） | 当前工作目录 |
+| `python -c "…"` | 当前目录名 | 当前工作目录 |
+| 管道喂给 `python -` | `-` | 当前工作目录 |
+
+```python
+from sc92_lib import script_dir, script_name
+script_dir() / "data" / "x.txt"     # 返回 pathlib.Path，可以直接用 / 拼
+```
+
+## 2. 日志：`init_logging_config()`
+
+```python
+init_logging_config()                                     # 全默认
+init_logging_config(log_file=r"D:\somewhere\logs\myapp")   # 指定前缀
+init_logging_config(max_bytes=50 * 1024 * 1024, backup_count=30)
+init_logging_config(force=True)                           # 强行接管已有 handler
+```
+
+- 一次调用得到 `<前缀>_debug.log`（DEBUG 全量）+ `<前缀>_info.log`（INFO 及以上）+ 控制台
+  （stderr，INFO 及以上），默认每个 10 MB、留 7 份备份。
+- 默认前缀是 `<脚本目录>/logs/<脚本名>`，目录自动创建。
+- **根日志器已经有 handler 时（pytest、Jupyter、或别的库先配置过）本函数不做任何事**，
+  只往 stderr 提示一句 —— 因为静默失效等于"日志一个都没落盘，还不知道为什么"。
+  确实要接管就传 `force=True`，它会先移除已有 handler。
+- 没有控制台时（`pythonw.exe`、PyInstaller `--noconsole`，此时 `sys.stderr is None`）
+  自动跳过控制台 handler，只留文件日志。
+- 格式：`时间 [级别] 文件名:行号 函数名: 消息`。
+- 嫌第三方库吵就单独抬级别，paho 2.x 的内部 logger 名是 `paho.mqtt.client`：
+  `logging.getLogger("paho.mqtt.client").setLevel(logging.WARNING)`。
+
+## 3. 单实例锁：`check_running_lock()`
+
+```python
+check_running_lock()                     # 默认 <脚本名>.running.lock，抢不到就 exit(1)
+if not check_running_lock(lock_file=r"D:\tmp\myapp.lock", on_conflict="return"):
+    logging.warning("已有实例在运行，本次退出")     # 自己决定怎么善后
+    raise SystemExit
+```
+
+- **只在脚本开头调用一次。** 锁按"文件"判定，同一进程里第二次抢同一个 `lock_file`
+  必然失败（哪怕路径写法不同、加了 `.\` 或改了大小写 —— 实测都一样），于是被自己
+  上一次留下的锁当成"别人在跑"而当场退出。
+- **"单实例"的含义是"这个目录下的这个脚本名只跑一份"**：改名、复制一份、换目录跑
+  就是另一把锁，检查绕得过去 —— 这是设计。要跨目录互斥就显式传同一个绝对路径。
+- filelock 在 `acquire()` 时会顺手创建锁文件的**父目录**（构造对象时不建），传个不存在
+  的目录不会报错；目录不会被回收。
+- 锁文件是 **0 字节空文件**，纯占位。持锁期间别去读它 —— 实测同一进程和别的进程读都是
+  `PermissionError`。抢锁失败的一方不会破坏正在持锁的那一份。
+- 进程退出（正常结束、`sys.exit`、未捕获异常都算）时操作系统随句柄一起释放锁。
+  filelock 4.x 以 DELETE_ON_CLOSE 打开，最后一个持有者关句柄后文件一般就消失了；
+  多线程里还有别的句柄开着时可能残留。**别依赖锁文件是否存在**：残留不影响下次抢锁。
+
+## 4. 未捕获异常：`enable_exception_logging()`
+
+```python
+enable_exception_logging()
+# 等价于：
+#   sys.excepthook = handle_global_exception
+#   threading.excepthook = handle_thread_exception
+```
+
+子线程不受 `sys.excepthook` 管辖，不挂 `threading.excepthook` 的话线程里的 traceback 只会
+打到 stderr，永远进不了日志文件 —— 所以两个都挂。
+
+注意：`sys.exit()` / `SystemExit` / `os._exit()` 不算未捕获异常，不会走钩子；
+日志本身写不出去（例如盘满）时，Python 只会抱怨一句 `Error in sys.excepthook`。
+
+## 5. YAML 配置：`read_yaml()` / `write_yaml()`
+
+```python
+from sc92_lib import read_yaml, write_yaml
+
+cfg = read_yaml(default_config={"服务器": "127.0.0.1", "端口": 8080})
+# 首次运行：在脚本旁生成 configs/<脚本名>.config.yaml，提示后以退出码 1 结束
+cfg["端口"] = 9090
+write_yaml(cfg)                 # 写回同一个默认文件（config 在前，路径可选在后）
+```
+
+**`read_yaml(config_file=None, default_config={})`**
+
+- 默认路径 `<脚本目录>/configs/<脚本名>.config.yaml`。
+- 文件不存在 → 按 `default_config` 写出模板 + ERROR + `exit(1)`，让你检查修改后再跑
+  （**故意**的，不是崩溃）。
+- 非 UTF-8（记事本存成 ANSI/GBK）/ YAML 语法坏 → ERROR + `exit(1)`，坏文件原样保留交人工。
+- 其余情况把 `yaml.safe_load` 的结果**原样返回**，不校验顶层类型：`dict` / `list` / 标量 /
+  `None` / `{}` 都可能，空文件和纯注释都返回 `None`。需要当 dict 用就自己收窄。
+
+**`write_yaml(config, config_file=None)`**
+
+- `config` 必填、位置在前，只接受 `dict` / `list` / `str` / `int` / `float` / `bool` / `None`；
+  `tuple` / `set` / `date` / 自定义对象一律 ERROR + `exit(1)`。
+- 用 `safe_dump` + `allow_unicode` + `sort_keys=False`：中文和插入顺序保留，且写出的文件
+  `read_yaml()` 必定读得回来。顶层是裸标量时会去掉 YAML 的 `...` 结束标记。
+- **原子落盘**：先写同目录 `<文件名>.tmp` 并 `fsync`，再用 `os.replace` 换成正式名字。
+  所以写到一半被强杀 / 崩溃 / 断电，目标文件仍是上一次的完整内容，不会出现"半截 YAML
+  把原配置毁掉"。异常路径由 `finally` 清掉 `.tmp`；被强杀或断电来不及跑 `finally` 时会
+  残留一个 `.tmp`，下次写入直接覆盖，不影响正确性。
+- **Windows 特例**：目标文件被别的进程以"不共享删除"方式开着时，改名会被拒
+  （实测：记事本、PowerShell 都不挡，只有另一个 Python 进程 `open()` 挂着句柄才挡）。
+  这时记一条 WARNING 并**退回直接覆盖写** —— 这一趟没有原子保护，但保证配置照样存得下。
+  连直接写也失败（真没权限 / 磁盘问题）则异常照常抛出。
+
+## 6. 值转 YAML 文本：`to_yaml()`
+
+```python
+to_yaml({"姓名": "张三", "年龄": 25})     # "姓名: 张三\n年龄: 25\n"
+to_yaml('{"姓名": "李四", "年龄": 30}')   # "姓名: 李四\n年龄: 30\n"
+to_yaml("[1, 2, 3]")                      # "- 1\n- 2\n- 3\n"
+
+to_yaml("普通字符串")                      # 原字符串（JSON 解析失败）
+to_yaml("123")                             # 原字符串（JSON 标量，不是 dict/list）
+to_yaml("姓名: 王五\n年龄: 40")            # 原字符串（不按 YAML 解析）
+to_yaml(object())                          # 原对象（是同一个对象）
+```
+
+规则：`dict` / `list` 直接 `safe_dump`；其它类型先 `str(value)` 再 `json.loads`，只有解析
+结果是 dict/list 才 dump；**任一步失败都原样返回入参，绝不抛异常**。成功和失败都写
+`logging.debug`（失败那条会尽量带上原值的 repr）。
+
+本函数**不解析 YAML 文本**，也不会把 `"123"`、`'"abc"'` 这类 JSON 标量转成 YAML；
+pandas 的 `str(df)` 不是 JSON，也会原样返回 —— 要转就先传 `df.to_dict()` / `df.to_json()`。
+返回的 YAML 文本保留 `safe_dump` 自带的末尾换行（`print` 会多一个空行，可用 `end=""`）。
+
+## 7. 工作时段判断：`is_worktime()`
+
+```python
+from sc92_lib import is_worktime
+
+工作时间 = {
+    "1-5": ["0900-1200", "1330-1800"],   # 周一到周五，两段班
+    "6":   ["0900-1200"],                # 周六上午
+    "7":   [],                           # 周日休息
+}
+is_worktime(工作时间)     # True / False
+is_worktime()            # False（没给配置）
+```
+
+- **键**：`1`=周一 … `7`=周日，只能是单个数字或 `"起-止"` 区间（两端都是 1–7 且 **起 ≤ 止**）。
+  **不支持跨周**：`"6-2"` 报错退出，周六日再加周一请拆成 `"6-7"` 和 `"1-2"`。
+  同一个星期写多次时以**最后一次**为准。
+- **值**：`"HHMM-HHMM"` 字符串列表，横杠两端**各必须是 4 位数字**且 **起 ≤ 止**；
+  这天不上班写空列表 `[]`。时段**左闭右开** `[起, 止)`，所以 `"0900-1300"` 在 13:00 整算下班。
+- **写法不合法**（键、值任何一个）→ ERROR 说清是哪个键、哪个时段、错在哪，然后 `exit(1)`。
+  不猜、不补全（不会把 `"900"` 补成 `"0900"`，也不会把裸字符串当成单元素列表）。
+  **整个配置都会校验**，不是只看今天那一行 —— 周日写错了，周二运行同样当场退出。
+- 传 `None` 或 `{}` → WARNING 后返回 `False`；今天没排班 → `False`。
+- **不支持跨零点**：`"2200-0200"` 报错退出，22:00 上到次日 02:00 请在 `"1-5"` 写
+  `"2200-2400"`、在 `"2-6"` 写 `"0000-0200"`。
+- 只管形状不管语义：`"2400-2500"`、`"0961"` 这种 4 位数字但不是合法时刻的写法会放行，
+  然后因为永远匹配不上而一直返回 `False`。
+
+```python
+is_worktime({"6-2": ["0900-1200"]})    # ERROR 起 6 大于止 2，不支持跨周 → exit(1)
+is_worktime({"1-8": ["0900-1200"]})    # ERROR 两端都要是 1-7 的数字 → exit(1)
+is_worktime({"1": [900]})              # ERROR 900 是 int，不是 "HHMM-HHMM" 字符串 → exit(1)
+is_worktime({"1": ["09-17"]})          # ERROR 横杠两端各要 4 位数字 → exit(1)
+is_worktime({"1": ["1200-0900"]})      # ERROR 起大于止，不支持跨零点 → exit(1)
+```
+
+日志：每次调用**只写一条 INFO 结论**（例：`星期二 10:30 命中时段 0900-1200 → True`），
+时段列表和逐时段比较过程写在 DEBUG，只进 `*_debug.log`，不会刷屏。
+
+## 8. MQTT 发布：`MqttPublisher`
+
+凭据**只从构造函数的显式参数来**，源码里没有任何硬编码默认值、也不读环境变量 ——
+放在你自己的 `configs/<脚本名>.config.yaml` 里，用 `read_yaml()` 读出来再传进来。
+（本包会发布到 PyPI，源码里的任何真实凭据都会公开。）
+
+```python
+from sc92_lib import MqttPublisher, read_yaml
+
+server = read_yaml()["mqtt服务器"]           # 嵌套字典
+pub = MqttPublisher(host=server["地址"], port=server["端口"],
+                    username=server["用户名"] or None,      # 留空 → None = 匿名连接
+                    password=server["密码"] or None,
+                    topic=server["主题"], qos=server["QoS"])
+pub.publish("hello")                              # 用实例上的 topic/qos
+pub.publish("hello", topic="other/t", qos=1)      # 单次调用覆盖
+```
+
+流程刻意保持朴素：`connect` → `loop_start` → `publish` → `wait_for_publish` → 收尾
+`disconnect` / `loop_stop`，一条消息一次连接。要知道的边界：
+
+- 返回值：QoS 1/2 拿到 broker 的 PUBACK/PUBCOMP 才算 `True`；**QoS 0 没有确认机制**，
+  `True` 只表示已写入 socket。连不上、密码被拒、发不出确认、任何网络异常 → `False` +
+  ERROR，**不抛异常**。
+- `connect_timeout` 交给 paho 的 `client.connect_timeout`，实测只封顶 TCP 连接建立；
+  paho 2.x 的 `connect()` 不等 CONNACK，所以**密码写错要等 `publish_timeout` 才失败**，
+  错误信息是"发布未被 broker 确认"。
+- 不支持 TLS，也没有 `protocol` 参数（走 paho 默认的 MQTT 3.1.1）。
+- `qos` 不在构造时校验 0–2，写错要等 broker 拒绝才看得出来。
+- **整条消息载荷会写进 INFO 日志**（`*_info.log` 和 `*_debug.log` 都有）—— 别用它发
+  明文密码/token，否则等于把凭据落盘。
+- `bytes` / `bytearray` 原样发送，其它类型走 `str()`（`None` 会发成字符串 `"None"`）。
+
+## API 一览
+
+| 名称 | 默认值 | 一句话 | 详见 |
+|---|---|---|---|
+| `__version__` / `__build_time__` | — | 版本号；手写的构建时间字符串 `YYYY-MM-DD HH:MM:SS`，改功能后手动更新，不参与构建 | — |
+| `script_dir()` / `script_name()` | — | 入口脚本目录/文件名，兼容 exe 与 `python -m` | §1 |
+| `init_logging_config(log_file=None, max_bytes=10MB, backup_count=7, force=False)` / `default_log_file()` | `<脚本目录>/logs/<脚本名>` | 装 debug+info 双轮转文件日志和控制台；根日志器已有 handler 时只提示不接管 | §2 |
+| `check_running_lock(lock_file=None, on_conflict="exit")` / `default_lock_file()` | `<脚本目录>/<脚本名>.running.lock` | 抢"本脚本已在运行"这把独占锁；每进程只调一次 | §3 |
+| `enable_exception_logging()` / `handle_global_exception` / `handle_thread_exception` | — | 主线程 + 子线程的未捕获异常都写进日志 | §4 |
+| `read_yaml(config_file=None, default_config={})` | `<脚本目录>/configs/<脚本名>.config.yaml` | 读 YAML 原样返回；只有"文件不存在"和"文件损坏"会 `exit(1)` | §5 |
+| `write_yaml(config, config_file=None)` | 同上默认文件 | `safe_dump` 原子落盘；目标被占用时退回直写（Windows） | §5 |
+| `to_yaml(value)` | — | 值转 YAML 文本，失败原样返回，不抛异常 | §6 |
+| `is_worktime(worktime_config=None)` | — | 按星期几 + `HHMM-HHMM` 判断现在是否在工作时段，写法不合法就 `exit(1)` | §7 |
+| `MqttPublisher(host, port=1883, username=None, password=None, topic=None, qos=2, client_id=None, connect_timeout=5, publish_timeout=10)` | 只认显式参数 | 一次性发布器；`host`/`topic` 缺失抛 `ValueError` | §8 |
+| `MqttPublisher.publish(msg, topic=None, qos=None)` | 用实例默认值 | 发一条；成功 `True`，失败 `False` 不抛 | §8 |
+
+## 变更记录
+
+### 0.1.0（2026-11-12）
+
+首次发布。单实例文件锁、轮转日志、全局异常钩子（主线程 + 子线程）、一次性 MQTT 发布、
+YAML 配置读写、值转 YAML 文本、工作时段判断，全部从包根 `sc92_lib` 导入。

sc92_lib-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+sc92_lib/__init__.py,sha256=vOqOvDeVBuAIQYQgpW28LFn0a4o2Dp-qkwZelfyoCEk,2522
+sc92_lib/check_running_lock.py,sha256=s_rfJJpMjc7CyQ1bLozE7UJpI62tUVVomFI_86pF94A,3668
+sc92_lib/enable_exception_logging.py,sha256=1cj__WC0YeGoH8xLoRGxKis1TyVUiwEzPvukaKKGMDY,1162
+sc92_lib/init_logging_config.py,sha256=rWeA0VzAYYQ6LUhvLT3dkkOw-IPmhFBU2T-BSacnmRI,2575
+sc92_lib/is_worktime.py,sha256=Dhv5ZoDmhChLaERvMZ5nphpttx1n6KOSQjTtOEumGn0,6225
+sc92_lib/mqtt_publisher.py,sha256=HF-152vMyzwA_Kp_oK_1ITAKSLkA4Q0LPQ35D3pX3Do,3713
+sc92_lib/paths.py,sha256=38v7WUeFPYdZFPeGfvnLcbcXg60_emQc7PXfpfIwGug,2063
+sc92_lib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sc92_lib/to_yaml.py,sha256=o-7xanLXJsMa_nW81xxtHo-93jrjp1wcZFwnZ0FlHh0,3013
+sc92_lib/yaml_config.py,sha256=wT5ZNT4yyOuMxa7yWh8qw-dGr3L8Pa-I0PMOmyotRU4,6819
+sc92_lib-0.1.0.dist-info/licenses/LICENSE,sha256=CDNGjpcAw0Yxah17hAt_jF3NWRI84b71n9cIe8hKWZM,1061
+sc92_lib-0.1.0.dist-info/METADATA,sha256=R8OibbZescAH4O6iaeRWVo49hrrXXF4uOXntfBRQKrc,18917
+sc92_lib-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sc92_lib-0.1.0.dist-info/top_level.txt,sha256=eMScDdAipRv4w7ChdW2e9PZymV7zaJ4D4jTsaRskPuk,9
+sc92_lib-0.1.0.dist-info/RECORD,,

sc92_lib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sc92_lib-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sc92
+
+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.

sc92_lib-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sc92_lib