bykpy 0.1.0__tar.gz

bykpy-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: bykpy
+Version: 0.1.0
+Summary: Python Plugin infrastructure for bykpy
+Author-email: fcbyk <731240932@qq.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0.0
+Provides-Extra: test
+Requires-Dist: pytest<8.0.0,>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == "test"
+Provides-Extra: build
+Requires-Dist: commitizen; extra == "build"
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+
+# bykpy
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/github/license/fcbyk/bykcli.svg)](https://github.com/fcbyk/byk/blob/main/LICENSE)
+
+Plugin infrastructure for [byk](https://github.com/fcbyk/byk).
+
+## Install
+
+```bash
+pip install bykpy
+```
+
+## Usage
+
+Implement `PluginProtocol` and register your commands:
+
+```python
+# my_plugin.py
+import click
+from bykpy import PluginProtocol
+
+class MyPlugin(PluginProtocol):
+    commands = {"hello": "say hello"}
+
+    def register(self, cli: click.Group) -> None:
+        @cli.command()
+        @click.pass_context
+        def hello(ctx):
+            click.echo("Hello from my plugin!")
+```
+
+## API
+
+- **PluginProtocol** — class-based plugin registration protocol
+- **CommandContext / pass_command_context / get_app_context** — command runtime context
+- **get_private_networks / ensure_port_available** — network utilities
+- **StateStore** — persistent key-value storage per command
+
+## License
+
+MIT

bykpy-0.1.0/README.md

@@ -0,0 +1,42 @@
+# bykpy
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/github/license/fcbyk/bykcli.svg)](https://github.com/fcbyk/byk/blob/main/LICENSE)
+
+Plugin infrastructure for [byk](https://github.com/fcbyk/byk).
+
+## Install
+
+```bash
+pip install bykpy
+```
+
+## Usage
+
+Implement `PluginProtocol` and register your commands:
+
+```python
+# my_plugin.py
+import click
+from bykpy import PluginProtocol
+
+class MyPlugin(PluginProtocol):
+    commands = {"hello": "say hello"}
+
+    def register(self, cli: click.Group) -> None:
+        @cli.command()
+        @click.pass_context
+        def hello(ctx):
+            click.echo("Hello from my plugin!")
+```
+
+## API
+
+- **PluginProtocol** — class-based plugin registration protocol
+- **CommandContext / pass_command_context / get_app_context** — command runtime context
+- **get_private_networks / ensure_port_available** — network utilities
+- **StateStore** — persistent key-value storage per command
+
+## License
+
+MIT

bykpy-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bykpy"
+version = "0.1.0"
+description = "Python Plugin infrastructure for bykpy"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "fcbyk", email = "731240932@qq.com"}
+]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "click>=8.0.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0,<8.0.0",
+    "pytest-cov>=4.0.0,<5.0.0",
+]
+build = [
+    "commitizen",
+    "build",
+    "twine",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=bykpy --cov-report=term-missing"
+
+[tool.pyright]
+extraPaths = ["src"]

bykpy-0.1.0/setup.cfg

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

bykpy-0.1.0/src/bykpy/__init__.py

@@ -0,0 +1,5 @@
+from bykpy.core.plugin import PluginProtocol
+
+__version__ = "0.1.0"
+
+

bykpy-0.1.0/src/bykpy/__main__.py

@@ -0,0 +1,23 @@
+"""支持 ``python -m bykpy`` 运行。"""
+
+import sys
+
+
+if __name__ == "__main__":
+    # --scan-plugins: Rust 调用的无头模式，仅扫描插件并写缓存，不启动 CLI
+    if len(sys.argv) >= 2 and sys.argv[1] == "--scan-plugins":
+        from pathlib import Path
+
+        from bykpy.infra.cache import _build_cache
+        from bykpy.infra.persistence import write_json
+
+        cache_dir = Path.home() / ".byk" / "cache"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+
+        data = _build_cache()
+        write_json(cache_dir / "app.json", data)
+        sys.exit(0)
+
+    from bykpy.app import create_cli
+
+    create_cli()()

bykpy-0.1.0/src/bykpy/api/__init__.py

@@ -0,0 +1,22 @@
+"""面向子命令和插件的公开运行时 API。"""
+
+from bykpy.api.context import CommandContext, pass_command_context, get_app_context
+
+from bykpy.api.network import (
+    get_private_networks,
+    ensure_port_available,
+)
+
+from bykpy.core.state import StateStore
+
+__all__ = [
+    # 上下文
+    "CommandContext",
+    "pass_command_context",
+    "get_app_context",
+    # 网络工具
+    "get_private_networks",
+    "ensure_port_available",
+    # 状态存储
+    "StateStore",
+]

bykpy-0.1.0/src/bykpy/api/context.py

@@ -0,0 +1,65 @@
+"""面向子命令的上下文封装。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from functools import update_wrapper
+import logging
+from typing import Any, Callable, TypeVar, cast
+
+import click
+
+from bykpy.app import CliState
+from bykpy.core.context import AppContext, CommandContextLike
+from bykpy.core.state import StateStore
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(slots=True)
+class CommandContext(CommandContextLike):
+    """提供给子命令的便捷上下文。"""
+
+    name: str
+    app: AppContext
+    logger: logging.Logger
+    _state_cache: dict[str, StateStore] = field(default_factory=dict, init=False, repr=False)
+
+    def state(self, name: str = "state") -> StateStore:
+        """获取当前命令的专属存储。"""
+        if name not in self._state_cache:
+            self._state_cache[name] = self.app.command_store(self.name, name)
+        return self._state_cache[name]
+
+def _get_group_name(ctx: click.Context) -> str:
+    """获取二级命令名"""
+    node = ctx
+    while node.parent and node.parent.parent is not None:
+        node = node.parent
+    return node.command.name or "unknown"
+
+def build_command_context(ctx: click.Context) -> CommandContext:
+    """根据当前 Click 上下文构建命令上下文"""
+    state = cast(CliState, ctx.obj)
+    command_name = _get_group_name(ctx)
+    return CommandContext(
+        name=command_name,
+        app=state.context,
+        logger=state.context.get_command_logger(command_name),
+    )
+
+
+def pass_command_context(func: F) -> F:
+    """向子命令注入便捷上下文。"""
+
+    @click.pass_context
+    def new_func(ctx: click.Context, *args: Any, **kwargs: Any) -> Any:
+        return ctx.invoke(func, build_command_context(ctx), *args, **kwargs)
+
+    return cast(F, update_wrapper(new_func, func))
+
+
+def get_app_context() -> AppContext:
+    """获取当前应用上下文。"""
+    from bykpy.runtime import build_runtime
+    return build_runtime()

bykpy-0.1.0/src/bykpy/api/network.py

@@ -0,0 +1,91 @@
+"""网络工具函数。"""
+import socket
+from typing import List, Dict
+
+
+# 网络接口分类规则：(关键词列表，类型名称，是否虚拟接口，优先级)
+IFACE_RULES = [
+    (['vmware', 'vmnet'],         'vmware',     True,  30),
+    (['vbox', 'virtualbox'],      'virtualbox', True,  30),
+    (['docker', 'wsl'],           'container',  True,  40),
+    (['bluetooth'],               'bluetooth',  True,  60),
+    (['ethernet', '以太网'],       'ethernet',   False, 10),
+    (['wlan', 'wi-fi', '无线'],   'wifi',       False, 10),
+    (['loopback'],                'loopback',   True,  100),
+]
+
+
+def detect_iface_type(iface: str) -> tuple[str, bool, int]:
+    """检测网络接口类型。"""
+    lname = iface.lower()
+    for keywords, t, virtual, prio in IFACE_RULES:
+        if any(k in lname for k in keywords):
+            return t, virtual, prio
+    return 'unknown', False, 50
+
+
+def get_private_networks() -> List[Dict]:
+    """获取所有局域网 IP 地址信息。"""
+    try:
+        import psutil
+    except ImportError:
+        return [{
+            "iface": "localhost",
+            "ips": ["127.0.0.1"],
+            "type": "loopback",
+            "virtual": True,
+            "priority": 100
+        }]
+
+    results = []
+    interfaces = psutil.net_if_addrs()
+
+    for iface, addrs in interfaces.items():
+        ips = []
+        iface_type, is_virtual, priority = detect_iface_type(iface)
+
+        for addr in addrs:
+            if addr.family != socket.AF_INET:
+                continue
+
+            ip = addr.address
+
+            # 跳过回环地址和链路本地地址
+            if ip.startswith('127.'):
+                continue
+            if ip.startswith('169.254.'):
+                continue
+            # 只保留私有 IP 地址
+            if ip.startswith(('10.', '192.168.', '172.')):
+                ips.append(ip)
+
+        if ips:
+            results.append({
+                "iface": iface,
+                "ips": ips,
+                "type": iface_type,
+                "virtual": is_virtual,
+                "priority": priority
+            })
+
+    # 按优先级排序（数字越小优先级越高）
+    results.sort(key=lambda x: x['priority'])
+    
+    # 如果没有找到任何局域网 IP，返回 localhost
+    if not results:
+        results.append({
+            "iface": "localhost",
+            "ips": ["127.0.0.1"],
+            "type": "loopback",
+            "virtual": True,
+            "priority": 100
+        })
+    
+    return results
+
+
+def ensure_port_available(port: int, host: str = "0.0.0.0") -> None:
+    """检查端口是否可用。"""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind((host, int(port)))

bykpy-0.1.0/src/bykpy/app.py

@@ -0,0 +1,160 @@
+"""CLI 应用装配。"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import click
+
+from bykpy.core.context import AppContext
+from bykpy.core.errors import CliError
+
+logger = logging.getLogger("bykpy")
+
+
+def _resolve_log_path(ctx: click.Context) -> str:
+    """解析日志文件绝对路径，提供健壮的 fallback。"""
+    try:
+        if ctx.obj is not None:
+            paths = ctx.obj.context.paths
+            if paths is not None:
+                return str(paths.app_log_file)
+    except Exception:
+        pass
+
+    # 运行时未初始化时的备选路径
+    return str(Path.home() / ".byk" / "logs" / "app.log")
+
+
+class PluginAwareGroup(click.Group):
+    """支持插件动态加载的命令组。"""
+
+    runtime_provider: Any = None
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        return super().parse_args(ctx, args)
+
+    def resolve_command(
+        self,
+        ctx: click.Context,
+        args: list[str],
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        orig_args = list(args)
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            pass
+
+        if not orig_args:
+            return super().resolve_command(ctx, orig_args)
+
+        context = self._get_context(ctx)
+
+        # 检查缓存中的插件命令，按需加载单个插件
+        from bykpy.infra.cache import load_cache
+        from bykpy.infra.registry import load_single_plugin
+
+        cache_data = load_cache(context.paths.cache_dir / "app.json")
+        if orig_args[0] in cache_data.get("commands", {}):
+            cmd_name = orig_args[0]
+            module_path = cache_data["commands"][cmd_name]["module"]
+            load_single_plugin(self, cmd_name, module_path)
+            return super().resolve_command(ctx, orig_args)
+
+        # 未知命令
+        raise click.UsageError(f"Unknown command: {orig_args[0]}")
+
+    def _get_context(self, ctx: click.Context) -> AppContext:
+        """在命令解析阶段获取运行时上下文。"""
+        if ctx.obj is not None:
+            return ctx.obj.context
+        if callable(self.runtime_provider):
+            return self.runtime_provider()  # type: ignore[return-type]
+        raise click.ClickException("Runtime context not yet initialized")
+
+    def invoke(self, ctx: click.Context) -> Any:
+        """统一兜底未处理异常"""
+        try:
+            return super().invoke(ctx)
+        except click.ClickException:
+            raise
+        except click.exceptions.Exit:
+            raise
+        except CliError as exc:
+            logger.warning("cli error: %s", exc)
+            raise click.ClickException(str(exc)) from exc
+        except SystemExit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("unexpected cli error")
+            log_file = _resolve_log_path(ctx)
+            raise click.ClickException(
+                f"Unexpected error occurred, see logs at: {log_file}"
+            ) from exc
+
+
+@dataclass(slots=True)
+class CliState:
+    """Click 根命令共享状态。"""
+
+    context: AppContext
+
+
+def version_callback(
+    ctx: click.Context,
+    _param: click.Parameter,
+    value: bool,
+) -> None:
+    """Show version and exit."""
+    if not value or ctx.resilient_parsing:
+        return
+
+    from bykpy.runtime import build_runtime
+
+    app_context: AppContext = ctx.obj.context if ctx.obj else build_runtime()
+    click.echo(f"v{app_context.version}")
+    ctx.exit()
+
+
+def create_cli() -> click.Group:
+    """创建根 CLI 对象。"""
+
+    from bykpy.runtime import build_runtime
+
+    runtime: AppContext | None = None
+
+    def get_runtime() -> AppContext:
+        nonlocal runtime
+        if runtime is None:
+            runtime = build_runtime()
+        return runtime
+
+    @click.group(
+        cls=PluginAwareGroup,
+        context_settings={"help_option_names": ["-h", "--help"]},
+        add_help_option=False,
+        invoke_without_command=True,
+    )
+    @click.option(
+        "--version",
+        "-v",
+        is_flag=True,
+        callback=version_callback,
+        expose_value=False,
+        is_eager=True,
+        help="Show version and exit.",
+    )
+    @click.pass_context
+    def cli(ctx: click.Context) -> None:
+        ctx.obj = CliState(context=get_runtime())
+        ctx.obj.context.logger.info("BYK v%s started", ctx.obj.context.version)
+        if ctx.invoked_subcommand is None:
+            from bykpy.infra.view import render_dashboard
+
+            render_dashboard(ctx.obj.context, cli)
+
+    cli.runtime_provider = get_runtime
+    return cli

bykpy-0.1.0/src/bykpy/core/__init__.py

@@ -0,0 +1,14 @@
+"""核心能力模块。"""
+
+from bykpy.core.context import AppContext, CommandContextLike
+from bykpy.core.environment import EnvironmentInfo
+from bykpy.core.persistence import PathLayout
+from bykpy.core.state import StateStore
+
+__all__ = [
+    "AppContext",
+    "CommandContextLike",
+    "EnvironmentInfo",
+    "PathLayout",
+    "StateStore",
+]

bykpy-0.1.0/src/bykpy/core/context.py

@@ -0,0 +1,50 @@
+"""CLI 运行时上下文。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+from typing import TYPE_CHECKING, Protocol
+
+from bykpy.core.environment import EnvironmentInfo
+from bykpy.core.persistence import PathLayout
+
+if TYPE_CHECKING:
+    from bykpy.core.state import StateStore
+
+
+class CommandContextLike(Protocol):
+    """命令上下文协议。"""
+
+    name: str
+    app: "AppContext"
+    logger: logging.Logger
+
+    def state(self, name: str = "state") -> "StateStore": ...
+
+
+@dataclass(slots=True)
+class AppContext:
+    """子命令共享的核心上下文。"""
+
+    app_name: str
+    version: str
+    paths: PathLayout
+    environment: EnvironmentInfo
+    logger: logging.Logger
+
+    def command_store(
+        self,
+        command_name: str,
+        name: str = "state",
+    ) -> StateStore:
+        """返回某个子命令的状态存储。"""
+        raise NotImplementedError
+
+    def store(self, name: str = "byk.config") -> StateStore:
+        """返回应用级共享状态存储。"""
+        raise NotImplementedError
+
+    def get_command_logger(self, command_name: str) -> logging.Logger:
+        """获取命令专属 logger。"""
+        raise NotImplementedError

bykpy-0.1.0/src/bykpy/core/environment.py

@@ -0,0 +1,29 @@
+"""运行环境信息。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import platform
+import sys
+
+
+@dataclass(slots=True)
+class EnvironmentInfo:
+    """CLI 运行环境信息。"""
+
+    app_name: str
+    version: str
+    python_version: str
+    executable: str
+    platform_name: str
+
+
+def collect_environment(app_name: str, version: str) -> EnvironmentInfo:
+    """收集当前运行环境。"""
+    return EnvironmentInfo(
+        app_name=app_name,
+        version=version,
+        python_version=platform.python_version(),
+        executable=sys.executable,
+        platform_name=platform.platform(),
+    )

bykpy-0.1.0/src/bykpy/core/errors.py

@@ -0,0 +1,7 @@
+"""统一异常定义。"""
+
+from __future__ import annotations
+
+
+class CliError(RuntimeError):
+    """面向终端用户的业务异常。"""

bykpy-0.1.0/src/bykpy/core/persistence.py

@@ -0,0 +1,53 @@
+"""持久化路径布局。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class PathLayout:
+    """持久化目录布局数据结构。"""
+
+    root_dir: Path
+    state_dir: Path
+    logs_dir: Path
+    runtime_dir: Path
+    app_log_file: Path
+    cache_dir: Path
+
+    @staticmethod
+    def _validate_safe_name(value: str, field_name: str) -> str:
+        """校验名称安全性，防止路径穿越和脏数据文件名。"""
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError(f"{field_name} 不能为空")
+        if normalized in {".", ".."}:
+            raise ValueError(f"{field_name} 不能为 '.' 或 '..'")
+        if "/" in normalized or "\\" in normalized:
+            raise ValueError(f"{field_name} 不能包含路径分隔符")
+        return normalized
+
+    def command_state_dir(self, command_name: str) -> Path:
+        """返回子命令专属目录。"""
+        safe_command_name = self._validate_safe_name(command_name, "command_name")
+        path = self.state_dir / safe_command_name
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def command_state_file(self, command_name: str, *parts: str) -> Path:
+        """返回子命令专属文件路径。"""
+        target = self.command_state_dir(command_name)
+        for part in parts:
+            safe_part = self._validate_safe_name(part, "part")
+            target = target / safe_part
+        target.parent.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def state_file(self, name: str) -> Path:
+        """返回应用级状态文件路径。"""
+        safe_name = self._validate_safe_name(name, "name")
+        path = self.state_dir / f"{safe_name}.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return path