ros2docker 0.1.1__py3-none-any.whl

ros2docker/__init__.py

@@ -0,0 +1,19 @@
+"""ros2docker package."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+_DISTRIBUTION_NAME = "ros2docker"
+
+
+def _package_version() -> str:
+    try:
+        return version(_DISTRIBUTION_NAME)
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+__version__ = _package_version()
+
+__all__ = ["__version__"]

ros2docker/__main__.py

@@ -0,0 +1,8 @@
+"""Module entry point for ``python -m ros2docker``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ros2docker/api.py

@@ -0,0 +1,152 @@
+"""Public Python API for ros2docker."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from importlib import resources
+from pathlib import Path
+
+from .commands import (
+    make_build_command,
+    make_exec_shell_command,
+    make_run_command,
+    make_stop_command,
+)
+from .config import get_config_dir, load_config
+
+RunResult = list[str] | subprocess.CompletedProcess[bytes]
+
+
+def build(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+    *,
+    dry_run: bool = False,
+) -> RunResult:
+    with build_context(config_file, override) as context_dir:
+        command = make_build_command(config_file, override, context_dir=context_dir)
+        return _run(command, dry_run=dry_run)
+
+
+def run(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+    *,
+    mount: str | os.PathLike[str] | None = None,
+    extra_run_args: Sequence[str] | None = None,
+    dry_run: bool = False,
+) -> RunResult:
+    command = make_run_command(
+        config_file,
+        override,
+        mount=mount,
+        extra_run_args=extra_run_args,
+    )
+    return _run(command, dry_run=dry_run, cwd=get_config_dir(config_file))
+
+
+def build_run(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+    *,
+    mount: str | os.PathLike[str] | None = None,
+    extra_run_args: Sequence[str] | None = None,
+    dry_run: bool = False,
+) -> tuple[RunResult, RunResult]:
+    build_result = build(config_file, override, dry_run=dry_run)
+    run_result = run(
+        config_file,
+        override,
+        mount=mount,
+        extra_run_args=extra_run_args,
+        dry_run=dry_run,
+    )
+    return build_result, run_result
+
+
+def stop(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+    *,
+    dry_run: bool = False,
+) -> RunResult:
+    command = make_stop_command(config_file, override)
+    return _run(command, dry_run=dry_run, check=False)
+
+
+def exec_shell(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+    *,
+    command: Sequence[str] | None = None,
+    interactive: bool = True,
+    dry_run: bool = False,
+) -> RunResult:
+    docker_command = make_exec_shell_command(
+        config_file,
+        override,
+        command=command,
+        interactive=interactive,
+    )
+    return _run(docker_command, dry_run=dry_run)
+
+
+@contextmanager
+def build_context(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+) -> Iterator[Path]:
+    config = load_config(config_file, override, resolve_run_args=False)
+    with tempfile.TemporaryDirectory(prefix="ros2docker-build-") as temp_dir:
+        context_dir = Path(temp_dir)
+        _copy_build_resources(context_dir)
+        _stage_bake_packages(config, context_dir / "bake_packages")
+        yield context_dir
+
+
+def _copy_build_resources(context_dir: Path) -> None:
+    build_resource = resources.files("ros2docker").joinpath("resources").joinpath("build")
+    for item in build_resource.iterdir():
+        destination = context_dir / item.name
+        with resources.as_file(item) as source:
+            if source.is_dir():
+                shutil.copytree(source, destination)
+            else:
+                shutil.copy2(source, destination)
+    (context_dir / "bake_packages").mkdir(exist_ok=True)
+
+
+def _stage_bake_packages(config: Mapping[str, object], bake_dir: Path) -> None:
+    seen_names: set[str] = set()
+    package_paths = config.get("bake_ros_packages", [])
+    if not isinstance(package_paths, list):
+        raise ValueError("'bake_ros_packages' must be a list.")
+
+    for package_path in package_paths:
+        if not isinstance(package_path, str | os.PathLike):
+            raise TypeError(f"bake package path must be path-like, got {type(package_path).__name__}.")
+        source = Path(package_path)
+        package_name = source.name
+        if package_name in seen_names:
+            raise ValueError(f"Duplicate bake package directory name: {package_name}")
+        seen_names.add(package_name)
+        shutil.copytree(source, bake_dir / package_name, symlinks=True)
+
+
+def _run(
+    command: Sequence[str],
+    *,
+    dry_run: bool,
+    cwd: str | os.PathLike[str] | None = None,
+    check: bool = True,
+) -> RunResult:
+    print(shlex.join(list(command)), flush=True)
+    if dry_run:
+        return list(command)
+    return subprocess.run(command, check=check, cwd=cwd)

ros2docker/cli.py

@@ -0,0 +1,115 @@
+"""Command line interface for ros2docker."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .api import build, build_run, exec_shell, run, stop
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _make_parser()
+    args = parser.parse_args(argv)
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+
+    try:
+        args.func(args)
+    except Exception as exc:  # noqa: BLE001 - CLI should report concise user errors.
+        print(f"ros2docker: error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ros2docker")
+    parser.add_argument("--version", action="version", version=f"ros2docker {__version__}")
+    subparsers = parser.add_subparsers(dest="command_name")
+
+    build_parser = subparsers.add_parser("build", help="Build the configured Docker image.")
+    _add_config_options(build_parser)
+    _add_dry_run(build_parser)
+    build_parser.set_defaults(func=_build)
+
+    run_parser = subparsers.add_parser("run", help="Build and run the configured Docker container.")
+    _add_config_options(run_parser)
+    _add_dry_run(run_parser)
+    run_parser.add_argument("-m", "--mount", metavar="PATH", help="Mount PATH into /ws.")
+    run_parser.add_argument("--no-build", action="store_true", help="Run without building first.")
+    run_parser.add_argument("extra_run_args", nargs=argparse.REMAINDER, help="Extra docker run args after --.")
+    run_parser.set_defaults(func=_run)
+
+    stop_parser = subparsers.add_parser("stop", help="Stop the configured Docker container.")
+    _add_config_options(stop_parser)
+    _add_dry_run(stop_parser)
+    stop_parser.set_defaults(func=_stop)
+
+    exec_parser = subparsers.add_parser("exec", help="Execute a command in the configured Docker container.")
+    _add_config_options(exec_parser)
+    _add_dry_run(exec_parser)
+    exec_parser.add_argument("command", nargs=argparse.REMAINDER, help="Command after --, defaults to bash.")
+    exec_parser.set_defaults(func=_exec)
+
+    return parser
+
+
+def _add_config_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-f", "--config", metavar="CONFIG", help="Path to ros2docker config.")
+    parser.add_argument("-o", "--override", metavar="JSON", help="JSON object overriding config values.")
+
+
+def _add_dry_run(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--dry-run", action="store_true", help="Print Docker argv without running Docker.")
+
+
+def _strip_separator(args: list[str]) -> list[str]:
+    if args and args[0] == "--":
+        return args[1:]
+    return args
+
+
+def _build(args: argparse.Namespace) -> None:
+    build(args.config, args.override, dry_run=args.dry_run)
+
+
+def _run(args: argparse.Namespace) -> None:
+    extra_run_args = _strip_separator(args.extra_run_args)
+    if args.no_build:
+        run(
+            args.config,
+            args.override,
+            mount=args.mount,
+            extra_run_args=extra_run_args,
+            dry_run=args.dry_run,
+        )
+    else:
+        build_run(
+            args.config,
+            args.override,
+            mount=args.mount,
+            extra_run_args=extra_run_args,
+            dry_run=args.dry_run,
+        )
+
+
+def _stop(args: argparse.Namespace) -> None:
+    stop(args.config, args.override, dry_run=args.dry_run)
+
+
+def _exec(args: argparse.Namespace) -> None:
+    command = _strip_separator(args.command)
+    exec_shell(
+        args.config,
+        args.override,
+        command=command or None,
+        interactive=not command,
+        dry_run=args.dry_run,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ros2docker/commands.py

@@ -0,0 +1,191 @@
+"""Docker command rendering for ros2docker."""
+
+from __future__ import annotations
+
+import os
+import shlex
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from .config import ConfigError, get_config_dir, load_config, normalize_docker_host_paths, resolve_host_path
+
+
+def make_build_command(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+    *,
+    context_dir: str | os.PathLike[str],
+) -> list[str]:
+    config = load_config(config_file, override, resolve_run_args=False)
+    build_args = [
+        "-t",
+        _image_name(config),
+        "--build-arg",
+        f"USER_UID={os.getuid()}",
+        "--build-arg",
+        f"USER_GID={os.getgid()}",
+    ]
+
+    for key, value in config.get("build_args", {}).items():
+        build_args.extend(["--build-arg", f"{key}={value}"])
+
+    return ["docker", "build", *build_args, str(Path(context_dir))]
+
+
+def make_run_command(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+    *,
+    mount: str | os.PathLike[str] | None = None,
+    extra_run_args: Sequence[str] | None = None,
+) -> list[str]:
+    config = load_config(config_file, override)
+    run_args = [
+        "docker",
+        "run",
+        *_core_run_args(config),
+        *_local_run_args(config),
+        *_workspace_mount_args(config_file, config, mount),
+        *normalize_docker_host_paths(extra_run_args or [], Path.cwd()),
+        *_run_type_args(config),
+        _image_name(config),
+        *_run_command(config),
+    ]
+    return run_args
+
+
+def make_stop_command(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+) -> list[str]:
+    config = load_config(config_file, override, resolve_run_args=False)
+    return ["docker", "stop", _container_name(config)]
+
+
+def make_exec_shell_command(
+    config_file: str | os.PathLike[str] | None = None,
+    override: str | Mapping[str, object] | None = None,
+    *,
+    command: Sequence[str] | None = None,
+    interactive: bool = True,
+) -> list[str]:
+    config = load_config(config_file, override, resolve_run_args=False)
+    exec_args = ["docker", "exec"]
+    if interactive:
+        exec_args.append("-it")
+    exec_args.append(_container_name(config))
+    exec_args.extend(command or ["bash"])
+    return exec_args
+
+
+def _image_name(config: Mapping[str, object]) -> str:
+    return str(config.get("image_name") or "ros2docker")
+
+
+def _container_name(config: Mapping[str, object]) -> str:
+    return str(config.get("container_name") or config.get("image_name") or "ros2docker")
+
+
+def _core_run_args(config: Mapping[str, object]) -> list[str]:
+    return [
+        "--name",
+        _container_name(config),
+        "--user",
+        f"{os.getuid()}:{os.getgid()}",
+        "--rm",
+        "-e",
+        "LIBGL_ALWAYS_SOFTWARE=1",
+    ]
+
+
+def _local_run_args(config: Mapping[str, object]) -> list[str]:
+    args: list[str] = []
+
+    if config.get("enable_gui_forwarding"):
+        x11_socket = Path("/tmp/.X11-unix")
+        if not x11_socket.exists():
+            raise FileNotFoundError("GUI forwarding requested but /tmp/.X11-unix does not exist.")
+        args.extend(["-v", "/tmp/.X11-unix:/tmp/.X11-unix", "-e", "DISPLAY"])
+
+    if config.get("forward_ssh_agent"):
+        ssh_auth_sock = os.environ.get("SSH_AUTH_SOCK")
+        if not ssh_auth_sock:
+            raise ConfigError("forward_ssh_agent is true but SSH_AUTH_SOCK is not set.")
+        sock_path = Path(ssh_auth_sock)
+        if not sock_path.exists():
+            raise FileNotFoundError(f"forward_ssh_agent is true but SSH_AUTH_SOCK does not exist: {ssh_auth_sock}")
+        args.extend(["-e", "SSH_AUTH_SOCK", "-v", f"{ssh_auth_sock}:{ssh_auth_sock}"])
+
+    args.extend(_string_list(config, "run_args"))
+    args.extend(_string_list(config, "extra_run_args"))
+    return args
+
+
+def _workspace_mount_args(
+    config_file: str | os.PathLike[str] | None,
+    config: Mapping[str, object],
+    mount: str | os.PathLike[str] | None,
+) -> list[str]:
+    if mount is not None:
+        mount_path = resolve_host_path(os.fspath(mount), Path.cwd())
+        return ["-v", f"{mount_path}:/ws", "-w", "/ws"]
+
+    if config.get("mount_ws"):
+        ws_host = Path(get_config_dir(config_file)) / "ws"
+        if not ws_host.exists():
+            raise FileNotFoundError(f"mount_ws is true but workspace directory does not exist: {ws_host}")
+        return ["-v", f"{ws_host.resolve()}:/ws", "-w", "/ws"]
+
+    return []
+
+
+def _run_type_args(config: Mapping[str, object]) -> list[str]:
+    run_type = str(config.get("run_type") or "bash")
+    if run_type in {"bash", "catmux"}:
+        return ["-it"]
+    if run_type == "command":
+        return []
+    if run_type == "up":
+        return ["-d"]
+    raise ConfigError(f"Unsupported run_type: {run_type!r}")
+
+
+def _run_command(config: Mapping[str, object]) -> list[str]:
+    run_type = str(config.get("run_type") or "bash")
+
+    if run_type == "catmux":
+        catmux_file = str(config["catmux_file"])
+        catmux_command = [
+            "catmux_create_session",
+            catmux_file,
+            "--session_name",
+            _container_name(config),
+        ]
+        catmux_params = config.get("catmux_params")
+        if isinstance(catmux_params, Mapping) and catmux_params:
+            params = ",".join(f"{key}={value}" for key, value in catmux_params.items())
+            catmux_command.extend(["--overwrite", params])
+        return catmux_command
+
+    if run_type == "bash":
+        return ["bash"]
+
+    if run_type == "up":
+        return ["tail", "-f", "/dev/null"]
+
+    if run_type == "command":
+        raw_command = config["command"]
+        if isinstance(raw_command, str):
+            return shlex.split(raw_command)
+        if isinstance(raw_command, list):
+            return [str(part) for part in raw_command]
+        raise ConfigError("'command' must be a string or list.")
+
+    raise ConfigError(f"Unsupported run_type: {run_type!r}")
+
+
+def _string_list(config: Mapping[str, object], key: str) -> list[str]:
+    value = config.get(key, [])
+    if not isinstance(value, list):
+        raise ConfigError(f"{key!r} must be a list.")
+    return [str(item) for item in value]