commute-optimizer 1.1.0__py3-none-any.whl

commute/__main__.py

@@ -0,0 +1,76 @@
+"""CLI entry point: python -m commute {poll|report}"""
+
+import argparse
+
+
+def _version():
+    try:
+        from importlib.metadata import version
+        return version("commute-optimizer")
+    except Exception:  # running from a source checkout without install
+        return "dev"
+
+
+def main():
+    p = argparse.ArgumentParser(prog="commute",
+                                description="Track commute times and find the best departure time.")
+    p.add_argument("-c", "--config", help="Path to config.json (default: ./config.json)")
+    p.add_argument("--version", action="version", version=f"commute {_version()}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("init", help="Write an example config.json to the current directory")
+    pp = sub.add_parser("poll", help="Start the adaptive polling loop (Ctrl+C to stop)")
+    pp.add_argument("-d", "--duration",
+                    help="Auto-stop after this long and generate the report "
+                         "(e.g. 7d, 24h, 90m, 1d12h)")
+    pp.add_argument("--no-report", action="store_true",
+                    help="Don't auto-generate the report when the duration ends")
+    pp.add_argument("--until",
+                    help="Auto-stop at this ISO timestamp (what 'schedule' uses "
+                         "so the deadline survives reboots)")
+    rp = sub.add_parser("report", help="Analyze samples and generate report.html")
+    rp.add_argument("--no-open", action="store_true", help="Don't open the report in a browser")
+    wp = sub.add_parser("watch",
+                        help="Watch an in-progress run: regenerate the report and a "
+                             "day-by-day report on an interval")
+    wp.add_argument("-i", "--interval", default="15m",
+                    help="How often to regenerate (default 15m)")
+    wp.add_argument("--no-open", action="store_true",
+                    help="Don't open report-daily.html in a browser")
+    sp = sub.add_parser("schedule",
+                        help="Keep polling alive across sleep and reboots via a "
+                             "scheduled task (Windows)")
+    sp.add_argument("action", choices=["install", "remove", "status"])
+    sp.add_argument("-d", "--duration",
+                    help="With install: stop polling this long from now and "
+                         "generate the report (e.g. 7d)")
+    sub.add_parser("check", help="Preflight: verify config, API key, DB, and live API access")
+    sub.add_parser("demo", help="Seed the DB with a synthetic week of two-direction data")
+    args = p.parse_args()
+
+    if args.cmd == "init":
+        from .config import init_config
+        init_config(args.config)
+    elif args.cmd == "poll":
+        from . import poller
+        poller.run(args.config, duration=args.duration,
+                   report_on_end=not args.no_report, until=args.until)
+    elif args.cmd == "schedule":
+        from . import schedule
+        schedule.run(args.action, args.config, args.duration)
+    elif args.cmd == "watch":
+        from . import watch
+        watch.run(args.config, interval=args.interval,
+                  open_browser=not args.no_open)
+    elif args.cmd == "check":
+        from . import check
+        raise SystemExit(check.run(args.config))
+    elif args.cmd == "demo":
+        from . import demo
+        demo.run(args.config)
+    else:
+        from . import report
+        report.run(args.config, open_browser=not args.no_open)
+
+
+if __name__ == "__main__":
+    main()

commute/check.py

@@ -0,0 +1,84 @@
+"""Preflight check: validate config, API key, database, and make one real
+Routes API call per direction before committing to a week-long run."""
+
+from datetime import datetime, timedelta
+
+from . import db
+from .config import load_api_key, load_config
+from .poller import current_interval, fetch_route
+
+
+def _estimate_calls_per_day(cfg):
+    """Walk a synthetic day in 1-minute steps and count when a poll would fire."""
+    calls = 0
+    t = datetime(2026, 1, 5, 0, 0)  # any Monday; only time-of-day matters
+    next_poll = t
+    while t.date() == datetime(2026, 1, 5).date():
+        interval = current_interval(cfg, t)
+        if interval is not None and t >= next_poll:
+            calls += 1
+            next_poll = t + timedelta(seconds=interval)
+        t += timedelta(minutes=1)
+    return calls * (2 if cfg.get("track_both_directions", True) else 1)
+
+
+def run(config_path=None):
+    ok = True
+
+    # 1. config
+    try:
+        cfg = load_config(config_path)
+        print(f"[ok] config: {cfg['origin']!r} -> {cfg['destination']!r}")
+    except SystemExit as e:
+        print(f"[FAIL] config: {e}")
+        return 1
+
+    # 2. API key present
+    try:
+        api_key = load_api_key()
+        print(f"[ok] API key found ({api_key[:6]}...{api_key[-4:]})")
+    except SystemExit as e:
+        print(f"[FAIL] API key: {e}")
+        return 1
+
+    # 3. database writable
+    try:
+        conn = db.connect()
+        conn.execute("SELECT 1")
+        n = db.count_samples(conn)
+        conn.close()
+        print(f"[ok] database writable at {db.DB_PATH} ({n} existing samples)")
+        if n:
+            print("     note: existing samples will mix into the report — "
+                  "delete commute.db for a clean run.")
+    except Exception as e:
+        print(f"[FAIL] database: {e!r}")
+        ok = False
+
+    # 4. live API call per direction
+    directions = [("ab", cfg["origin"], cfg["destination"])]
+    if cfg.get("track_both_directions", True):
+        directions.append(("ba", cfg["destination"], cfg["origin"]))
+    for name, origin, destination in directions:
+        arrow = "->" if name == "ab" else "<-"
+        try:
+            r = fetch_route(api_key, origin, destination,
+                            cfg.get("travel_mode", "DRIVE"))
+            print(f"[ok] live route {arrow} {r['duration_s'] / 60:.1f} min now "
+                  f"(free-flow {r['static_duration_s'] / 60:.1f} min, "
+                  f"{r['distance_m'] / 1000:.1f} km)")
+        except Exception as e:
+            msg = getattr(e, "read", None)
+            detail = msg().decode(errors="replace")[:300] if msg else repr(e)
+            print(f"[FAIL] live route {arrow}: {detail}")
+            ok = False
+
+    # 5. quota estimate
+    per_day = _estimate_calls_per_day(cfg)
+    per_week = per_day * 7
+    print(f"[{'ok' if per_week < 9500 else 'WARN'}] estimated API usage: "
+          f"~{per_day}/day, ~{per_week}/week (free tier ~10,000/month)")
+
+    print("\nAll checks passed — ready for a long run."
+          if ok else "\nFix the failures above before starting a long run.")
+    return 0 if ok else 1

commute/config.example.json

@@ -0,0 +1,12 @@
+{
+  "origin": "1600 Amphitheatre Parkway, Mountain View, CA",
+  "destination": "1 Market St, San Francisco, CA",
+  "travel_mode": "DRIVE",
+  "track_both_directions": true,
+  "poll": {
+    "active_window": ["00:00", "23:59"],
+    "rush_windows": [["07:00", "10:00"], ["16:00", "19:00"]],
+    "rush_interval_min": 1,
+    "offpeak_interval_min": 10
+  }
+}

commute/config.py

@@ -0,0 +1,76 @@
+"""Load config.json and the API key from .env / environment."""
+
+import json
+import os
+from datetime import time
+from pathlib import Path
+
+# All data files (config.json, .env, commute.db, reports, poll.log/lock) live
+# in the directory you run the command from, so a pip-installed `commute` can
+# keep several tracking projects in separate folders.
+ROOT = Path.cwd()
+
+
+def _parse_hhmm(s):
+    h, m = s.split(":")
+    return time(int(h), int(m))
+
+
+def load_config(path=None):
+    path = Path(path) if path else ROOT / "config.json"
+    if not path.exists():
+        raise SystemExit(
+            f"Config not found at {path}. Copy config.example.json to config.json and edit it."
+        )
+    with open(path, encoding="utf-8") as f:
+        cfg = json.load(f)
+
+    poll = cfg.get("poll", {})
+    cfg["_active_window"] = tuple(
+        _parse_hhmm(s) for s in poll.get("active_window", ["00:00", "23:59"])
+    )
+    cfg["_rush_windows"] = [
+        tuple(_parse_hhmm(s) for s in w) for w in poll.get("rush_windows", [])
+    ]
+    cfg["_rush_interval"] = int(poll.get("rush_interval_min", 1)) * 60
+    cfg["_offpeak_interval"] = int(poll.get("offpeak_interval_min", 10)) * 60
+    return cfg
+
+
+def init_config(dest=None):
+    """Write the packaged example config to ./config.json (for `commute init`)."""
+    from importlib.resources import files
+    dest = Path(dest) if dest else ROOT / "config.json"
+    if dest.exists():
+        raise SystemExit(f"{dest} already exists — edit it instead.")
+    template = files("commute").joinpath("config.example.json").read_text(
+        encoding="utf-8")
+    dest.write_text(template, encoding="utf-8")
+    print(f"Wrote {dest}\nEdit the addresses, put GOOGLE_MAPS_API_KEY in a .env "
+          "file next to it, then run: commute check")
+
+
+def load_api_key():
+    key = os.environ.get("GOOGLE_MAPS_API_KEY")
+    if not key:
+        env_file = ROOT / ".env"
+        if env_file.exists():
+            for line in env_file.read_text(encoding="utf-8-sig").splitlines():
+                line = line.strip()
+                if line.startswith("GOOGLE_MAPS_API_KEY="):
+                    key = line.split("=", 1)[1].strip().strip('"').strip("'")
+                    break
+    if not key:
+        raise SystemExit(
+            "No API key. Set GOOGLE_MAPS_API_KEY in the environment or in a .env file "
+            "(GOOGLE_MAPS_API_KEY=your-key)."
+        )
+    return key
+
+
+def in_window(t, window):
+    """True if time t falls inside (start, end), handling overnight windows."""
+    start, end = window
+    if start <= end:
+        return start <= t <= end
+    return t >= start or t <= end

commute/db.py

@@ -0,0 +1,65 @@
+"""SQLite storage for commute samples."""
+
+import sqlite3
+
+from .config import ROOT
+
+DB_PATH = ROOT / "commute.db"
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS samples (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts_utc TEXT NOT NULL,
+    ts_local TEXT NOT NULL,
+    direction TEXT NOT NULL DEFAULT 'ab', -- 'ab' = origin->destination, 'ba' = reverse
+    weekday INTEGER NOT NULL,             -- 0 = Monday
+    minute_of_day INTEGER NOT NULL,       -- local time, 0..1439
+    duration_s INTEGER,                   -- traffic-aware travel time
+    static_duration_s INTEGER,            -- free-flow travel time
+    distance_m INTEGER,
+    error TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_samples_dir_wd_min
+    ON samples(direction, weekday, minute_of_day);
+"""
+
+
+def connect(path=None):
+    # timeout so readers (report/watch) wait out the poller's brief write locks
+    conn = sqlite3.connect(path or DB_PATH, timeout=15)
+    conn.executescript(SCHEMA)
+    return conn
+
+
+def insert_sample(conn, row, commit=True):
+    conn.execute(
+        """INSERT INTO samples
+           (ts_utc, ts_local, direction, weekday, minute_of_day, duration_s,
+            static_duration_s, distance_m, error)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+        (
+            row["ts_utc"], row["ts_local"], row.get("direction", "ab"),
+            row["weekday"], row["minute_of_day"],
+            row.get("duration_s"), row.get("static_duration_s"),
+            row.get("distance_m"), row.get("error"),
+        ),
+    )
+    if commit:
+        conn.commit()
+
+
+def fetch_samples(conn, direction):
+    cur = conn.execute(
+        """SELECT ts_local, weekday, minute_of_day, duration_s
+           FROM samples WHERE duration_s IS NOT NULL AND direction = ?
+           ORDER BY ts_utc""",
+        (direction,),
+    )
+    return [
+        {"ts": r[0], "weekday": r[1], "minute": r[2], "duration_s": r[3]}
+        for r in cur.fetchall()
+    ]
+
+
+def count_samples(conn):
+    return conn.execute("SELECT COUNT(*) FROM samples").fetchone()[0]

commute/demo.py

@@ -0,0 +1,79 @@
+"""Seed the database with a synthetic week of two-direction commute data,
+so the report can be previewed without polling for a week."""
+
+import math
+import random
+from datetime import datetime, timedelta
+
+from . import db
+from .config import load_config
+
+
+def _bump(minute, center, width, amp):
+    """Gaussian traffic bump in minutes of extra delay."""
+    return amp * math.exp(-(((minute - center) / width) ** 2))
+
+
+def synth_duration(direction, weekday, minute, rng):
+    """Plausible drive time (seconds) for a suburb<->city commute."""
+    weekend = weekday >= 5
+    if direction == "ab":  # home -> work: morning peak
+        base = 28.0
+        if not weekend:
+            delay = _bump(minute, 8 * 60 + 15, 55, 24)   # AM peak ~8:15
+            delay += _bump(minute, 17 * 60 + 30, 70, 7)  # light PM echo
+            if weekday == 4:                              # Friday AM is lighter
+                delay *= 0.8
+        else:
+            delay = _bump(minute, 12 * 60, 150, 6)        # midday weekend bump
+    else:  # work -> home: evening peak
+        base = 29.0
+        if not weekend:
+            delay = _bump(minute, 17 * 60 + 30, 60, 26)  # PM peak ~17:30
+            delay += _bump(minute, 8 * 60 + 15, 70, 6)
+            if weekday == 4:                              # Friday PM starts earlier
+                delay = _bump(minute, 16 * 60 + 30, 75, 28)
+        else:
+            delay = _bump(minute, 12 * 60, 150, 6)
+    total = base + delay + rng.gauss(0, 1.5)
+    if rng.random() < 0.01:  # occasional incident
+        total += rng.uniform(8, 25)
+    return int(max(base * 0.9, total) * 60)
+
+
+def run(config_path=None):
+    cfg = load_config(config_path)
+    conn = db.connect()
+    if db.count_samples(conn) > 0:
+        raise SystemExit(
+            "commute.db already contains samples — refusing to mix demo data with "
+            "real data. Delete commute.db first if you want a fresh demo."
+        )
+    rng = random.Random(42)
+    start = datetime(2026, 6, 29, 0, 0)  # a Monday
+    rush = cfg["_rush_windows"]
+    n = 0
+    for day in range(7):
+        t = start + timedelta(days=day)
+        end_of_day = t + timedelta(days=1)
+        while t < end_of_day:
+            minute = t.hour * 60 + t.minute
+            in_rush = any(w[0] <= t.time() <= w[1] for w in rush)
+            for direction in ("ab", "ba"):
+                dur = synth_duration(direction, t.weekday(), minute, rng)
+                db.insert_sample(conn, {
+                    "ts_utc": t.isoformat(timespec="seconds"),
+                    "ts_local": t.isoformat(timespec="seconds"),
+                    "direction": direction,
+                    "weekday": t.weekday(),
+                    "minute_of_day": minute,
+                    "duration_s": dur,
+                    "static_duration_s": int((28 if direction == "ab" else 29) * 60),
+                    "distance_m": 31000,
+                }, commit=False)
+                n += 1
+            t += timedelta(minutes=1 if in_rush else 10)
+    conn.commit()
+    conn.close()
+    print(f"Seeded {n} demo samples (one synthetic week, both directions).")
+    print("Now run: commute report")

commute/poller.py

@@ -0,0 +1,199 @@
+"""Poll the Google Routes API on an adaptive schedule and store samples."""
+
+import json
+import os
+import sys
+import time as time_mod
+import urllib.error
+import urllib.request
+from datetime import datetime, timedelta, timezone
+
+from . import db
+from .config import ROOT, in_window, load_api_key, load_config
+
+ROUTES_URL = "https://routes.googleapis.com/directions/v2:computeRoutes"
+FIELD_MASK = "routes.duration,routes.staticDuration,routes.distanceMeters"
+RETRY_DELAYS = (5, 15, 45)  # seconds between attempts on transient failures
+LOCK_PATH = ROOT / "poll.lock"
+LOG_PATH = ROOT / "poll.log"
+
+
+def fetch_route(api_key, origin, destination, travel_mode="DRIVE"):
+    """One traffic-aware route request. Returns dict or raises."""
+    body = {
+        "origin": {"address": origin},
+        "destination": {"address": destination},
+        "travelMode": travel_mode,
+        "routingPreference": "TRAFFIC_AWARE",
+    }
+    req = urllib.request.Request(
+        ROUTES_URL,
+        data=json.dumps(body).encode(),
+        headers={
+            "Content-Type": "application/json",
+            "X-Goog-Api-Key": api_key,
+            "X-Goog-FieldMask": FIELD_MASK,
+        },
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        data = json.load(resp)
+    route = data["routes"][0]
+    return {
+        "duration_s": int(route["duration"].rstrip("s").split(".")[0]),
+        "static_duration_s": int(route["staticDuration"].rstrip("s").split(".")[0]),
+        "distance_m": route.get("distanceMeters"),
+    }
+
+
+def _is_transient(e):
+    """Worth retrying? Rate limits and server/network errors, yes; a bad key
+    or malformed request (4xx) will fail the same way every time, no."""
+    if isinstance(e, urllib.error.HTTPError):
+        return e.code == 429 or e.code >= 500
+    return isinstance(e, (urllib.error.URLError, TimeoutError, OSError,
+                          json.JSONDecodeError, KeyError))
+
+
+def fetch_route_retrying(api_key, origin, destination, travel_mode="DRIVE"):
+    """fetch_route with backoff on transient failures. Raises the last error."""
+    for i, delay in enumerate((*RETRY_DELAYS, None)):
+        try:
+            return fetch_route(api_key, origin, destination, travel_mode)
+        except Exception as e:
+            if delay is None or not _is_transient(e):
+                raise
+            print(f"    transient error ({type(e).__name__}), "
+                  f"retry {i + 1}/{len(RETRY_DELAYS)} in {delay}s")
+            time_mod.sleep(delay)
+
+
+def current_interval(cfg, now):
+    t = now.time()
+    if not in_window(t, cfg["_active_window"]):
+        return None
+    for w in cfg["_rush_windows"]:
+        if in_window(t, w):
+            return cfg["_rush_interval"]
+    return cfg["_offpeak_interval"]
+
+
+def take_sample(conn, cfg, api_key):
+    directions = [("ab", cfg["origin"], cfg["destination"])]
+    if cfg.get("track_both_directions", True):
+        directions.append(("ba", cfg["destination"], cfg["origin"]))
+    for direction, origin, destination in directions:
+        now_utc = datetime.now(timezone.utc)
+        now = now_utc.astimezone()
+        row = {
+            "ts_utc": now_utc.isoformat(timespec="seconds"),
+            "ts_local": now.isoformat(timespec="seconds"),
+            "direction": direction,
+            "weekday": now.weekday(),
+            "minute_of_day": now.hour * 60 + now.minute,
+        }
+        arrow = "->" if direction == "ab" else "<-"
+        try:
+            row.update(fetch_route_retrying(api_key, origin, destination,
+                                            cfg.get("travel_mode", "DRIVE")))
+            mins = row["duration_s"] / 60
+            print(f"[{now:%a %H:%M:%S}] {arrow} {mins:.1f} min "
+                  f"(free-flow {row['static_duration_s'] / 60:.1f} min)")
+        except urllib.error.HTTPError as e:
+            row["error"] = f"HTTP {e.code}: {e.read().decode(errors='replace')[:500]}"
+            print(f"[{now:%a %H:%M:%S}] {arrow} ERROR {row['error']}")
+        except Exception as e:  # network blips shouldn't kill a week-long run
+            row["error"] = repr(e)
+            print(f"[{now:%a %H:%M:%S}] {arrow} ERROR {row['error']}")
+        db.insert_sample(conn, row)
+
+
+def parse_duration(s):
+    """'7d', '24h', '90m', or combinations like '1d12h' -> seconds."""
+    import re
+    parts = re.findall(r"(\d+(?:\.\d+)?)([dhm])", s.lower())
+    if not parts or "".join(f"{n}{u}" for n, u in parts) != s.lower():
+        raise SystemExit(f"Can't parse duration {s!r} — use e.g. 7d, 24h, 90m, 1d12h")
+    mult = {"d": 86400, "h": 3600, "m": 60}
+    return sum(float(n) * mult[u] for n, u in parts)
+
+
+def acquire_lock():
+    """Exclusive poll.lock so a second poller (e.g. a scheduled-task tick while
+    one is already running) exits instead of double-sampling. Returns the open
+    file to hold for the process lifetime, or None if another poller has it."""
+    f = open(LOCK_PATH, "a+", encoding="utf-8")
+    try:
+        if os.name == "nt":
+            import msvcrt
+            f.seek(0)
+            msvcrt.locking(f.fileno(), msvcrt.LK_NBLCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(f, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        f.close()
+        return None
+    f.seek(0)
+    f.truncate()
+    f.write(str(os.getpid()))
+    f.flush()
+    return f
+
+
+def run(config_path=None, duration=None, report_on_end=True, until=None):
+    if sys.stdout is None:  # pythonw.exe (scheduled task) — log to a file
+        sys.stdout = sys.stderr = open(LOG_PATH, "a", buffering=1,
+                                       encoding="utf-8")
+        print(f"\n--- poller started {datetime.now().astimezone():%Y-%m-%d %H:%M:%S} ---")
+    lock = acquire_lock()  # noqa: F841 — held (not used) until process exit
+    if lock is None:
+        print("Another poll is already running — exiting.")
+        return
+    cfg = load_config(config_path)
+    api_key = load_api_key()
+    conn = db.connect()
+    both = cfg.get("track_both_directions", True)
+    print(f"Polling {cfg['origin']!r} {'<->' if both else '->'} {cfg['destination']!r}")
+    print(f"Rush interval {cfg['_rush_interval'] // 60} min, "
+          f"off-peak {cfg['_offpeak_interval'] // 60} min. Ctrl+C to stop.")
+    deadline = None
+    if until is not None:
+        deadline = datetime.fromisoformat(until)
+        if datetime.now().astimezone() >= deadline:
+            # a scheduled task can keep ticking past its deadline; exit without
+            # re-generating (and re-opening) the report every time
+            print(f"Deadline {deadline:%Y-%m-%d %H:%M} already passed — exiting.")
+            return
+        print(f"Will stop automatically at {deadline:%Y-%m-%d %H:%M} "
+              f"and generate the report.")
+    elif duration is not None:
+        seconds = parse_duration(duration)
+        deadline = datetime.now().astimezone() + timedelta(seconds=seconds)
+        print(f"Will stop automatically at {deadline:%Y-%m-%d %H:%M} "
+              f"and generate the report.")
+    finished = False
+    try:
+        while True:
+            now = datetime.now().astimezone()
+            if deadline and now >= deadline:
+                finished = True
+                print(f"\nReached the scheduled stop time ({deadline:%Y-%m-%d %H:%M}).")
+                break
+            interval = current_interval(cfg, now)
+            if interval is None:
+                sleep_s = 60
+            else:
+                take_sample(conn, cfg, api_key)
+                elapsed = (datetime.now().astimezone() - now).total_seconds()
+                sleep_s = max(1, interval - elapsed)
+            if deadline:  # never sleep past the deadline
+                sleep_s = min(sleep_s, max(
+                    1, (deadline - datetime.now().astimezone()).total_seconds()))
+            time_mod.sleep(sleep_s)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+    finally:
+        conn.close()
+    if finished and report_on_end:
+        from . import report
+        report.run(config_path)