comfyui-docker-helper 0.5.1__tar.gz

comfyui_docker_helper-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jim Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

comfyui_docker_helper-0.5.1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: comfyui-docker-helper
+Version: 0.5.1
+Summary: Unofficial command-line helper for using ComfyUI with Docker
+Keywords: comfyui,docker,docker-buildx,buildkit,cli,developer-tools,container-images
+Author: jimlee2048
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: Utilities
+Requires-Dist: aria2p
+Requires-Dist: build>=1,<2
+Requires-Dist: httpx
+Requires-Dist: packaging>=26.2
+Requires-Dist: pydantic>=2,<3
+Requires-Dist: python-on-whales>=0.81.0
+Requires-Dist: rich
+Requires-Dist: tomli-w
+Requires-Dist: typer
+Maintainer: jimlee2048
+Requires-Python: >=3.12, <3.15
+Project-URL: Homepage, https://github.com/jimlee2048/comfyui-docker-helper
+Project-URL: Repository, https://github.com/jimlee2048/comfyui-docker-helper
+Project-URL: Issues, https://github.com/jimlee2048/comfyui-docker-helper/issues
+Project-URL: Changelog, https://github.com/jimlee2048/comfyui-docker-helper/releases
+Description-Content-Type: text/markdown
+
+`comfyui-docker-helper` (`cdh`) is an independent, unofficial command-line
+helper for using ComfyUI with Docker. It is not affiliated with or endorsed by
+the ComfyUI project.
+
+See the [GitHub repository](https://github.com/jimlee2048/comfyui-docker-helper)
+for current capabilities, requirements, documentation, examples, and issue
+tracking.

comfyui_docker_helper-0.5.1/pyproject.toml

@@ -0,0 +1,105 @@
+[project]
+name = "comfyui-docker-helper"
+version = "0.5.1"
+description = "Unofficial command-line helper for using ComfyUI with Docker"
+readme = { text = """
+`comfyui-docker-helper` (`cdh`) is an independent, unofficial command-line
+helper for using ComfyUI with Docker. It is not affiliated with or endorsed by
+the ComfyUI project.
+
+See the [GitHub repository](https://github.com/jimlee2048/comfyui-docker-helper)
+for current capabilities, requirements, documentation, examples, and issue
+tracking.""", content-type = "text/markdown" }
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12,<3.15"
+authors = [
+    { name = "jimlee2048" },
+]
+maintainers = [
+    { name = "jimlee2048" },
+]
+keywords = [
+    "comfyui",
+    "docker",
+    "docker-buildx",
+    "buildkit",
+    "cli",
+    "developer-tools",
+    "container-images",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Installation/Setup",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "aria2p",
+    "build>=1,<2",
+    "httpx",
+    "packaging>=26.2",
+    "pydantic>=2,<3",
+    "python-on-whales>=0.81.0",
+    "rich",
+    "tomli-w",
+    "typer",
+]
+
+[project.scripts]
+cdh = "comfyui_docker_helper.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/jimlee2048/comfyui-docker-helper"
+Repository = "https://github.com/jimlee2048/comfyui-docker-helper"
+Issues = "https://github.com/jimlee2048/comfyui-docker-helper/issues"
+Changelog = "https://github.com/jimlee2048/comfyui-docker-helper/releases"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff",
+    "twine",
+]
+
+[build-system]
+requires = ["uv_build==0.11.28"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "comfyui_docker_helper"
+
+[tool.pytest.ini_options]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+]
+markers = [
+    "unit: fast tests for isolated units",
+    "smoke: lightweight smoke checks or smoke fixture validation",
+    "acceptance: tests parameterized by the typed release acceptance catalog",
+    "docker: tests that require Docker and --run-docker authorization",
+    "network: tests that require network access and --run-network authorization",
+    "gpu: tests that require GPU access and --run-gpu authorization",
+    "slow: tests that require --run-slow authorization",
+]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.format]
+indent-style = "space"
+line-ending = "lf"
+quote-style = "double"

comfyui_docker_helper-0.5.1/src/comfyui_docker_helper/__init__.py

@@ -0,0 +1 @@
+"""ComfyUI Docker Helper package."""

comfyui_docker_helper-0.5.1/src/comfyui_docker_helper/cli.py

