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

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)

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)

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

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

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).