sc92-public-define 0.3.1__tar.gz

sc92_public_define-0.3.1/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_public_define-0.3.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sc92-public-define
+Version: 0.3.1
+Summary: Personal shared utilities: file lock, logging, MQTT publishing and YAML config helpers
+Author: sc92
+License-Expression: MIT
+Keywords: filelock,logging,mqtt,yaml,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: 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-public-define
+
+Personal shared utilities extracted from everyday scripts:
+
+1. **Single-instance file lock** — `check_running_lock()`: if the script is
+   already running elsewhere, exit (or return False) immediately.
+2. **Rotating logging setup** — `init_logging_config()`: one call to get
+   `*_debug.log` + `*_info.log` (10 MB × 7 backups) + console output. If another
+   library already configured the root logger it now warns on stderr instead of
+   silently doing nothing (pass `force=True` to take over); with no console
+   (`pythonw.exe`, PyInstaller `--noconsole`) the console handler is skipped.
+3. **Global exception hooks** — `enable_exception_logging()`: uncaught
+   exceptions are written to the log instead of only printed to stderr — for the
+   main thread **and for worker threads** (`threading.excepthook`, which
+   `sys.excepthook` never covers).
+4. **MQTT publisher** — `MqttPublisher.publish()`: one-shot connect →
+   publish → disconnect. Credentials are taken from **explicit constructor
+   args only** (no hardcoded defaults, no environment variables) — keep them
+   in your local YAML config file and pass the values in.
+5. **YAML config helpers** — `read_yaml()` / `write_yaml()`: first run writes
+   a default template into `configs/` next to the script and exits for review;
+   Chinese keys and insertion order are preserved, and a file saved as
+   ANSI/GBK or broken YAML now fails with a readable message instead of a raw
+   `UnicodeDecodeError`.
+
+All helpers are PyInstaller-frozen aware and default to paths derived from
+the entry script, so typical usage needs **zero arguments**.
+
+The derived name is `<script dir>/…/<script name>…`, so one instance means
+"one running copy of this script in this directory": a renamed or copied script
+is a separate instance. `python -m pkg[.mod]` is handled as module `pkg[.mod]`
+with the current working directory as its base — it never writes into
+site-packages.
+
+## Install
+
+```bash
+pip install sc92-public-define
+```
+
+Requires Python >= 3.11 (`filelock>=4.0`, `paho-mqtt>=2.0`, `PyYAML>=6.0`).
+
+## Typical usage (top of any script)
+
+```python
+import logging
+from sc92_public_define import (
+    check_running_lock,     # single-instance lock
+    init_logging_config,    # rotating logs + console
+    enable_exception_logging,     # uncaught exception -> log
+)
+
+init_logging_config()       # logs/<script name>_debug.log / _info.log
+check_running_lock()        # <script name>.running.lock next to the script;
+                            # exits with status 1 when another copy is running
+enable_exception_logging()
+
+logging.info("main started")
+```
+
+### MQTT publishing (credentials live in your YAML config, never in code)
+
+```python
+from sc92_public_define import MqttPublisher, read_yaml
+
+server = read_yaml()["mqtt服务器"]          # nested dict in <script>.config.yaml
+pub = MqttPublisher(host=server["地址"], port=server["端口"],
+                    username=server["用户名"] or None,
+                    password=server["密码"] or None,
+                    topic=server["主题"])
+pub.publish("hello")                       # uses instance topic/qos
+pub.publish("hello", topic="other/t", qos=1)   # per-call override
+```
+
+### YAML config
+
+```python
+from sc92_public_define import read_yaml, write_yaml
+
+cfg = read_yaml(default_config={"服务器": "127.0.0.1", "端口": 8080})
+# first run: creates configs/<script>.config.yaml next to the script, logs a hint, exits
+cfg["端口"] = 9090
+write_yaml(config_dict=cfg)     # writes back to the same default file
+```
+
+## API
+
+| Function | Default | Notes |
+|---|---|---|
+| `check_running_lock(lock_file=None, on_conflict="exit")` | `<script dir>/<script>.running.lock` | `on_conflict="exit"` → logs an error and exits with status 1; `"return"` → returns `False`; `True` when acquired |
+| `init_logging_config(log_file=None, max_bytes=10MB, backup_count=7, force=False)` | `<script dir>/logs/<script>` | warns on stderr and does nothing if the root logger already has handlers (`force=True` takes over); console handler skipped when there is no console |
+| `enable_exception_logging()` / `handle_global_exception` / `handle_thread_exception` | — | sets `sys.excepthook` **and** `threading.excepthook`, writes tracebacks via `logging.error` |
+| `MqttPublisher(host, port=1883, username=None, password=None, topic=None, qos=2, client_id=None, connect_timeout=5, publish_timeout=10)` | explicit args only | raises `ValueError` if host/topic missing; `connect_timeout` caps DNS + TCP + the wait for CONNACK |
+| `MqttPublisher.publish(msg, topic=None, qos=None)` | instance defaults | `True` only when the message really got through: QoS 1/2 require the broker acknowledgement, QoS 0 has none (written to the socket only). Wrong password, missing CONNACK, an unacknowledged publish or any network error → `False` plus a `logging.error`, never raises. `bytes`/`bytearray` payloads are sent as-is, anything else is `str()`-ed |
+| `read_yaml(config_file=None, default_config=None, on_missing="exit", merge_defaults=False)` | `<script dir>/configs/<script>.config.yaml` | missing → write template + exit(1); empty file or `{}` → overwrite with the template + exit(1); non-UTF-8 / broken YAML / top level not a mapping → `ValueError`; `merge_defaults=True` fills keys that only exist in `default_config` into the returned dict (the file on disk is untouched); the returned template is a deep copy |
+| `write_yaml(config_file=None, config_dict=None)` | same default file | `config_dict` is required (`None` or a non-dict raises `ValueError`); utf-8, Chinese keys & order preserved |
+| `script_dir()` / `script_name()` | — | entry-script path/name; frozen exe → exe folder/stem; `python -m pkg` → cwd + `pkg` |
+| `default_lock_file()` / `default_log_file()` / `default_config_file()` | — | expose the derived default paths |
+
+## Notes
+
+- The lock is released automatically by the OS when the process exits;
+  the lock **file** is left on disk (harmless, reuse next time).
+- The first `read_yaml()` run on a machine without a config file deliberately
+  exits with status 1 after writing the template: edit it, then run again.
+- `init_logging_config()` must come **before** `check_running_lock()` /
+  `read_yaml()`, otherwise their "抢锁结果 / 配置已加载" INFO lines are dropped
+  (only the ERROR lines still reach stderr through logging's last-resort handler).
+- See the `demo/` folder in the source tree for runnable examples (it is not
+  shipped inside the wheel or sdist).

sc92_public_define-0.3.1/README.md

@@ -0,0 +1,110 @@
+# sc92-public-define
+
+Personal shared utilities extracted from everyday scripts:
+
+1. **Single-instance file lock** — `check_running_lock()`: if the script is
+   already running elsewhere, exit (or return False) immediately.
+2. **Rotating logging setup** — `init_logging_config()`: one call to get
+   `*_debug.log` + `*_info.log` (10 MB × 7 backups) + console output. If another
+   library already configured the root logger it now warns on stderr instead of
+   silently doing nothing (pass `force=True` to take over); with no console
+   (`pythonw.exe`, PyInstaller `--noconsole`) the console handler is skipped.
+3. **Global exception hooks** — `enable_exception_logging()`: uncaught
+   exceptions are written to the log instead of only printed to stderr — for the
+   main thread **and for worker threads** (`threading.excepthook`, which
+   `sys.excepthook` never covers).
+4. **MQTT publisher** — `MqttPublisher.publish()`: one-shot connect →
+   publish → disconnect. Credentials are taken from **explicit constructor
+   args only** (no hardcoded defaults, no environment variables) — keep them
+   in your local YAML config file and pass the values in.
+5. **YAML config helpers** — `read_yaml()` / `write_yaml()`: first run writes
+   a default template into `configs/` next to the script and exits for review;
+   Chinese keys and insertion order are preserved, and a file saved as
+   ANSI/GBK or broken YAML now fails with a readable message instead of a raw
+   `UnicodeDecodeError`.
+
+All helpers are PyInstaller-frozen aware and default to paths derived from
+the entry script, so typical usage needs **zero arguments**.
+
+The derived name is `<script dir>/…/<script name>…`, so one instance means
+"one running copy of this script in this directory": a renamed or copied script
+is a separate instance. `python -m pkg[.mod]` is handled as module `pkg[.mod]`
+with the current working directory as its base — it never writes into
+site-packages.
+
+## Install
+
+```bash
+pip install sc92-public-define
+```
+
+Requires Python >= 3.11 (`filelock>=4.0`, `paho-mqtt>=2.0`, `PyYAML>=6.0`).
+
+## Typical usage (top of any script)
+
+```python
+import logging
+from sc92_public_define import (
+    check_running_lock,     # single-instance lock
+    init_logging_config,    # rotating logs + console
+    enable_exception_logging,     # uncaught exception -> log
+)
+
+init_logging_config()       # logs/<script name>_debug.log / _info.log
+check_running_lock()        # <script name>.running.lock next to the script;
+                            # exits with status 1 when another copy is running
+enable_exception_logging()
+
+logging.info("main started")
+```
+
+### MQTT publishing (credentials live in your YAML config, never in code)
+
+```python
+from sc92_public_define import MqttPublisher, read_yaml
+
+server = read_yaml()["mqtt服务器"]          # nested dict in <script>.config.yaml
+pub = MqttPublisher(host=server["地址"], port=server["端口"],
+                    username=server["用户名"] or None,
+                    password=server["密码"] or None,
+                    topic=server["主题"])
+pub.publish("hello")                       # uses instance topic/qos
+pub.publish("hello", topic="other/t", qos=1)   # per-call override
+```
+
+### YAML config
+
+```python
+from sc92_public_define import read_yaml, write_yaml
+
+cfg = read_yaml(default_config={"服务器": "127.0.0.1", "端口": 8080})
+# first run: creates configs/<script>.config.yaml next to the script, logs a hint, exits
+cfg["端口"] = 9090
+write_yaml(config_dict=cfg)     # writes back to the same default file
+```
+
+## API
+
+| Function | Default | Notes |
+|---|---|---|
+| `check_running_lock(lock_file=None, on_conflict="exit")` | `<script dir>/<script>.running.lock` | `on_conflict="exit"` → logs an error and exits with status 1; `"return"` → returns `False`; `True` when acquired |
+| `init_logging_config(log_file=None, max_bytes=10MB, backup_count=7, force=False)` | `<script dir>/logs/<script>` | warns on stderr and does nothing if the root logger already has handlers (`force=True` takes over); console handler skipped when there is no console |
+| `enable_exception_logging()` / `handle_global_exception` / `handle_thread_exception` | — | sets `sys.excepthook` **and** `threading.excepthook`, writes tracebacks via `logging.error` |
+| `MqttPublisher(host, port=1883, username=None, password=None, topic=None, qos=2, client_id=None, connect_timeout=5, publish_timeout=10)` | explicit args only | raises `ValueError` if host/topic missing; `connect_timeout` caps DNS + TCP + the wait for CONNACK |
+| `MqttPublisher.publish(msg, topic=None, qos=None)` | instance defaults | `True` only when the message really got through: QoS 1/2 require the broker acknowledgement, QoS 0 has none (written to the socket only). Wrong password, missing CONNACK, an unacknowledged publish or any network error → `False` plus a `logging.error`, never raises. `bytes`/`bytearray` payloads are sent as-is, anything else is `str()`-ed |
+| `read_yaml(config_file=None, default_config=None, on_missing="exit", merge_defaults=False)` | `<script dir>/configs/<script>.config.yaml` | missing → write template + exit(1); empty file or `{}` → overwrite with the template + exit(1); non-UTF-8 / broken YAML / top level not a mapping → `ValueError`; `merge_defaults=True` fills keys that only exist in `default_config` into the returned dict (the file on disk is untouched); the returned template is a deep copy |
+| `write_yaml(config_file=None, config_dict=None)` | same default file | `config_dict` is required (`None` or a non-dict raises `ValueError`); utf-8, Chinese keys & order preserved |
+| `script_dir()` / `script_name()` | — | entry-script path/name; frozen exe → exe folder/stem; `python -m pkg` → cwd + `pkg` |
+| `default_lock_file()` / `default_log_file()` / `default_config_file()` | — | expose the derived default paths |
+
+## Notes
+
+- The lock is released automatically by the OS when the process exits;
+  the lock **file** is left on disk (harmless, reuse next time).
+- The first `read_yaml()` run on a machine without a config file deliberately
+  exits with status 1 after writing the template: edit it, then run again.
+- `init_logging_config()` must come **before** `check_running_lock()` /
+  `read_yaml()`, otherwise their "抢锁结果 / 配置已加载" INFO lines are dropped
+  (only the ERROR lines still reach stderr through logging's last-resort handler).
+- See the `demo/` folder in the source tree for runnable examples (it is not
+  shipped inside the wheel or sdist).

sc92_public_define-0.3.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sc92-public-define"
+version = "0.3.1"
+description = "Personal shared utilities: file lock, logging, MQTT publishing and YAML config helpers"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "sc92" }]
+keywords = ["filelock", "logging", "mqtt", "yaml", "utility"]
+dependencies = ["filelock>=4.0", "paho-mqtt>=2.0", "PyYAML>=6.0"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sc92_public_define*"]
+
+[tool.setuptools.package-data]
+sc92_public_define = ["py.typed"]

sc92_public_define-0.3.1/setup.cfg

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

sc92_public_define-0.3.1/src/sc92_public_define/__init__.py

@@ -0,0 +1,33 @@
+"""sc92-public-define: single-instance file lock, rotating logging, global
+exception hooks (main thread + worker threads), one-shot MQTT publishing and
+YAML config helpers."""
+
+from .lock import check_running_lock, default_lock_file
+from .log import default_log_file, init_logging_config
+from .excepthook import (
+    enable_exception_logging,
+    handle_global_exception,
+    handle_thread_exception,
+)
+from .mqtt_publisher import MqttPublisher
+from .yaml_config import default_config_file, read_yaml, write_yaml
+from .paths import script_dir, script_name
+
+__version__ = "0.3.1"
+
+__all__ = [
+    "check_running_lock",
+    "default_lock_file",
+    "init_logging_config",
+    "default_log_file",
+    "handle_global_exception",
+    "handle_thread_exception",
+    "enable_exception_logging",
+    "MqttPublisher",
+    "read_yaml",
+    "write_yaml",
+    "default_config_file",
+    "script_dir",
+    "script_name",
+    "__version__",
+]

sc92_public_define-0.3.1/src/sc92_public_define/excepthook.py

@@ -0,0 +1,28 @@
+"""Global uncaught exception hooks: main thread and worker threads -> the log."""
+
+import logging
+import sys
+import threading
+import traceback
+
+
+def handle_global_exception(exc_type, exc_value, exc_traceback) -> None:
+    """sys.excepthook implementation: write uncaught exception to the log."""
+    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 implementation: worker threads are not covered by
+    sys.excepthook, so without this their tracebacks only hit stderr and never
+    reach the log file."""
+    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:
+    """Shortcut for: sys.excepthook / threading.excepthook = the two hooks above."""
+    sys.excepthook = handle_global_exception
+    threading.excepthook = handle_thread_exception

sc92_public_define-0.3.1/src/sc92_public_define/lock.py

@@ -0,0 +1,48 @@
+"""Single-instance running check based on filelock."""
+
+import logging
+import sys
+
+from .paths import script_dir, script_name
+
+_held_locks: dict = {}
+
+
+def default_lock_file() -> str:
+    """<script dir>/<script name>.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:
+    """Try to acquire an exclusive lock meaning "this script is already running".
+
+    lock_file   defaults to <script>.running.lock next to the entry script.
+    on_conflict "exit" (default): terminate this process with exit code 1 when
+                the lock is held elsewhere; "return": return False and let the
+                caller decide.
+
+    Returns True when the lock was acquired, False on conflict with
+    on_conflict="return". The OS releases the lock automatically on exit;
+    the lock FILE itself is left on disk.
+    """
+    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
+
+    # keep a reference so the lock is held for the whole life of the process
+    _held_locks[str(lock_file)] = lock
+    logging.info(f"脚本未运行，继续执行（锁文件：{lock_file}）")
+    return True

sc92_public_define-0.3.1/src/sc92_public_define/log.py

@@ -0,0 +1,69 @@
+"""Rotating-file + console logging setup."""
+
+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:
+    """<script dir>/logs/<script name> (debug/info suffixes added automatically)."""
+    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:
+    """Configure root logger: *_debug.log + *_info.log (rotating) + console.
+
+    log_file defaults to logs/<script name> next to the entry script.
+    If the root logger already has handlers (pytest, Jupyter, another library
+    configured logging first) this does nothing and warns on stderr, because
+    silently skipping it used to mean "no log file at all, no hint why".
+    Pass force=True to remove the existing handlers and take over.
+    The console handler is skipped when there is no console (pythonw.exe,
+    PyInstaller --noconsole), where sys.stderr is None.
+    """
+    if logging.root.handlers and not force:
+        if sys.stderr is not None:
+            print(
+                "[sc92_public_define] 根日志器已有 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_public_define-0.3.1/src/sc92_public_define/mqtt_publisher.py

@@ -0,0 +1,144 @@
+"""MQTT publisher. Credentials come from explicit constructor args ONLY.
+
+NEVER hardcode host / username / password / topic in this source file.
+Recommended: keep them in your own YAML config file (see read_yaml) and
+pass the values into MqttPublisher(...).
+"""
+
+import logging
+import socket
+import threading
+
+import paho.mqtt.client as mqtt
+
+
+class MqttPublisher:
+    """One-shot MQTT publisher: connect, publish one message, disconnect."""
+
+    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:
+        """Publish one message. Returns True only when the broker really took it.
+
+        QoS 1/2: True means the broker acknowledged the message.
+        QoS 0 has no acknowledgement: True only means it was written to the socket.
+        connect_timeout caps DNS lookup + TCP connect + the wait for CONNACK
+        (TCP connect alone is not enough: a wrong password still gives you a
+        working TCP connection).
+        """
+        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)
+
+        connack = threading.Event()
+        reject: dict = {}
+        closed: dict = {}
+
+        def _on_connect(c, userdata, flags, reason_code, properties):
+            if getattr(reason_code, "is_failure", False):
+                reject["code"] = reason_code
+            connack.set()
+
+        def _on_disconnect(c, userdata, flags, reason_code, properties):
+            closed["code"] = reason_code
+            connack.set()
+
+        client.on_connect = _on_connect
+        client.on_disconnect = _on_disconnect
+
+        try:
+            logging.info(f"正在连接 MQTT Broker {self.host}:{self.port} ...")
+            box: dict = {}
+
+            def _do_connect() -> None:
+                old_timeout = socket.getdefaulttimeout()
+                socket.setdefaulttimeout(self.connect_timeout)
+                try:
+                    client.connect(self.host, self.port, keepalive=60)
+                    box["err"] = None
+                except Exception as exc:
+                    box["err"] = exc
+                finally:
+                    socket.setdefaulttimeout(old_timeout)
+
+            # connect() 里的 DNS 解析(getaddrinfo)不受 socket 超时约束，放到线程里
+            # join(timeout) 才能真正被 connect_timeout 封顶；超时后放弃（后台线程是
+            # daemon，卡住的解析随进程结束一起回收）。
+            connector = threading.Thread(target=_do_connect, daemon=True)
+            connector.start()
+            connector.join(self.connect_timeout)
+            if connector.is_alive():
+                logging.error(
+                    f"MQTT 连接超时（{self.connect_timeout}s，含 DNS 解析），放弃："
+                    f"{self.host}:{self.port}"
+                )
+                return False
+            if box.get("err") is not None:
+                raise box["err"]
+            client.loop_start()
+
+            if not connack.wait(self.connect_timeout):
+                logging.error(
+                    f"MQTT 连接失败：{self.connect_timeout}s 内没收到 CONNACK（{self.host}:{self.port}）"
+                )
+                return False
+            if reject:
+                logging.error(f"MQTT 连接被 broker 拒绝：{reject['code']}")
+                return False
+            if closed:
+                logging.error(f"MQTT 连接在建立会话前被中断：{closed['code']}")
+                return False
+
+            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}): {msg}")
+                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_public_define-0.3.1/src/sc92_public_define/paths.py

