zjs-kit 0.1.0__tar.gz

zjs_kit-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: zjs-kit
+Version: 0.1.0
+Summary: Jenson Zhang Kit
+Author: Jenson Zhang
+Requires-Python: >=3.8

zjs_kit-0.1.0/README.md

@@ -0,0 +1,14 @@
+[project]
+name = "zjs-kit"
+version = "0.1.0"
+description = "Jenson Zhang Kit"
+readme = "README.md"
+authors = [{ name = "Jenson Zhang", email = "zhang.jinshuo@163.com" }]
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["logging", "utils", "tools"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]

zjs_kit-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zjs-kit"
+version = "0.1.0"
+description = "Jenson Zhang Kit"
+authors = [{ name = "Jenson Zhang" }]
+requires-python = ">=3.8"
+
+[tool.setuptools.packages.find]
+where = ["src"]

zjs_kit-0.1.0/setup.cfg

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

zjs_kit-0.1.0/src/zjs_kit/Logger.py

@@ -0,0 +1,453 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# ========================================
+# @Created  :   2026/8/21 16:35
+# @File     :   Logger.py
+# @Project  :   None
+# @Author   :   Jenson Zhang
+# @Contact  :   zhang.jinshuo@163.com
+# @Software :   PyCharm
+# @Purpose  :
+# ----------------------------------------
+# Updated   :   2026/8/21 16:35 (v1.0.0)
+# Upd. Cont.:   初始版本
+# Introduce :   
+# ========================================
+
+import os
+import sys
+import time
+import shutil
+import socket
+import getpass
+import platform
+import threading
+import inspect
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+try:
+    import colorama
+    colorama.init()
+    HAS_COLORAMA = True
+except ImportError:
+    HAS_COLORAMA = False
+
+# 日志级别定义
+class ELogLevel:
+    """ 日志级别枚举 """
+    LOG_DEBUG = 0
+    LOG_INFO = 1
+    LOG_WARN = 2
+    LOG_ERROR = 3
+
+# 为方便使用，定义模块级常量
+LOG_DEBUG = ELogLevel.LOG_DEBUG
+LOG_INFO = ELogLevel.LOG_INFO
+LOG_WARN = ELogLevel.LOG_WARN
+LOG_ERROR = ELogLevel.LOG_ERROR
+
+# 全局状态
+_logger_lock = threading.RLock()          # 保护全局状态的锁
+_logger_initialized = False               # 是否已初始化
+_log_file = None                          # 日志文件对象
+_logger_path = ""                         # 日志根目录
+_logger_name = ""                         # 日志名称（子目录名）
+_logger_keep_days = 3                     # 日志保留天数
+_en_con = True                            # 是否启用控制台输出
+_file_log_level = LOG_DEBUG               # 文件输出最低级别
+_con_log_level = LOG_DEBUG                # 控制台输出最低级别
+_current_log_date = ""                    # 当前日志文件对应的日期，用于跨天切换
+
+# 内部工具函数
+def _get_date_str() -> str:
+    """
+    返回当前日期字符串
+    """
+    return datetime.now().strftime("%Y%m%d")
+
+def _get_time_str() -> str:
+    """
+    返回当前时间字符串
+    """
+    return datetime.now().strftime("%H%M_%S")
+
+def _get_timestamp_str() -> str:
+    """
+    返回完整时间戳字符串
+    """
+    now = datetime.now()
+    return f"[{now.year:04d}-{now.month:02d}-{now.day:02d}] ({now.hour:02d}:{now.minute:02d}:{now.second:02d})"
+
+def _get_level_text(level: int) -> str:
+    """
+    返回日志级别文本
+    """
+    if level == LOG_DEBUG:
+        return "[DEBUG]"
+    elif level == LOG_INFO:
+        return "[INFO ]"
+    elif level == LOG_WARN:
+        return "[WARN ]"
+    elif level == LOG_ERROR:
+        return "[ERROR]"
+    else:
+        return "[UNK  ]"
+
+def _get_level_color(level: int) -> str:
+    """
+    返回控制台颜色代码
+    """
+    if not HAS_COLORAMA:
+        return ""
+    # 使用 colorama 颜色常量
+    if level == LOG_DEBUG:
+        return colorama.Style.DIM        # 灰色
+    elif level == LOG_INFO:
+        return colorama.Fore.GREEN       # 绿色
+    elif level == LOG_WARN:
+        return colorama.Fore.YELLOW      # 黄色
+    elif level == LOG_ERROR:
+        return colorama.Fore.RED         # 红色
+    else:
+        return colorama.Fore.RESET
+
+def _reset_color() -> str:
+    """ 恢复颜色 """
+    if HAS_COLORAMA:
+        return colorama.Style.RESET_ALL
+    return ""
+
+def _get_mac_address() -> str:
+    """
+    获取 MAC 地址
+    """
+    try:
+        import uuid
+        mac = uuid.getnode()
+        if mac == 0:
+            return "None"
+        # 转换为 6 字节
+        mac_hex = f"{mac:012x}"
+        return "-".join(mac_hex[i:i+2].upper() for i in range(0, 12, 2))
+    except Exception:
+        return "None"
+
+def _get_computer_name() -> str:
+    """
+    获取计算机名
+    """
+    return socket.gethostname()
+
+def _get_user_name() -> str:
+    """
+    获取当前用户名
+    """
+    try:
+        return getpass.getuser()
+    except Exception:
+        return "Unknown"
+
+def _get_program_name() -> str:
+    """
+    获取当前程序名称
+    """
+    # 尝试获取主脚本路径
+    try:
+        main_script = sys.argv[0]
+        if main_script:
+            return os.path.basename(main_script)
+    except Exception:
+        pass
+    return "Python"
+
+def _create_multi_dir(path: str) -> None:
+    """
+    递归创建多级目录
+    """
+    if path:
+        os.makedirs(path, exist_ok=True)
+
+def _delete_folder(folder_path: str) -> None:
+    """
+    删除整个文件夹
+    """
+    if os.path.exists(folder_path):
+        shutil.rmtree(folder_path, ignore_errors=True)
+
+def _clean_old_logs() -> None:
+    """
+    清理过期日志文件夹
+    """
+    if not _logger_path or not _logger_name:
+        return
+
+    logger_base_dir = os.path.join(_logger_path, _logger_name)
+    if not os.path.isdir(logger_base_dir):
+        return
+
+    today = datetime.now().date()
+    for item in os.listdir(logger_base_dir):
+        item_path = os.path.join(logger_base_dir, item)
+        if os.path.isdir(item_path):
+            try:
+                # 尝试解析目录名为日期 YYYYMMDD
+                folder_date = datetime.strptime(item, "%Y%m%d").date()
+                diff_days = (today - folder_date).days
+                if diff_days > _logger_keep_days:
+                    _delete_folder(item_path)
+            except ValueError:
+                # 目录名不是日期格式，忽略
+                continue
+
+def _write_header_info() -> None:
+    """
+    写入日志头信息到文件和控制台
+    """
+    global _log_file, _en_con
+
+    if _log_file is None:
+        return
+
+    # 如果文件已有内容，则跳过头部
+    _log_file.seek(0, os.SEEK_END)
+    if _log_file.tell() > 0:
+        _log_file.seek(0, os.SEEK_END)
+        return
+
+    now = datetime.now()
+    mac = _get_mac_address()
+    comp_name = _get_computer_name()
+    user_name = _get_user_name()
+    prog_name = _get_program_name()
+
+    header1 = f"=== MAC: {mac} || PC Name: {comp_name} || User Name: {user_name} ==="
+    header2 = f"=== Init Time: [{now.year:04d}-{now.month:02d}-{now.day:02d}]({now.hour:02d}:{now.minute:02d}:{now.second:02d}) || EXE Name: {prog_name} ==="
+
+    # 写入文件
+    _log_file.write(header1 + "\n")
+    _log_file.write(header2 + "\n")
+    _log_file.flush()
+
+    # 输出到控制台
+    if _en_con:
+        if HAS_COLORAMA:
+            print(colorama.Fore.BLUE + header1 + _reset_color())
+            print(colorama.Fore.BLUE + header2 + _reset_color())
+        else:
+            print(header1)
+            print(header2)
+
+def _open_new_log_file() -> None:
+    """
+    根据当前日期和时间打开新的日志文件
+    """
+    global _log_file, _current_log_date
+
+    date_str = _get_date_str()
+    time_str = _get_time_str()
+
+    # 构建日志目录
+    log_dir = os.path.join(_logger_path, _logger_name, date_str)
+    _create_multi_dir(log_dir)
+
+    # 日志文件完整路径
+    log_file_path = os.path.join(log_dir, f"{time_str}.log")
+
+    # 打开文件
+    try:
+        _log_file = open(log_file_path, "a+", encoding="utf-8")
+        _current_log_date = date_str
+    except Exception as e:
+        _log_file = None
+        error_msg = f"[Logger] Failed to open log file: {log_file_path}, error: {e}"
+        if _en_con:
+            if HAS_COLORAMA:
+                print(colorama.Fore.RED + error_msg + _reset_color())
+            else:
+                print(error_msg)
+        else:
+            # 输出到调试器（这里使用 stderr 代替）
+            sys.stderr.write(error_msg + "\n")
+        return
+
+    # 写入日志头
+    _write_header_info()
+
+def _maybe_rotate_log_file() -> None:
+    """
+    如果日期变化，则切换新日志文件
+    """
+    global _log_file, _current_log_date
+    today = _get_date_str()
+    if today != _current_log_date:
+        # 关闭旧文件，打开新文件
+        if _log_file:
+            _log_file.close()
+            _log_file = None
+        _open_new_log_file()
+        # 顺便清理旧日志
+        _clean_old_logs()
+
+# 公共接口
+def Logger_Init(
+    logger_path: str = ".",
+    logger_name: str = "zjs_kit",
+    logger_keep_days: int = 3,
+    en_con: bool = True,
+    file_log_level: int = LOG_DEBUG,
+    con_log_level: int = LOG_DEBUG
+) -> None:
+    """
+    初始化日志系统
+    """
+    global _logger_initialized, _logger_path, _logger_name, _logger_keep_days
+    global _en_con, _file_log_level, _con_log_level, _log_file, _current_log_date
+
+    with _logger_lock:
+        if _logger_initialized:
+            return  # 防止重复初始化
+
+        # 处理日志根目录
+        if not logger_path or logger_path == ".":
+            # 使用当前脚本所在目录
+            try:
+                script_path = os.path.dirname(os.path.abspath(sys.argv[0]))
+                logger_path = script_path
+            except Exception:
+                logger_path = os.getcwd()
+
+        _logger_path = logger_path
+        _logger_name = logger_name
+        _logger_keep_days = logger_keep_days
+        _en_con = en_con
+        _file_log_level = file_log_level
+        _con_log_level = con_log_level
+
+        # 打开日志文件
+        _open_new_log_file()
+
+        # 清理旧日志
+        _clean_old_logs()
+
+        _logger_initialized = True
+
+def Logger_Uninit() -> None:
+    """
+    关闭日志系统
+    """
+    global _logger_initialized, _log_file
+
+    with _logger_lock:
+        if not _logger_initialized:
+            return
+
+        if _log_file:
+            _log_file.close()
+            _log_file = None
+
+        _logger_initialized = False
+
+def Logger_Write(
+    log_level: int,
+    class_name: Optional[str],
+    func_name: Optional[str],
+    fmt: str,
+    *args
+) -> None:
+    """
+    写日志
+    """
+    global _logger_initialized, _file_log_level, _con_log_level, _log_file, _en_con
+
+    if not _logger_initialized:
+        return
+
+    # 如果文件和控制台都不需要输出，直接返回
+    if log_level < _file_log_level and log_level < _con_log_level:
+        return
+
+    with _logger_lock:
+        # 跨天自动切换日志文件
+        _maybe_rotate_log_file()
+
+        timestamp = _get_timestamp_str()
+        level_text = _get_level_text(log_level)
+
+        # 构建上下文：类名.函数名
+        context = ""
+        if class_name and func_name:
+            context = f"{class_name}.{func_name}"
+        elif class_name:
+            context = class_name
+        elif func_name:
+            context = func_name
+
+        # 格式化用户消息
+        try:
+            if args:
+                user_msg = fmt % args
+            else:
+                user_msg = fmt
+        except Exception:
+            user_msg = fmt  # 格式化失败就保留原始字符串
+
+        # 组装完整日志行
+        if context:
+            full_line = f"{timestamp} {level_text} - {context} - {user_msg}"
+        else:
+            full_line = f"{timestamp} {level_text} - {user_msg}"
+
+        # 输出到文件
+        if _log_file and log_level >= _file_log_level:
+            _log_file.write(full_line + "\n")
+            _log_file.flush()
+
+        # 输出到控制台（带颜色）
+        if _en_con and log_level >= _con_log_level:
+            if HAS_COLORAMA:
+                color = _get_level_color(log_level)
+                reset = _reset_color()
+                print(color + full_line + reset)
+            else:
+                print(full_line)
+
+def Get_Exe_Path() -> str:
+    """
+    获取当前程序
+    """
+    try:
+        return os.path.abspath(sys.argv[0])
+    except Exception:
+        return ""
+
+# 便捷日志函数
+def log_debug(class_name: Optional[str], func_name: Optional[str], fmt: str, *args):
+    """Debug 级别日志"""
+    Logger_Write(LOG_DEBUG, class_name, func_name, fmt, *args)
+
+def log_info(class_name: Optional[str], func_name: Optional[str], fmt: str, *args):
+    """Info 级别日志"""
+    Logger_Write(LOG_INFO, class_name, func_name, fmt, *args)
+
+def log_warn(class_name: Optional[str], func_name: Optional[str], fmt: str, *args):
+    """Warn 级别日志"""
+    Logger_Write(LOG_WARN, class_name, func_name, fmt, *args)
+
+def log_error(class_name: Optional[str], func_name: Optional[str], fmt: str, *args):
+    """Error 级别日志"""
+    Logger_Write(LOG_ERROR, class_name, func_name, fmt, *args)
+
+# 自动获取函数名的装饰器/辅助函数
+def auto_log(level: int, fmt: str, *args):
+    """
+    自动获取调用者的函数名
+    """
+    frame = inspect.currentframe().f_back
+    func_name = frame.f_code.co_name
+    class_name = None
+    # 尝试从 self 参数获取类名（仅当在方法中调用时有效）
+    if 'self' in frame.f_locals:
+        class_name = frame.f_locals['self'].__class__.__name__
+    Logger_Write(level, class_name, func_name, fmt, *args)

