easy-or-not 0.1.0__tar.gz

easy_or_not-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+# never commit real activity data or keys
+*.fit
+*.zip
+!tests/fixtures/*.fit
+connect-personal-api-key

easy_or_not-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Nicholson
+
+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.

easy_or_not-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: easy-or-not
+Version: 0.1.0
+Summary: Are your easy runs actually easy? Time-in-zone and aerobic efficiency from your own Garmin data.
+Project-URL: Homepage, https://github.com/stephen-a-nicholson/easy-or-not
+Project-URL: Issues, https://github.com/stephen-a-nicholson/easy-or-not/issues
+Author: Stephen Nicholson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 80/20,fit,garmin,heart-rate,running,training
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Requires-Dist: fitdecode>=0.10
+Requires-Dist: garmin-connect-personal-api-python>=1.0
+Provides-Extra: dev
+Requires-Dist: fit-tool>=0.9; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# easy-or-not
+
+Are your easy runs actually easy?
+
+Most runners who stop improving are not lazy. They run almost everything at the same medium effort, too hard to recover from and too easy to make them faster. This tool reads your own runs and tells you how much of your time went where, how much of your "easy" running drifted into the middle, whether you are getting faster at the same heart rate, and your training load from week to week.
+
+It was built for watches like the Vivoactive 5, which record every heartbeat but leave Training Load to Garmin's more expensive models.
+
+It works on FIT files you have exported, or straight from your account with a [Garmin Personal API](https://developer.garmin.com/gc-developer-program/personal/personal-api/) key. Everything runs on your machine. Your data and your key never leave it.
+
+```
+30 runs, heart-rate bands from your Garmin running zones
+  easy below 154 bpm   middle 154-172 bpm   hard 173+ bpm
+
+Where your running time went
+  easy     47%  ##############................
+  middle   27%  ########......................
+  hard     25%  ########......................
+  A common target is around 80% easy with the rest mostly hard.
+
+Your easy runs (18 of 30, sessions excluded)
+  44% of easy-run time was in the middle band.
+    Thu 08 Oct    32 min    68% middle  (treadmill)
+    Mon 14 Sep    32 min    65% middle  (outdoor)
+    Sun 04 Oct    32 min    56% middle  (outdoor)
+
+Same heart rate, faster? (outdoor easy runs only)
+  1.40 -> 1.43 metres per heartbeat (+2.5%).
+  Higher means you cover more ground for the same effort.
+
+Training load (heart-rate minutes, weighted 1 to 5 by zone)
+  Last 7 days to Thu 22 Oct: 412
+  Your average week over the last 4: 380
+  Ratio 1.08: in line with your recent weeks.
+```
+
+*(Example output from synthetic data.)*
+
+## Install
+
+Python 3.12 or newer.
+
+```bash
+uv tool install easy-or-not
+# or: pipx install easy-or-not
+```
+
+## Use it with your Garmin account
+
+```bash
+easy-or-not setup    # once: paste your Personal API key
+easy-or-not          # your last 8 weeks of runs
+easy-or-not garmin --days 90
+```
+
+`setup` tells you where to create the key in Garmin Connect ([Settings, Personal API Token](https://connect.garmin.com/app/settings/personalApiToken)), reads it without showing it on screen, saves it to `~/.config/garmin/connect-personal-api-key` readable only by you, and checks it with Garmin.
+
+Authentication is handled by Garmin's official [Python client](https://github.com/garmin/connect-personal-api-python), which also reads `GARMIN_PERSONAL_API_KEY` if you prefer an environment variable. Original activity files are cached in `~/.cache/easy-or-not`, so later runs only download new activities. Your heart-rate zones are read from your Garmin settings.
+
+## Use it with exported files
+
+In Garmin Connect on the web, open an activity, click the gear icon and choose **Export Original**. Point the tool at the files or the folder:
+
+```bash
+easy-or-not --max-hr 192 files ~/Downloads/runs/
+```
+
+Without the API there are no Garmin zones to read, so pass your max heart rate.
+
+## What it measures
+
+**Bands.** Easy, middle and hard come from your heart-rate zones. By default easy is zones 1 and 2, middle is zone 3, hard is zones 4 and 5. Garmin's default zones start zone 3 at 70% of max HR, which is stricter than the roughly 80% easy ceiling used in polarised-training research. If you are on Garmin's defaults and everything looks "middle", try `--easy-up-to 3`. With `--max-hr`, the bands are below 80%, 80 to 90%, and above 90% of max.
+
+**Easy runs.** Any run with less than 10% of its time in the hard band. That is a session-free run, whatever you meant it to be.
+
+**Efficiency.** Metres covered per heartbeat while in the easy band, ignoring the first five minutes while heart rate catches up. The tool compares the median of your first third of outdoor easy runs with your last third. It needs at least six.
+
+**What gets left out.** Activities with under 10 minutes of heart-rate data (a GPS test, a watch started by accident), and walks logged as runs (median cadence under 140 steps per minute). A walk home or a watch left recording after the run is trimmed off the end, so it does not count as easy running. The report says how many were left out and why.
+
+**Zones that look too low.** If you held a median heart rate in zone 5 for half an hour or more, the report says your zones are probably set too low rather than telling you that you ran half an hour flat out.
+
+**Training load.** Each run's load is its Edwards TRIMP: minutes in each heart-rate zone multiplied by the zone number, so a minute in zone 5 counts five times a minute in zone 1. The report compares the last 7 days with your average week over the last 4 (it needs 4 weeks of runs). Below 0.8 is lighter than usual, 0.8 to 1.3 is in line, 1.3 to 1.5 is a step up, above 1.5 is a big jump. Runs under 10 minutes still count towards load; walks do not. From your Garmin account, load is measured up to today, so a week off shows as a week off. It is a heart-rate estimate, not Garmin's Training Load, and it is only as right as your zones.
+
+**Pauses.** Gaps of more than 10 seconds between samples (traffic lights, a stopped watch) are not counted.
+
+## Limits
+
+- **Treadmill pace is an estimate.** Indoors, the watch works out speed from your wrist, so treadmill runs count towards time in zone but are left out of the efficiency trend.
+- **Heart rate is only as good as the sensor.** Wrist HR can lock on to cadence, especially in the first few minutes or in the cold. A chest strap gives cleaner numbers.
+- **Your zones decide the answer.** If the max heart rate in your Garmin settings is a guess, the bands are too. If you know your real max (from a race finish or a hard hill effort), pass `--max-hr`.
+- **It describes, it does not coach.** "44% of your easy running was in the middle" is a fact about your data. What to do about it is up to you.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+uv run pytest -q
+uv run ruff check .
+```
+
+The tests build real FIT files in memory, so nothing personal is committed. `*.fit`, `*.zip` and key files are git-ignored.
+
+## Licence
+
+MIT. Not affiliated with Garmin.

easy_or_not-0.1.0/README.md

@@ -0,0 +1,105 @@
+# easy-or-not
+
+Are your easy runs actually easy?
+
+Most runners who stop improving are not lazy. They run almost everything at the same medium effort, too hard to recover from and too easy to make them faster. This tool reads your own runs and tells you how much of your time went where, how much of your "easy" running drifted into the middle, whether you are getting faster at the same heart rate, and your training load from week to week.
+
+It was built for watches like the Vivoactive 5, which record every heartbeat but leave Training Load to Garmin's more expensive models.
+
+It works on FIT files you have exported, or straight from your account with a [Garmin Personal API](https://developer.garmin.com/gc-developer-program/personal/personal-api/) key. Everything runs on your machine. Your data and your key never leave it.
+
+```
+30 runs, heart-rate bands from your Garmin running zones
+  easy below 154 bpm   middle 154-172 bpm   hard 173+ bpm
+
+Where your running time went
+  easy     47%  ##############................
+  middle   27%  ########......................
+  hard     25%  ########......................
+  A common target is around 80% easy with the rest mostly hard.
+
+Your easy runs (18 of 30, sessions excluded)
+  44% of easy-run time was in the middle band.
+    Thu 08 Oct    32 min    68% middle  (treadmill)
+    Mon 14 Sep    32 min    65% middle  (outdoor)
+    Sun 04 Oct    32 min    56% middle  (outdoor)
+
+Same heart rate, faster? (outdoor easy runs only)
+  1.40 -> 1.43 metres per heartbeat (+2.5%).
+  Higher means you cover more ground for the same effort.
+
+Training load (heart-rate minutes, weighted 1 to 5 by zone)
+  Last 7 days to Thu 22 Oct: 412
+  Your average week over the last 4: 380
+  Ratio 1.08: in line with your recent weeks.
+```
+
+*(Example output from synthetic data.)*
+
+## Install
+
+Python 3.12 or newer.
+
+```bash
+uv tool install easy-or-not
+# or: pipx install easy-or-not
+```
+
+## Use it with your Garmin account
+
+```bash
+easy-or-not setup    # once: paste your Personal API key
+easy-or-not          # your last 8 weeks of runs
+easy-or-not garmin --days 90
+```
+
+`setup` tells you where to create the key in Garmin Connect ([Settings, Personal API Token](https://connect.garmin.com/app/settings/personalApiToken)), reads it without showing it on screen, saves it to `~/.config/garmin/connect-personal-api-key` readable only by you, and checks it with Garmin.
+
+Authentication is handled by Garmin's official [Python client](https://github.com/garmin/connect-personal-api-python), which also reads `GARMIN_PERSONAL_API_KEY` if you prefer an environment variable. Original activity files are cached in `~/.cache/easy-or-not`, so later runs only download new activities. Your heart-rate zones are read from your Garmin settings.
+
+## Use it with exported files
+
+In Garmin Connect on the web, open an activity, click the gear icon and choose **Export Original**. Point the tool at the files or the folder:
+
+```bash
+easy-or-not --max-hr 192 files ~/Downloads/runs/
+```
+
+Without the API there are no Garmin zones to read, so pass your max heart rate.
+
+## What it measures
+
+**Bands.** Easy, middle and hard come from your heart-rate zones. By default easy is zones 1 and 2, middle is zone 3, hard is zones 4 and 5. Garmin's default zones start zone 3 at 70% of max HR, which is stricter than the roughly 80% easy ceiling used in polarised-training research. If you are on Garmin's defaults and everything looks "middle", try `--easy-up-to 3`. With `--max-hr`, the bands are below 80%, 80 to 90%, and above 90% of max.
+
+**Easy runs.** Any run with less than 10% of its time in the hard band. That is a session-free run, whatever you meant it to be.
+
+**Efficiency.** Metres covered per heartbeat while in the easy band, ignoring the first five minutes while heart rate catches up. The tool compares the median of your first third of outdoor easy runs with your last third. It needs at least six.
+
+**What gets left out.** Activities with under 10 minutes of heart-rate data (a GPS test, a watch started by accident), and walks logged as runs (median cadence under 140 steps per minute). A walk home or a watch left recording after the run is trimmed off the end, so it does not count as easy running. The report says how many were left out and why.
+
+**Zones that look too low.** If you held a median heart rate in zone 5 for half an hour or more, the report says your zones are probably set too low rather than telling you that you ran half an hour flat out.
+
+**Training load.** Each run's load is its Edwards TRIMP: minutes in each heart-rate zone multiplied by the zone number, so a minute in zone 5 counts five times a minute in zone 1. The report compares the last 7 days with your average week over the last 4 (it needs 4 weeks of runs). Below 0.8 is lighter than usual, 0.8 to 1.3 is in line, 1.3 to 1.5 is a step up, above 1.5 is a big jump. Runs under 10 minutes still count towards load; walks do not. From your Garmin account, load is measured up to today, so a week off shows as a week off. It is a heart-rate estimate, not Garmin's Training Load, and it is only as right as your zones.
+
+**Pauses.** Gaps of more than 10 seconds between samples (traffic lights, a stopped watch) are not counted.
+
+## Limits
+
+- **Treadmill pace is an estimate.** Indoors, the watch works out speed from your wrist, so treadmill runs count towards time in zone but are left out of the efficiency trend.
+- **Heart rate is only as good as the sensor.** Wrist HR can lock on to cadence, especially in the first few minutes or in the cold. A chest strap gives cleaner numbers.
+- **Your zones decide the answer.** If the max heart rate in your Garmin settings is a guess, the bands are too. If you know your real max (from a race finish or a hard hill effort), pass `--max-hr`.
+- **It describes, it does not coach.** "44% of your easy running was in the middle" is a fact about your data. What to do about it is up to you.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+uv run pytest -q
+uv run ruff check .
+```
+
+The tests build real FIT files in memory, so nothing personal is committed. `*.fit`, `*.zip` and key files are git-ignored.
+
+## Licence
+
+MIT. Not affiliated with Garmin.

easy_or_not-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "easy-or-not"
+version = "0.1.0"
+description = "Are your easy runs actually easy? Time-in-zone and aerobic efficiency from your own Garmin data."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Stephen Nicholson" }]
+keywords = ["garmin", "running", "heart-rate", "fit", "training", "80/20"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fitdecode>=0.10",
+    "garmin-connect-personal-api-python>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/stephen-a-nicholson/easy-or-not"
+Issues = "https://github.com/stephen-a-nicholson/easy-or-not/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "fit-tool>=0.9"]
+
+[project.scripts]
+easy-or-not = "easy_or_not.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+exclude = ["CLAUDE.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/easy_or_not"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

easy_or_not-0.1.0/src/easy_or_not/__init__.py

@@ -0,0 +1,3 @@
+"""Are your easy runs actually easy?"""
+
+__version__ = "0.1.0"

easy_or_not-0.1.0/src/easy_or_not/analysis.py

@@ -0,0 +1,168 @@
+"""The three questions the tool answers.
+
+1. How is your running time split between easy, middle and hard?
+2. Of the runs that were meant to be easy, how much drifted into the middle?
+3. At the same easy heart rate, are you getting faster over time?
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from statistics import median
+
+from easy_or_not.checks import IMPLAUSIBLE_Z5_S, SHORT_REASON, skip_reason, trim_tail
+from easy_or_not.models import Run
+from easy_or_not.zones import Zones
+
+# Gaps longer than this between samples are pauses (traffic lights, stopping
+# the watch) and are not counted as time in any zone.
+MAX_GAP_S = 10.0
+
+# A run with less hard time than this was not a session, so it counts as a
+# run that was meant to be easy.
+SESSION_HARD_FRACTION = 0.10
+
+# Ignore the first few minutes when measuring efficiency: heart rate lags
+# pace while you warm up and would make everyone look efficient.
+WARMUP_S = 300.0
+
+
+@dataclass
+class RunSummary:
+    run: Run
+    seconds: dict[str, float]  # band -> seconds
+    efficiency: float | None  # metres per heartbeat while in the easy band
+    zone_seconds: dict[int, float] = field(default_factory=dict)  # zone 1-5 -> seconds
+
+    @property
+    def load(self) -> float:
+        """Edwards TRIMP: minutes in each heart-rate zone times the zone number."""
+        return sum(zone * s / 60.0 for zone, s in self.zone_seconds.items())
+
+    @property
+    def total_s(self) -> float:
+        return sum(self.seconds.values())
+
+    def fraction(self, band: str) -> float:
+        return self.seconds.get(band, 0.0) / self.total_s if self.total_s else 0.0
+
+    @property
+    def is_session(self) -> bool:
+        return self.fraction("hard") >= SESSION_HARD_FRACTION
+
+
+@dataclass
+class Report:
+    zones: Zones
+    runs: list[RunSummary]
+    skipped: list[tuple[Run, str]] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    # Runs too short for the time-in-zone figures still count towards load.
+    load_only: list[RunSummary] = field(default_factory=list)
+    as_of: date | None = None
+
+    def total_fraction(self, band: str) -> float:
+        total = sum(r.total_s for r in self.runs)
+        return sum(r.seconds.get(band, 0.0) for r in self.runs) / total if total else 0.0
+
+    @property
+    def easy_runs(self) -> list[RunSummary]:
+        return [r for r in self.runs if not r.is_session]
+
+    @property
+    def sessions(self) -> list[RunSummary]:
+        return [r for r in self.runs if r.is_session]
+
+    def easy_run_middle_fraction(self) -> float:
+        runs = self.easy_runs
+        total = sum(r.total_s for r in runs)
+        return sum(r.seconds.get("middle", 0.0) for r in runs) / total if total else 0.0
+
+    def weekly(self) -> list[tuple[date, dict[str, float]]]:
+        weeks: dict[date, dict[str, float]] = defaultdict(lambda: defaultdict(float))
+        for r in self.runs:
+            monday = r.run.start.date() - timedelta(days=r.run.start.weekday())
+            for band, s in r.seconds.items():
+                weeks[monday][band] += s
+        return sorted((k, dict(v)) for k, v in weeks.items())
+
+    def efficiency_trend(self) -> tuple[float, float] | None:
+        """Median efficiency of the first and last third of outdoor easy runs."""
+        points = [r.efficiency for r in self.easy_runs if r.efficiency and not r.run.treadmill]
+        if len(points) < 6:
+            return None
+        third = len(points) // 3
+        return median(points[:third]), median(points[-third:])
+
+
+def summarise(run: Run, zones: Zones) -> RunSummary:
+    seconds: dict[str, float] = defaultdict(float)
+    zone_seconds: dict[int, float] = defaultdict(float)
+    metres = 0.0
+    beats = 0.0
+    samples = run.samples
+    for prev, cur in zip(samples, samples[1:], strict=False):
+        dt = cur.elapsed_s - prev.elapsed_s
+        if dt <= 0 or dt > MAX_GAP_S or prev.heart_rate is None or prev.heart_rate <= 0:
+            continue
+        band = zones.band(prev.heart_rate)
+        seconds[band] += dt
+        zone_seconds[zones.zone(prev.heart_rate)] += dt
+        if band == "easy" and prev.elapsed_s >= WARMUP_S and prev.speed_mps:
+            metres += prev.speed_mps * dt
+            beats += prev.heart_rate * dt / 60.0
+    efficiency = metres / beats if beats > 60 else None
+    return RunSummary(
+        run=run, seconds=dict(seconds), efficiency=efficiency, zone_seconds=dict(zone_seconds)
+    )
+
+
+def median_hr(run: Run) -> float | None:
+    rates = [s.heart_rate for s in run.samples if s.heart_rate]
+    return median(rates) if rates else None
+
+
+def zone_warnings(runs: list[RunSummary], zones: Zones) -> list[str]:
+    """Flag zones that the data says are too low."""
+    suspicious = [
+        (r, hr)
+        for r in runs
+        if r.total_s >= IMPLAUSIBLE_Z5_S and (hr := median_hr(r.run)) and hr >= zones.z5
+    ]
+    if not suspicious:
+        return []
+    r, hr = max(suspicious, key=lambda pair: pair[1])
+    return [
+        f"Your zones may be set too low. On {r.run.start:%a %d %b} you held a median of "
+        f"{hr:.0f} bpm for {r.total_s / 60:.0f} min, above your zone 5 floor of {zones.z5}. "
+        "Zone 5 is meant to be a few minutes at most, so your real max heart rate is "
+        "probably higher than your zones assume. If you know it, pass --max-hr."
+    ]
+
+
+def analyse(runs: list[Run], zones: Zones, as_of: date | None = None) -> Report:
+    """Summarise runs. `as_of` is the day load is measured to (default: the last run)."""
+    kept: list[RunSummary] = []
+    load_only: list[RunSummary] = []
+    skipped: list[tuple[Run, str]] = []
+    for run in sorted(runs, key=lambda r: r.start):
+        summary = summarise(trim_tail(run), zones)
+        reason = skip_reason(run, summary.total_s)
+        if reason:
+            skipped.append((run, reason))
+            if reason == SHORT_REASON:
+                load_only.append(summary)
+        else:
+            kept.append(summary)
+    if as_of is None and runs:
+        as_of = max(r.start for r in runs).date()
+    return Report(
+        zones=zones,
+        runs=kept,
+        skipped=skipped,
+        warnings=zone_warnings(kept, zones),
+        load_only=load_only,
+        as_of=as_of,
+    )

easy_or_not-0.1.0/src/easy_or_not/checks.py

@@ -0,0 +1,65 @@
+"""Data sanity checks: catch recordings that would make the numbers misleading.
+
+Each check either cleans a run up, drops it with a stated reason, or adds a
+warning to the report. None of them changes the zones.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from statistics import median
+
+from easy_or_not.models import Run, Sample
+
+# Running is almost always above this many steps per minute and walking below it.
+RUNNING_CADENCE_SPM = 140.0
+
+# Without cadence, treat anything slower than about 9:15/km as not running.
+RUNNING_SPEED_MPS = 1.8
+
+# Runs with less heart-rate data than this are fragments (a GPS test, a
+# watch started by accident) and say nothing about how you train.
+MIN_HR_S = 600.0
+
+# Zone 5 is the top few percent of your range. Holding it for this long is
+# not plausible, so it points to zones (or a max HR) set too low.
+IMPLAUSIBLE_Z5_S = 30 * 60.0
+
+SHORT_REASON = "under 10 minutes of heart-rate data"
+
+
+def _is_running(sample: Sample) -> bool | None:
+    if sample.cadence_spm is not None:
+        return sample.cadence_spm >= RUNNING_CADENCE_SPM
+    if sample.speed_mps is not None:
+        return sample.speed_mps >= RUNNING_SPEED_MPS
+    return None
+
+
+def trim_tail(run: Run) -> Run:
+    """Drop samples after the last running sample.
+
+    This removes a walk home, or a watch left recording on the sofa, which
+    would otherwise count as a long stretch of very easy running.
+    """
+    flags = [_is_running(s) for s in run.samples]
+    if not any(flags):
+        return run
+    last = max(i for i, f in enumerate(flags) if f)
+    if last == len(run.samples) - 1:
+        return run
+    return replace(run, samples=run.samples[: last + 1])
+
+
+def skip_reason(run: Run, hr_seconds: float) -> str | None:
+    """Why this run should be left out of the analysis, or None to keep it.
+
+    `run` is the activity as recorded; `hr_seconds` is the heart-rate time
+    left after trimming, so a walk is reported as a walk, not as too short.
+    """
+    cadences = [s.cadence_spm for s in run.samples if s.cadence_spm]
+    if len(cadences) > len(run.samples) / 2 and median(cadences) < RUNNING_CADENCE_SPM:
+        return "walking cadence"
+    if hr_seconds < MIN_HR_S:
+        return SHORT_REASON
+    return None

easy_or_not-0.1.0/src/easy_or_not/cli.py

@@ -0,0 +1,96 @@
+"""easy-or-not: are your easy runs actually easy?"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import replace
+from datetime import date
+from pathlib import Path
+
+from easy_or_not import __version__
+from easy_or_not.analysis import analyse
+from easy_or_not.fit import NotARun, load_path
+from easy_or_not.models import Run
+from easy_or_not.report import render_json, render_text
+from easy_or_not.zones import Zones, from_max_hr
+
+DEFAULT_CACHE = Path("~/.cache/easy-or-not").expanduser()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="easy-or-not", description=__doc__)
+    p.add_argument("--version", action="version", version=__version__)
+    p.add_argument("--max-hr", type=int, help="derive zones from max HR instead of Garmin's")
+    p.add_argument(
+        "--easy-up-to",
+        type=int,
+        choices=(2, 3),
+        default=2,
+        help="highest heart-rate zone that counts as easy (default 2; try 3 on Garmin defaults)",
+    )
+    p.add_argument("--json", action="store_true", help="print JSON instead of text")
+    p.set_defaults(days=56, cache_dir=DEFAULT_CACHE)  # for a bare `easy-or-not`
+    sub = p.add_subparsers(dest="source", metavar="{garmin,files,setup}")
+
+    sub.add_parser("setup", help="save your Garmin Personal API key (run this once)")
+
+    files = sub.add_parser("files", help="analyse .fit or .zip files you have exported")
+    files.add_argument("paths", nargs="+", type=Path)
+
+    garmin = sub.add_parser(
+        "garmin", help="fetch your runs with a Garmin Personal API key (the default)"
+    )
+    garmin.add_argument("--days", type=int, default=56, help="how far back to look (default 56)")
+    garmin.add_argument("--cache-dir", type=Path, default=DEFAULT_CACHE)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    args.source = args.source or "garmin"
+    zones: Zones | None = None
+    runs: list[Run] = []
+
+    if args.source == "setup":
+        from easy_or_not.setup import setup
+
+        return setup()
+    if args.source == "files":
+        for path in args.paths:
+            try:
+                runs.extend(load_path(path))
+            except NotARun as e:
+                print(f"skipping {e}", file=sys.stderr)
+    else:
+        from easy_or_not.garmin import GarminPersonalApiError, fetch  # so `files` works offline
+
+        try:
+            runs, zones = fetch(args.days, args.cache_dir, quiet=args.json)
+        except GarminPersonalApiError as e:
+            print(f"Could not reach your Garmin account: {e}", file=sys.stderr)
+            print("If you have not saved a key yet, run: easy-or-not setup", file=sys.stderr)
+            return 2
+
+    if args.max_hr:
+        zones = from_max_hr(args.max_hr)
+    if zones is None:
+        print(
+            "No heart-rate zones: pass --max-hr, or use the garmin source to read yours.",
+            file=sys.stderr,
+        )
+        return 2
+    if not runs:
+        print("No running activities found.", file=sys.stderr)
+        return 1
+
+    zones = replace(zones, easy_up_to=args.easy_up_to)
+    # From the API, load is measured to today, so a week off shows as a week off.
+    as_of = date.today() if args.source == "garmin" else None
+    report = analyse(runs, zones, as_of=as_of)
+    print(render_json(report) if args.json else render_text(report))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())