bitool 0.1.2__py3-none-any.whl

bitool/core/logger.py

@@ -0,0 +1,237 @@
+"""Bitool 的日志模块.
+
+本模块提供一个简单的、类似 loguru 的日志系统,具有彩色输出、文件轮转和易于使用的 API.
+
+快速开始
+--------
+>>> from bitool.core import logger
+>>> logger.info("Hello, World!")  # 彩色输出到控制台和文件
+>>> logger.debug("看不到调试信息")
+>>> logger.setLevel(logger.DEBUG)
+>>> logger.debug("现在可以看到调试信息了")
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import logging.handlers
+import platform
+import sys
+import threading
+from pathlib import Path
+from typing import ClassVar, Final
+
+__all__ = ["logger"]
+
+# 默认日志格式
+_DEFAULT_CONSOLE_FORMAT: Final[str] = "%(asctime)s | %(levelname)-8s | %(message)s"
+_DEFAULT_FILE_FORMAT: Final[str] = (
+    "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+_DEFAULT_CONSOLE_DATEFMT: Final[str] = "%H:%M:%S"
+_DEFAULT_FILE_DATEFMT: Final[str] = "%Y-%m-%d %H:%M:%S"
+
+# 默认日志路径
+_DEFAULT_LOG_DIR: Final[Path] = Path.home() / ".bitool" / "logs"
+_DEFAULT_LOG_FILE: Final[Path] = _DEFAULT_LOG_DIR / "bitool.log"
+_DEFAULT_MAX_BYTES: Final[int] = 10 * 1024 * 1024  # 10MB
+_DEFAULT_BACKUP_COUNT: Final[int] = 5
+
+
+class _ColoredFormatter(logging.Formatter):
+    """自定义格式化器,为日志消息添加 ANSI 颜色."""
+
+    COLORS: ClassVar[dict[str, str]] = {
+        "DEBUG": "\033[36m",  # 青色
+        "INFO": "\033[32m",  # 绿色
+        "WARNING": "\033[33m",  # 黄色
+        "ERROR": "\033[31m",  # 红色
+        "CRITICAL": "\033[41m",  # 红底白字
+        "RESET": "\033[0m",  # 重置颜色
+    }
+
+    def __init__(self, fmt: str | None = None, datefmt: str | None = None) -> None:
+        """初始化格式化器,检测是否支持 ANSI 颜色."""
+        super().__init__(fmt, datefmt)
+        # 检测是否启用彩色输出
+        self._enable_colors = self._check_color_support()
+
+    @staticmethod
+    def _check_color_support() -> bool:
+        """检查当前环境是否支持 ANSI 颜色."""
+        # Windows 10 及以上版本支持 ANSI 转义序列
+        if platform.system() == "Windows":
+            try:
+                # 获取 Windows 版本号
+                version = platform.version()
+                # Windows 版本号格式为 "major.minor.build"
+                major_version = int(version.split(".")[0])
+                # Windows 10 的版本号为 10, Windows 7 为 6
+
+            except (ValueError, IndexError):
+                # 如果无法解析版本号,保守起见禁用颜色
+                return False
+            else:
+                return major_version >= 10
+
+        # 非 Windows 系统通常支持 ANSI 颜色
+        return True
+
+    def format(self, record: logging.LogRecord) -> str:
+        """使用适当的颜色格式化日志记录."""
+        message = super().format(record)
+        if not self._enable_colors:
+            return message
+        log_color = self.COLORS.get(record.levelname, self.COLORS["RESET"])
+        return f"{log_color}{message}{self.COLORS['RESET']}"
+
+
+class _Logger:
+    """一个简单的、类似 loguru 的日志器.
+
+    提供干净、最小化的 API,用于带有自动控制台颜色和文件轮转的日志记录。
+
+    示例
+    --------
+        >>> from bitool.core import logger
+        >>> logger.info("Hello, World!")
+        >>> logger.debug("Debug message")  # 仅在启用调试时显示
+        >>> logger.error("Error occurred")
+    """
+
+    _instance: ClassVar[logging.Logger | None] = None
+    _setup_lock: ClassVar[threading.Lock] = threading.Lock()
+    _is_setup: ClassVar[bool] = False
+
+    # 日志级别常量 (与 Python logging 模块兼容)
+    DEBUG: Final[int] = logging.DEBUG
+    INFO: Final[int] = logging.INFO
+    WARNING: Final[int] = logging.WARNING
+    ERROR: Final[int] = logging.ERROR
+    CRITICAL: Final[int] = logging.CRITICAL
+
+    @classmethod
+    def _setup(
+        cls,
+        name: str = "bitool",
+        level: int = logging.INFO,
+        console_format: str | None = None,
+        file_format: str | None = None,
+    ) -> logging.Logger:
+        """设置带有控制台和文件处理器的日志器.
+
+        此方法应在应用程序启动时调用一次。
+        后续调用将返回现有的日志器实例。
+
+        参数
+        ----------
+        name : str
+            日志器名称。默认为 "bitool"
+        level : int
+            最低日志级别。默认为 INFO
+            使用 logger.DEBUG 获取更详细的输出
+        console_format : str, optional
+            控制台日志格式。默认为 "%(asctime)s | %(levelname)-8s | %(message)s"
+        file_format : str, optional
+            文件日志格式。默认为 "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+        返回
+        -------
+        logging.Logger
+            配置好的带有控制台和文件处理器的日志器
+        """
+        # 线程安全的单例初始化
+        with cls._setup_lock:
+            if cls._is_setup and cls._instance is not None:
+                return cls._instance
+
+            # 确保日志目录存在
+            with contextlib.suppress(OSError):
+                _DEFAULT_LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+            # 创建日志器
+            logger_instance = logging.getLogger(name)
+            logger_instance.setLevel(logging.DEBUG)  # 捕获所有级别,在处理器级别过滤
+
+            # 控制台处理器
+            console_handler = logging.StreamHandler(sys.stdout)
+            console_handler.setLevel(level)
+            console_fmt = console_format if console_format else _DEFAULT_CONSOLE_FORMAT
+            console_formatter = _ColoredFormatter(
+                console_fmt, datefmt=_DEFAULT_CONSOLE_DATEFMT
+            )
+            console_handler.setFormatter(console_formatter)
+
+            # 文件处理器 - 捕获所有 DEBUG+ 日志并带轮转功能
+            file_handler = logging.handlers.RotatingFileHandler(
+                _DEFAULT_LOG_FILE,
+                maxBytes=_DEFAULT_MAX_BYTES,
+                backupCount=_DEFAULT_BACKUP_COUNT,
+                encoding="utf-8",
+            )
+            file_handler.setLevel(logging.DEBUG)
+            file_fmt = file_format if file_format else _DEFAULT_FILE_FORMAT
+            file_formatter = logging.Formatter(file_fmt, datefmt=_DEFAULT_FILE_DATEFMT)
+            file_handler.setFormatter(file_formatter)
+
+            # 添加处理器
+            logger_instance.addHandler(console_handler)
+            logger_instance.addHandler(file_handler)
+
+            # 防止多次添加处理器
+            logger_instance.propagate = False
+
+            cls._instance = logger_instance
+            cls._is_setup = True
+            return cls._instance
+
+    @classmethod
+    def _get_logger(cls, name: str = "bitool") -> logging.Logger:
+        """获取日志器实例.
+
+        如果日志器尚未设置,此方法将使用默认设置进行设置。
+        如需自定义配置,请显式调用 setup()。
+
+        参数
+        ----------
+        name : str
+            日志器名称。默认为 "bitool"
+
+        返回
+        -------
+        logging.Logger
+            配置好的日志器实例
+        """
+        if cls._instance is None:
+            return cls._setup(name)
+        return cls._instance
+
+    @classmethod
+    def setLevel(cls, level: int) -> None:
+        """设置日志级别,同时更新 Logger 和所有 Handler 的级别.
+
+        解决 Python logging 的两级过滤问题:
+        - Logger 级别:决定哪些消息进入日志系统
+        - Handler 级别:决定哪些消息实际输出
+
+        参数
+        ----------
+        level : int
+            日志级别,如 logging.DEBUG, logging.INFO 等
+
+        示例
+        --------
+        >>> from bitool.core import logger
+        >>> logger.setLevel(logger.DEBUG)  # 启用调试日志
+        >>> logger.debug("调试信息")  # 现在会正常输出
+        """
+        if cls._instance is not None:
+            logging.Logger.setLevel(cls._instance, level)
+            for handler in cls._instance.handlers:
+                handler.setLevel(level)
+
+
+# 预配置的日志器实例,便于导入
+logger: Final[logging.Logger] = _Logger._get_logger()
+logger.setLevel = _Logger.setLevel  # type: ignore

bitool/core/plugin.py

@@ -0,0 +1,117 @@
+"""插件系统基础框架."""
+
+from __future__ import annotations
+
+import importlib.util
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass
+class PluginMetadata:
+    """插件元数据."""
+
+    name: str
+    version: str = "0.1.0"
+    description: str = ""
+    author: str = ""
+
+
+class Plugin(ABC):
+    """插件基类."""
+
+    @property
+    @abstractmethod
+    def metadata(self) -> PluginMetadata:
+        """返回插件元数据."""
+        ...
+
+    @abstractmethod
+    def register(self, registry: PluginRegistry) -> None:
+        """注册插件提供的命令和能力."""
+        ...
+
+    def initialize(self, context: PluginContext) -> None:  # noqa: B027
+        """插件初始化钩子（可选覆盖）."""
+        # 默认实现：无需初始化操作
+
+    def shutdown(self) -> None:  # noqa: B027
+        """插件关闭钩子（可选覆盖）."""
+        # 默认实现：无需清理操作
+
+
+@dataclass
+class PluginContext:
+    """插件上下文，提供插件运行所需的环境."""
+
+    workspace: Any = None
+    config: Any = None
+    registry: Any = None
+
+
+@dataclass
+class PluginRegistry:
+    """插件注册表."""
+
+    _plugins: dict[str, Plugin] = field(default_factory=dict)
+    _commands: dict[str, Callable[..., Any]] = field(default_factory=dict)
+
+    def register_plugin(self, plugin: Plugin) -> None:
+        """注册插件."""
+        meta = plugin.metadata
+        if meta.name in self._plugins:
+            raise ValueError(f"插件 {meta.name} 已注册")
+        self._plugins[meta.name] = plugin
+
+    def register_command(self, name: str, handler: Callable[..., Any]) -> None:
+        """注册命令."""
+        if name in self._commands:
+            raise ValueError(f"命令 {name} 已注册")
+        self._commands[name] = handler
+
+    def get_plugin(self, name: str) -> Plugin | None:
+        """获取插件."""
+        return self._plugins.get(name)
+
+    def get_command(self, name: str) -> Callable[..., Any] | None:
+        """获取命令处理器."""
+        return self._commands.get(name)
+
+    def list_plugins(self) -> list[str]:
+        """列出所有已注册的插件."""
+        return list(self._plugins.keys())
+
+    def list_commands(self) -> list[str]:
+        """列出所有已注册的命令."""
+        return list(self._commands.keys())
+
+    def load_plugins_from_directory(self, directory: str | Path) -> None:
+        """从目录加载插件."""
+        directory = Path(directory).expanduser()
+        if not directory.exists():
+            return
+
+        for plugin_file in directory.glob("*.py"):
+            self._load_plugin_module(plugin_file)
+
+    def _load_plugin_module(self, plugin_file: Path) -> None:
+        """加载单个插件模块."""
+        import sys
+
+        spec = importlib.util.spec_from_file_location(plugin_file.stem, plugin_file)
+        if spec is None or spec.loader is None:
+            return
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[plugin_file.stem] = module
+        spec.loader.exec_module(module)
+
+        # 查找 Plugin 子类并实例化
+        for attr_name in dir(module):
+            attr = getattr(module, attr_name)
+            if isinstance(attr, type) and issubclass(attr, Plugin) and attr is not Plugin:
+                plugin = attr()
+                self.register_plugin(plugin)
+                plugin.register(self)

bitool/core/workspace.py

@@ -0,0 +1,76 @@
+"""工作空间管理模块."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class WorkspaceManager:
+    """工作空间管理器."""
+
+    def __init__(self, root: str | Path | None = None) -> None:
+        """初始化工作空间管理器.
+
+        Args:
+            root: 工作空间根路径
+        """
+        self._root = Path(root) if root else Path.cwd()
+        self._variables: dict[str, str] = {}
+
+    @property
+    def root(self) -> str:
+        """获取工作空间根路径."""
+        return str(self._root)
+
+    @root.setter
+    def root(self, value: str | Path) -> None:
+        """设置工作空间根路径."""
+        self._root = Path(value)
+
+    def set_var(self, name: str, value: str) -> None:
+        """设置工作空间变量.
+
+        Args:
+            name: 变量名
+            value: 变量值
+        """
+        self._variables[name] = value
+
+    def get_var(self, name: str, default: str = "") -> str:
+        """获取工作空间变量.
+
+        Args:
+            name: 变量名
+            default: 默认值
+
+        Returns:
+            变量值
+        """
+        return self._variables.get(name, default)
+
+    def resolve_path(self, relative_path: str | Path) -> Path:
+        """解析相对于工作空间根目录的路径.
+
+        Args:
+            relative_path: 相对路径
+
+        Returns:
+            绝对路径
+        """
+        path = Path(relative_path)
+        if path.is_absolute():
+            return path
+        return self._root / path
+
+    def ensure_dir(self, relative_path: str | Path) -> Path:
+        """确保目录存在.
+
+        Args:
+            relative_path: 相对路径
+
+        Returns:
+            绝对路径
+        """
+        path = self.resolve_path(relative_path)
+        path.mkdir(parents=True, exist_ok=True)
+        return path

