chrome-time-clock 0.1.0__tar.gz

chrome_time_clock-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maurice Frank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chrome_time_clock-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: chrome-time-clock
+Version: 0.1.0
+Summary: Infer workday start and end from Chrome, Chromium or Brave history, then plot or merge the hours.
+Author-email: Maurice Frank <maurice.frank@posteo.de>
+License: MIT
+Project-URL: Homepage, https://github.com/morris-frank/chrome-time-clock
+Project-URL: Issues, https://github.com/morris-frank/chrome-time-clock/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.5.0
+Dynamic: license-file
+
+<img src="brand/icon/icon-chrome-time-clock-on-obsidian-1024.png" align="left" width="128" hspace="16" alt="chrome-time-clock icon">
+
+<h3>chrome-time-clock</h3>
+
+<p>
+  <sub>YOUR BROWSER ALREADY KEPT THE TIMESHEET</sub>
+  <br>
+  <strong>Infer workday start and end from Chrome, Chromium or Brave history, then plot or merge the hours.</strong>
+  <br>
+  <br>
+  <a href="https://pypi.org/project/chrome-time-clock/"><img src="https://img.shields.io/pypi/v/chrome-time-clock?style=flat-square&amp;color=3775A9&amp;logo=pypi&amp;logoColor=white&amp;labelColor=2D2825" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/python-%E2%89%A53.9-D78A7A?style=flat-square&amp;labelColor=2D2825" alt="Python 3.9+">
+  <img src="https://img.shields.io/badge/browsers-Chrome%20%C2%B7%20Chromium%20%C2%B7%20Brave-D78A7A?style=flat-square&amp;labelColor=2D2825" alt="Chrome, Chromium, Brave">
+  <img src="https://img.shields.io/badge/OS-macOS%20%C2%B7%20Windows%20%C2%B7%20Linux-7E9688?style=flat-square&amp;labelColor=2D2825" alt="macOS, Windows, Linux">
+  <img src="https://img.shields.io/badge/license-MIT-7E9688?style=flat-square&amp;labelColor=2D2825" alt="MIT license">
+</p>
+
+<br clear="left">
+
+```sh
+uv tool install chrome-time-clock                      # or: pipx install chrome-time-clock
+chrome-time-clock extract --out ./export --markdown     # history → daily_summary.csv (+ .md)
+chrome-time-clock plot ./export/daily_summary.csv       # timeline + histograms, .png and .pdf
+chrome-time-clock merge laptop.csv desktop.csv          # union of blocks across machines
+```
+
+Everything runs locally against a copy of the browser's History SQLite file; nothing leaves the machine.
+
+## Extract
+
+Groups history visits into active blocks, split wherever the gap exceeds `--gap-minutes`, and reports each day's first and last block.
+
+| Option | Default | |
+|---|---|---|
+| `--browser` | `chrome` | `chrome`, `chromium` or `brave` |
+| `--profile` | `Default` | e.g. `Profile 1` |
+| `--history-db` | — | a History file directly; overrides browser/profile |
+| `--from` / `--to` | — | `YYYY-MM-DD`, inclusive |
+| `--timezone` | `Europe/Amsterdam` | IANA name |
+| `--gap-minutes` | `60` | inactivity that ends a block |
+| `--out` | `./chrome_workhours_export` | CSV output directory |
+| `--markdown` | off | also write `daily_summary.md` |
+
+## Plot
+
+Dark-theme timeline and start/end histograms from `daily_summary.csv`.
+
+| Option | Default | |
+|---|---|---|
+| `--from` / `--to` | `2026-02-22` / — | `YYYY-MM-DD`, inclusive |
+| `--bins` | `15` | histogram bins |
+| `--out` | `workhours_plot` | file stem; `.png` and `.pdf` appended |
+| `--show` | off | open an interactive window |
+
+## Merge
+
+Combines several `blocks.csv` files — one per machine or profile — collapsing overlapping intervals:
+
+```sh
+chrome-time-clock merge a.csv b.csv --out-blocks merged_blocks.csv --out-daily merged_daily.csv
+```
+
+Each subcommand also has a standalone shortcut: `chrome-workhours`, `plot-workhours`, `merge-blocks`.
+
+## Python API
+
+```python
+from datetime import date
+from chrome_time_clock import extract_workhours, plot_workhours, merge_blocks
+
+daily, blocks, warnings = extract_workhours(browser="chrome", profile="Default",
+                                            date_from=date(2026, 6, 1), timezone_str="Europe/Amsterdam")
+plot_workhours(csv_path="./export/daily_summary.csv", date_from=date(2026, 6, 1), out_stem="plot")
+merge_blocks(files=["a.csv", "b.csv"], out_blocks="merged_blocks.csv", out_daily="merged_daily.csv")
+```

