repwise 1.0.0__py3-none-any.whl

repwise/__init__.py

@@ -0,0 +1,4 @@
+"""Advance Garmin strength workout targets using double progression."""
+
+__all__ = ["__version__"]
+__version__ = "1.0.0"

repwise/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for `python -m repwise`."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

repwise/app/__init__.py

@@ -0,0 +1,7 @@
+"""The use cases: one module per command, and the report they print.
+
+Each `run_*` function is the whole of a command apart from parsing and
+dispatch. It is handed the things it needs - a Garmin session, a config, its
+options - rather than building them, so nothing here imports argparse and
+nothing here decides what a process exits with beyond returning it.
+"""

repwise/app/checking.py

@@ -0,0 +1,109 @@
+"""Report where workouts.yaml and the Garmin workouts disagree."""
+
+import logging
+
+from ..checker import Finding, check_catalog, check_programming, check_workout
+from ..domain.models import Config, GarminSettings
+from ..errors import ExitCode, GarminError
+from ..garmin.catalog import ExerciseCatalog, ensure
+from ..garmin.client import GarminSession
+from .report import SEVERITY
+
+logger = logging.getLogger(__name__)
+
+
+def _catalog(settings: GarminSettings) -> ExerciseCatalog | None:
+    """Garmin's exercise list, downloaded on the first run that wants it.
+
+    Fetched here rather than demanded of the user, because a check that only
+    works after another command has been run is a check that goes unrun. The
+    copy is cached, so this costs one download ever.
+
+    A failure costs the name checks and nothing else, exactly as a missing
+    weigh-in costs the range checks. `check` is worth running with no network
+    at all, and the questions it can still answer are worth answering.
+    """
+    try:
+        return ensure(settings)
+    except GarminError as exc:
+        logger.warning(f"Exercise names were not checked: {exc}")
+        return None
+
+
+def _bodyweight(session: GarminSession, config: Config) -> float | None:
+    """How much of you the bodyweight-loaded exercises are carrying.
+
+    What the config states wins, since someone who wrote it down means it.
+    Otherwise Garmin is asked, which is the answer that stays current without
+    anyone editing a file. A failure here is not worth failing the command
+    over: it costs the range checks on a few exercises, and `check_programming`
+    reports each of those where it finds them.
+    """
+    if config.bodyweight is not None:
+        return config.bodyweight
+
+    if not any(
+        spec.bodyweight_factor for workout in config for spec in workout.exercises
+    ):
+        return None  # nothing would read it, so do not spend a request on it
+
+    try:
+        weight = session.bodyweight()
+    except GarminError as exc:
+        logger.debug(f"Could not read your weigh-ins: {exc}")
+        return None
+
+    if weight is not None:
+        logger.debug(f"Bodyweight {weight:g} kg, averaged from your Garmin weigh-ins.")
+    return weight
+
+
+def run_check(session: GarminSession, config: Config) -> ExitCode:
+    findings: list[Finding] = []
+    bodyweight = _bodyweight(session, config)
+    catalog = _catalog(config.garmin)
+    for workout in config:
+        workout_id = workout.garmin_workout_id
+        # First, and outside the branch below, because it is the only check
+        # that does not need Garmin to hold the workout. Reported first too: an
+        # exercise that does not exist explains whatever the checks below go on
+        # to say about it, which reads better before them than after.
+        found = check_catalog(workout, catalog) if catalog else []
+
+        if workout_id is None:
+            # Nothing in Garmin to disagree with yet. Said out loud, because
+            # silence here would read as "checked, and fine" - and the names
+            # above were checked, which is the point of doing it now.
+            logger.info(f"{workout.key} (not in Garmin yet)")
+        else:
+            logger.info(f"{workout.key} ({workout_id})")
+            try:
+                payload = session.workout(workout_id)
+            except GarminError as exc:
+                # A workout that cannot be read is itself an error-level
+                # finding, so an unreachable workout still fails the command.
+                found.append(
+                    Finding(
+                        workout.key,
+                        f"could not fetch workout {workout_id}: {exc}",
+                        "error",
+                    )
+                )
+            else:
+                found += check_workout(workout, payload)
+                found += check_programming(workout, payload, bodyweight)
+
+        if not found:
+            logger.info("  ok")
+        for finding in found:
+            marker, level = SEVERITY[finding.severity]
+            logger.log(level, f"  {marker} {finding.detail}")
+        logger.info("")
+        findings.extend(found)
+
+    # Everything reported here needs a hand, so any finding at all fails the
+    # command. That is what makes it worth putting in a cron job: it goes off
+    # when the config is wrong, not when you have edited a rest and not yet
+    # run `update`.
+    logger.info(f"{len(findings)} issue(s) across {len(config.workouts)} workout(s)")
+    return ExitCode.NOTHING_USABLE if findings else ExitCode.OK