zjs_kit-0.1.0/src/zjs_kit/__init__.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# ========================================
+# @Created  :   2026/8/21 16:24
+# @File     :   __init__.py
+# @Project  :   None
+# @Author   :   Jenson Zhang
+# @Contact  :   zhang.jinshuo@163.com
+# @Software :   PyCharm
+# @Purpose  :
+# ----------------------------------------
+# Updated   :   2026/8/21 16:24 (v1.0.0)
+# Upd. Cont.:   初始版本
+# Introduce :   
+# ========================================
+from .Logger import (
+    Logger_Init,
+    Logger_Uninit,
+    Logger_Write,
+    Get_Exe_Path,
+    log_debug,
+    log_info,
+    log_warn,
+    log_error,
+    auto_log,
+    LOG_DEBUG,
+    LOG_INFO,
+    LOG_WARN,
+    LOG_ERROR,
+)
+from .utils import read_json, write_json, timestamp, timestamp_ms
+
+__all__ = [
+    "Logger_Init", "Logger_Uninit", "Logger_Write", "Get_Exe_Path",
+    "log_debug", "log_info", "log_warn", "log_error", "auto_log",
+    "LOG_DEBUG", "LOG_INFO", "LOG_WARN", "LOG_ERROR",
+    "read_json", "write_json", "timestamp", "timestamp_ms",
+]