chrome_time_clock-0.1.0/README.md

@@ -0,0 +1,75 @@
+<img src="brand/icon/icon-chrome-time-clock-on-obsidian-1024.png" align="left" width="128" hspace="16" alt="chrome-time-clock icon">
+
+<h3>chrome-time-clock</h3>
+
+<p>
+  <sub>YOUR BROWSER ALREADY KEPT THE TIMESHEET</sub>
+  <br>
+  <strong>Infer workday start and end from Chrome, Chromium or Brave history, then plot or merge the hours.</strong>
+  <br>
+  <br>
+  <a href="https://pypi.org/project/chrome-time-clock/"><img src="https://img.shields.io/pypi/v/chrome-time-clock?style=flat-square&amp;color=3775A9&amp;logo=pypi&amp;logoColor=white&amp;labelColor=2D2825" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/python-%E2%89%A53.9-D78A7A?style=flat-square&amp;labelColor=2D2825" alt="Python 3.9+">
+  <img src="https://img.shields.io/badge/browsers-Chrome%20%C2%B7%20Chromium%20%C2%B7%20Brave-D78A7A?style=flat-square&amp;labelColor=2D2825" alt="Chrome, Chromium, Brave">
+  <img src="https://img.shields.io/badge/OS-macOS%20%C2%B7%20Windows%20%C2%B7%20Linux-7E9688?style=flat-square&amp;labelColor=2D2825" alt="macOS, Windows, Linux">
+  <img src="https://img.shields.io/badge/license-MIT-7E9688?style=flat-square&amp;labelColor=2D2825" alt="MIT license">
+</p>
+
+<br clear="left">
+
+```sh
+uv tool install chrome-time-clock                      # or: pipx install chrome-time-clock
+chrome-time-clock extract --out ./export --markdown     # history → daily_summary.csv (+ .md)
+chrome-time-clock plot ./export/daily_summary.csv       # timeline + histograms, .png and .pdf
+chrome-time-clock merge laptop.csv desktop.csv          # union of blocks across machines
+```
+
+Everything runs locally against a copy of the browser's History SQLite file; nothing leaves the machine.
+
+## Extract
+
+Groups history visits into active blocks, split wherever the gap exceeds `--gap-minutes`, and reports each day's first and last block.
+
+| Option | Default | |
+|---|---|---|
+| `--browser` | `chrome` | `chrome`, `chromium` or `brave` |
+| `--profile` | `Default` | e.g. `Profile 1` |
+| `--history-db` | — | a History file directly; overrides browser/profile |
+| `--from` / `--to` | — | `YYYY-MM-DD`, inclusive |
+| `--timezone` | `Europe/Amsterdam` | IANA name |
+| `--gap-minutes` | `60` | inactivity that ends a block |
+| `--out` | `./chrome_workhours_export` | CSV output directory |
+| `--markdown` | off | also write `daily_summary.md` |
+
+## Plot
+
+Dark-theme timeline and start/end histograms from `daily_summary.csv`.
+
+| Option | Default | |
+|---|---|---|
+| `--from` / `--to` | `2026-02-22` / — | `YYYY-MM-DD`, inclusive |
+| `--bins` | `15` | histogram bins |
+| `--out` | `workhours_plot` | file stem; `.png` and `.pdf` appended |
+| `--show` | off | open an interactive window |
+
+## Merge
+
+Combines several `blocks.csv` files — one per machine or profile — collapsing overlapping intervals:
+
+```sh
+chrome-time-clock merge a.csv b.csv --out-blocks merged_blocks.csv --out-daily merged_daily.csv
+```
+
+Each subcommand also has a standalone shortcut: `chrome-workhours`, `plot-workhours`, `merge-blocks`.
+
+## Python API
+
+```python
+from datetime import date
+from chrome_time_clock import extract_workhours, plot_workhours, merge_blocks
+
+daily, blocks, warnings = extract_workhours(browser="chrome", profile="Default",
+                                            date_from=date(2026, 6, 1), timezone_str="Europe/Amsterdam")
+plot_workhours(csv_path="./export/daily_summary.csv", date_from=date(2026, 6, 1), out_stem="plot")
+merge_blocks(files=["a.csv", "b.csv"], out_blocks="merged_blocks.csv", out_daily="merged_daily.csv")
+```

