tas-tech.net/event-tracker
Watch
2
0
Fork
You've already forked event-tracker
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit: EventTracker desktop app + Android companion

Browse source 
Desktop: GTK3 + matplotlib app tracking arbitrary events (button ->
timestamp -> CSV), with per-event stats, trend charts, settings
(rename/add events, relocate data file), and a reset-with-backup flow.
Portable desktop launcher via a .desktop.in template + install script,
no machine-specific paths baked in.

Android: minimal Kivy v1 companion reading/writing the same CSV format,
plus buildozer build tooling isolated in a venv and a local p4a recipe
override for kivy (see CLAUDE.md for why).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
AI_Assistant 2026-08-22 07:52:54 +00:00
commit cd9f9456e9
No known key found for this signature in database
17 changed files with 1722 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

120
README.md Normal file
View file

@ -0,0 +1,120 @@
# Event Tracker
Single-window GTK3 app. One button per event logs a timestamp to a CSV
file; the window shows total count, avg/hour, avg/day, last logged
time, and time since last event (to the minute, ticks forward live) per
event, plus a line graph of **today's** counts by hour (whole-number
y-axis).
**View Stats & Trends** opens a per-event breakdown: today / this week /
this month, last 7 and 30 days with daily average, trend vs the prior 7
days, current/longest day streaks, busiest hour and day, a weekday
breakdown, and three trend charts (by hour, by week, by month).
**Settings** lets you rename an existing event (renaming migrates its
past log entries to the new name, nothing is lost), add a new event —
each gets its own button and its own color, cycling through 6 colors if
you add more than that — and relocate the data file itself (Browse to
pick a new location; the existing log is moved there on Save, and
anything already at the destination is backed up first).
**Reset Stats** clears the log after a confirmation dialog. The current
log is copied to a timestamped `.bak-YYYYMMDD-HHMMSS` file first, so a
mis-click doesn't destroy history — restore it by copying that file back
over `event_log.csv`.
## 1. Check what's already installed (read-only)
Run this before installing anything — it tells you exactly what's missing:
```sh
python3 -c "import gi; gi.require_version('Gtk','3.0'); from gi.repository import Gtk; print('PyGObject/GTK3: OK')" 2>&1
python3 -c "import matplotlib; print('matplotlib:', matplotlib.__version__)" 2>&1
python3 -c "import matplotlib; matplotlib.use('GTK3Agg'); from matplotlib.backends.backend_gtk3agg import FigureCanvasGTK3Agg; print('GTK3Agg backend: OK')" 2>&1
```
Any line printing a Traceback instead of "OK" / a version number tells you
which piece is missing.
## 2. Install missing pieces
**Arch / EndeavourOS:**
```sh
sudo pacman -S --needed python-gobject gtk3 python-matplotlib
```
**Debian / derivatives:**
```sh
sudo apt install python3-gi gir1.2-gtk-3.0 python3-matplotlib
```
Don't `pip install PyGObject` — it needs the system GTK3 dev headers and
is far more reliable installed as a distro package.
## 3. Run
```sh
chmod +x event_tracker.py
./event_tracker.py
```
## 4. Optional: desktop launcher
```sh
./install-launcher.sh
```
Generates `event-tracker.desktop` for wherever you actually cloned this
repo (`event-tracker.desktop.in` is a template with no machine-specific
path baked in) and installs it to `~/.local/share/applications/`.
Re-run it if you move the clone.
## Data
Log file: `~/.local/share/event-tracker/event_log.csv` by default —
columns `event,timestamp`, plain CSV, edit by hand if you need to
correct an entry. Created automatically on first run. Move it anywhere
via **Settings → Data file location**; the app always reads its current
location from `config.json` rather than a hardcoded path.
App settings (event list + current data file location):
`~/.local/share/event-tracker/config.json` — always lives here, written
the first time you Save changes in Settings. This one small file isn't
user-relocatable (it's the pointer to where your real data is, not the
data itself); until it exists the app uses `DEFAULT_EVENTS` /
`DEFAULT_DATA_PATH` from the script.
If you're upgrading from the single-event version, the old
`cigarette_log.csv` (header: `timestamp` only) is auto-migrated the
first time this version runs — its rows are relabelled `Cigarette` and
written into `event_log.csv` in the new two-column format. The old file
is left untouched on disk.
## Configuration
All tunables sit at the top of `event_tracker.py`:
| Variable | Meaning |
|---|---|
| `DEFAULT_EVENTS` | Starting event list, used only if `config.json` doesn't exist yet |
| `COLOR_PALETTE` | Colors assigned to events by list position, cycles if you have more events than colors |
| `DEFAULT_DATA_PATH` | Starting data file location, used only if `config.json` doesn't exist yet |
| `CONFIG_PATH` | Where app settings (event list + current data file location) are saved — fixed, not relocatable |
| `WEEKLY_WEEKS` | Trailing weeks shown in the stats popup's weekly chart |
| `MONTHLY_MONTHS` | Trailing months shown in the stats popup's monthly chart |
| `TIMESTAMP_FORMAT` | Format used to read/write timestamps in the CSV |
Renaming/adding events or moving the data file day-to-day: use the
in-app **Settings** button, not this file — it persists to
`config.json`, migrates existing log rows on rename, and moves the CSV
on relocation.
## Android companion
`android/` has a minimal Kivy app that reads/writes this same CSV
format — point it at whatever local folder your phone's sync tool
(FolderSync, DAVx5, etc.) mirrors from wherever this app's data file
lives. See `android/README.md` for the build (you build it yourself on
a Linux machine — no signing keys or accounts of ours involved).