repwise/app/fetch.py

@@ -0,0 +1,58 @@
+"""Download what Garmin holds as JSON: your workouts, or its exercise catalog."""
+
+import json
+import logging
+import os
+
+from ..domain.models import Config, GarminSettings
+from ..errors import ExitCode, GarminError
+from ..garmin import catalog
+from ..garmin.client import GarminSession
+
+logger = logging.getLogger(__name__)
+
+
+def run_fetch_exercises(settings: GarminSettings) -> ExitCode:
+    """Download Garmin's exercise catalog, replacing any cached copy.
+
+    Unconditional, unlike the first-run download `check` does for itself:
+    asking for the catalog by name is how you refresh one that has gone stale,
+    so finding a copy already there is not a reason to stop.
+
+    No session is opened. The catalog is public, and requiring a login to
+    download it would be a password prompt in exchange for nothing.
+    """
+    payload = catalog.download()
+    # Parsed for the count, and to fail before overwriting a good cache with a
+    # response that turned out not to be a catalog at all.
+    parsed = catalog.ExerciseCatalog.parse(payload)
+    path = catalog.save(settings, payload)
+    logger.info(
+        f"Saved {len(parsed)} exercises in {len(parsed.categories)} "
+        f"categories -> {path}"
+    )
+    return ExitCode.OK
+
+
+def run_fetch(
+    session: GarminSession, config: Config, workout_ids: list[str] | None = None
+) -> ExitCode:
+    # A workout Garmin does not hold yet has no definition to download, so it
+    # is simply not among the ids rather than a failure to report.
+    ids = workout_ids or [w.garmin_workout_id for w in config if w.garmin_workout_id]
+    failed = False
+    for workout_id in ids:
+        try:
+            payload = session.workout(workout_id)
+        except GarminError as exc:
+            # One unreachable workout should not cost the user the others.
+            logger.error(f"FAILED {workout_id}: {exc}")
+            failed = True
+            continue
+
+        path = os.path.join(config.garmin.dump_dir, f"workout-{workout_id}.json")
+        with open(path, "w") as fh:
+            json.dump(payload, fh, indent=2)
+        logger.info(f"Saved {payload.get('workoutName', '(unnamed)')} -> {path}")
+
+    return ExitCode.NOTHING_USABLE if failed else ExitCode.OK

repwise/app/importing.py

@@ -0,0 +1,72 @@
+"""Turn workouts built in Garmin Connect into workouts.yaml content."""
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from ..errors import ActivityNotFound, ExitCode, UsageError
+from ..garmin.client import STRENGTH, GarminSession
+from ..importer import describe_workout, render_config
+from ..yamlio import write
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ImportOptions:
+    """Which workouts to import, and where the result goes."""
+
+    name: str | None = None
+    id: str | None = None
+    output: str | None = None
+    force: bool = False
+
+
+def select(session: GarminSession, options: ImportOptions) -> list[dict[str, Any]]:
+    """The workout summaries an import should cover."""
+    workouts = session.list_workouts(sport_type=STRENGTH)
+    if options.id:
+        wanted = [w for w in workouts if str(w.get("workoutId")) == options.id]
+        if not wanted:
+            raise ActivityNotFound(f"No strength workout with id {options.id}.")
+        return wanted
+    if options.name:
+        needle = options.name.lower()
+        wanted = [w for w in workouts if needle in (w.get("workoutName") or "").lower()]
+        if not wanted:
+            names = ", ".join(repr(w.get("workoutName")) for w in workouts)
+            raise ActivityNotFound(
+                f"No strength workout matching {options.name!r}. Found: {names}"
+            )
+        return wanted
+    return workouts
+
+
+def run_import(session: GarminSession, options: ImportOptions) -> ExitCode:
+    summaries = select(session, options)
+
+    imported = [
+        describe_workout(session.workout(str(s["workoutId"]))) for s in summaries
+    ]
+    text = render_config(imported)
+
+    if not options.output:
+        # Config content, not a report: written straight out so that it stays
+        # redirectable and never picks up a log prefix.
+        print(text)
+        return ExitCode.OK
+
+    if os.path.exists(options.output) and not options.force:
+        raise UsageError(
+            f"{options.output} already exists. Pass --force to overwrite it."
+        )
+
+    write(options.output, text)
+
+    exercises = sum(len(w.exercises) for w in imported)
+    logger.info(
+        f"Wrote {len(imported)} workout(s), {exercises} exercises -> {options.output}"
+    )
+    logger.info("Check the TODO comments before using it.")
+    return ExitCode.OK