chrome_time_clock-0.1.0/chrome_time_clock/__init__.py

@@ -0,0 +1,17 @@
+"""
+Chrome Time Clock
+
+Infer approximate workday start/end from Chrome browser history and plot/merge work hours.
+"""
+
+from chrome_time_clock.extractor import extract_workhours
+from chrome_time_clock.merger import merge_blocks
+from chrome_time_clock.plotter import plot_workhours
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "extract_workhours",
+    "plot_workhours",
+    "merge_blocks",
+]

chrome_time_clock-0.1.0/chrome_time_clock/cli.py

@@ -0,0 +1,228 @@
+"""Unified command-line interface for chrome-time-clock."""
+
+import argparse
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from chrome_time_clock.extractor import DEFAULT_GAP_MINUTES, DEFAULT_OUT_DIR, DEFAULT_PROFILE, DEFAULT_TIMEZONE, extract_workhours, write_csv, write_markdown
+from chrome_time_clock.merger import merge_blocks
+from chrome_time_clock.plotter import plot_workhours
+
+
+def main() -> None:
+    """Main entry point for the unified chrome-time-clock CLI."""
+    parser = argparse.ArgumentParser(
+        prog="chrome-time-clock",
+        description="Chrome Time Clock: Infer, plot, and merge work hours from browser history.",
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", required=True, title="subcommands")
+
+    # ── Extract Subcommand ────────────────────────────────────────────────────
+    extract_parser = subparsers.add_parser(
+        "extract",
+        help="Infer workday start/end from browser history",
+        description="Infer workday start/end from Chrome/Chromium/Brave browser history.",
+    )
+    extract_parser.add_argument(
+        "--profile",
+        default=DEFAULT_PROFILE,
+        help=f"Browser profile name (default: {DEFAULT_PROFILE})",
+    )
+    extract_parser.add_argument(
+        "--browser",
+        default="chrome",
+        choices=["chrome", "chromium", "brave"],
+        help="Browser type (default: chrome)",
+    )
+    extract_parser.add_argument(
+        "--history-db",
+        default=None,
+        help="Direct path to History SQLite file (overrides browser/profile resolution)",
+    )
+    extract_parser.add_argument(
+        "--from",
+        dest="date_from",
+        default=None,
+        help="Start date YYYY-MM-DD (inclusive)",
+    )
+    extract_parser.add_argument(
+        "--to",
+        dest="date_to",
+        default=None,
+        help="End date YYYY-MM-DD (inclusive)",
+    )
+    extract_parser.add_argument(
+        "--timezone",
+        default=DEFAULT_TIMEZONE,
+        help=f"IANA timezone (default: {DEFAULT_TIMEZONE})",
+    )
+    extract_parser.add_argument(
+        "--gap-minutes",
+        type=int,
+        default=DEFAULT_GAP_MINUTES,
+        help=f"Inactivity gap threshold in minutes (default: {DEFAULT_GAP_MINUTES})",
+    )
+    extract_parser.add_argument(
+        "--out",
+        default=DEFAULT_OUT_DIR,
+        help=f"Output directory (default: {DEFAULT_OUT_DIR})",
+    )
+    extract_parser.add_argument(
+        "--markdown",
+        action="store_true",
+        help="Also write daily_summary.md inside the output directory",
+    )
+
+    # ── Plot Subcommand ───────────────────────────────────────────────────────
+    plot_parser = subparsers.add_parser(
+        "plot",
+        help="Work-hour timelines and histograms",
+        description="Generate work-hour timelines and histograms in dark Soilytix style.",
+    )
+    plot_parser.add_argument(
+        "csv",
+        help="Path to the daily summary CSV file",
+    )
+    plot_parser.add_argument(
+        "--from",
+        dest="date_from",
+        default="2026-02-22",
+        help="Start date YYYY-MM-DD (inclusive) (default: 2026-02-22)",
+    )
+    plot_parser.add_argument(
+        "--to",
+        dest="date_to",
+        default=None,
+        help="End date YYYY-MM-DD (inclusive)",
+    )
+    plot_parser.add_argument(
+        "--bins",
+        type=int,
+        default=15,
+        help="Number of bins for histograms (default: 15)",
+    )
+    plot_parser.add_argument(
+        "--out",
+        default="workhours_plot",
+        help="Output file stem — .png and .pdf are appended (default: workhours_plot)",
+    )
+    plot_parser.add_argument(
+        "--show",
+        action="store_true",
+        help="Display the plot window",
+    )
+
+    # ── Merge Subcommand ──────────────────────────────────────────────────────
+    merge_parser = subparsers.add_parser(
+        "merge",
+        help="Merge blocks.csv files",
+        description="Merge multiple blocks.csv files, collapsing overlapping time intervals.",
+    )
+    merge_parser.add_argument(
+        "files",
+        nargs="+",
+        help="List of blocks.csv files to merge",
+    )
+    merge_parser.add_argument(
+        "--out-blocks",
+        default="merged_blocks.csv",
+        help="Output filename for merged blocks (default: merged_blocks.csv)",
+    )
+    merge_parser.add_argument(
+        "--out-daily",
+        default="merged_daily.csv",
+        help="Output filename for derived daily summary (default: merged_daily.csv)",
+    )
+
+    # Parse arguments
+    args = parser.parse_args()
+
+    try:
+        if args.command == "extract":
+            date_from = (
+                datetime.strptime(args.date_from, "%Y-%m-%d").date() if args.date_from else None
+            )
+            date_to = (
+                datetime.strptime(args.date_to, "%Y-%m-%d").date() if args.date_to else None
+            )
+
+            daily_rows, block_rows, warnings = extract_workhours(
+                browser=args.browser,
+                profile=args.profile,
+                history_db=args.history_db,
+                date_from=date_from,
+                date_to=date_to,
+                timezone_str=args.timezone,
+                gap_minutes=args.gap_minutes,
+            )
+
+            if not daily_rows:
+                print("No visits found after filtering. Nothing to do.")
+                return
+
+            print(f"Days summarised: {len(daily_rows)}")
+            for w in warnings:
+                print(f"  {w}")
+
+            out_dir = Path(args.out)
+            out_dir.mkdir(parents=True, exist_ok=True)
+
+            daily_path = out_dir / "daily_summary.csv"
+            blocks_path = out_dir / "blocks.csv"
+
+            write_csv(
+                daily_rows,
+                daily_path,
+                ["date", "first_seen", "last_seen", "gross_span_hours", "active_block_hours", "n_blocks", "n_visits"],
+            )
+            write_csv(
+                block_rows,
+                blocks_path,
+                ["date", "block_start", "block_end", "duration_hours", "n_visits"],
+            )
+
+            if args.markdown:
+                md_path = out_dir / "daily_summary.md"
+                write_markdown(daily_rows, md_path)
+                print(f"Markdown written to:  {md_path}")
+
+            print(f"Output written to: {out_dir.resolve()}")
+            print(f"  {daily_path.name}: {len(daily_rows)} days")
+            print(f"  {blocks_path.name}: {len(block_rows)} blocks")
+
+        elif args.command == "plot":
+            date_from = (
+                datetime.strptime(args.date_from, "%Y-%m-%d").date() if args.date_from else None
+            )
+            date_to = (
+                datetime.strptime(args.date_to, "%Y-%m-%d").date() if args.date_to else None
+            )
+
+            plot_workhours(
+                csv_path=args.csv,
+                date_from=date_from,
+                date_to=date_to,
+                bins=args.bins,
+                out_stem=args.out,
+                show=args.show,
+            )
+
+        elif args.command == "merge":
+            merge_blocks(
+                files=args.files,
+                out_blocks=args.out_blocks,
+                out_daily=args.out_daily,
+            )
+            print(f"Successfully merged {len(args.files)} file(s).")
+            print(f"Written: {args.out_blocks}")
+            print(f"Written: {args.out_daily}")
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()