dkview 3.0.0b5__py3-none-any.whl

dkview/__init__.py

@@ -0,0 +1,3 @@
+"""dkview: readable, colored output for docker commands."""
+
+__version__ = "3.0.0b5"

dkview/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

dkview/ansi.py

@@ -0,0 +1,124 @@
+"""Terminal colors and helpers that measure text without escape codes."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import sys
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+BLUE = "\033[34m"
+MAGENTA = "\033[35m"
+CYAN = "\033[36m"
+REVERSE = "\033[7m"
+
+ANSI_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+
+
+def _enable_windows_ansi() -> bool:
+    """Windows 10+ consoles understand color codes once asked to.
+
+    Returns False when they can't (old Windows), so colors stay off there.
+    """
+    if os.name != "nt":
+        return True
+    try:
+        import ctypes
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        handle = kernel32.GetStdHandle(-11)  # stdout
+        mode = ctypes.c_uint32()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        return bool(kernel32.SetConsoleMode(handle, mode.value | 0x0004))
+    except Exception:
+        return False
+
+
+# Plain-ASCII stand-ins, for outputs that can't show box drawing or symbols
+# (a pipe or an old console on Windows that uses a legacy code page).
+# Characters that can sit inside a table cell map to one character.
+ASCII = str.maketrans({
+    "┌": "+", "┬": "+", "┐": "+", "├": "+", "┼": "+", "┤": "+", "└": "+", "┴": "+",
+    "┘": "+", "─": "-", "│": "|", "●": "*", "○": "o", "✓": "OK", "✗": "X",
+    "·": "-", "…": "~", "×": "x", "→": "->", "⚠": "!",
+})
+
+
+class _AsciiWriter:
+    """Wraps a text stream, writing ASCII stand-ins for what it can't encode."""
+
+    def __init__(self, stream) -> None:
+        self._stream = stream
+
+    def write(self, text: str) -> int:
+        return self._stream.write(text.translate(ASCII))
+
+    def __getattr__(self, name: str):
+        return getattr(self._stream, name)
+
+
+def _can_show(stream, sample: str = "┌─●✓") -> bool:
+    try:
+        sample.encode(getattr(stream, "encoding", None) or "ascii")
+        return True
+    except (LookupError, UnicodeEncodeError):
+        return False
+
+
+def prepare_output() -> None:
+    """Never crash on a character the output's encoding lacks: use ASCII
+    stand-ins for box lines and symbols, and '?' for anything else."""
+    for name in ("stdout", "stderr"):
+        stream = getattr(sys, name)
+        if stream is None or _can_show(stream):
+            continue
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(errors="replace")
+            except (ValueError, OSError):
+                pass
+        setattr(sys, name, _AsciiWriter(stream))
+
+
+class _Colors:
+    """Process-wide switch for colored output."""
+
+    def __init__(self) -> None:
+        self.enabled = (sys.stdout.isatty() and "NO_COLOR" not in os.environ
+                        and _enable_windows_ansi())
+
+
+colors = _Colors()
+
+
+def paint(text: str, *codes: str) -> str:
+    if not colors.enabled or not text or not codes:
+        return text
+    return "".join(codes) + text + RESET
+
+
+def strip(text: str) -> str:
+    return ANSI_RE.sub("", text)
+
+
+def visible_len(text: str) -> int:
+    return len(strip(text))
+
+
+def pad(text: str, width: int) -> str:
+    """ljust that ignores ANSI escape codes when measuring."""
+    return text + " " * max(0, width - visible_len(text))
+
+
+def terminal_size() -> "os.terminal_size":
+    return shutil.get_terminal_size((120, 40))
+
+
+def terminal_width() -> int:
+    return terminal_size().columns

dkview/cli.py

