comfy-cli-slim 1.23.0.post2__py3-none-any.whl

comfy_cli_slim/__main__.py

@@ -0,0 +1,172 @@
+"""Console-script entrypoint for `comfy` / `comfy-cli` / `comfycli`.
+
+A thin wrapper around `comfy_cli_slim.cmdline.main` whose only job is to make the
+process a well-behaved pipe producer. When the consumer of our stdout goes away
+early — `comfy run --wait … | head`, `comfy jobs ls | head -5` — the next write
+raises `BrokenPipeError`. The right answer is a silent exit 0: the consumer got
+exactly what it asked for. Without this wrapper the process instead exits 1 (or,
+when the failing write is the interpreter's own shutdown flush, prints an
+"Exception ignored" traceback), which reads as a command failure to every
+shell/CI/agent downstream.
+
+The exit 0 is only ever granted to a command that *succeeded*. A closed reader
+on a command that failed still exits with the failure's code — `comfy --json
+<failing-cmd> | head` is a failure that happened to be piped, not a success.
+Absorbing the broken pipe there would launder a genuine error into 0, which is
+the one outcome worse than the exit 1 this wrapper exists to remove.
+
+Output written before the pipe closed is of course truncated — a half-written
+`--json` envelope stays half-written. That is the consumer's problem by
+construction; the exit code is ours.
+"""
+
+import os
+import sys
+
+from comfy_cli_slim.cmdline import main as _cli_main
+
+
+def _silence_stdout() -> None:
+    """Point fd 1 at /dev/null so nothing later can hit EPIPE a second time.
+
+    Between here and process death an atexit hook, a `finally` that prints, or
+    the interpreter's own shutdown flush can all write to stdout. Once its
+    reader is gone each of those turns into a fresh `BrokenPipeError` — an
+    "Exception ignored" traceback on stderr, and (for the shutdown flush) exit
+    120 in place of whatever code we meant to report.
+    """
+    try:
+        devnull_fd = os.open(os.devnull, os.O_WRONLY)
+    except OSError:  # pragma: no cover — /dev/null is not openable
+        return
+    try:
+        os.dup2(devnull_fd, sys.stdout.fileno())
+    except (OSError, ValueError, AttributeError):
+        # No usable fd 1 (already closed, or stdout was replaced by something
+        # without a real file descriptor). Nothing to protect.
+        pass
+    finally:
+        # dup2 gives fd 1 its own reference, so this one is ours to release.
+        os.close(devnull_fd)
+
+
+def _exit_quietly_on_broken_pipe() -> None:
+    """Absorb a closed stdout and exit 0. Never returns."""
+    _silence_stdout()
+    # os._exit rather than sys.exit: it skips atexit handlers and stdio
+    # flushing entirely, so no buffered-but-unwritable stdout can resurrect the
+    # error we just absorbed. The cost is that the telemetry atexit flush in
+    # comfy_cli_slim.tracking is skipped for this invocation, which is the intended
+    # trade — a truncated pipe is not worth risking a second failure or a
+    # shutdown hang on the way out.
+    os._exit(0)
+
+
+def _broken_pipe_swallowed_by_click() -> bool:
+    """Report whether the `SystemExit` we just caught is click's EPIPE bail-out.
+
+    click's `BaseCommand.main` handles EPIPE itself: it swaps `sys.stdout` and
+    `sys.stderr` for a `PacifyFlushWrapper` and raises `SystemExit(1)`. So on
+    the common path a broken pipe never reaches us as a `BrokenPipeError` at
+    all, and the exit 1 is otherwise indistinguishable from a genuine command
+    failure. That wrapper — which click installs in this branch and nowhere
+    else — is the one reliable in-process signal.
+
+    The class is matched by name and owning package because there is no single
+    class to point at: typer >= 0.24 runs on a vendored click, so the wrapper the
+    CLI actually meets is `typer._click.utils.PacifyFlushWrapper` rather than the
+    one in the installed `click`, and click 8.5 renamed its own copy to a private
+    name whose public alias warns on access. The package test keeps a same-named
+    class from anywhere else — `my_click_adapter.PacifyFlushWrapper` — out, since
+    a false positive here reports a failed command as a success.
+    """
+    cls = type(sys.stdout)
+    if cls.__name__.removeprefix("_") != "PacifyFlushWrapper":
+        return False
+    return cls.__module__.partition(".")[0] in ("click", "typer")
+
+
+def _flush_stdout(*, unwinding: bool) -> bool:
+    """Flush stdout; return False iff the flush hit a broken pipe.
+
+    Reporting the broken pipe by return value instead of raising is what lets
+    `main` keep the two cases apart. This flush runs at a point where a real
+    exception may already be on its way out, and a `BrokenPipeError` raised
+    from here would silently *replace* it — turning a failed command's non-zero
+    exit into 0.
+
+    `unwinding` says whether that is the case. While unwinding, every other
+    flush failure is swallowed too, for the same reason: a `finally`-time flush
+    must never mask the exception it is running underneath. On the clean path
+    there is nothing to mask, so a non-broken-pipe `OSError` (a full disk, EIO)
+    is allowed to propagate — output was genuinely lost and a real traceback
+    beats the interpreter's opaque exit 120. Only the nothing-to-flush shapes
+    stay quiet either way.
+    """
+    stream = sys.stdout
+    if stream is None:  # stdout detached (pythonw and friends)
+        return True
+    try:
+        stream.flush()
+    except BrokenPipeError:
+        return False
+    except (ValueError, AttributeError):
+        # Closed or non-file-like stdout (`comfy … >&-`) — nothing to flush,
+        # and not the broken-pipe case we are guarding against.
+        pass
+    except OSError:
+        if not unwinding:
+            raise
+    return True
+
+
+def _is_clean_exit(exc: SystemExit) -> bool:
+    """Whether this `SystemExit` reports success (`sys.exit(0)` / `sys.exit()`)."""
+    return exc.code is None or exc.code == 0
+
+
+def main() -> None:
+    try:
+        _cli_main()
+    except BrokenPipeError:
+        # click's standalone `main` converts every EPIPE raised inside a command
+        # into the pacified `SystemExit(1)` handled just below, so a raw
+        # `BrokenPipeError` reaching here is stdout dying outside that guard.
+        _exit_quietly_on_broken_pipe()
+    except SystemExit as exc:
+        # `exc.code == 1` narrows the shortcut to the only code click's EPIPE
+        # branch raises, so no other exit status can be laundered into a 0 by a
+        # stdout that merely looks pacified.
+        if exc.code == 1 and _broken_pipe_swallowed_by_click():
+            _exit_quietly_on_broken_pipe()
+        # stdout is block-buffered when it is a pipe, so the write that actually
+        # lands on the closed reader is frequently the interpreter's shutdown
+        # flush — long after any handler here could run. Flushing now pulls that
+        # failure forward to where we can still decide what it means.
+        clean = _is_clean_exit(exc)
+        if _flush_stdout(unwinding=not clean):
+            raise
+        if clean:
+            # The command succeeded and its reader left early: that is the whole
+            # story, so exit 0.
+            _exit_quietly_on_broken_pipe()
+        # The command failed. Its exit code is the truth and outranks the closed
+        # reader; only silence fd 1 so the shutdown flush cannot re-raise what
+        # we just absorbed (which would replace that code with 120).
+        _silence_stdout()
+        raise
+    except BaseException:
+        # A crash is already on its way out. Same rule: flush what we can, let
+        # nothing from the flush displace it.
+        if not _flush_stdout(unwinding=True):
+            _silence_stdout()
+        raise
+    else:
+        # `_cli_main` returned instead of exiting. click always raises in
+        # standalone mode, but `cmdline.main` can fall through on rc == 0.
+        if not _flush_stdout(unwinding=False):
+            _exit_quietly_on_broken_pipe()
+
+
+if __name__ == "__main__":  # pragma: nocover
+    main()

