klok-cli 1.0.0__py3-none-any.whl

klok/config.py

@@ -0,0 +1,162 @@
+"""Configuration and on-disk locations.
+
+Everything klok keeps lives under a single data directory so a whole
+install can be backed up, synced or version-controlled by copying one
+folder.  ``KLOK_HOME`` overrides it, which is also what the test-suite
+uses to stay away from real data.
+"""
+
+import configparser
+import os
+from pathlib import Path
+
+DEFAULTS = {
+    "general": {
+        # Project used by `klok start` when none is given.
+        "default_project": "",
+        # monday or sunday - drives :week and the week charts.
+        "week_start": "monday",
+        # Round durations to a multiple of this many minutes in reports (0 = off).
+        "round": "0",
+        # 24 or 12 hour clock in rendered output.
+        "time_format": "24",
+        # Stop a running frame automatically when a new one is started.
+        "autostop": "true",
+        # auto, always or never.
+        "color": "auto",
+        # Overrides $VISUAL / $EDITOR for `klok edit`.
+        "editor": "",
+        # Refuse to create a project that has never been seen before.
+        "confirm_new_project": "false",
+    },
+    "exclusions": {
+        # Hours considered "working hours"; `klok gaps` ignores anything outside.
+        "hours": "",
+        # Days that are never expected to hold tracked time.
+        "days": "",
+        # Comma separated YYYY-MM-DD dates treated like excluded days.
+        "holidays": "",
+    },
+    "mindful": {
+        # Practice is recorded here so it never lands in a client's report.
+        "project": "mindfulness",
+        "sheet": "wellbeing",
+        "track": "true",
+        # Default breathing pattern and length.
+        "pattern": "box",
+        "breath_rounds": "6",
+        # Default sit, and how often the interval bell rings during it.
+        "default_sit": "10m",
+        "interval_bell": "",
+        "warmup": "",
+        "guidance": "true",
+        # `klok status` suggests a pause once a stretch of work runs this long.
+        "break_after": "90m",
+    },
+    "focus": {
+        "work": "25m",
+        "break": "5m",
+        "long_break": "15m",
+        "rounds": "4",
+        "notify": "true",
+        "bell": "true",
+        # Record focus sessions as tracked frames.
+        "track": "true",
+    },
+}
+
+TRUTHY = {"1", "true", "yes", "on", "y"}
+
+
+def data_home() -> Path:
+    """Directory holding frames, state, config and the undo stack."""
+    env = os.environ.get("KLOK_HOME")
+    if env:
+        return Path(env).expanduser()
+    xdg = os.environ.get("XDG_DATA_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".local" / "share"
+    return base / "klok"
+
+
+class Config:
+    def __init__(self, home: Path = None):
+        self.home = Path(home) if home else data_home()
+        self.path = self.home / "config.ini"
+        self._parser = configparser.ConfigParser()
+        self._parser.read_dict(DEFAULTS)
+        if self.path.exists():
+            self._parser.read(self.path, encoding="utf-8")
+
+    # -- paths ---------------------------------------------------------
+    @property
+    def frames_path(self) -> Path:
+        return self.home / "frames.jsonl"
+
+    @property
+    def state_path(self) -> Path:
+        return self.home / "state.json"
+
+    @property
+    def undo_path(self) -> Path:
+        return self.home / "undo.jsonl"
+
+    @property
+    def checkins_path(self) -> Path:
+        return self.home / "checkins.jsonl"
+
+    def ensure_home(self) -> None:
+        self.home.mkdir(parents=True, exist_ok=True)
+
+    # -- values --------------------------------------------------------
+    def get(self, key: str, fallback=None):
+        section, _, option = key.partition(".")
+        if not option:
+            raise KeyError("config keys look like 'section.option', got %r" % key)
+        try:
+            return self._parser.get(section, option)
+        except (configparser.NoSectionError, configparser.NoOptionError):
+            return fallback
+
+    def get_bool(self, key: str, fallback: bool = False) -> bool:
+        raw = self.get(key)
+        if raw is None or raw == "":
+            return fallback
+        return str(raw).strip().lower() in TRUTHY
+
+    def get_int(self, key: str, fallback: int = 0) -> int:
+        raw = self.get(key)
+        try:
+            return int(str(raw).strip())
+        except (TypeError, ValueError):
+            return fallback
+
+    def get_list(self, key: str):
+        raw = self.get(key) or ""
+        return [part.strip() for part in raw.split(",") if part.strip()]
+
+    def set(self, key: str, value: str) -> None:
+        section, _, option = key.partition(".")
+        if not option:
+            raise KeyError("config keys look like 'section.option', got %r" % key)
+        if not self._parser.has_section(section):
+            self._parser.add_section(section)
+        self._parser.set(section, option, value)
+
+    def unset(self, key: str) -> bool:
+        section, _, option = key.partition(".")
+        try:
+            return self._parser.remove_option(section, option)
+        except configparser.NoSectionError:
+            return False
+
+    def items(self):
+        for section in sorted(self._parser.sections()):
+            for option, value in sorted(self._parser.items(section)):
+                yield "%s.%s" % (section, option), value
+
+    def save(self) -> None:
+        self.ensure_home()
+        tmp = self.path.with_suffix(".ini.tmp")
+        with tmp.open("w", encoding="utf-8") as handle:
+            self._parser.write(handle)
+        os.replace(tmp, self.path)

klok/focus.py

@@ -0,0 +1,169 @@
+"""Countdown timers, pomodoro rounds and desktop notifications.
+
+This is the part that covers the "minimal timer" tools - a visible
+countdown, a big clock, a nudge when the time is up - and it feeds the
+same frame store as everything else so focus sessions show up in reports.
+"""
+
+import shutil
+import subprocess
+import sys
+import time
+from datetime import timedelta
+
+from klok.timeparse import format_duration
+from klok.utils import bar
+
+BIG_DIGITS = {
+    "0": ["█▀▀█", "█  █", "█  █", "█  █", "█▄▄█"],
+    "1": ["  ▀█", "   █", "   █", "   █", "   █"],
+    "2": ["█▀▀█", "   █", " ▄▀ ", "▄▀  ", "█▄▄▄"],
+    "3": ["█▀▀█", "   █", " ▀▀▄", "   █", "█▄▄█"],
+    "4": ["█  █", "█  █", "█▄▄█", "   █", "   █"],
+    "5": ["█▀▀▀", "█▄▄ ", "   █", "   █", "▀▄▄▀"],
+    "6": ["█▀▀▀", "█   ", "█▀▀█", "█  █", "█▄▄█"],
+    "7": ["▀▀▀█", "   █", "  ▄▀", " ▄▀ ", "▄▀  "],
+    "8": ["█▀▀█", "█  █", "█▄▄█", "█  █", "█▄▄█"],
+    "9": ["█▀▀█", "█  █", "▀▀▀█", "   █", "▄▄▄█"],
+    ":": ["    ", " ██ ", "    ", " ██ ", "    "],
+    " ": ["    ", "    ", "    ", "    ", "    "],
+}
+
+ART = {
+    "coffee": [
+        "        (  )   (   )  )",
+        "         ) (   )  (  (",
+        "         ( )  (    ) )",
+        "         _____________",
+        "        <_____________> ___",
+        "        |             |/ _ \\",
+        "        |               | | |",
+        "        |               |_| |",
+        "     ___|             |\\___/",
+        "    /    \\___________/    \\",
+        "    \\_____________________/",
+    ],
+    "tree": [
+        "         &&& &&  & &&",
+        "     && &\\/&\\|& ()|/ @, &&",
+        "     &\\/(/&/&||/& /_/)_&/_&",
+        "  &() &\\/&|()|/&\\/ '%\" & ()",
+        " &_\\_&&_\\ |& |&&/&__%_/_& &&",
+        "&&   && & &| &| /& & % ()& /&&",
+        "          |||   |||",
+    ],
+    "cat": [
+        "     /\\_/\\",
+        "    ( o.o )",
+        "     > ^ <",
+    ],
+    "none": [],
+}
+
+
+def notify(title: str, message: str, enabled: bool = True, bell: bool = True) -> None:
+    """Best-effort desktop notification; never fails the command."""
+    if bell:
+        try:
+            sys.stdout.write("\a")
+            sys.stdout.flush()
+        except Exception:
+            pass
+    if not enabled:
+        return
+    commands = []
+    if shutil.which("notify-send"):
+        commands.append(["notify-send", title, message])
+    if shutil.which("terminal-notifier"):
+        commands.append(["terminal-notifier", "-title", title, "-message", message])
+    if sys.platform == "darwin" and shutil.which("osascript"):
+        script = 'display notification "%s" with title "%s"' % (
+            message.replace('"', "'"), title.replace('"', "'"))
+        commands.append(["osascript", "-e", script])
+    if sys.platform.startswith("win") and shutil.which("powershell"):
+        commands.append(["powershell", "-NoProfile", "-Command",
+                         "[console]::beep(880,300); Write-Host '%s: %s'" % (title, message)])
+    for command in commands:
+        try:
+            subprocess.run(command, check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            return
+        except OSError:
+            continue
+
+
+def big_clock(text: str) -> str:
+    """Render ``MM:SS`` in block characters, arttime style."""
+    rows = ["" for _ in range(5)]
+    for char in text:
+        glyph = BIG_DIGITS.get(char, BIG_DIGITS[" "])
+        for index in range(5):
+            rows[index] += glyph[index] + " "
+    return "\n".join(row.rstrip() for row in rows)
+
+
+def _clock_text(remaining: timedelta) -> str:
+    total = max(0, int(remaining.total_seconds()))
+    hours, rest = divmod(total, 3600)
+    minutes, seconds = divmod(rest, 60)
+    if hours:
+        return "%d:%02d:%02d" % (hours, minutes, seconds)
+    return "%02d:%02d" % (minutes, seconds)
+
+
+def countdown(duration: timedelta, label: str, term, art: str = None,
+              big: bool = False, quiet: bool = False, notify_on_end: bool = True,
+              bell: bool = True, stream=None) -> bool:
+    """Run a countdown.  Returns False when the user interrupts it."""
+    stream = stream or sys.stdout
+    total_seconds = max(1, int(duration.total_seconds()))
+    started = time.monotonic()
+    art_lines = ART.get(art or "", []) if art else []
+    interactive = bool(getattr(stream, "isatty", lambda: False)()) and not quiet
+    drawn_lines = 0
+
+    try:
+        while True:
+            elapsed = time.monotonic() - started
+            remaining = timedelta(seconds=max(0, total_seconds - int(elapsed)))
+            if interactive:
+                block = []
+                if art_lines:
+                    block.extend(art_lines)
+                    block.append("")
+                if big:
+                    block.extend(big_clock(_clock_text(remaining)).splitlines())
+                    block.append("")
+                width = min(40, max(20, term.width() - 30))
+                block.append("%s  %s  %s" % (
+                    term.paint(label, "bold"),
+                    term.paint(bar(total_seconds - remaining.total_seconds(), total_seconds, width), "cyan"),
+                    term.paint(_clock_text(remaining), "yellow")))
+                if drawn_lines:
+                    stream.write("\033[%dA" % drawn_lines)
+                for line in block:
+                    stream.write("\033[2K" + line + "\n")
+                drawn_lines = len(block)
+                stream.flush()
+            if remaining.total_seconds() <= 0:
+                break
+            time.sleep(min(1.0, max(0.05, total_seconds - elapsed)))
+    except KeyboardInterrupt:
+        if interactive:
+            stream.write("\n")
+        return False
+
+    if not interactive and not quiet:
+        stream.write("%s finished (%s)\n" % (label, format_duration(duration)))
+    notify("klok", "%s finished (%s)" % (label, format_duration(duration)),
+           enabled=notify_on_end, bell=bell)
+    return True
+
+
+def pomodoro_plan(rounds: int, work: timedelta, short_break: timedelta, long_break: timedelta):
+    """Yield ``(kind, label, duration)`` for a full pomodoro cycle."""
+    for index in range(1, rounds + 1):
+        yield ("work", "Focus %d/%d" % (index, rounds), work)
+        if index == rounds:
+            yield ("long_break", "Long break", long_break)
+        else:
+            yield ("break", "Break %d" % index, short_break)

klok/formats.py

@@ -0,0 +1,169 @@
+"""Machine-readable output: JSON, CSV, iCalendar, ledger timeclock, Markdown.
+
+These are what let klok hand its data to a spreadsheet, an invoicing
+script or ``hledger`` without anyone writing a parser.
+"""
+
+import csv
+import io
+import json
+from datetime import timedelta
+
+from klok.model import Frame
+from klok.timeparse import format_duration, to_iso
+
+FORMATS = ("text", "json", "csv", "ical", "ledger", "timeclock", "md", "tsv")
+
+
+def _rows(frames, now):
+    for frame in frames:
+        end = frame.end_or(now)
+        yield {
+            "id": frame.id,
+            "sheet": frame.sheet,
+            "project": frame.project,
+            "tags": frame.tags,
+            "note": frame.note,
+            "start": to_iso(frame.start),
+            "stop": to_iso(frame.stop) if frame.stop else "",
+            "running": frame.running,
+            "seconds": int((end - frame.start).total_seconds()),
+            "hours": round((end - frame.start).total_seconds() / 3600.0, 4),
+        }
+
+
+def to_json(frames, now, indent: int = 2) -> str:
+    return json.dumps(list(_rows(frames, now)), indent=indent, ensure_ascii=False)
+
+
+def to_csv(frames, now, delimiter: str = ",") -> str:
+    buffer = io.StringIO()
+    fields = ["id", "sheet", "project", "tags", "note", "start", "stop", "seconds", "hours"]
+    writer = csv.DictWriter(buffer, fieldnames=fields, delimiter=delimiter, lineterminator="\n")
+    writer.writeheader()
+    for row in _rows(frames, now):
+        row = dict(row)
+        row["tags"] = " ".join(row["tags"])
+        row.pop("running", None)
+        writer.writerow(row)
+    return buffer.getvalue().rstrip("\n")
+
+
+def to_ical(frames, now) -> str:
+    def stamp(value):
+        return value.astimezone().strftime("%Y%m%dT%H%M%S")
+
+    lines = ["BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//klok//EN", "CALSCALE:GREGORIAN"]
+    for frame in frames:
+        summary = frame.project or "(no project)"
+        if frame.tags:
+            summary += " " + " ".join("+" + tag for tag in frame.tags)
+        lines += [
+            "BEGIN:VEVENT",
+            "UID:%s@klok" % frame.id,
+            "DTSTART:%s" % stamp(frame.start),
+            "DTEND:%s" % stamp(frame.end_or(now)),
+            "SUMMARY:%s" % _escape_ical(summary),
+        ]
+        if frame.note:
+            lines.append("DESCRIPTION:%s" % _escape_ical(frame.note))
+        lines.append("END:VEVENT")
+    lines.append("END:VCALENDAR")
+    return "\n".join(lines)
+
+
+def _escape_ical(text: str) -> str:
+    return text.replace("\\", "\\\\").replace(";", "\;").replace(",", "\\,").replace("\n", "\\n")
+
+
+def to_timeclock(frames, now) -> str:
+    """The ``i``/``o`` timeclock format ledger and hledger read natively."""
+    lines = []
+    for frame in frames:
+        account = frame.project or "unsorted"
+        if frame.tags:
+            account += ":" + ":".join(frame.tags)
+        lines.append("i %s %s%s" % (frame.start.strftime("%Y/%m/%d %H:%M:%S"), account,
+                                    ("  " + frame.note) if frame.note else ""))
+        lines.append("o %s" % frame.end_or(now).strftime("%Y/%m/%d %H:%M:%S"))
+    return "\n".join(lines)
+
+
+def to_ledger(frames, now) -> str:
+    """Postings with hour amounts, one transaction per entry."""
+    lines = []
+    for frame in frames:
+        hours = (frame.end_or(now) - frame.start).total_seconds() / 3600.0
+        payee = frame.note or frame.project or "time"
+        lines.append("%s * %s" % (frame.start.strftime("%Y/%m/%d"), payee))
+        account = (frame.project or "unsorted").replace(".", ":")
+        lines.append("    %s  %.2fh" % (account, hours))
+        lines.append("    (%s)" % frame.sheet)
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def to_markdown(frames, now) -> str:
+    lines = ["| Date | Start | End | Project | Tags | Note | Duration |",
+             "| --- | --- | --- | --- | --- | --- | --- |"]
+    total = timedelta(0)
+    for frame in frames:
+        length = frame.end_or(now) - frame.start
+        total += length
+        lines.append("| %s | %s | %s | %s | %s | %s | %s |" % (
+            frame.start.strftime("%Y-%m-%d"),
+            frame.start.strftime("%H:%M"),
+            frame.stop.strftime("%H:%M") if frame.stop else "running",
+            frame.project or "",
+            " ".join("+" + tag for tag in frame.tags),
+            frame.note.replace("|", "\\|"),
+            format_duration(length),
+        ))
+    lines.append("")
+    lines.append("**Total: %s**" % format_duration(total))
+    return "\n".join(lines)
+
+
+def render(frames, now, fmt: str) -> str:
+    fmt = (fmt or "json").lower()
+    if fmt == "json":
+        return to_json(frames, now)
+    if fmt == "csv":
+        return to_csv(frames, now)
+    if fmt == "tsv":
+        return to_csv(frames, now, delimiter="\t")
+    if fmt == "ical":
+        return to_ical(frames, now)
+    if fmt == "timeclock":
+        return to_timeclock(frames, now)
+    if fmt == "ledger":
+        return to_ledger(frames, now)
+    if fmt in ("md", "markdown"):
+        return to_markdown(frames, now)
+    raise ValueError("unknown format %r (pick one of %s)" % (fmt, ", ".join(FORMATS)))
+
+
+def parse_import(text: str):
+    """Read frames from JSON, JSONL or CSV produced by klok or a sibling tool."""
+    text = text.strip()
+    if not text:
+        return []
+    if text.startswith("["):
+        return [Frame.from_dict(item) for item in json.loads(text)]
+    if text.startswith("{"):
+        return [Frame.from_dict(json.loads(line)) for line in text.splitlines() if line.strip()]
+    reader = csv.DictReader(io.StringIO(text))
+    frames = []
+    for row in reader:
+        if not row.get("start"):
+            continue
+        frames.append(Frame.from_dict({
+            "id": row.get("id"),
+            "start": row["start"],
+            "stop": row.get("stop") or row.get("end") or None,
+            "project": row.get("project", ""),
+            "tags": row.get("tags", ""),
+            "note": row.get("note", ""),
+            "sheet": row.get("sheet") or "default",
+        }))
+    return frames