fcmd 0.3.2__tar.gz → 0.3.4__tar.gz

{fcmd-0.3.2 → fcmd-0.3.4}/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.3.2"
+current_version = "0.3.4"
 commit = true
 exclude = ["template/*"]
 message = "chore: 更新版本 {current_version} → {new_version}"

{fcmd-0.3.2 → fcmd-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fcmd
-Version: 0.3.2
+Version: 0.3.4
 Summary: 极速 Python 工具集应用：DAG 任务调度 + 组合 CLI
 Author: fcmd
 License: MIT

{fcmd-0.3.2 → fcmd-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fcmd"
-version = "0.3.2"
+version = "0.3.4"
 description = "极速 Python 工具集应用：DAG 任务调度 + 组合 CLI"
 readme = "README.md"
 requires-python = ">=3.13"

{fcmd-0.3.2 → fcmd-0.3.4}/src/fcmd/__init__.py

@@ -20,7 +20,7 @@
 
 from typing import Any
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 __all__ = [
     "Context",

fcmd-0.3.4/src/fcmd/apis/__init__.py

@@ -0,0 +1,127 @@
+"""fcmd.apis —— 框架级公共 API 聚合。
+
+包含 7 个子模块：
+- task: 任务数据结构（TaskSpec、RetryPolicy、RunConfig）
+- dag: 图编排（Graph、GraphDefaults、graph 快捷构造）
+- errors: 异常类型
+- report: 执行报告（RunReport、TaskResult）
+- context: 依赖注入工具
+- profiling: 性能分析（ProfileReport、TaskProfile）
+- toolkit: @fx.tool 装饰器框架（ToolSpec、build_tool_graph 等）
+
+执行引擎（run/executors）位于 :mod:`fcmd.engine`，YAML 编排位于
+:mod:`fcmd.orchestration`，经顶层 ``fcmd.__init__`` 懒加载暴露。
+
+本包自身也通过 ``__getattr__`` 懒加载所有子模块，使首次访问
+``fcmd.apis.toolkit`` / ``fcmd.apis.run_tool`` 等不会在父包加载时
+触发整条导入链（toolkit → _tool_exec → engine → asyncio）。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "Context",
+    "CycleError",
+    "DuplicateTaskError",
+    "FcmdError",
+    "Graph",
+    "GraphDefaults",
+    "InjectionError",
+    "MissingDependencyError",
+    "ProfileReport",
+    "RetryPolicy",
+    "RunConfig",
+    "RunReport",
+    "TaskCmd",
+    "TaskFailedError",
+    "TaskProfile",
+    "TaskResult",
+    "TaskSpec",
+    "TaskStatus",
+    "TaskTimeoutError",
+    "ToolExitCode",
+    "ToolSpec",
+    "_tool_exec",
+    "build_call_args",
+    "build_tool_graph",
+    "clear_tool_registry",
+    "cmd",
+    "describe_injection",
+    "get_tool",
+    "graph",
+    "list_subcommands",
+    "list_tools",
+    "run_tool",
+    "task",
+    "tool",
+    "toolkit",
+]
+
+# 懒加载映射：公共符号 / 子模块名 -> (模块路径, 符号名 或 None 表示模块自身)
+_LAZY_ATTRS: dict[str, tuple[str, str | None]] = {
+    # ---- 公共符号 ----
+    "Context": ("fcmd.apis.context", "Context"),
+    "build_call_args": ("fcmd.apis.context", "build_call_args"),
+    "describe_injection": ("fcmd.apis.context", "describe_injection"),
+    "Graph": ("fcmd.apis.dag", "Graph"),
+    "GraphDefaults": ("fcmd.apis.dag", "GraphDefaults"),
+    "graph": ("fcmd.apis.dag", "graph"),
+    "CycleError": ("fcmd.apis.errors", "CycleError"),
+    "DuplicateTaskError": ("fcmd.apis.errors", "DuplicateTaskError"),
+    "FcmdError": ("fcmd.apis.errors", "FcmdError"),
+    "InjectionError": ("fcmd.apis.errors", "InjectionError"),
+    "MissingDependencyError": ("fcmd.apis.errors", "MissingDependencyError"),
+    "TaskFailedError": ("fcmd.apis.errors", "TaskFailedError"),
+    "TaskTimeoutError": ("fcmd.apis.errors", "TaskTimeoutError"),
+    "ProfileReport": ("fcmd.apis.profiling", "ProfileReport"),
+    "TaskProfile": ("fcmd.apis.profiling", "TaskProfile"),
+    "RunReport": ("fcmd.apis.report", "RunReport"),
+    "RetryPolicy": ("fcmd.apis.task", "RetryPolicy"),
+    "RunConfig": ("fcmd.apis.task", "RunConfig"),
+    "TaskCmd": ("fcmd.apis.task", "TaskCmd"),
+    "TaskResult": ("fcmd.apis.task", "TaskResult"),
+    "TaskSpec": ("fcmd.apis.task", "TaskSpec"),
+    "TaskStatus": ("fcmd.apis.task", "TaskStatus"),
+    "cmd": ("fcmd.apis.task", "cmd"),
+    "task": ("fcmd.apis.task", "task"),
+    "ToolExitCode": ("fcmd.apis.toolkit", "ToolExitCode"),
+    "ToolSpec": ("fcmd.apis.toolkit", "ToolSpec"),
+    "build_tool_graph": ("fcmd.apis.toolkit", "build_tool_graph"),
+    "clear_tool_registry": ("fcmd.apis.toolkit", "clear_tool_registry"),
+    "get_tool": ("fcmd.apis.toolkit", "get_tool"),
+    "list_subcommands": ("fcmd.apis.toolkit", "list_subcommands"),
+    "list_tools": ("fcmd.apis.toolkit", "list_tools"),
+    "run_tool": ("fcmd.apis.toolkit", "run_tool"),
+    "tool": ("fcmd.apis.toolkit", "tool"),
+    # ---- 子模块名（供测试 from fcmd.apis import toolkit / _tool_exec）----
+    "toolkit": ("fcmd.apis.toolkit", None),
+    "_tool_exec": ("fcmd.apis._tool_exec", None),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """懒加载公共 API 符号与子模块。
+
+    首次访问时从对应模块导入并缓存到 ``globals()``，后续直接命中。
+    """
+    mapping = _LAZY_ATTRS.get(name)
+    if mapping is None:
+        raise AttributeError(f"module 'fcmd.apis' has no attribute {name!r}")
+    module_path, attr_name = mapping
+    import importlib
+
+    module = importlib.import_module(module_path)
+    if attr_name is None:
+        # 请求子模块自身（如 ``from fcmd.apis import toolkit``）
+        value = module
+    else:
+        value = getattr(module, attr_name)
+    globals()[name] = value  # 缓存到全局，后续直接命中
+    return value
+
+
+def __dir__() -> list[str]:
+    """补全建议。"""
+    return sorted(set(globals()) | set(__all__))

{fcmd-0.3.2 → fcmd-0.3.4}/src/fcmd/apis/dag.py

@@ -160,6 +160,9 @@ class Graph:
             raise DuplicateTaskError(spec.name)
         self.specs[spec.name] = spec
         self.deps[spec.name] = spec.depends_on
+        # 失效缓存：specs 变更后，旧的 resolved_spec / layers 不再可靠。
+        self._resolved_cache.clear()
+        self._layers_cache = None
         self._validate_references()
         return self
 

{fcmd-0.3.2 → fcmd-0.3.4}/src/fcmd/cli/dev/gittool.py

@@ -7,7 +7,8 @@
     fcmd gittool a -m "feat: 新功能"   # 添加并提交
     fcmd gittool i                       # 初始化并提交
     fcmd gittool isub                    # 初始化所有子目录的 Git 仓库
-    fcmd gittool c                       # 清理未跟踪文件并查看状态
+    fcmd gittool c                       # 清理未跟踪文件（保留排除目录）并查看状态
+    fcmd gittool ca                      # 清理全部未跟踪文件（含排除目录）
     fcmd gittool p                       # 推送
     fcmd gittool pl                      # 拉取
 """
@@ -168,6 +169,16 @@ def c() -> None:
     """清理未跟踪文件并查看 Git 状态。"""
 
 
+@fcmd.tool(
+    "gittool",
+    subcommand="ca",
+    help="清理全部未跟踪文件（含排除目录）",
+    cmd=["git", "clean", "-xfd", "."],
+)
+def ca() -> None:
+    """清理全部未跟踪文件，等同于 ``git clean -xfd .``，不保留排除目录。"""
+
+
 @fcmd.tool("gittool", subcommand="p", help="推送", cmd=["git", "push"])
 def p() -> None:
     """推送代码到远程仓库。"""

{fcmd-0.3.2 → fcmd-0.3.4}/src/fcmd/cli/dev/pymake.py

@@ -213,12 +213,13 @@ def test_n_cpu(cwd: Path = Path()) -> None:
         "pytest",
         "-m",
         "not slow",
+        "-n",
+        "auto",
         "--cov=fcmd",
         f"--cov-fail-under={_COVERAGE_THRESHOLD}",
         "--color=yes",
         "--durations=10",
     ],
-    needs=["c"],
 )
 def test_coverage(cwd: Path = Path()) -> None:
     """测试并生成覆盖率（内部 job）。"""

fcmd-0.3.4/src/fcmd/engine/__init__.py

@@ -0,0 +1,52 @@
+"""fcmd.engine —— DAG 执行引擎层。
+
+承载 ``run()`` 调用链中全部**执行侧**关注点（"动词"：调度与执行）：
+
+- ``executors``：公共 :func:`run` 入口与策略派发（``sequential`` /
+  ``thread`` / ``async`` / ``dependency`` 四种策略）
+- ``task_runner``：任务级执行内核（执行上下文、线程池复用、跳过/
+  重试/失败处理、同步/异步任务执行器）
+- ``layer_runner``：层屏障模型调度（同层并发、整层完成后进入下一层）
+- ``dependency_runner``：依赖驱动调度（无层屏障，任务就绪即启动）
+- ``task_command``：TaskSpec ``cmd`` 字段执行器（list / shell 字符串 /
+  可调用对象）
+
+与 :mod:`fcmd.apis`（API 定义层，"名词"：数据结构与类型）相对。
+本包通过 ``__getattr__`` 懒加载，避免父包加载时 eager import 整个
+``executors`` 模块（它依赖 ``fcmd.apis.toolkit → asyncio`` 整条链）。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "Strategy",
+    "run",
+    "run_command",
+]
+
+_LAZY_ATTRS: dict[str, tuple[str, str]] = {
+    "Strategy": ("fcmd.engine.executors", "Strategy"),
+    "run": ("fcmd.engine.executors", "run"),
+    "run_command": ("fcmd.engine.task_command", "run_command"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """懒加载执行引擎公共 API。"""
+    mapping = _LAZY_ATTRS.get(name)
+    if mapping is None:
+        raise AttributeError(f"module 'fcmd.engine' has no attribute {name!r}")
+    module_path, attr_name = mapping
+    import importlib
+
+    module = importlib.import_module(module_path)
+    value = getattr(module, attr_name)
+    globals()[name] = value  # 缓存到全局，后续直接命中
+    return value
+
+
+def __dir__() -> list[str]:
+    """补全建议。"""
+    return sorted(set(globals()) | set(__all__))

{fcmd-0.3.2 → fcmd-0.3.4}/src/fcmd/engine/dependency_runner.py

@@ -51,6 +51,8 @@ async def _run_dependency(
     sorter.prepare()
 
     in_flight: dict[str, asyncio.Task[TaskResult[Any]]] = {}
+    # 反向映射：task -> 任务名，O(1) 完成任务查找（替代 O(N) next() 扫描）。
+    _task_to_name: dict[asyncio.Task[TaskResult[Any]], str] = {}
     loop = asyncio.get_running_loop()
 
     async def _run_one(name: str) -> TaskResult[Any]:
@@ -67,7 +69,9 @@ async def _run_dependency(
     # fail-fast：首个异常即取消剩余任务并抛出（匹配 gather 语义）。
     while ready or in_flight:
         for name in ready:
-            in_flight[name] = loop.create_task(_run_one(name))
+            task = loop.create_task(_run_one(name))
+            in_flight[name] = task
+            _task_to_name[task] = name
         ready = []
 
         if not in_flight:  # pragma: no cover - 图已校验无环，防御性处理
@@ -75,7 +79,7 @@ async def _run_dependency(
 
         done, _ = await asyncio.wait(in_flight.values(), return_when=asyncio.FIRST_COMPLETED)
         for task in done:
-            done_name = next(n for n, t in in_flight.items() if t is task)
+            done_name = _task_to_name.pop(task)
             del in_flight[done_name]
             exc = task.exception()
             if exc is not None:

{fcmd-0.3.2 → fcmd-0.3.4}/tests/test_cli_gittool.py

@@ -131,6 +131,22 @@ class TestGittool:
         result = subprocess.run(["git", "log", "--oneline"], capture_output=True, text=True, check=True)
         assert "chore: update" in result.stdout
 
+    def test_gittool_ca_removes_excluded_dirs(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """gittool ca 会清理 EXCLUDE_DIRS 中的目录（如 .venv）。"""
+        monkeypatch.chdir(tmp_path)
+        subprocess.run(["git", "init"], check=True, capture_output=True)
+        # 放入排除目录中的一个（.venv）以及一个普通未跟踪文件
+        (tmp_path / ".venv").mkdir()
+        (tmp_path / ".venv" / "pyvenv.cfg").write_text("home = /usr/bin", encoding="utf-8")
+        (tmp_path / "extra.log").write_text("junk", encoding="utf-8")
+        assert (tmp_path / ".venv").is_dir()
+        assert (tmp_path / "extra.log").is_file()
+        code = run_tool("gittool", ["ca"])
+        assert code == 0
+        # 两个都应该被删除
+        assert not (tmp_path / ".venv").exists(), "ca 应删除 .venv 排除目录"
+        assert not (tmp_path / "extra.log").exists(), "ca 应删除普通未跟踪文件"
+
 
 # ---------------------------------------------------------------------- #
 # gittool cmd 子命令验证
@@ -172,6 +188,16 @@ class TestGittoolCmdSpecs:
         assert spec.cmd is not None
         assert "pull" in spec.cmd
 
+    def test_ca_is_cmd_without_exclude(self) -> None:
+        """ca 是 cmd 类型子命令，直接 git clean -xfd . 不含 -e 排除。"""
+        from fcmd.apis.toolkit import _TOOL_REGISTRY
+
+        spec = _TOOL_REGISTRY["gittool"]["ca"]
+        assert spec.cmd is not None
+        assert spec.cmd == ("git", "clean", "-xfd", ".")
+        assert "-e" not in spec.cmd
+        assert spec.hidden is not True  # ca 不是隐藏命令
+
 
 # ============================================================================ #
 # gittool isub 测试

{fcmd-0.3.2 → fcmd-0.3.4}/tests/test_cli_lscalc.py

@@ -279,6 +279,10 @@ class TestGetLsDynaCommand:
     def test_mpp_sp_intel_mpi_windows(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """MPP 单精度 + Intel MPI（Windows）。"""
         monkeypatch.setattr(sys, "platform", "win32")
+        # shutil.which 在模块导入时根据真实 sys.platform 设置 _winapi，
+        # 不能只 patch sys.platform 就让它走 Windows 分支——需要
+        # 同时 mock 掉 which 返回 None 让 solver 发现走回退路径。
+        monkeypatch.setattr("shutil.which", lambda _n: None)
         config = LsDynaConfig(
             input_file="test.k",
             parallel="mpp",
@@ -296,6 +300,8 @@ class TestGetLsDynaCommand:
     def test_mpp_dp_intel_mpi_linux(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """MPP 双精度 + Intel MPI（Linux）。"""
         monkeypatch.setattr(sys, "platform", "linux")
+        # 同上——mock shutil.which 避免真实探测
+        monkeypatch.setattr("shutil.which", lambda _n: None)
         config = LsDynaConfig(
             input_file="test.k",
             parallel="mpp",

{fcmd-0.3.2 → fcmd-0.3.4}/tests/test_cli_pymake.py

@@ -229,11 +229,6 @@ class TestPymakeHybridTasks:
         assert "--cov-fail-under=95" in spec.cmd
         assert spec.hidden is False
 
-    def test_cov_needs_c(self) -> None:
-        """cov 应依赖 c（先清理）。"""
-        spec = get_tool("pymake", "cov")
-        assert "c" in spec.needs
-
     def test_bump_cmd_uses_patch(self) -> None:
         """bump 应使用 patch。"""
         spec = get_tool("pymake", "bump")

{fcmd-0.3.2 → fcmd-0.3.4}/tests/test_perf_baseline.py

@@ -36,7 +36,7 @@ _DISCOVERY_SCRIPT = (
     "import time\n"
     "import fcmd.cli.main as m\n"
     "t=time.perf_counter()\n"
-    "m._ensure_tools_discovered()\n"
+    "m.ensure_tools_discovered()\n"
     "print((time.perf_counter()-t)*1000)\n"
 )
 

{fcmd-0.3.2 → fcmd-0.3.4}/uv.lock

@@ -94,7 +94,7 @@ wheels = [
 
 [[package]]
 name = "fcmd"
-version = "0.3.1"
+version = "0.3.3"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },

fcmd-0.3.2/src/fcmd/apis/__init__.py

@@ -1,87 +0,0 @@
-"""fcmd.apis —— 框架级公共 API 聚合。
-
-包含 7 个子模块：
-- task: 任务数据结构（TaskSpec、RetryPolicy、RunConfig）
-- dag: 图编排（Graph、GraphDefaults、graph 快捷构造）
-- errors: 异常类型
-- report: 执行报告（RunReport、TaskResult）
-- context: 依赖注入工具
-- profiling: 性能分析（ProfileReport、TaskProfile）
-- toolkit: @fx.tool 装饰器框架（ToolSpec、build_tool_graph 等）
-
-执行引擎（run/executors）位于 :mod:`fcmd.engine`，YAML 编排位于
-:mod:`fcmd.orchestration`，经顶层 ``fcmd.__init__`` 懒加载暴露。
-"""
-
-from __future__ import annotations
-
-from fcmd.apis.context import Context, build_call_args, describe_injection
-from fcmd.apis.dag import Graph, GraphDefaults, graph
-from fcmd.apis.errors import (
-    CycleError,
-    DuplicateTaskError,
-    FcmdError,
-    InjectionError,
-    MissingDependencyError,
-    TaskFailedError,
-    TaskTimeoutError,
-)
-from fcmd.apis.profiling import ProfileReport, TaskProfile
-from fcmd.apis.report import RunReport
-from fcmd.apis.task import (
-    RetryPolicy,
-    RunConfig,
-    TaskCmd,
-    TaskResult,
-    TaskSpec,
-    TaskStatus,
-    cmd,
-    task,
-)
-from fcmd.apis.toolkit import (
-    ToolExitCode,
-    ToolSpec,
-    build_tool_graph,
-    clear_tool_registry,
-    get_tool,
-    list_subcommands,
-    list_tools,
-    run_tool,
-    tool,
-)
-
-__all__ = [
-    "Context",
-    "CycleError",
-    "DuplicateTaskError",
-    "FcmdError",
-    "Graph",
-    "GraphDefaults",
-    "InjectionError",
-    "MissingDependencyError",
-    "ProfileReport",
-    "RetryPolicy",
-    "RunConfig",
-    "RunReport",
-    "TaskCmd",
-    "TaskFailedError",
-    "TaskProfile",
-    "TaskResult",
-    "TaskSpec",
-    "TaskStatus",
-    "TaskTimeoutError",
-    "ToolExitCode",
-    "ToolSpec",
-    "build_call_args",
-    "build_tool_graph",
-    "clear_tool_registry",
-    "cmd",
-    "describe_injection",
-    "get_tool",
-    "graph",
-    "list_subcommands",
-    "list_tools",
-    "run_tool",
-    "task",
-    "tool",
-]

fcmd-0.3.2/src/fcmd/engine/__init__.py

@@ -1,28 +0,0 @@
-"""fcmd.engine —— DAG 执行引擎层。
-
-承载 ``run()`` 调用链中全部**执行侧**关注点（"动词"：调度与执行）：
-
-- ``executors``：公共 :func:`run` 入口与策略派发（``sequential`` /
-  ``thread`` / ``async`` / ``dependency`` 四种策略）
-- ``task_runner``：任务级执行内核（执行上下文、线程池复用、跳过/
-  重试/失败处理、同步/异步任务执行器）
-- ``layer_runner``：层屏障模型调度（同层并发、整层完成后进入下一层）
-- ``dependency_runner``：依赖驱动调度（无层屏障，任务就绪即启动）
-- ``task_command``：TaskSpec ``cmd`` 字段执行器（list / shell 字符串 /
-  可调用对象）
-
-与 :mod:`fcmd.apis`（API 定义层，"名词"：数据结构与类型）相对。
-本包顶层模块仅供人读与兼容引用；内部代码应使用深路径
-（如 ``fcmd.engine.executors``）以避免不必要的导入开销。
-"""
-
-from __future__ import annotations
-
-from fcmd.engine.executors import Strategy, run
-from fcmd.engine.task_command import run_command
-
-__all__ = [
-    "Strategy",
-    "run",
-    "run_command",
-]