kotonebot 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

kotonebot/devtools/cli/__init__.py

@@ -0,0 +1,6 @@
+def main():
+    """Entry point for the kbot command."""
+    from .main import main as _main
+    return _main()
+
+__all__ = ["main"]

kotonebot/devtools/cli/main.py

@@ -0,0 +1,53 @@
+import sys
+import argparse
+
+from ..web.server.server import start_devtools
+
+
+def main():
+    """KotoneBot CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="kbot",
+        description="KotoneBot command-line interface"
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # devtools subcommand
+    devtools_parser = subparsers.add_parser(
+        "devtools",
+        help="Start the KotoneBot DevTools web server"
+    )
+    devtools_parser.add_argument(
+        "--port",
+        type=int,
+        default=1178,
+        help="Port to listen on (default: 1178)"
+    )
+    devtools_parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host to listen on (default: 127.0.0.1)"
+    )
+    devtools_parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Do not automatically open browser"
+    )
+    
+    args = parser.parse_args()
+    
+    if args.command == "devtools":
+        start_devtools(
+            host=args.host,
+            port=args.port,
+            open_browser=not args.no_browser
+        )
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

kotonebot/devtools/project/project.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+try:
+    from tomllib import loads as toml_loader  # py>=3.11 # type: ignore
+except ModuleNotFoundError:  # pragma: no cover
+    from tomli import loads as toml_loader  # py<3.11
+
+from kotonebot.devtools.project.schema import PyProjectData
+
+
+PYPROJECT_PATH = './pyproject.toml'
+
+class Project:
+    def __init__(self, *, conf_path: str = PYPROJECT_PATH) -> None:
+        self.conf_path: str = conf_path
+        self.conf: PyProjectData
+
+        self.load()
+    
+    def load(self) -> None:
+        """
+        载入项目的配置文件。
+        
+        :raises FileNotFoundError: 如果配置文件不存在。
+        :raises toml.TomlDecodeError: 如果配置文件格式无效。
+        """
+        conf_dict = toml_loader(Path(self.conf_path).read_text(encoding='utf-8'))
+
+        tool_conf = conf_dict.get('tool', {}).get('kotonebot', {})
+        if tool_conf:
+            self.conf = PyProjectData.model_validate(tool_conf)
+        else:
+            self.conf = PyProjectData()
+        
+        if self.conf.editor and self.conf.editor.resource_path is not None:
+            self.conf.editor.resource_path = str(Path(self.conf.editor.resource_path).absolute())
+
+
+if __name__ == '__main__':
+    project = Project()
+    print(project.conf)

kotonebot/devtools/project/scanner.py

@@ -0,0 +1,202 @@
+import os
+import json
+import sys
+import pkgutil
+import inspect
+import importlib
+import subprocess
+import contextlib
+from typing import Any, Dict
+
+from pydantic import BaseModel
+
+# ==============================================================================
+#  Public API
+# ==============================================================================
+
+def scan_prefabs(package_name: str, python_executable: str = sys.executable) -> Dict[str, Any]:
+    """
+    在一个隔离的子进程中扫描指定的 Python 包，先扫描默认包
+    `kotonebot.core.entities`，然后扫描传入的包（两次扫描在一次子进程内完成）。
+
+    Args:
+        package_name: 要扫描的包的点分名称 (例如 'my_app.components')。
+        python_executable: 用于运行子进程的 Python 解释器路径。
+                           默认为当前正在运行的 Python 解释器。
+
+    Returns:
+        一个字典，包含扫描结果；在错误情况下返回空字典。
+    """
+    default_pkg = 'kotonebot.core.entities'
+    print(f"--- Main process (PID: {os.getpid()}) starting worker for packages: '{default_pkg}' and '{package_name}'... ---")
+
+    packages = [default_pkg]
+    if package_name and package_name != default_pkg:
+        packages.append(package_name)
+
+    # `__file__` 指向当前脚本文件，它将以工作模式被再次执行，传入要扫描的包列表
+    command = [python_executable, __file__, '--worker', *packages]
+    
+    try:
+        child_env = os.environ.copy()
+        child_env.setdefault('PYTHONUTF8', '1')
+        child_env.setdefault('PYTHONIOENCODING', 'utf-8:replace')
+
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=False, # 手动处理错误，不让它自动抛出异常
+            encoding='utf-8',
+            env=child_env,
+            cwd=os.getcwd()
+        )
+    except FileNotFoundError:
+        print(f"Error: Python executable not found at '{python_executable}'.", file=sys.stderr)
+        return {}
+
+    # 打印来自子进程的任何日志/调试信息
+    if result.stderr:
+        print("\n--- Logs/Errors from worker process ---", file=sys.stderr)
+        print(result.stderr.strip(), file=sys.stderr)
+        print("-------------------------------------\n", file=sys.stderr)
+    
+    if result.returncode != 0:
+        print(f"Error: Worker process exited abnormally with return code: {result.returncode}", file=sys.stderr)
+        return {}
+
+    try:
+        # 从子进程的标准输出解析 JSON 数据
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        print("Error: Failed to parse JSON from worker process output.", file=sys.stderr)
+        print("--- STDOUT from worker process ---", file=sys.stderr)
+        print(result.stdout, file=sys.stderr)
+        print("--------------------------------", file=sys.stderr)
+        return {}
+
+# ==============================================================================
+#  Internal Worker Logic (在子进程中运行)
+# ==============================================================================
+
+def _get_class_properties(cls: type) -> Dict[str, Any]:
+    # Collect attributes from the class and its bases (inheritance),
+    # allowing subclass attributes to override base attributes.
+    properties: Dict[str, Any] = {}
+    for base in reversed(cls.__mro__):
+        # skip builtin object and EditorMetadata base to avoid copying framework internals
+        if base is object or base.__name__ == 'EditorMetadata':
+            continue
+
+        for key, value in vars(base).items():
+            if key.startswith('__') or callable(value):
+                continue
+
+            properties[key] = value
+
+    return properties
+
+
+def _json_default(obj: Any):
+    try:
+        if isinstance(obj, BaseModel):
+            return obj.model_dump()
+    except Exception:
+        pass
+    return str(obj)
+
+@contextlib.contextmanager
+def _redirect_stdout_to_stderr():
+    """上下文管理器，临时将 stdout 重定向到 stderr 以隔离用户代码的输出。"""
+    original_stdout = sys.stdout
+    sys.stdout = sys.stderr
+    try:
+        yield
+    finally:
+        sys.stdout = original_stdout
+
+def _worker_main(package_names):
+    """
+    在隔离的子进程中执行的实际工作逻辑。
+    结果通过打印 JSON 到 stdout 来返回。
+    """
+    # 确保子进程的 sys.path 包含项目根目录
+    sys.path.insert(0, os.getcwd())
+    
+    final_results: dict[str, dict[str, Any]] = {}
+    try:
+        from kotonebot.devtools import EditorMetadata
+
+        # Normalize package_names to a list
+        if isinstance(package_names, str):
+            package_names = [package_names]
+
+        all_module_names: list[str] = []
+        for pkg_name in package_names:
+            try:
+                package = importlib.import_module(pkg_name)
+            except Exception as e:
+                print(f"[Worker] Failed to import package {pkg_name}: {e}", file=sys.stderr)
+                continue
+
+            if hasattr(package, '__path__'):
+                module_names = [
+                    name for _, name, _ in pkgutil.walk_packages(
+                        path=package.__path__, prefix=package.__name__ + '.'
+                    )
+                ]
+            else:
+                # package is actually a single module (no __path__), include it directly
+                module_names = [package.__name__]
+
+            # 保持顺序并去重（默认包先）
+            for name in module_names:
+                if name not in all_module_names:
+                    all_module_names.append(name)
+
+        for module_name in all_module_names:
+            try:
+                # 隔离导入，防止用户代码的 print 污染 stdout
+                with _redirect_stdout_to_stderr():
+                    module = importlib.import_module(module_name)
+            except Exception as e:
+                print(f"[Worker] Failed to import module {module_name}: {e}", file=sys.stderr)
+                continue
+
+            for _, outer_cls in inspect.getmembers(module, inspect.isclass):
+                if outer_cls.__module__ != module_name:
+                    continue
+
+                for _, nested_cls in inspect.getmembers(outer_cls, inspect.isclass):
+                    if nested_cls is not EditorMetadata and issubclass(nested_cls, EditorMetadata):
+                        properties = _get_class_properties(nested_cls)
+                        prefab_id = properties.get('id') or outer_cls.__name__
+                        if prefab_id:
+                            properties['id'] = prefab_id
+                            final_results[prefab_id] = properties
+                        break
+    except Exception as e:
+        # 将关键错误打印到 stderr，并以非零代码退出
+        print(f"[Worker] A critical error occurred: {e}", file=sys.stderr)
+        # 即使出错，也打印空 JSON 到 stdout，避免父进程解析失败
+        print(json.dumps({}, default=_json_default, ensure_ascii=False))
+        sys.exit(1)
+        
+    output = {
+        "version": 1, # Schema version
+        "prefabs": final_results
+    }
+    print(json.dumps(output, default=_json_default, ensure_ascii=False))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 2 and sys.argv[1] == '--worker':
+        # Pass all package args (sys.argv[2:]) to the worker so it scans multiple packages in one run
+        _worker_main(sys.argv[2:])
+    else:
+        print("This is a library module and its own scanning worker.", file=sys.stderr)
+        print("Please do not run this file directly.", file=sys.stderr)
+        print("You should import and call the `scan_prefabs` function from your application.", file=sys.stderr)
+        sys.exit(1)
+

kotonebot/devtools/project/schema.py

@@ -0,0 +1,99 @@
+from typing import Any
+from pydantic import BaseModel, Field
+
+class EditorMetadata:
+    """
+    ## Prefab 元数据类
+    
+    此类用于声明自定义 Prefab 的编辑器元数据，包括ID、名称、
+    描述、自定义字段等。只需要在你的 Prefab 类下声明一个
+    继承自此类的嵌套类（名称随意），Devtool 会自动扫描并识别
+    出你的自定义 Prefab，并按照元数据展示。
+
+    ### 例
+    ```python
+    class MyButtonPrefab(Prefab):
+        # 实际属性
+        type: Literal['primary' | 'secondary'] = 'primary'
+        region: Rect | None = None
+        match_text: str = ''
+
+        # 编辑器元数据
+        class Editor(EditorMetadata):
+            id = 'my_button'
+            name = '按钮'
+            description = '一个自定义按钮 Prefab'
+            props = {
+                'type': ChoiceProp(label='按钮类型', description='按钮的样式类型', default_value='primary', choices=[('主按钮', 'primary'), ('次按钮', 'secondary')]),
+                'region': RectProp(label='按钮区域', description='按钮在屏幕上的位置区域', default_value=None),
+                'match_text': StrProp(label='匹配文本', description='按钮上的文本内容', default_value=''),
+            }
+
+    ```
+    """
+    id: str
+    name: str
+    description: str | None = None
+    primary_prop: str | None = None
+    shortcut: str | None = None
+    """
+    用于切换到此工具的快捷键，可以为单按键。
+    """
+    icon: str | None = None
+    """展示在编辑器上的 icon 名称。"""
+    """
+    主属性 key（例如 rect / anchor / image）。
+    """
+    props: 'dict[str, EditorProp]' = {}
+    """
+    此 Prefab 的属性，格式为 dict[属性键名, EditorProp]。
+    """
+
+
+class EditorProp(BaseModel):
+    kind: str
+    label: str
+    description: str | None = None
+    default_value: Any = None
+
+
+class RectProp(EditorProp):
+    kind: str = 'rect'
+
+
+class PointProp(EditorProp):
+    kind: str = 'point'
+
+
+class ImageProp(EditorProp):
+    kind: str = 'image'
+
+class BoolProp(EditorProp):
+    kind: str = 'bool'
+
+
+class FloatProp(EditorProp):
+    kind: str = 'float'
+    min: float | None = None
+    max: float | None = None
+
+
+class IntProp(EditorProp):
+    kind: str = 'int'
+
+
+class StrProp(EditorProp):
+    kind: str = 'str'
+
+
+class ChoiceProp(EditorProp):
+    kind: str = 'choice'
+    choices: list[tuple[str, Any]] = Field(...)
+
+class EditorData(BaseModel):
+    prefabs_module: str | None = None
+    resource_path: str | None = None
+
+
+class PyProjectData(BaseModel):
+    editor: EditorData | None = None

kotonebot/devtools/resgen/__init__.py

@@ -0,0 +1,42 @@
+from .core import (
+    CodeWriter,
+    ResourceNode,
+    ClassNode,
+    SchemaParser,
+)
+from .codegen import (
+    StandardGenerator,
+)
+from .parsers import (
+    ParserRegistry,
+    KotoneV1Parser,
+    BasicSpriteParser,
+)
+from .utils import (
+    to_camel_case,
+    unify_path,
+    build_class_tree,
+    ImageProcessor,
+)
+
+__all__ = [
+    # core
+    "CodeWriter",
+    "ResourceNode",
+    "ClassNode",
+    "SchemaParser",
+
+    # generator
+    "StandardGenerator",
+
+    # parsers
+    "ParserRegistry",
+    "KotoneV1Parser",
+    "BasicSpriteParser",
+
+    # utils
+    "to_camel_case",
+    "unify_path",
+    "build_class_tree",
+    "ImageProcessor",
+]