repwise/app/listing.py

@@ -0,0 +1,35 @@
+"""Show the Garmin workouts in the account, with the ids workouts.yaml needs."""
+
+import logging
+
+from ..domain.models import Config
+from ..errors import ExitCode
+from ..garmin.client import STRENGTH, GarminSession
+
+logger = logging.getLogger(__name__)
+
+
+def run_list(
+    session: GarminSession, config: Config, every_sport: bool = False
+) -> ExitCode:
+    workouts = session.list_workouts(sport_type=None if every_sport else STRENGTH)
+
+    if not workouts:
+        logger.warning("No workouts found.")
+        return ExitCode.NOTHING_USABLE
+
+    known = {w.garmin_workout_id for w in config if w.garmin_workout_id}
+    logger.info(f"{'ID':<12} {'UPDATED':<11} {'':<3}NAME")
+    for entry in workouts:
+        workout_id = str(entry.get("workoutId"))
+        updated = (entry.get("updateDate") or "")[:10]
+        mark = "*" if workout_id in known else " "
+        name = entry.get("workoutName") or "(unnamed)"
+        if every_sport:
+            kind = (entry.get("sportType") or {}).get("sportTypeKey", "?")
+            name = f"{name}  [{kind}]"
+        logger.info(f"{workout_id:<12} {updated:<11} {mark:<3}{name}")
+
+    logger.info("")
+    logger.info(f"{len(workouts)} workout(s); * already in your config")
+    return ExitCode.OK

repwise/app/report.py