@@ -0,0 +1,49 @@
+"""Top-level command-line interface."""
+
+from typing import Annotated
+
+import typer
+
+from comfyui_docker_helper.cli_settings import HELP_CONTEXT_SETTINGS
+from comfyui_docker_helper.container.cli import app as container_app
+from comfyui_docker_helper.errors import ApplicationGroup
+from comfyui_docker_helper.host.cli import app as host_app
+from comfyui_docker_helper.version import package_version
+
+app = typer.Typer(
+    cls=ApplicationGroup,
+    name="cdh",
+    help="Build ComfyUI images and run their image-internal helpers.",
+    no_args_is_help=True,
+    add_completion=False,
+    context_settings=HELP_CONTEXT_SETTINGS,
+)
+
+
+def _version_callback(show_version: bool) -> None:
+    if show_version:
+        typer.echo(f"cdh {package_version()}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            help="Show the version and exit.",
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """Route host and image-internal commands."""
+
+
+app.add_typer(host_app, name="host", help="commands executed on the host machine")
+app.add_typer(
+    container_app,
+    name="container",
+    help="helpers executed inside ComfyUI images",
+)

comfyui_docker_helper-0.5.1/src/comfyui_docker_helper/cli_settings.py

@@ -0,0 +1,3 @@
+"""Shared CLI settings."""
+
+HELP_CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}

comfyui_docker_helper-0.5.1/src/comfyui_docker_helper/comfyui_requirements.py