@@ -0,0 +1,59 @@
+"""Resolve the running script's directory and name, PyInstaller-frozen aware."""
+
+import pathlib
+import sys
+
+
+def _is_frozen() -> bool:
+    return getattr(sys, "frozen", False)
+
+
+def _module_entry() -> str | None:
+    """Module-style entry name, or None for a normal standalone script.
+
+    `python -m pkg[.mod]` (and running a package's __main__.py by hand) has no
+    entry-script name of its own: sys.argv[0] would give ".__main__" and the real
+    module usually sits inside site-packages, where logs/locks/config must not be
+    written. Those cases return the module / package name instead.
+    """
+    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:
+    """Directory of the entry script (or of the exe when frozen by PyInstaller).
+
+    `python -m ...` runs a module instead of a script, so the current working
+    directory is used: the module's own folder is often 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:
+    """File name (without suffix) of the entry script (exe stem when frozen,
+    module/package name when started with 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_public_define-0.3.1/src/sc92_public_define/yaml_config.py

@@ -0,0 +1,142 @@
+"""YAML config file read/write helpers.
+
+Missing or empty file -> write a default template then exit(1) by default, so
+the user can review the template and re-run (same workflow as the original
+script). Pass on_missing="return" to continue programmatically instead.
+"""
+
+import copy
+import logging
+import pathlib
+import sys
+
+import yaml
+
+from .paths import script_dir, script_name
+
+
+def default_config_file() -> str:
+    """<script dir>/configs/<script name>.config.yaml (like logs go into logs/)."""
+    return str(script_dir() / "configs" / f"{script_name()}.config.yaml")
+
+
+def write_yaml(config_file: str | pathlib.Path | None = None,
+               config_dict: dict | None = None) -> None:
+    """Write a dict to a YAML file (utf-8, Chinese keys kept, insertion order kept).
+
+    config_file defaults to <script dir>/configs/<script name>.config.yaml.
+    config_dict is required: passing nothing used to write an empty file that
+    later read_yaml() calls would silently accept.
+    """
+    if config_dict is None:
+        raise ValueError("write_yaml 必须显式传入 config_dict（不传会写出空文件）")
+    if not isinstance(config_dict, dict):
+        raise ValueError(f"write_yaml 的 config_dict 必须是 dict，实际为 {type(config_dict).__name__}")
+    if config_file is None:
+        config_file = default_config_file()
+    path = pathlib.Path(config_file)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        yaml.dump(
+            config_dict,
+            f,
+            allow_unicode=True,
+            default_flow_style=False,
+            sort_keys=False,
+        )
+    logging.info(f"配置已写入: {path}")
+
+
+def _fill_missing(base: dict, defaults: dict, prefix: str = "") -> list:
+    """递归把 defaults 里 base 缺少的键补进 base（文件里的值优先），返回补齐的键路径。"""
+    added = []
+    for key, value in defaults.items():
+        if key not in base:
+            base[key] = copy.deepcopy(value)
+            added.append(f"{prefix}{key}")
+        elif isinstance(base[key], dict) and isinstance(value, dict):
+            added.extend(_fill_missing(base[key], value, f"{prefix}{key}."))
+    return added
+
+
+def read_yaml(config_file: str | pathlib.Path | None = None,
+              default_config: dict | None = None,
+              on_missing: str = "exit",
+              merge_defaults: bool = False) -> dict:
+    """Read a YAML config file as a dict. Errors stop the script (never silent defaults).
+
+    config_file      defaults to <script dir>/configs/<script name>.config.yaml.
+    File missing     -> write default_config as a template, logging.error, exit(1).
+    File empty/`{}`  -> OVERWRITE it with default_config, logging.error, exit(1).
+    Not UTF-8        -> logging.error, raise ValueError (file kept untouched).
+    YAML broken      -> logging.error, raise ValueError (file kept untouched).
+    Not a mapping    -> logging.error, raise ValueError (file kept untouched).
+    on_missing       "exit" (default) or "return": with "return" the two template
+                     cases above return a deep copy of default_config instead of
+                     exiting.
+    merge_defaults   True: after loading, fill keys that only exist in
+                     default_config into the returned dict (file values win, the
+                     file on disk is NOT rewritten).
+
+    Returns the loaded dict only when the file really contains a valid mapping.
+    """
+    if on_missing not in ("exit", "return"):
+        raise ValueError(f'on_missing must be "exit" or "return", got {on_missing!r}')
+
+    if config_file is None:
+        config_file = default_config_file()
+    path = pathlib.Path(config_file)
+
+    if default_config is None:
+        default_config = {}
+
+    if not path.is_file():
+        template = copy.deepcopy(default_config)
+        write_yaml(path, template)
+        logging.error(
+            f"配置文件不存在: {path}，已按默认配置生成模板，请检查修改后重新运行本脚本"
+        )
+        if on_missing == "exit":
+            sys.exit(1)
+        return template
+
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            loaded = yaml.safe_load(f)
+    except UnicodeDecodeError as exc:
+        logging.error(
+            f"配置文件不是 UTF-8 编码（多半是记事本另存为时选了 ANSI/GBK）: {path}，"
+            f"请用 UTF-8 重新保存后重试。错误信息: {exc}"
+        )
+        raise ValueError(f"配置文件编码不是 UTF-8: {path}") from exc
+    except yaml.YAMLError as exc:
+        logging.error(f"配置文件解析失败: {path}，错误信息: {exc}，脚本退出")
+        raise ValueError(f"配置文件解析失败: {path}") from exc
+
+    if loaded is None or loaded == {}:
+        template = copy.deepcopy(default_config)
+        write_yaml(path, template)
+        logging.error(
+            f"配置文件为空: {path}，已按默认配置覆盖写入，请检查修改后重新运行本脚本"
+        )
+        if on_missing == "exit":
+            sys.exit(1)
+        return template
+
+    if not isinstance(loaded, dict):
+        logging.error(
+            f"配置文件顶层必须是键值对(key: value)，实际为 {type(loaded).__name__}: "
+            f"{path}，请修改后重新运行，脚本退出"
+        )
+        raise ValueError(f"配置文件顶层不是键值映射: {path}")
+
+    if merge_defaults and default_config:
+        added = _fill_missing(loaded, default_config)
+        if added:
+            logging.info(
+                f"配置文件缺少 {len(added)} 项，已按默认模板补齐（只补内存里的结果，"
+                f"不改动 {path}）: {', '.join(added)}"
+            )
+
+    logging.info(f"配置已加载: {path}")
+    return loaded

sc92_public_define-0.3.1/src/sc92_public_define.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sc92-public-define
+Version: 0.3.1
+Summary: Personal shared utilities: file lock, logging, MQTT publishing and YAML config helpers
+Author: sc92
+License-Expression: MIT
+Keywords: filelock,logging,mqtt,yaml,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: 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-public-define
+
+Personal shared utilities extracted from everyday scripts:
+
+1. **Single-instance file lock** — `check_running_lock()`: if the script is
+   already running elsewhere, exit (or return False) immediately.
+2. **Rotating logging setup** — `init_logging_config()`: one call to get
+   `*_debug.log` + `*_info.log` (10 MB × 7 backups) + console output. If another
+   library already configured the root logger it now warns on stderr instead of
+   silently doing nothing (pass `force=True` to take over); with no console
+   (`pythonw.exe`, PyInstaller `--noconsole`) the console handler is skipped.
+3. **Global exception hooks** — `enable_exception_logging()`: uncaught
+   exceptions are written to the log instead of only printed to stderr — for the
+   main thread **and for worker threads** (`threading.excepthook`, which
+   `sys.excepthook` never covers).
+4. **MQTT publisher** — `MqttPublisher.publish()`: one-shot connect →
+   publish → disconnect. Credentials are taken from **explicit constructor
+   args only** (no hardcoded defaults, no environment variables) — keep them
+   in your local YAML config file and pass the values in.
+5. **YAML config helpers** — `read_yaml()` / `write_yaml()`: first run writes
+   a default template into `configs/` next to the script and exits for review;
+   Chinese keys and insertion order are preserved, and a file saved as
+   ANSI/GBK or broken YAML now fails with a readable message instead of a raw
+   `UnicodeDecodeError`.
+
+All helpers are PyInstaller-frozen aware and default to paths derived from
+the entry script, so typical usage needs **zero arguments**.
+
+The derived name is `<script dir>/…/<script name>…`, so one instance means
+"one running copy of this script in this directory": a renamed or copied script
+is a separate instance. `python -m pkg[.mod]` is handled as module `pkg[.mod]`
+with the current working directory as its base — it never writes into
+site-packages.
+
+## Install
+
+```bash
+pip install sc92-public-define
+```
+
+Requires Python >= 3.11 (`filelock>=4.0`, `paho-mqtt>=2.0`, `PyYAML>=6.0`).
+
+## Typical usage (top of any script)
+
+```python
+import logging
+from sc92_public_define import (
+    check_running_lock,     # single-instance lock
+    init_logging_config,    # rotating logs + console
+    enable_exception_logging,     # uncaught exception -> log
+)
+
+init_logging_config()       # logs/<script name>_debug.log / _info.log
+check_running_lock()        # <script name>.running.lock next to the script;
+                            # exits with status 1 when another copy is running
+enable_exception_logging()
+
+logging.info("main started")
+```
+
+### MQTT publishing (credentials live in your YAML config, never in code)
+
+```python
+from sc92_public_define import MqttPublisher, read_yaml
+
+server = read_yaml()["mqtt服务器"]          # nested dict in <script>.config.yaml
+pub = MqttPublisher(host=server["地址"], port=server["端口"],
+                    username=server["用户名"] or None,
+                    password=server["密码"] or None,
+                    topic=server["主题"])
+pub.publish("hello")                       # uses instance topic/qos
+pub.publish("hello", topic="other/t", qos=1)   # per-call override
+```
+
+### YAML config
+
+```python
+from sc92_public_define import read_yaml, write_yaml
+
+cfg = read_yaml(default_config={"服务器": "127.0.0.1", "端口": 8080})
+# first run: creates configs/<script>.config.yaml next to the script, logs a hint, exits
+cfg["端口"] = 9090
+write_yaml(config_dict=cfg)     # writes back to the same default file
+```
+
+## API
+
+| Function | Default | Notes |
+|---|---|---|
+| `check_running_lock(lock_file=None, on_conflict="exit")` | `<script dir>/<script>.running.lock` | `on_conflict="exit"` → logs an error and exits with status 1; `"return"` → returns `False`; `True` when acquired |
+| `init_logging_config(log_file=None, max_bytes=10MB, backup_count=7, force=False)` | `<script dir>/logs/<script>` | warns on stderr and does nothing if the root logger already has handlers (`force=True` takes over); console handler skipped when there is no console |
+| `enable_exception_logging()` / `handle_global_exception` / `handle_thread_exception` | — | sets `sys.excepthook` **and** `threading.excepthook`, writes tracebacks via `logging.error` |
+| `MqttPublisher(host, port=1883, username=None, password=None, topic=None, qos=2, client_id=None, connect_timeout=5, publish_timeout=10)` | explicit args only | raises `ValueError` if host/topic missing; `connect_timeout` caps DNS + TCP + the wait for CONNACK |
+| `MqttPublisher.publish(msg, topic=None, qos=None)` | instance defaults | `True` only when the message really got through: QoS 1/2 require the broker acknowledgement, QoS 0 has none (written to the socket only). Wrong password, missing CONNACK, an unacknowledged publish or any network error → `False` plus a `logging.error`, never raises. `bytes`/`bytearray` payloads are sent as-is, anything else is `str()`-ed |
+| `read_yaml(config_file=None, default_config=None, on_missing="exit", merge_defaults=False)` | `<script dir>/configs/<script>.config.yaml` | missing → write template + exit(1); empty file or `{}` → overwrite with the template + exit(1); non-UTF-8 / broken YAML / top level not a mapping → `ValueError`; `merge_defaults=True` fills keys that only exist in `default_config` into the returned dict (the file on disk is untouched); the returned template is a deep copy |
+| `write_yaml(config_file=None, config_dict=None)` | same default file | `config_dict` is required (`None` or a non-dict raises `ValueError`); utf-8, Chinese keys & order preserved |
+| `script_dir()` / `script_name()` | — | entry-script path/name; frozen exe → exe folder/stem; `python -m pkg` → cwd + `pkg` |
+| `default_lock_file()` / `default_log_file()` / `default_config_file()` | — | expose the derived default paths |
+
+## Notes
+
+- The lock is released automatically by the OS when the process exits;
+  the lock **file** is left on disk (harmless, reuse next time).
+- The first `read_yaml()` run on a machine without a config file deliberately
+  exits with status 1 after writing the template: edit it, then run again.
+- `init_logging_config()` must come **before** `check_running_lock()` /
+  `read_yaml()`, otherwise their "抢锁结果 / 配置已加载" INFO lines are dropped
+  (only the ERROR lines still reach stderr through logging's last-resort handler).
+- See the `demo/` folder in the source tree for runnable examples (it is not
+  shipped inside the wheel or sdist).

sc92_public_define-0.3.1/src/sc92_public_define.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/sc92_public_define/__init__.py
+src/sc92_public_define/excepthook.py
+src/sc92_public_define/lock.py
+src/sc92_public_define/log.py
+src/sc92_public_define/mqtt_publisher.py
+src/sc92_public_define/paths.py
+src/sc92_public_define/py.typed
+src/sc92_public_define/yaml_config.py
+src/sc92_public_define.egg-info/PKG-INFO
+src/sc92_public_define.egg-info/SOURCES.txt
+src/sc92_public_define.egg-info/dependency_links.txt
+src/sc92_public_define.egg-info/requires.txt
+src/sc92_public_define.egg-info/top_level.txt

sc92_public_define-0.3.1/src/sc92_public_define.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sc92_public_define-0.3.1/src/sc92_public_define.egg-info/requires.txt

@@ -0,0 +1,3 @@
+filelock>=4.0
+paho-mqtt>=2.0
+PyYAML>=6.0

sc92_public_define-0.3.1/src/sc92_public_define.egg-info/top_level.txt

@@ -0,0 +1 @@
+sc92_public_define