bitool/models/__init__.py

@@ -0,0 +1,3 @@
+from .version import Version, VersionError, VersionPart
+
+__all__ = ["Version", "VersionError", "VersionPart"]

bitool/models/version.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from functools import lru_cache
+from re import Pattern
+from typing import Final
+
+VERSION_PATTERN: Final[Pattern[str]] = re.compile(
+    r"(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?"
+)
+
+
+class VersionPart(Enum):
+    """可更新的版本号部分."""
+
+    MAJOR = "major"
+    MINOR = "minor"
+    PATCH = "patch"
+
+
+class VersionError(Exception):
+    """版本号相关异常."""
+
+
+@dataclass
+class Version:
+    """语义化版本号, 遵循 SemVer 2.0.0 规范.
+
+    Attributes
+    ----------
+    major: 主版本号 (破坏性变更时递增)
+    minor: 次版本号 (向后兼容的功能新增时递增)
+    patch: 补丁号 (向后兼容的 bug 修复时递增)
+    prerelease: 预发布标识 (如 "alpha", "beta.1", "rc")
+    buildmetadata: 构建元数据 (不参与版本比较)
+    """
+
+    major: int
+    minor: int
+    patch: int
+    prerelease: str | None = None
+    buildmetadata: str | None = None
+
+    def __str__(self) -> str:
+        """返回版本号的字符串表示."""
+        version = f"{self.major}.{self.minor}.{self.patch}"
+        if self.prerelease:
+            version += f"-{self.prerelease}"
+        if self.buildmetadata:
+            version += f"+{self.buildmetadata}"
+        return version
+
+    @classmethod
+    @lru_cache(maxsize=128)
+    def parse(cls, version_string: str) -> Version:
+        """解析版本号字符串为 Version 对象.
+
+        Parameters
+        ----------
+        version_string : str
+            版本号字符串
+
+        Returns
+        -------
+        Version
+            解析后的 Version 对象
+
+        Raises
+        ------
+        VersionError
+            版本号格式无效时抛出
+        """
+        if not version_string:
+            msg = "版本号字符串不能为空"
+            raise VersionError(msg)
+
+        match = VERSION_PATTERN.match(version_string)
+        if not match:
+            msg = f"无效的版本号格式: {version_string}"
+            raise VersionError(msg)
+
+        return cls(
+            major=int(match.group("major")),
+            minor=int(match.group("minor")),
+            patch=int(match.group("patch")),
+            prerelease=match.group("prerelease"),
+            buildmetadata=match.group("buildmetadata"),
+        )
+
+    def bump(
+        self,
+        part: VersionPart,
+        *,
+        reset_prerelease: bool = True,
+        prerelease: str | None = None,
+    ) -> Version:
+        """返回递增指定部分后的新版本号.
+
+        Parameters
+        ----------
+        part : VersionPart
+            要递增的版本号部分 (major, minor, patch)
+        reset_prerelease : bool
+            是否重置预发布标识, 默认是
+        prerelease : str | None
+            可选的预发布标识, 默认 None
+
+        Returns
+        -------
+        Version
+            递增后的新版本号
+        """
+        # 确定新的预发布标识值
+        new_prerelease = None
+        if prerelease is not None:
+            new_prerelease = prerelease
+        elif not reset_prerelease:
+            new_prerelease = self.prerelease
+
+        if part == VersionPart.MAJOR:
+            return Version(
+                major=self.major + 1,
+                minor=0,
+                patch=0,
+                prerelease=new_prerelease,
+                buildmetadata=None,  # 总是重置构建元数据
+            )
+        if part == VersionPart.MINOR:
+            return Version(
+                major=self.major,
+                minor=self.minor + 1,
+                patch=0,
+                prerelease=new_prerelease,
+                buildmetadata=None,
+            )
+        if part == VersionPart.PATCH:
+            return Version(
+                major=self.major,
+                minor=self.minor,
+                patch=self.patch + 1,
+                prerelease=new_prerelease,
+                buildmetadata=None,
+            )
+
+        msg = f"不支持的版本号部分: {part}"
+        raise VersionError(msg)
+
+    def set_prerelease(self, prerelease: str) -> Version:
+        """返回设置预发布标识后的新版本号.
+
+        Parameters
+        ----------
+        prerelease : str
+            预发布标识
+
+        Returns
+        -------
+        Version
+            设置预发布标识后的新版本号
+        """
+        if not prerelease:
+            msg = "预发布标识不能为空"
+            raise VersionError(msg)
+
+        return Version(
+            major=self.major,
+            minor=self.minor,
+            patch=self.patch,
+            prerelease=prerelease,
+            buildmetadata=None,
+        )

bitool/scripts/__init__.py

@@ -0,0 +1 @@
+"""Scripts 工具模块."""