zjs_kit-0.1.0/src/zjs_kit/utils.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# ========================================
+# @Created  :   2026/8/21 16:37
+# @File     :   utils.py
+# @Project  :   None
+# @Author   :   Jenson Zhang
+# @Contact  :   zhang.jinshuo@163.com
+# @Software :   PyCharm
+# @Purpose  :
+# ----------------------------------------
+# Updated   :   2026/8/21 16:37 (v1.0.0)
+# Upd. Cont.:   初始版本
+# Introduce :   
+# ========================================
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+def read_json(file_path: str) -> Any:
+    """
+    读取 JSON 文件并返回解析结果
+    """
+    with open(file_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+def write_json(file_path: str, data: Any, indent: int = 2, ensure_ascii: bool = False) -> None:
+    """
+    将数据写入 JSON 文件
+    """
+    Path(file_path).parent.mkdir(parents=True, exist_ok=True)
+    with open(file_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=ensure_ascii, indent=indent)
+
+def timestamp() -> int:
+    """
+    返回当前 Unix 时间戳 [s]
+    """
+    return int(time.time())
+
+def timestamp_ms() -> int:
+    """
+    返回当前 Unix 时间戳 [ms]
+    """
+    return int(time.time() * 1000)
+    return int(time.time() * 1000)

zjs_kit-0.1.0/src/zjs_kit.egg-info/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: zjs-kit
+Version: 0.1.0
+Summary: Jenson Zhang Kit
+Author: Jenson Zhang
+Requires-Python: >=3.8

zjs_kit-0.1.0/src/zjs_kit.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/zjs_kit/Logger.py
+src/zjs_kit/__init__.py
+src/zjs_kit/utils.py
+src/zjs_kit.egg-info/PKG-INFO
+src/zjs_kit.egg-info/SOURCES.txt
+src/zjs_kit.egg-info/dependency_links.txt
+src/zjs_kit.egg-info/top_level.txt

zjs_kit-0.1.0/src/zjs_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zjs_kit-0.1.0/src/zjs_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+zjs_kit