dktcli 1.0.0__py3-none-any.whl

devkittools/tools/timetool.py

@@ -0,0 +1,130 @@
+"""dkt time (tm) - convert timestamps, show time in many formats, compute differences."""
+from __future__ import annotations
+
+import argparse
+import re
+import time
+from datetime import datetime, timedelta, timezone
+
+from ..utils import DktError, c, kv, output_result
+
+META = ("Generate & Convert", "time", "tm", "epoch <-> date converter, 'time ago', date math")
+
+EPILOG = """\
+examples:
+  dkt tm                         now in every common format
+  dkt tm 1700000000              epoch -> date (seconds, ms or us auto-detected)
+  dkt tm 2024-03-01T12:00:00Z    date -> epoch
+  dkt tm "2024-03-01 09:30" --tz +05:30
+  dkt tm now --add 3d4h          date math (units: s m h d w)
+  dkt tm 2024-01-01 --diff 2024-03-15   difference between two moments
+"""
+
+
+def parse_offset(s: str) -> timezone:
+    if s.upper() in ("Z", "UTC"):
+        return timezone.utc
+    m = re.fullmatch(r"([+-])(\d{1,2})(?::?(\d{2}))?", s)
+    if not m:
+        raise DktError("Bad timezone '%s'. Use UTC or an offset like +05:30 / -08." % s)
+    delta = timedelta(hours=int(m.group(2)), minutes=int(m.group(3) or 0))
+    return timezone(delta if m.group(1) == "+" else -delta)
+
+
+def parse_moment(s: str, assume_tz: timezone) -> datetime:
+    s = s.strip()
+    if s.lower() in ("", "now"):
+        return datetime.now(timezone.utc)
+    if re.fullmatch(r"-?\d+(\.\d+)?", s):
+        v = float(s)
+        a = abs(v)
+        if a >= 1e17:
+            v /= 1e9
+        elif a >= 1e14:
+            v /= 1e6
+        elif a >= 1e11:
+            v /= 1e3
+        return datetime.fromtimestamp(v, tz=timezone.utc)
+    t = s.replace("Z", "+00:00").replace("z", "+00:00")
+    for candidate in (t, t.replace(" ", "T", 1)):
+        try:
+            dt = datetime.fromisoformat(candidate)
+            return dt if dt.tzinfo else dt.replace(tzinfo=assume_tz)
+        except ValueError:
+            pass
+    for fmt in ("%Y/%m/%d %H:%M:%S", "%Y/%m/%d", "%d/%m/%Y", "%m/%d/%Y %H:%M", "%b %d %Y", "%d %b %Y", "%B %d, %Y"):
+        try:
+            return datetime.strptime(s, fmt).replace(tzinfo=assume_tz)
+        except ValueError:
+            pass
+    raise DktError("Couldn't understand '%s'. Try epoch seconds or ISO like 2024-03-01T12:00:00Z." % s)
+
+
+def parse_delta(s: str) -> timedelta:
+    total = 0
+    found = False
+    for num, unit in re.findall(r"(-?\d+)\s*([smhdw])", s.lower()):
+        found = True
+        total += int(num) * {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}[unit]
+    if not found:
+        raise DktError("Bad duration '%s'. Example: 3d4h30m" % s)
+    return timedelta(seconds=total)
+
+
+def human_delta(td: timedelta) -> str:
+    secs = int(abs(td.total_seconds()))
+    parts = []
+    for name, n in (("y", 31536000), ("d", 86400), ("h", 3600), ("m", 60), ("s", 1)):
+        if secs >= n:
+            parts.append("%d%s" % (secs // n, name))
+            secs %= n
+    return " ".join(parts[:3]) or "0s"
+
+
+def relative(dt: datetime) -> str:
+    d = dt - datetime.now(timezone.utc)
+    return ("in " + human_delta(d)) if d.total_seconds() > 0 else (human_delta(d) + " ago")
+
+
+def run(args) -> int:
+    tz = parse_offset(args.tz) if args.tz else datetime.now().astimezone().tzinfo
+    dt = parse_moment(args.moment or "now", tz)
+    if args.add:
+        dt += parse_delta(args.add)
+    if args.diff:
+        other = parse_moment(args.diff, tz)
+        d = other - dt
+        kv([("from", dt.isoformat()), ("to", other.isoformat()),
+            ("difference", c(human_delta(d), "bold") + (" later" if d.total_seconds() >= 0 else " earlier")),
+            ("seconds", "%d" % d.total_seconds()), ("days", "%.2f" % (d.total_seconds() / 86400))])
+        return 0
+    local = dt.astimezone(tz) if args.tz else dt.astimezone()
+    epoch = dt.timestamp()
+    rows = [("UTC", dt.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M:%S"))]
+    if not (args.tz and args.tz.upper() in ("UTC", "Z")):
+        rows.append((args.tz.upper() if args.tz else "local", local.strftime("%Y-%m-%d %H:%M:%S %z")))
+    rows += [
+        ("ISO 8601", dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")),
+        ("epoch (s)", "%d" % epoch),
+        ("epoch (ms)", "%d" % (epoch * 1000)),
+        ("RFC 2822", local.strftime("%a, %d %b %Y %H:%M:%S %z")),
+        ("day", "%s, week %s, day %s of year" % (local.strftime("%A"), local.strftime("%V"), local.strftime("%j"))),
+        ("relative", relative(dt)),
+    ]
+    if args.raw:
+        print("%d" % epoch)
+        return 0
+    kv([(k, c(v, "bold") if k in ("epoch (s)", "ISO 8601") else v) for k, v in rows])
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("time", aliases=["tm"], parents=[common], help=META[3],
+                       description="Convert and inspect timestamps.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("moment", nargs="?", help="epoch, ISO date, or 'now' (default)")
+    p.add_argument("--tz", metavar="OFFSET", help="timezone offset for input/output, e.g. +05:30 or UTC")
+    p.add_argument("--add", metavar="DUR", help="add a duration, e.g. 3d4h or -90m")
+    p.add_argument("--diff", metavar="OTHER", help="show the difference to another moment")
+    p.add_argument("--raw", action="store_true", help="print only epoch seconds")
+    p.set_defaults(func=run)

devkittools/tools/todo.py

@@ -0,0 +1,69 @@
+"""dkt todo (td) - collect TODO / FIXME / HACK comments across a project."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from collections import Counter
+
+from ..utils import c, is_binary_chunk, list_project_files, resolve_folder, sym, warn, human_num
+
+META = ("Project & Code", "todo", "td", "list TODO/FIXME/HACK comments with file:line")
+
+EPILOG = """\
+examples:
+  dkt td                      scan the current project
+  dkt td --tags FIXME BUG     only these tags
+  dkt td --json               machine-readable
+"""
+
+DEFAULT_TAGS = ["TODO", "FIXME", "HACK", "XXX", "BUG", "OPTIMIZE", "NOTE"]
+TAG_COLOR = {"TODO": "bcyan", "FIXME": "bred", "BUG": "bred", "HACK": "byellow", "XXX": "byellow",
+             "OPTIMIZE": "bmagenta", "NOTE": "bgreen"}
+
+
+def run(args) -> int:
+    folder = resolve_folder(args.folder)
+    tags = [t.upper() for t in (args.tags or DEFAULT_TAGS)]
+    rx = re.compile(r"(?:#|//|/\*|<!--|--|;|\*|%)\s*(?:@)?\b(" + "|".join(map(re.escape, tags)) + r")\b[\s:(\-]*(.*)", re.I)
+    found = []
+    for rel in list_project_files(folder):
+        p = folder / rel
+        try:
+            if p.stat().st_size > 1_000_000:
+                continue
+            raw = p.read_bytes()
+        except OSError:
+            continue
+        if is_binary_chunk(raw[:4096]):
+            continue
+        for i, line in enumerate(raw.decode("utf-8", errors="replace").splitlines(), 1):
+            m = rx.search(line)
+            if m:
+                found.append({"file": str(rel).replace("\\", "/"), "line": i,
+                              "tag": m.group(1).upper(), "text": m.group(2).strip(" */-->")[:120]})
+    if args.json:
+        print(json.dumps(found, indent=2))
+        return 0
+    if not found:
+        print("  %s nothing to do - no %s found" % (c(sym("ok"), "bgreen"), "/".join(tags[:3])))
+        return 0
+    cur = None
+    for f in found:
+        if f["file"] != cur:
+            cur = f["file"]
+            print("\n  " + c(cur, "bold underline"))
+        print("   %s %s  %s" % (c(str(f["line"]).rjust(5), "gray"), c(f["tag"].ljust(8), TAG_COLOR.get(f["tag"], "white")), f["text"]))
+    counts = Counter(f["tag"] for f in found)
+    print("\n  " + "  ".join("%s %s" % (c(human_num(n), "bold"), t) for t, n in counts.most_common()))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("todo", aliases=["td"], parents=[common], help=META[3],
+                       description="Find TODO-style comments in your project (respects .gitignore).",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("-f", "--folder", metavar="PATH")
+    p.add_argument("--tags", nargs="+", metavar="TAG")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

devkittools/tools/tree.py

@@ -0,0 +1,86 @@
+"""dkt tree (tr) - a pretty directory tree that respects .gitignore."""
+from __future__ import annotations
+
+import argparse
+from collections import defaultdict
+from pathlib import Path
+
+from ..utils import c, human_size, list_project_files, resolve_folder, sym
+
+META = ("Project & Code", "tree", "tr", "pretty directory tree with sizes, respects .gitignore")
+
+EPILOG = """\
+examples:
+  dkt tr                  tree of the current project
+  dkt tr -d 2             only two levels deep
+  dkt tr --sizes          show file sizes
+  dkt tr --dirs           directories only
+  dkt tr src --copy       copy the tree to the clipboard (great for docs / AI prompts)
+"""
+
+ICONS = {".py": "bgreen", ".js": "byellow", ".ts": "bblue", ".json": "yellow", ".md": "bcyan",
+         ".html": "bred", ".css": "bmagenta", ".bat": "gray", ".toml": "yellow", ".yml": "yellow", ".yaml": "yellow"}
+
+
+def run(args) -> int:
+    root = resolve_folder(args.folder)
+    files = list_project_files(root)
+    tree = defaultdict(lambda: {"dirs": set(), "files": []})
+    for f in files:
+        parts = f.parts
+        for i in range(len(parts) - 1):
+            tree[Path(*parts[:i]) if i else Path(".")]["dirs"].add(parts[i])
+        tree[f.parent if len(parts) > 1 else Path(".")]["files"].append(f.name)
+    plain = []
+    out = []
+    counts = [0, 0]
+    T, L, P = sym("t") + sym("h") * 2 + " ", sym("l") + sym("h") * 2 + " ", sym("pipe") + "   "
+
+    def walk(rel: Path, prefix: str, depth: int):
+        node = tree.get(rel, {"dirs": set(), "files": []})
+        entries = [(d, True) for d in sorted(node["dirs"], key=str.lower)]
+        if not args.dirs:
+            entries += [(f, False) for f in sorted(node["files"], key=str.lower)]
+        for i, (name, is_dir) in enumerate(entries):
+            last = i == len(entries) - 1
+            branch = L if last else T
+            if is_dir:
+                counts[0] += 1
+                out.append(prefix + c(branch, "gray") + c(name + "/", "bold bblue"))
+                plain.append(prefix + branch + name + "/")
+                if args.depth is None or depth < args.depth:
+                    walk(rel / name if str(rel) != "." else Path(name), prefix + ("    " if last else P), depth + 1)
+            else:
+                counts[1] += 1
+                size = ""
+                if args.sizes:
+                    try:
+                        size = "  " + human_size((root / (rel / name)).stat().st_size)
+                    except OSError:
+                        size = ""
+                col = ICONS.get(Path(name).suffix.lower(), "white")
+                out.append(prefix + c(branch, "gray") + c(name, col) + c(size, "gray"))
+                plain.append(prefix + branch + name + size)
+
+    out.append(c(root.name + "/", "bold bmagenta"))
+    plain.append(root.name + "/")
+    walk(Path("."), "", 1)
+    print("\n".join(out))
+    print(c("\n  %d directories, %d files" % tuple(counts), "gray"))
+    if args.copy:
+        from ..utils import copy_to_clipboard, info
+        if copy_to_clipboard("\n".join(plain)):
+            info(c(sym("ok") + " copied to clipboard", "green"))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("tree", aliases=["tr"], parents=[common], help=META[3],
+                       description="Show a directory tree (git-ignored files and junk folders are skipped).",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("folder", nargs="?")
+    p.add_argument("-d", "--depth", type=int, metavar="N")
+    p.add_argument("--sizes", action="store_true")
+    p.add_argument("--dirs", action="store_true", help="directories only")
+    p.add_argument("--copy", action="store_true")
+    p.set_defaults(func=run)

devkittools/tools/watch.py

@@ -0,0 +1,82 @@
+"""dkt watch (w) - re-run a command whenever files change."""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import time
+
+from ..utils import DktError, c, list_project_files, resolve_folder, sym
+
+META = ("Project & Code", "watch", "w", "re-run any command when files change")
+
+EPILOG = """\
+examples:
+  dkt w -c "pytest -q"                    run tests on every save
+  dkt w -c "npm run build" --ext .js .ts
+  dkt w -c "python main.py" --clear --debounce 0.5
+  dkt w -c "make" -f src --interval 0.3
+"""
+
+
+def snapshot(root, exts):
+    snap = {}
+    for rel in list_project_files(root):
+        if exts and not str(rel).lower().endswith(exts):
+            continue
+        try:
+            st = (root / rel).stat()
+            snap[str(rel)] = (st.st_mtime_ns, st.st_size)
+        except OSError:
+            pass
+    return snap
+
+
+def run(args) -> int:
+    root = resolve_folder(args.folder)
+    exts = tuple(e if e.startswith(".") else "." + e for e in args.ext) if args.ext else None
+    if not args.command:
+        raise DktError('Tell me what to run, e.g. dkt w -c "pytest -q"')
+    prev = snapshot(root, exts)
+    runs = 0
+
+    def execute(reason: str):
+        nonlocal runs
+        runs += 1
+        if args.clear:
+            os.system("cls" if os.name == "nt" else "clear")
+        print("%s %s  %s" % (c(sym("arrow"), "bcyan"), c(time.strftime("%H:%M:%S"), "gray"), c(args.command, "bold")))
+        if reason:
+            print(c("  changed: " + reason, "gray"))
+        t0 = time.time()
+        rc = subprocess.call(args.command, shell=True, cwd=str(root))
+        dt = time.time() - t0
+        col, mark = ("bgreen", sym("ok")) if rc == 0 else ("bred", sym("fail"))
+        print("%s %s\n" % (c(mark + " exit %d" % rc, col), c("(%.2fs) waiting for changes... Ctrl+C to stop" % dt, "gray")))
+
+    execute("")
+    try:
+        while True:
+            time.sleep(args.interval)
+            cur = snapshot(root, exts)
+            if cur != prev:
+                changed = [k for k in set(cur) | set(prev) if cur.get(k) != prev.get(k)]
+                time.sleep(args.debounce)
+                prev = snapshot(root, exts)
+                execute(", ".join(sorted(changed)[:3]) + (" ..." if len(changed) > 3 else ""))
+    except KeyboardInterrupt:
+        print("\n  stopped after %d run%s." % (runs, "" if runs == 1 else "s"))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("watch", aliases=["w"], parents=[common], help=META[3],
+                       description="Watch a folder and re-run a command on changes (no dependencies).",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("-c", "--command", metavar="CMD", help="command to run")
+    p.add_argument("-f", "--folder", metavar="PATH", help="folder to watch (default: current)")
+    p.add_argument("--ext", nargs="+", metavar="EXT", help="only react to these extensions")
+    p.add_argument("--interval", type=float, default=0.7, help="poll seconds (default 0.7)")
+    p.add_argument("--debounce", type=float, default=0.3, help="settle time after a change")
+    p.add_argument("--clear", action="store_true", help="clear the screen before each run")
+    p.set_defaults(func=run)