@@ -0,0 +1,335 @@
+"""Strict ComfyUI requirements projection and PyTorch-group merge rules."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.utils import canonicalize_name
+from packaging.version import InvalidVersion, Version
+
+from comfyui_docker_helper.config.canonical_lock import DirectPythonRequestMember
+from comfyui_docker_helper.exact_ledger import (
+    CUDA_PROTECTED_REQUIREMENTS as CUDA_PROTECTED_REQUIREMENTS,
+)
+
+COMFYUI_REQUIREMENTS_PATH = "requirements.txt"
+_SOURCE_OPTION = re.compile(
+    r"(?:-e(?:ditable)?|-i|--index-url|--extra-index-url|--find-links|"
+    r"--trusted-host|--no-index|--pre|--prefer-binary|--only-binary|"
+    r"--no-binary|--require-hashes|--constraint|-c)"
+    r"(?:\s|=|$)"
+)
+
+
+class ComfyUIRequirementsError(ValueError):
+    """One contextual strict-requirements or merge failure."""
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedComfyUIRequirements:
+    """Canonical target projection plus ordinary install remainder."""
+
+    digest: str
+    protected: tuple[DirectPythonRequestMember, ...]
+    ordinary: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class DeclaredManagerRequirement:
+    """One target-active checkout-declared Manager requirement."""
+
+    package: str
+    requirement: str
+    specifier: str
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedManagerRequirements:
+    """Strict install rows plus the exact checkout-owned Manager identity."""
+
+    digest: str
+    rows: tuple[str, ...]
+    active: tuple[DeclaredManagerRequirement, ...]
+    manager_version: str
+
+
+def parse_comfyui_requirements(
+    content: bytes,
+    *,
+    python_version: str,
+    platform: str,
+    machine: str,
+    protected_names: tuple[str, ...],
+) -> ParsedComfyUIRequirements:
+    """Parse PEP 508 rows and optionally project target-active protected members."""
+    names = (
+        set(_normalized_protected_names(protected_names)) if protected_names else set()
+    )
+    environment = target_marker_environment(python_version, platform, machine)
+    protected: list[DirectPythonRequestMember] = []
+    ordinary: list[str] = []
+    try:
+        document = content.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise ComfyUIRequirementsError("ComfyUI requirements must be UTF-8") from error
+    for line_number, raw in enumerate(document.splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("-") or _SOURCE_OPTION.match(line):
+            raise ComfyUIRequirementsError(
+                f"ComfyUI requirements line {line_number} changes package sources"
+            )
+        try:
+            requirement = Requirement(line)
+        except InvalidRequirement as error:
+            raise ComfyUIRequirementsError(
+                f"ComfyUI requirements line {line_number} is not valid PEP 508"
+            ) from error
+        if requirement.url is not None:
+            raise ComfyUIRequirementsError(
+                f"ComfyUI requirements line {line_number} uses a direct source"
+            )
+        name = canonicalize_name(requirement.name)
+        if name in names:
+            if requirement.marker is None or requirement.marker.evaluate(environment):
+                protected.append(_member(requirement))
+            continue
+        ordinary.append(str(requirement))
+    merged = merge_requirement_members(tuple(protected))
+    return ParsedComfyUIRequirements(
+        digest=f"sha256:{hashlib.sha256(content).hexdigest()}",
+        protected=merged,
+        ordinary=tuple(ordinary),
+    )
+
+
+def parse_ordinary_requirements(
+    content: bytes,
+    *,
+    python_version: str,
+    platform: str,
+    machine: str,
+) -> tuple[str, ...]:
+    """Return strict ordinary rows for a cdh-owned requirements operation."""
+    return parse_comfyui_requirements(
+        content,
+        python_version=python_version,
+        platform=platform,
+        machine=machine,
+        protected_names=(),
+    ).ordinary
+
+
+def parse_manager_requirements(
+    content: bytes,
+    *,
+    python_version: str,
+    platform: str,
+    machine: str,
+) -> ParsedManagerRequirements:
+    """Parse checkout-owned Manager requirements without accepting source control."""
+    environment = target_marker_environment(python_version, platform, machine)
+    rows: list[str] = []
+    active: list[DeclaredManagerRequirement] = []
+    seen_active: set[str] = set()
+    try:
+        document = content.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise ComfyUIRequirementsError("Manager requirements must be UTF-8") from error
+    for line_number, raw in enumerate(document.splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("-") or _SOURCE_OPTION.match(line):
+            raise ComfyUIRequirementsError(
+                f"Manager requirements line {line_number} changes package sources"
+            )
+        try:
+            requirement = Requirement(line)
+        except InvalidRequirement as error:
+            raise ComfyUIRequirementsError(
+                f"Manager requirements line {line_number} is not valid PEP 508"
+            ) from error
+        if requirement.url is not None:
+            raise ComfyUIRequirementsError(
+                f"Manager requirements line {line_number} uses a direct source"
+            )
+        canonical = str(requirement)
+        rows.append(canonical)
+        if requirement.marker is not None and not requirement.marker.evaluate(
+            environment
+        ):
+            continue
+        package = canonicalize_name(requirement.name)
+        if package in seen_active:
+            raise ComfyUIRequirementsError(
+                f"Manager requirements duplicate target package {package}"
+            )
+        seen_active.add(package)
+        active.append(
+            DeclaredManagerRequirement(
+                package=package,
+                requirement=canonical,
+                specifier=str(requirement.specifier),
+            )
+        )
+    manager = [item for item in active if item.package == "comfyui-manager"]
+    if len(manager) != 1:
+        raise ComfyUIRequirementsError(
+            "Manager requirements must declare exactly one active comfyui-manager"
+        )
+    manager_version = _exact_version(
+        manager[0].specifier,
+        subject="comfyui-manager",
+    )
+    return ParsedManagerRequirements(
+        digest=f"sha256:{hashlib.sha256(content).hexdigest()}",
+        rows=tuple(rows),
+        active=tuple(active),
+        manager_version=manager_version,
+    )
+
+
+def merge_pytorch_requirements(
+    mandatory_torch: DirectPythonRequestMember,
+    upstream: tuple[DirectPythonRequestMember, ...],
+    configured_extras: tuple[DirectPythonRequestMember, ...],
+) -> tuple[DirectPythonRequestMember, ...]:
+    """Merge all direct PyTorch ownership into one deterministic request."""
+    if mandatory_torch.package != "torch":
+        raise ComfyUIRequirementsError("mandatory PyTorch member must be torch")
+    return merge_requirement_members((mandatory_torch, *upstream, *configured_extras))
+
+
+def merge_requirement_members(
+    members: tuple[DirectPythonRequestMember, ...],
+) -> tuple[DirectPythonRequestMember, ...]:
+    """Merge normalized PEP 503 identities, extras, and compatible selectors."""
+    grouped: dict[str, list[DirectPythonRequestMember]] = {}
+    for member in members:
+        canonical = DirectPythonRequestMember.model_validate(
+            member.model_dump(mode="python")
+        )
+        grouped.setdefault(canonical.package, []).append(canonical)
+    result: list[DirectPythonRequestMember] = []
+    for package in sorted(grouped):
+        values = grouped[package]
+        extras = sorted({extra for item in values for extra in item.extras})
+        selector = _merge_selectors(package, tuple(item.selector for item in values))
+        result.append(
+            DirectPythonRequestMember(
+                package=package,
+                extras=extras,
+                selector=selector,
+            )
+        )
+    return tuple(result)
+
+
+def _member(requirement: Requirement) -> DirectPythonRequestMember:
+    try:
+        selector = str(SpecifierSet(str(requirement.specifier)))
+    except InvalidSpecifier as error:  # pragma: no cover - Requirement owns syntax.
+        raise ComfyUIRequirementsError("requirement specifier is invalid") from error
+    return DirectPythonRequestMember(
+        package=canonicalize_name(requirement.name),
+        extras=sorted(canonicalize_name(extra) for extra in requirement.extras),
+        selector=selector,
+    )
+
+
+def _exact_version(specifier: str, *, subject: str) -> str:
+    clauses = tuple(SpecifierSet(specifier))
+    if len(clauses) != 1 or clauses[0].operator != "==" or "*" in clauses[0].version:
+        raise ComfyUIRequirementsError(
+            f"{subject} must have one exact checkout-owned version"
+        )
+    try:
+        version = Version(clauses[0].version)
+    except InvalidVersion as error:
+        raise ComfyUIRequirementsError(
+            f"{subject} has an invalid exact version"
+        ) from error
+    value = str(version)
+    if value != clauses[0].version:
+        raise ComfyUIRequirementsError(
+            f"{subject} must have one canonical exact checkout-owned version"
+        )
+    return value
+
+
+def _merge_selectors(package: str, selectors: tuple[str, ...]) -> str:
+    clauses = sorted(
+        {
+            clause
+            for selector in selectors
+            if selector
+            for clause in selector.split(",")
+            if clause
+        }
+    )
+    combined = str(SpecifierSet(",".join(clauses))) if clauses else ""
+    exact: set[Version] = set()
+    for clause in clauses:
+        if (
+            clause.startswith("==")
+            and not clause.startswith("===")
+            and "*" not in clause
+        ):
+            try:
+                exact.add(Version(clause[2:]))
+            except InvalidVersion as error:
+                raise ComfyUIRequirementsError(
+                    f"protected requirement {package} has an invalid exact selector"
+                ) from error
+    if len(exact) > 1:
+        raise ComfyUIRequirementsError(
+            f"protected requirement {package} has conflicting exact selectors"
+        )
+    if exact and not SpecifierSet(combined).contains(
+        next(iter(exact)), prereleases=True
+    ):
+        raise ComfyUIRequirementsError(
+            f"protected requirement {package} has incompatible selectors"
+        )
+    return combined
+
+
+def _normalized_protected_names(names: tuple[str, ...]) -> tuple[str, ...]:
+    normalized = tuple(sorted(canonicalize_name(name) for name in names))
+    if not normalized or len(normalized) != len(set(normalized)):
+        raise ComfyUIRequirementsError(
+            "protected requirement names must be non-empty and unique"
+        )
+    return normalized
+
+
+def target_marker_environment(
+    python_version: str, platform: str, machine: str
+) -> dict[str, str]:
+    """Return the exact target environment used for PEP 508 marker evaluation."""
+    try:
+        parsed = Version(python_version)
+    except InvalidVersion as error:
+        raise ComfyUIRequirementsError("target Python version is invalid") from error
+    if platform != "linux/amd64" or machine != "x86_64" or len(parsed.release) < 2:
+        raise ComfyUIRequirementsError("requirements target is unsupported")
+    return {
+        "implementation_name": "cpython",
+        "implementation_version": python_version,
+        "os_name": "posix",
+        "platform_machine": machine,
+        "platform_python_implementation": "CPython",
+        "platform_release": "",
+        "platform_system": "Linux",
+        "platform_version": "",
+        "python_full_version": python_version,
+        "python_version": ".".join(str(value) for value in parsed.release[:2]),
+        "sys_platform": "linux",
+        "extra": "",
+    }