docker-dsl 0.1.0__py3-none-any.whl

docker_dsl/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from docker_dsl.context import context, rendering
+from docker_dsl.core import Dockerfile
+from docker_dsl.stage import Stage
+from docker_dsl.state import current_stage
+
+# Load-bearing for the docs site: without it, great-docs walks every public
+# symbol, including the ~4500 generated methods in builder.pyi.
+__all__ = ["Dockerfile", "Stage", "context", "current_stage", "rendering"]

docker_dsl/__main__.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from docker_dsl.context import Registry
+from docker_dsl.core import Dockerfile
+
+
+class Main:
+    @classmethod
+    def parse_bool(cls, value: str) -> bool:
+        match value.lower():
+            case "true" | "1" | "yes":
+                return True
+            case "false" | "0" | "no":
+                return False
+        raise argparse.ArgumentTypeError(f"expected true/false, got {value!r}")
+
+    @classmethod
+    def type_for(cls, type_: type) -> Callable[[str], Any]:
+        return cls.parse_bool if type_ is bool else type_
+
+    @classmethod
+    def run(cls, argv: list[str] | None = None) -> None:
+        args = sys.argv[1:] if argv is None else argv
+        usage = "usage: docker-dsl <module.path> [--<key>=<value> ...] [--out PATH]"
+        if args and args[0] in ("-h", "--help"):
+            print(usage)
+            return
+        if not args:
+            raise SystemExit(usage)
+        module_path, *rest = args
+        module = importlib.import_module(module_path)
+        schema = Registry.get(module)
+
+        parser = argparse.ArgumentParser(prog=f"python -m docker_dsl {module_path}")
+        parser.add_argument("--out", type=Path, default=None)
+        for name, type_ in schema.items():
+            parser.add_argument(f"--{name}", type=cls.type_for(type_), required=True)
+
+        namespace = parser.parse_args(rest)
+        out: Path | None = namespace.out
+        config_values = {name: getattr(namespace, name) for name in schema}
+
+        text = Dockerfile(module).render(path=out, **config_values)
+        if out is None:
+            sys.stdout.write(text)
+
+
+if __name__ == "__main__":
+    Main.run()