comfy_cli_slim/_lazy.py

@@ -0,0 +1,188 @@
+"""Lazy-import helpers for the CLI's startup path.
+
+Every ``comfy`` invocation pays ``cmdline.py``'s import graph before doing
+any work, and agents pay it on every tool call. Most of that graph is the
+subcommand modules, of which a single invocation uses one. These helpers let
+``cmdline.py`` keep its flat, module-level names (tests patch
+``comfy_cli_slim.cmdline.run_inner`` and friends) while deferring the actual import
+to first use.
+
+Two pieces:
+
+* :class:`LazyModule` — a module proxy. Attribute reads import the module on
+  first touch; reads, writes and deletes all forward to the real module, so
+  ``patch("comfy_cli_slim.cmdline.run_inner.execute")`` patches the real function
+  exactly as it did when ``run_inner`` was the module itself.
+* :class:`LazyTyperGroup` — a ``TyperGroup`` whose subgroups are declared as
+  ``(module, attr)`` pairs and built on first lookup with typer's own
+  ``get_group_from_info``, so help text, hidden flags and callbacks behave
+  exactly as ``app.add_typer(...)`` did. ``list_commands`` keeps the eager
+  commands first and the lazy groups in table order, so ``comfy --help`` is
+  byte-identical to the eager wiring.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from types import ModuleType
+from typing import TYPE_CHECKING, Any
+
+import typer
+from typer.core import TyperGroup
+from typer.models import CommandInfo, TyperInfo
+
+if TYPE_CHECKING:
+    import click
+
+
+class LazyModule:
+    """Proxy for a module that is imported on first attribute access.
+
+    ``get``/``set``/``del`` of attributes all forward to the real module, and
+    ``__dict__`` is the real module's namespace, so ``unittest.mock.patch``
+    and ``monkeypatch.setattr`` treat the proxy as the module.
+    """
+
+    __slots__ = ("_lazy_path", "_lazy_target")
+
+    def __init__(self, path: str) -> None:
+        object.__setattr__(self, "_lazy_path", path)
+        object.__setattr__(self, "_lazy_target", None)
+
+    def _lazy_resolve(self) -> ModuleType:
+        target = object.__getattribute__(self, "_lazy_target")
+        if target is None:
+            target = importlib.import_module(object.__getattribute__(self, "_lazy_path"))
+            object.__setattr__(self, "_lazy_target", target)
+        return target
+
+    @property
+    def __dict__(self) -> dict[str, Any]:  # type: ignore[override]
+        return self._lazy_resolve().__dict__
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._lazy_resolve(), name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        setattr(self._lazy_resolve(), name, value)
+
+    def __delattr__(self, name: str) -> None:
+        delattr(self._lazy_resolve(), name)
+
+    def __dir__(self) -> list[str]:
+        return dir(self._lazy_resolve())
+
+    def __repr__(self) -> str:
+        return f"<LazyModule {object.__getattribute__(self, '_lazy_path')!r}>"
+
+
+@dataclass(frozen=True)
+class LazySubcommand:
+    """One deferred ``app.add_typer(...)``: the module holding the sub-``Typer``
+    and the ``add_typer`` keyword arguments that were passed with it."""
+
+    module: str
+    attr: str = "app"
+    help: str | None = None
+    hidden: bool = False
+    callback: Callable[..., Any] | None = None
+
+
+@dataclass(frozen=True)
+class LazyCommand:
+    """One deferred ``app.command(name, ...)(fn)``. ``attr`` names the function
+    in ``module``. ``register`` instead names a ``register_with(app)`` hook on
+    the module that registers the command onto a Typer app itself (``generate``
+    does this because its command is a closure)."""
+
+    module: str
+    attr: str | None = None
+    register: str | None = None
+    help: str | None = None
+    hidden: bool = False
+
+
+class LazyTyperGroup(TyperGroup):
+    """Root group with subcommands declared in ``lazy_subcommands`` and built
+    on first lookup. Set the table on a subclass::
+
+        class RootGroup(LazyTyperGroup):
+            lazy_subcommands = {"nodes": LazySubcommand("comfy_cli_slim.command.nodes", help="...")}
+
+        app = typer.Typer(cls=RootGroup)
+    """
+
+    lazy_subcommands: dict[str, LazySubcommand | LazyCommand] = {}
+    # Assigned by the module that owns the root app
+    # (``_RootGroup.pretty_exceptions_short = app.pretty_exceptions_short`` in
+    # cmdline.py). The fallback is read off ``typer.Typer`` rather than
+    # restated here, so it cannot drift from typer.
+    pretty_exceptions_short: bool = (
+        inspect.signature(typer.Typer.__init__).parameters["pretty_exceptions_short"].default
+    )
+
+    def __init__(self, **attrs: Any) -> None:
+        super().__init__(**attrs)
+        self._lazy_loaded: dict[str, click.Command] = {}
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        eager = list(super().list_commands(ctx))
+        return eager + [name for name in self.lazy_subcommands if name not in self.commands]
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        command = super().get_command(ctx, cmd_name)
+        if command is not None:
+            return command
+        spec = self.lazy_subcommands.get(cmd_name)
+        if spec is None:
+            return None
+        if cmd_name not in self._lazy_loaded:
+            build = self._build_command if isinstance(spec, LazyCommand) else self._build_group
+            self._lazy_loaded[cmd_name] = build(cmd_name, spec)
+        return self._lazy_loaded[cmd_name]
+
+    def _factory_kwargs(self, factory: Callable[..., Any]) -> dict[str, Any]:
+        """The settings typer's own wiring passes to ``factory``, narrowed to the
+        keywords this typer version actually accepts. ``suggest_commands`` only
+        exists from typer 0.20 on, where it is required and has no default, while
+        pyproject still allows ``typer>=0.12.5``."""
+        candidates = {
+            "pretty_exceptions_short": self.pretty_exceptions_short,
+            "rich_markup_mode": self.rich_markup_mode,
+            "suggest_commands": getattr(self, "suggest_commands", True),
+        }
+        accepted = inspect.signature(factory).parameters
+        return {name: value for name, value in candidates.items() if name in accepted}
+
+    def _build_command(self, name: str, spec: LazyCommand) -> click.Command:
+        module = importlib.import_module(spec.module)
+        if spec.register is not None:
+            scratch = typer.Typer()
+            getattr(module, spec.register)(scratch)
+            infos = [info for info in scratch.registered_commands if info.name == name]
+            assert len(infos) == 1, f"{spec.module}.{spec.register} did not register exactly one {name!r} command"
+            info = infos[0]
+            if spec.hidden:
+                info.hidden = True
+        else:
+            assert spec.attr, "LazyCommand needs attr or register"
+            info = CommandInfo(name=name, callback=getattr(module, spec.attr), help=spec.help, hidden=spec.hidden)
+        return typer.main.get_command_from_info(info, **self._factory_kwargs(typer.main.get_command_from_info))
+
+    def _build_group(self, name: str, spec: LazySubcommand) -> click.Command:
+        sub_app = getattr(importlib.import_module(spec.module), spec.attr)
+        # Same TyperInfo ``add_typer`` would have appended: only the keywords
+        # that were given, so the sub-app's own settings fill the rest.
+        kwargs: dict[str, Any] = {"name": name}
+        if spec.help is not None:
+            kwargs["help"] = spec.help
+        if spec.hidden:
+            kwargs["hidden"] = True
+        if spec.callback is not None:
+            kwargs["callback"] = spec.callback
+        return typer.main.get_group_from_info(
+            TyperInfo(sub_app, **kwargs), **self._factory_kwargs(typer.main.get_group_from_info)
+        )