@@ -0,0 +1,170 @@
+"""How a change, a plan and a finding are printed.
+
+Report lines go out through the standard library logger, the way `log.py`
+describes: INFO is the report the user asked for and lands on stdout, WARNING
+and above are problems and land on stderr. A use case therefore emits its
+report without knowing where the report goes - only `main()` decides that.
+"""
+
+import logging
+
+from ..domain.models import ExerciseSpec
+from ..domain.progression import Target
+from ..planner import (
+    Change,
+    GapChange,
+    NoteChange,
+    Plan,
+    RestChange,
+    SetChange,
+    SkipChange,
+    StructureChange,
+)
+
+logger = logging.getLogger(__name__)
+
+#: How `check` shows a finding: the marker that survives a plain run, and the
+#: level it is logged at, so severity outlives a redirect of stdout too. Both
+#: levels are things to go and fix - an error stops the exercise working at
+#: all, a warning means it works by luck - and both fail the command.
+SEVERITY = {
+    "error": ("!!", logging.ERROR),
+    "warning": (" !", logging.WARNING),
+}
+
+#: How wide the before and after columns are. Enough for a target written out
+#: set by set - `9,9,8,8 x 30 kg` - so that a ramp does not push every reason
+#: beside it out of line.
+COLUMN = 17
+
+
+def describe(spec: ExerciseSpec, target: Target) -> str:
+    """Render a target the way the exercise is actually measured.
+
+    A ramped target is written out set by set - `9,9,8,8` - because the whole
+    point of it is that the sets differ, and a single figure could only ever
+    name one of them.
+    """
+    figure = target.spread(spec.sets, spec.rep_step)
+    if spec.time_based:
+        return f"{figure} s"
+    if spec.bodyweight:
+        return f"{figure} reps"
+    return f"{figure} x {target.weight:g} kg"
+
+
+def report_change(change: Change, force_flag: str | None = None) -> None:
+    flag = force_flag or ("*" if change.moved else " ")
+    logger.info(
+        f"{flag} {change.spec.name:<40}"
+        f" {describe(change.spec, change.old):>{COLUMN}}"
+        f"  ->  {describe(change.spec, change.new):<{COLUMN}} ({change.reason})"
+    )
+
+
+def report_prescribed(name: str, old: str, new: str, source: str) -> None:
+    """A number workouts.yaml moved, in the same columns as a target.
+
+    Shown like a target rather than hidden like a note: these change how the
+    workout is performed, and are on the watch from the next sync.
+    """
+    logger.info(f"* {name:<40} {old:>{COLUMN}}  ->  {new:<{COLUMN}} ({source})")
+
+
+def report_note(change: NoteChange) -> None:
+    """The one-line note the watch shows, which workouts.yaml also decides.
+
+    Shown rather than hidden because a config edit that only touches the
+    programming - a rep range, a weight step - moves no target at all, and the
+    run would otherwise say every exercise is up to date while still having a
+    reason to write.
+    """
+    report_prescribed(
+        change.spec.name,
+        change.old or "no note",
+        change.new,
+        "note from workouts.yaml",
+    )
+
+
+def report_rest(change: RestChange) -> None:
+    report_prescribed(
+        change.spec.name,
+        f"{change.old} s rest",
+        f"{change.new} s rest",
+        "rest from workouts.yaml",
+    )
+
+
+def report_sets(change: SetChange) -> None:
+    report_prescribed(
+        change.spec.name,
+        f"{change.old} sets",
+        f"{change.new} sets",
+        "sets from workouts.yaml",
+    )
+
+
+def report_skips(change: SkipChange) -> None:
+    """A group that had been dropping the rest after its final set."""
+    report_prescribed(
+        change.spec.name,
+        "no last rest",
+        "rest after every set",
+        "was skipping the last rest",
+    )
+
+
+def report_gaps(change: GapChange) -> None:
+    """The rest between exercises: one line for the workout, not one per gap."""
+    report_prescribed(
+        "Between exercises",
+        change.before,
+        f"{change.new} s rest",
+        f"{change.gaps} gap(s), from workouts.yaml",
+    )
+
+
+#: The marker each kind of structural change prints under. Deliberately not
+#: `*`: these change what the workout is, not what it asks of you.
+STRUCTURE = {"added": "+", "removed": "-", "moved": "~"}
+
+
+def report_structure(change: StructureChange) -> None:
+    """An exercise the config added, dropped, or put somewhere else."""
+    if change.kind == "added" and change.spec and change.target:
+        detail = (
+            f"new at position {change.position}, "
+            f"{change.spec.sets} x {describe(change.spec, change.target)}"
+        )
+    elif change.kind == "removed":
+        detail = "removed: no longer in workouts.yaml"
+    else:
+        detail = f"moved to position {change.position}"
+
+    logger.info(f"{STRUCTURE.get(change.kind, ' ')} {change.name:<40} {detail}")
+
+
+def report_plan(plan: Plan, force_flag: str | None = None) -> None:
+    # Structure first: what a workout holds has to make sense before what each
+    # of its exercises is asking for does.
+    for shape in plan.structure:
+        report_structure(shape)
+    for change in plan.changes:
+        report_change(change, force_flag)
+    for count in plan.sets:
+        report_sets(count)
+    for rest in plan.rests:
+        report_rest(rest)
+    for skip in plan.skips:
+        report_skips(skip)
+    if plan.gaps:
+        report_gaps(plan.gaps)
+    # Last of the config-driven lines, as in the closing summary: a note says
+    # how an exercise is programmed rather than what it asks of you today.
+    for note in plan.notes:
+        report_note(note)
+    for warning in plan.warnings:
+        # The marker survives the move to logging: it still sets a warning
+        # apart when the level itself is not shown.
+        logger.warning(f"  ! {warning}")