@@ -0,0 +1,261 @@
+"""Command-line entry point: decide what to do with the command given."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import shlex
+import sys
+from typing import List, Optional, Sequence
+
+from . import __version__, docker, engine
+from .ansi import colors, prepare_output
+from .features import clean, dashboard, doctor, errors, images, inspect, live, logs, shell, tables
+from .options import Options
+from .runner import passthrough
+
+EPILOG = """\
+examples:
+  dkview docker ps                 formatted, colored table
+  dkview ps -a                     same; "docker" can be left out
+  dkview --short --cols name,status,image ps
+  dkview --sort cpu --desc stats   live stats, busiest first (Ctrl+C quits)
+  dkview --watch service ls        redraw every 2 seconds
+  dkview inspect web               short summary; add --full for every field
+  dkview --grep timeout logs -f api
+  dkview dash                      overview of the whole host (--watch for live)
+  dkview images --group            one row per repository with total sizes
+  dkview clean --dry-run           old unused image tags that would be removed
+  dkview clean --keep 5            remove them, keeping the newest 5 per repository
+  dkview doctor                    failing swarm services with the real error
+  dkview errors                    errors and warnings in all logs, last 30 minutes
+  dkview errors orders --since 2d   one stack, service or container
+  dkview shell-init                make plain "docker ps" use dkview
+
+dkview's own options go before the command. Default options can be set in
+the DKVIEW_OPTS environment variable, e.g. DKVIEW_OPTS="--short".
+"""
+
+
+# Commands that are dkview's own rather than docker's.
+OWN_COMMANDS = {"dash", "clean", "doctor", "errors", "shell-init"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="dkview",
+        description="Readable, colored output for docker commands.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    view = p.add_argument_group("table view")
+    view.add_argument("--cols", metavar="A,B,...",
+                      help="show only these columns, in this order (names can be shortened)")
+    view.add_argument("--sort", metavar="COL", help="sort rows by a column (numbers, sizes and ages sort by value)")
+    view.add_argument("--desc", action="store_true", help="sort largest first")
+    view.add_argument("--grep", metavar="REGEX",
+                      help="keep only rows (or log lines) matching this, case-insensitive")
+    view.add_argument("--short", action="store_true",
+                      help="hide the registry host in image names")
+    view.add_argument("--long-times", action="store_true",
+                      help="keep docker's '4 minutes ago' instead of '4m ago'")
+    view.add_argument("--trunc", action="store_true",
+                      help="keep docker's own truncation of long values")
+    view.add_argument("--width", type=int, help="table width (default: terminal width)")
+
+    mode = p.add_argument_group("modes")
+    mode.add_argument("-w", "--watch", action="store_true",
+                      help="redraw the output every few seconds until Ctrl+C")
+    mode.add_argument("-n", "--interval", type=float, default=2.0, metavar="SEC",
+                      help="seconds between redraws (default: 2)")
+    mode.add_argument("--once", action="store_true",
+                      help="docker stats: print one snapshot instead of a live view")
+    mode.add_argument("--full", action="store_true",
+                      help="inspect: show every field as a tree instead of a summary")
+    mode.add_argument("--raw", action="store_true",
+                      help="run the command untouched")
+    mode.add_argument("--group", action="store_true",
+                      help="images: one row per repository with total and unused size")
+
+    cleaning = p.add_argument_group("dkview clean")
+    cleaning.add_argument("--keep", type=int, default=3, metavar="N",
+                       help="keep the newest N tags of each repository (default: 3)")
+    cleaning.add_argument("--dry-run", action="store_true",
+                       help="only show what would be deleted")
+    cleaning.add_argument("-y", "--yes", action="store_true",
+                       help="delete without asking")
+
+    logs_group = p.add_argument_group("dkview errors")
+    logs_group.add_argument("--since", metavar="TIME",
+                            help="how far back to read logs: 30m, 6h, 2d, 1w or a date "
+                                 f"(default: {errors.DEFAULT_SINCE})")
+
+    out = p.add_argument_group("output")
+    out.add_argument("--no-color", action="store_true", help="disable colors")
+    out.add_argument("--color", action="store_true",
+                     help="force colors even when not printing to a terminal")
+    out.add_argument("-V", "--version", action="version", version=f"dkview {__version__}")
+
+    p.add_argument("command", nargs=argparse.REMAINDER, help="the command to run")
+    return p
+
+
+def to_options(args: argparse.Namespace) -> Options:
+    return Options(
+        width=args.width,
+        cols=[c.strip() for c in (args.cols or "").split(",") if c.strip()],
+        sort=args.sort,
+        desc=args.desc,
+        grep=re.compile(args.grep, re.IGNORECASE) if args.grep else None,
+        short=args.short,
+        humanize=not args.long_times,
+        trunc=args.trunc,
+        watch=args.watch,
+        once=args.once,
+        interval=max(0.5, args.interval),
+        full=args.full,
+        group=args.group,
+        keep=max(0, args.keep),
+        dry_run=args.dry_run,
+        yes=args.yes,
+        since=args.since,
+    )
+
+
+def run(argv: Sequence[str]) -> int:
+    parser = build_parser()
+    args = parser.parse_args(shlex.split(os.environ.get("DKVIEW_OPTS", "")) + list(argv))
+
+    if args.no_color:
+        colors.enabled = False
+    elif args.color:
+        colors.enabled = True
+
+    try:
+        opts = to_options(args)
+    except re.error as error:
+        parser.error(f"--grep: {error}")
+
+    command: List[str] = list(args.command)
+    if command[:1] == ["--"]:
+        command = command[1:]
+    if not command:
+        parser.print_help()
+        return 2
+
+    if command[0] == "errors":
+        return run_errors(parser, command[1:], opts)
+
+    if command[0] in OWN_COMMANDS and len(command) > 1 and command[0] != "shell-init":
+        # `dkview clean --keep 5`: options after dkview's own commands are dkview's.
+        before = list(argv)[:len(argv) - len(args.command)]
+        return run(before + command[1:] + [command[0]])
+
+    if command[0] == "clean":
+        return clean.run([engine.name()], opts)
+    if command[0] == "doctor":
+        return doctor.run([engine.name()], opts)
+    if command[0] == "dash":
+        frame = lambda width: dashboard.frame(opts, width)  # noqa: E731
+        if opts.watch:
+            return live.run(frame, "dkview dash", opts.interval)
+        sys.stdout.write(frame(opts.width))
+        return 0
+
+    if command[0] == "shell-init":
+        return shell_init(command[1:])
+
+    command = docker.expand_shortcut(command)
+
+    if args.raw:
+        return passthrough(command)
+
+    if not docker.is_docker(command):
+        return run_table(command, opts)
+
+    kind = docker.classify(command).name
+    if kind == "logs":
+        return logs.run(command, opts)
+    if kind == "inspect":
+        return inspect.run(command, opts)
+    if kind == "stats":
+        live_stats = not opts.once and sys.stdout.isatty() and "--no-stream" not in command
+        if live_stats or opts.watch:
+            return live.run(tables.snapshot(command, opts), " ".join(command), opts.interval)
+        return tables.run(command, opts)
+    if kind == "table" and images.is_image_list(command):
+        if "--group" in command:  # also accepted after the command
+            command = [a for a in command if a != "--group"]
+            opts.group = True
+        if opts.group:
+            return images.run_group(command, opts)
+    if kind == "table":
+        return run_table(command, opts)
+    return passthrough(command)
+
+
+def run_errors(parser: argparse.ArgumentParser, rest: List[str], opts: Options) -> int:
+    """`dkview errors [TARGET...]`: targets and options can be mixed freely."""
+    sub = argparse.ArgumentParser(prog="dkview errors", description=errors.__doc__,
+                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub.add_argument("targets", nargs="*", metavar="NAME",
+                     help="stack, service or container name or ID (default: everything)")
+    sub.add_argument("--since", metavar="TIME",
+                     help=f"30m, 6h, 2d, 1w or a date (default: {errors.DEFAULT_SINCE})")
+    sub.add_argument("--grep", metavar="REGEX", help="count only lines matching this")
+    sub.add_argument("--full", action="store_true", help="show every kind of message")
+    sub.add_argument("--width", type=int, help="table width")
+    sub.add_argument("--no-color", action="store_true", help="disable colors")
+    sub.add_argument("--color", action="store_true", help="force colors")
+    args = sub.parse_intermixed_args(rest)
+
+    if args.since:
+        opts.since = args.since
+    if args.grep:
+        try:
+            opts.grep = re.compile(args.grep, re.IGNORECASE)
+        except re.error as error:
+            sub.error(f"--grep: {error}")
+    opts.full = opts.full or args.full
+    opts.width = args.width or opts.width
+    if args.no_color:
+        colors.enabled = False
+    elif args.color:
+        colors.enabled = True
+    return errors.run([engine.name()], args.targets, opts)
+
+
+def run_table(command: List[str], opts: Options) -> int:
+    if opts.watch:
+        return live.run(tables.snapshot(command, opts), " ".join(command), opts.interval)
+    return tables.run(command, opts)
+
+
+def shell_init(rest: List[str]) -> int:
+    name: Optional[str] = rest[0] if rest else None
+    if name is None:
+        sys.stdout.write(shell.USAGE)
+        return 0
+    if name not in shell.SCRIPTS:
+        sys.stderr.write(f"dkview: unsupported shell '{name}' (bash, zsh, fish, powershell)\n")
+        return 2
+    sys.stdout.write(shell.script(name))
+    return 0
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    prepare_output()
+    try:
+        return run(sys.argv[1:] if argv is None else argv)
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:
+        # Output piped into `head` or `less` that quit early.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dkview/docker.py

@@ -0,0 +1,190 @@
+"""Understanding docker command lines: which subcommand, and how to run it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Sequence
+
+from . import engine
+
+# Options that take a separate value (`--context prod`, `-f file.yml`,
+# `--filter status=exited`). The value is skipped when looking for the
+# subcommand words.
+VALUE_OPTIONS = {
+    "-c", "--context", "-H", "--host", "--config", "-l", "--log-level",
+    "--tlscacert", "--tlscert", "--tlskey",
+    "-f", "--file", "--filter", "-p", "--project-name",
+    "--project-directory", "--env-file", "--profile",
+    "-n", "--tail", "--since", "--until",
+}
+
+LIST_VERBS = {"ls", "list"}
+
+# Commands whose output is a table. Anything not listed here (run, exec,
+# build, events, typos, --help...) runs straight through untouched.
+TABLE_COMMANDS = {
+    "ps": None, "images": None, "stats": None, "top": None,
+    "history": None, "search": None,
+    "container": LIST_VERBS | {"ps", "stats", "top"},
+    "image": LIST_VERBS | {"history"},
+    "volume": LIST_VERBS,
+    "network": LIST_VERBS,
+    "service": LIST_VERBS | {"ps"},
+    "node": LIST_VERBS | {"ps"},
+    "stack": LIST_VERBS | {"ps", "services"},
+    "secret": LIST_VERBS,
+    "config": LIST_VERBS,
+    "context": LIST_VERBS,
+    "plugin": LIST_VERBS,
+    "system": {"df"},
+    "compose": {"ps", "ls", "images", "top", "stats"},
+    "buildx": LIST_VERBS,
+}
+
+INSPECT_OBJECTS = {"container", "image", "service", "network", "volume",
+                   "node", "secret", "config", "plugin", "context"}
+
+LOG_OBJECTS = {"container", "service", "compose"}
+
+# Every top-level docker command, so `dkview ps` can mean `docker ps`.
+DOCKER_COMMANDS = {
+    "attach", "build", "builder", "buildx", "commit", "compose", "config",
+    "container", "context", "cp", "create", "diff", "events", "exec",
+    "export", "history", "image", "images", "import", "info", "inspect",
+    "kill", "load", "login", "logout", "logs", "manifest", "network",
+    "node", "pause", "plugin", "port", "ps", "pull", "push", "rename",
+    "restart", "rm", "rmi", "run", "save", "search", "secret", "service",
+    "stack", "start", "stats", "stop", "swarm", "system", "tag", "top",
+    "trust", "unpause", "update", "version", "volume", "wait",
+}
+
+
+def is_docker(argv: Sequence[str]) -> bool:
+    """docker, or podman, which takes the same commands."""
+    return bool(argv) and engine.kind(argv[0]) != ""
+
+
+def expand_shortcut(argv: List[str]) -> List[str]:
+    """`dkview ps -a` -> `docker ps -a` (or `podman ps -a`)."""
+    if argv and argv[0] in DOCKER_COMMANDS:
+        return [engine.name()] + argv
+    return argv
+
+
+def words(argv: Sequence[str], limit: int = 2) -> List[str]:
+    """First non-option words after `docker`.
+
+    `docker --context prod service ls -q` -> ['service', 'ls']
+    """
+    found: List[str] = []
+    skip = False
+    for arg in argv[1:]:
+        if skip:
+            skip = False
+        elif arg in VALUE_OPTIONS:
+            skip = True
+        elif not arg.startswith("-"):
+            found.append(arg)
+            if len(found) == limit:
+                break
+    return found
+
+
+def has_option(argv: Sequence[str], *names: str) -> bool:
+    return any(a in names or any(a.startswith(n + "=") for n in names
+                                 if n.startswith("--"))
+               for a in argv)
+
+
+def user_chose_format(argv: Sequence[str]) -> bool:
+    return has_option(argv, "--format", "-q", "--quiet", "--pretty")
+
+
+@dataclass
+class Kind:
+    """What dkview should do with a docker command."""
+
+    name: str  # "table", "stats", "logs", "inspect" or "passthrough"
+
+
+def classify(argv: Sequence[str]) -> Kind:
+    w = words(argv)
+    if not w or has_option(argv, "-h", "--help"):
+        return Kind("passthrough")
+
+    first = w[0]
+    second = w[1] if len(w) > 1 else None
+
+    if first == "logs" or (first in LOG_OBJECTS and second == "logs"):
+        return Kind("logs")
+
+    if first == "inspect" or (first in INSPECT_OBJECTS and second == "inspect"):
+        if user_chose_format(argv):
+            return Kind("passthrough")
+        return Kind("inspect")
+
+    if user_chose_format(argv) and not _is_table_format(argv):
+        return Kind("passthrough")
+
+    if first not in TABLE_COMMANDS:
+        return Kind("passthrough")
+    verbs = TABLE_COMMANDS[first]
+    if verbs is not None and second not in verbs:
+        return Kind("passthrough")
+
+    # Layouts that are not a single table.
+    if [first, second] == ["system", "df"] and has_option(argv, "-v", "--verbose"):
+        return Kind("passthrough")
+    if has_option(argv, "--tree"):
+        return Kind("passthrough")
+
+    if first == "stats" or (first in ("container", "compose") and second == "stats"):
+        return Kind("stats")
+    return Kind("table")
+
+
+def _is_table_format(argv: Sequence[str]) -> bool:
+    """`--format 'table {{.Names}}\t{{.Status}}'` still prints a table."""
+    for i, arg in enumerate(argv):
+        value = None
+        if arg == "--format" and i + 1 < len(argv):
+            value = argv[i + 1]
+        elif arg.startswith("--format="):
+            value = arg.split("=", 1)[1]
+        if value is not None:
+            return value.strip().startswith("table")
+    return False
+
+
+# Commands that accept --no-trunc. dkview asks for full values and wraps
+# them itself, then shortens IDs back to docker's usual 12 characters.
+NO_TRUNC = {
+    ("ps",), ("images",), ("history",), ("search",),
+    ("container", "ls"), ("container", "ps"), ("container", "list"),
+    ("image", "ls"), ("image", "list"), ("image", "history"),
+    ("service", "ps"), ("stack", "ps"), ("node", "ps"),
+    ("network", "ls"), ("network", "list"), ("compose", "ps"),
+}
+
+
+def supports_no_trunc(argv: Sequence[str]) -> bool:
+    w = words(argv)
+    return tuple(w[:1]) in NO_TRUNC or tuple(w[:2]) in NO_TRUNC
+
+
+def prepare(argv: Sequence[str], trunc: bool) -> List[str]:
+    """Flags that make docker print one complete snapshot we can format."""
+    argv = list(argv)
+    kind = classify(argv)
+
+    # `docker stats` refreshes forever by default; take a single sample.
+    if kind.name == "stats" and "--no-stream" not in argv:
+        argv.append("--no-stream")
+
+    # Full values so COMMAND or ERROR are not cut short; dkview wraps
+    # long values itself.
+    if (kind.name == "table" and supports_no_trunc(argv) and not trunc
+            and not has_option(argv, "--no-trunc", "--format", "-q", "--quiet")):
+        argv.append("--no-trunc")
+
+    return argv

dkview/engine.py

@@ -0,0 +1,34 @@
+"""Which container engine to run: docker, or podman where docker is missing.
+
+DKVIEW_ENGINE=podman (or a full path) picks one explicitly.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+ENGINES = ("docker", "podman")
+
+
+def name() -> str:
+    chosen = os.environ.get("DKVIEW_ENGINE", "").strip()
+    if chosen:
+        return chosen
+    for engine in ENGINES:
+        if shutil.which(engine):
+            return engine
+    return "docker"   # not installed: let docker's own "not found" error show
+
+
+def kind(program: str) -> str:
+    """'docker', 'podman' or '' for /usr/bin/podman, docker.exe, ..."""
+    base = program.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    for ext in (".exe", ".cmd", ".bat"):
+        if base.endswith(ext):
+            base = base[:-len(ext)]
+    return base if base in ENGINES else ""
+
+
+def is_podman(argv) -> bool:
+    return bool(argv) and kind(argv[0]) == "podman"