docker_dsl/_completions.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Invoked by stubgen.py via: bash -lic 'source _completions.sh <output.json>'
+# Must run via -c so bash stays fully interactive for completion loading.
+
+OUTPUT="${1:?usage: source _completions.sh <output.json>}"
+
+# Collect all command names
+mapfile -t ALL_CMDS < <(compgen -c | sort -u)
+
+# Trigger lazy loading for common dev tools that might not be registered yet
+PRIORITY_CMDS=(git make cmake curl tar docker uv pip npm cargo gcc g++ clang
+    python python3 ruby node rustc go java javac scp ssh rsync sed awk
+    find xargs sort uniq wc head tail cat less grep diff patch chmod chown
+    cp mv rm mkdir rmdir ln touch kill ps mount umount df du free top htop
+    systemctl journalctl apt dpkg yum dnf pacman brew port)
+
+for cmd in "${PRIORITY_CMDS[@]}"; do
+    _completion_loader "$cmd" 2>/dev/null || true
+done
+
+# Collect all function-based completion specs
+declare -A COMP_FUNCS
+while IFS= read -r line; do
+    fn=$(echo "$line" | sed -n 's/.*-F \([^ ]*\).*/\1/p')
+    cmd=$(echo "$line" | awk '{print $NF}')
+    [ -n "$fn" ] && [ -n "$cmd" ] && COMP_FUNCS["$cmd"]="$fn"
+done < <(complete -p 2>/dev/null)
+
+extract_completions() {
+    local cmd="$1" fn="$2"
+
+    COMPREPLY=()
+    COMP_WORDS=("$cmd" "")
+    COMP_CWORD=1
+    COMP_LINE="$cmd "
+    COMP_POINT=$((${#cmd} + 1))
+    "$fn" >/dev/null 2>&1 || true
+
+    local subs=()
+    local is_filesystem=true
+    for s in "${COMPREPLY[@]}"; do
+        s="${s%% }"
+        [ -z "$s" ] && continue
+        [[ "$s" == */* ]] && continue
+        [[ "$s" == *.* ]] && continue
+        [ ! -e "$s" ] && is_filesystem=false
+        subs+=("$s")
+    done
+    $is_filesystem && [ ${#subs[@]} -gt 0 ] && subs=()
+
+    COMPREPLY=()
+    COMP_WORDS=("$cmd" "--")
+    COMP_CWORD=1
+    COMP_LINE="$cmd --"
+    COMP_POINT=$((${#cmd} + 3))
+    "$fn" >/dev/null 2>&1 || true
+
+    local flags=()
+    for f in "${COMPREPLY[@]}"; do
+        f="${f%% }"
+        f="${f%%=}"
+        [[ "$f" == --* ]] || continue
+        flags+=("$f")
+    done
+
+    # Discard if too many subcommands (dictionary/manpage completion noise)
+    [ ${#subs[@]} -gt 500 ] && subs=()
+    [ ${#subs[@]} -eq 0 ] && [ ${#flags[@]} -eq 0 ] && return
+
+    local subs_json flags_json
+    subs_json=$(printf '%s\n' "${subs[@]}" | sort -u | jq -Rsc 'split("\n") | map(select(. != ""))')
+    flags_json=$(printf '%s\n' "${flags[@]}" | sort -u | jq -Rsc 'split("\n") | map(select(. != ""))')
+
+    printf '"%s": {"subcommands": %s, "flags": %s}' "$cmd" "$subs_json" "$flags_json"
+}
+
+{
+    first=true
+    printf '{"commands": ['
+    for cmd in "${ALL_CMDS[@]}"; do
+        $first || printf ','
+        printf '"%s"' "$cmd"
+        first=false
+    done
+    printf '], "completions": {'
+
+    first=true
+    for cmd in "${!COMP_FUNCS[@]}"; do
+        result=$(extract_completions "$cmd" "${COMP_FUNCS[$cmd]}" 2>/dev/null </dev/null) || true
+        [ -z "$result" ] && continue
+        $first || printf ','
+        printf '%s' "$result"
+        first=false
+    done
+
+    printf '}}\n'
+} > "$OUTPUT"

docker_dsl/apt.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from docker_dsl.run import ShellCommand
+
+
+@dataclass(kw_only=True)
+class AptMixin:
+    apt_updated: bool = False
+    apt_dirty: bool = True
+
+    def append(self, command: ShellCommand) -> None: ...
+
+    def apt_install(self, *packages: str, fast: bool = False) -> None:
+        from docker_dsl.run import ShellCommand
+
+        if not self.apt_updated or self.apt_dirty:
+            self.append(ShellCommand(raw="apt-get update -y"))
+            self.apt_updated = True
+            self.apt_dirty = False
+        cmd = "apt-fast" if fast else "apt-get"
+        self.append(ShellCommand(raw=f"{cmd} install -y --no-install-recommends {' '.join(packages)}"))
+
+    def add_apt_ppa(self, ppa: str) -> None:
+        from docker_dsl.run import ShellCommand
+
+        self.append(ShellCommand(raw=f"add-apt-repository {ppa} -y"))
+        self.apt_dirty = True
+
+    def add_apt_repo(self, key_url: str, repo_url: str, *, name: str) -> None:
+        from docker_dsl.run import ShellCommand
+
+        self.append(
+            ShellCommand(raw=f"wget -O- {key_url} | gpg --dearmor | tee /usr/share/keyrings/{name}.gpg > /dev/null")
+        )
+        self.append(
+            ShellCommand(
+                raw=f'echo "deb [signed-by=/usr/share/keyrings/{name}.gpg] {repo_url}" '
+                f"| tee /etc/apt/sources.list.d/{name}.list"
+            )
+        )
+        self.apt_dirty = True

docker_dsl/builder.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import TYPE_CHECKING, Self
+
+from docker_dsl.apt import AptMixin
+from docker_dsl.run import CdScope, RedirectableCmd, ShellCommand
+
+if TYPE_CHECKING:
+    from docker_dsl.run import CmdInvoker
+    from docker_dsl.stage import Stage
+
+
+@dataclass
+class RunBuilder(AptMixin):
+    stage: Stage
+    commands: list[ShellCommand] = field(default_factory=list)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if exc_type is not None or not self.commands:
+            return
+        self.stage.emit_run(self.build_script())
+
+    def build_script(self) -> str:
+        return " \\\n  && ".join(c.render() for c in self.commands)
+
+    def append(self, command: ShellCommand) -> None:
+        self.commands.append(command)
+
+    # The generated builder.pyi shadows this module for type checkers, so
+    # `Self` here is a distinct type from the stub's `RunBuilder` that
+    # CmdInvoker & co. are annotated against.
+    def __getattr__(self, name: str) -> CmdInvoker:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        from docker_dsl.run import CmdInvoker
+
+        return CmdInvoker(self, name)  # type: ignore
+
+    def __call__(self, raw: str, *, env: dict[str, str] | None = None) -> None:
+        self.append(ShellCommand(raw=raw, env=env or {}))
+
+    def echo(self, text: str) -> RedirectableCmd:
+        return RedirectableCmd(self, text)  # type: ignore
+
+    def cd(self, path: str) -> CdScope:
+        return CdScope(self, path)  # type: ignore
+
+    def curl_bash(self, url: str, *, args: tuple[str, ...] = ()) -> None:
+        tail = f" -- {' '.join(args)}" if args else ""
+        self.append(ShellCommand(raw=f"curl --proto '=https' --tlsv1.2 -sSf {url} | bash -s{tail}"))
+
+    def install(self, url: str, *, target: str = "/usr/local/bin", strip: int = 1) -> None:
+        self.append(ShellCommand(raw=f"curl -fL {url} | tar xz -C {target} --strip-components={strip}"))
+
+    def fetch_file(self, url: str, dest: str) -> None:
+        self.append(ShellCommand(raw=f"mkdir -p $(dirname {dest}) && curl -fsSL {url} -o {dest}"))