fitdocs 0.1.0__py3-none-any.whl

fitdocs/__init__.py

@@ -0,0 +1,125 @@
+"""fitdocs: a pure library that decodes ``.fit`` files into a typed activity
+model and computes derived metrics.
+
+The package root is the top-level composition point -- not a layer -- so it
+publishes exactly one stable public API drawn from *both*
+:mod:`fitdocs.ingest` and :mod:`fitdocs.metrics`:
+
+- the two entry points, :func:`~fitdocs.ingest.parse_fit` (bytes/path ->
+  :class:`~fitdocs.model.Activity`) and
+  :func:`~fitdocs.metrics.compute_metrics` (Activity + athlete inputs ->
+  :class:`~fitdocs.metrics.types.DerivedMetrics`);
+- the activity-model types plus the ``SCHEMA_VERSION`` / ``fit_datetime``
+  helpers (:mod:`fitdocs.model`);
+- the metric-input and result contracts (:mod:`fitdocs.metrics.types`),
+  including :class:`~fitdocs.metrics.types.TrimpWeighting` -- a caller has no
+  type-checked way to state a training-impulse weighting selection (Req 17.1)
+  without importing the type that names it;
+- the decode error taxonomy (:mod:`fitdocs.ingest.errors`).
+
+**Re-exports are lazy** (PEP 562 module ``__getattr__``): the names above are
+resolved from their defining submodule only on first access, and the resolution
+always reads a concrete submodule, never the ``fitdocs`` package name, so no
+circular import can arise. Laziness is deliberate, not incidental -- it keeps
+``import fitdocs.model`` free of the ``garmin-fit-sdk`` (which
+:mod:`fitdocs.ingest` imports): the model stays consumable with zero FIT-format
+knowledge (Req 2.6), and the SDK loads only when a caller actually reaches for
+:func:`parse_fit`. Static tooling still sees fully typed re-exports via the
+``TYPE_CHECKING`` block; ``__all__`` lists the complete public surface.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Statically-visible, fully typed re-exports for type checkers and IDEs.
+    # The redundant ``as`` aliases mark each name as an explicit re-export.
+    from fitdocs.ingest import parse_fit as parse_fit
+    from fitdocs.ingest.errors import FitDecodeError as FitDecodeError
+    from fitdocs.ingest.errors import FitIntegrityError as FitIntegrityError
+    from fitdocs.ingest.errors import NotFitFileError as NotFitFileError
+    from fitdocs.metrics import compute_metrics as compute_metrics
+    from fitdocs.metrics.types import AthleteInputs as AthleteInputs
+    from fitdocs.metrics.types import DerivedMetrics as DerivedMetrics
+    from fitdocs.metrics.types import TrimpWeighting as TrimpWeighting
+    from fitdocs.metrics.types import ZoneSpec as ZoneSpec
+    from fitdocs.model import SCHEMA_VERSION as SCHEMA_VERSION
+    from fitdocs.model import Activity as Activity
+    from fitdocs.model import DeviceInfo as DeviceInfo
+    from fitdocs.model import Lap as Lap
+    from fitdocs.model import Modality as Modality
+    from fitdocs.model import Provenance as Provenance
+    from fitdocs.model import Samples as Samples
+    from fitdocs.model import SessionSummary as SessionSummary
+    from fitdocs.model import Sport as Sport
+    from fitdocs.model import StrengthSet as StrengthSet
+    from fitdocs.model import fit_datetime as fit_datetime
+
+# Public name -> (defining submodule, attribute) for lazy runtime resolution.
+_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
+    "parse_fit": ("fitdocs.ingest", "parse_fit"),
+    "compute_metrics": ("fitdocs.metrics", "compute_metrics"),
+    "Activity": ("fitdocs.model", "Activity"),
+    "Samples": ("fitdocs.model", "Samples"),
+    "SessionSummary": ("fitdocs.model", "SessionSummary"),
+    "Lap": ("fitdocs.model", "Lap"),
+    "StrengthSet": ("fitdocs.model", "StrengthSet"),
+    "DeviceInfo": ("fitdocs.model", "DeviceInfo"),
+    "Provenance": ("fitdocs.model", "Provenance"),
+    "Sport": ("fitdocs.model", "Sport"),
+    "Modality": ("fitdocs.model", "Modality"),
+    "SCHEMA_VERSION": ("fitdocs.model", "SCHEMA_VERSION"),
+    "fit_datetime": ("fitdocs.model", "fit_datetime"),
+    "AthleteInputs": ("fitdocs.metrics.types", "AthleteInputs"),
+    "ZoneSpec": ("fitdocs.metrics.types", "ZoneSpec"),
+    "DerivedMetrics": ("fitdocs.metrics.types", "DerivedMetrics"),
+    "TrimpWeighting": ("fitdocs.metrics.types", "TrimpWeighting"),
+    "FitDecodeError": ("fitdocs.ingest.errors", "FitDecodeError"),
+    "NotFitFileError": ("fitdocs.ingest.errors", "NotFitFileError"),
+    "FitIntegrityError": ("fitdocs.ingest.errors", "FitIntegrityError"),
+}
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "Activity",
+    "AthleteInputs",
+    "DerivedMetrics",
+    "DeviceInfo",
+    "FitDecodeError",
+    "FitIntegrityError",
+    "Lap",
+    "Modality",
+    "NotFitFileError",
+    "Provenance",
+    "Samples",
+    "SessionSummary",
+    "Sport",
+    "StrengthSet",
+    "TrimpWeighting",
+    "ZoneSpec",
+    "compute_metrics",
+    "fit_datetime",
+    "parse_fit",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Resolve a public re-export lazily from its defining submodule (PEP 562).
+
+    The resolved object is cached back onto the module globals so later access
+    skips this hook. Unknown names raise :class:`AttributeError` as usual.
+    """
+    try:
+        module_name, attr = _LAZY_EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    value = getattr(importlib.import_module(module_name), attr)
+    globals()[name] = value  # cache: subsequent lookups bypass __getattr__
+    return value
+
+
+def __dir__() -> list[str]:
+    """Include the lazy public names in ``dir(fitdocs)``."""
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))

fitdocs/agentskill.py

@@ -0,0 +1,105 @@
+"""The packaged-skill registry and by-name locator (design: AgentSkillLocator).
+
+fitdocs ships one or more "agent skills" -- self-contained markdown
+directories an LLM agent copies into its own skills directory -- inside the
+installed package under :data:`SKILLS_DIR`. This module is the *one*
+mechanism every packaged skill is located through: a declared registry of
+names (:data:`PACKAGED_SKILLS`), not a directory scan, so a skill can never
+silently fall out of the wheel while a scan-based listing still looks
+"correct". The CLI's ``skill`` command and every test that needs a skill's
+installed location resolve it here.
+
+Two skills are registered today: :data:`BLOCK_SKILL_NAME`
+(``build-training-block``, an athlete-facing plan-authoring workflow) and
+:data:`INBOX_SKILL_NAME` (``fitdocs-workouts``, the turnkey inbox-drain
+workflow for an LLM-managed wiki, distribution task 4.2). Both live under
+:data:`PACKAGED_SKILLS` in registration order; nothing about resolution
+distinguishes one registered name from another.
+
+Resolution goes through :func:`importlib.resources.files`, bound at module
+level (rather than imported and called inline) so a test has exactly one
+attribute to monkeypatch: ``fitdocs.agentskill.files``. Nothing happens at
+import time -- every function below does its filesystem work when called, not
+when this module is imported -- and a root is only ever *present* when it
+resolves to a real directory holding :data:`SKILL_FILENAME`; any other case
+(missing name, missing directory, missing file, or a zipped/import-time
+resource that has no real filesystem path) resolves as absent (``None`` or
+``()``), never an exception. A zipped install (for example a zipapp or an
+egg whose resources are not extracted to disk) therefore degrades to "the
+skill is absent" rather than raising -- callers that want to *fail* on an
+incomplete installation (the CLI command) turn that absence into their own
+error path.
+
+This module imports nothing from :mod:`fitdocs`: it is a pure leaf, holds no
+package-wide state, and is not part of :data:`fitdocs.__all__`.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+from typing import Final
+
+SKILLS_DIR: Final[str] = "skills"
+SKILL_FILENAME: Final[str] = "SKILL.md"
+BLOCK_SKILL_NAME: Final[str] = "build-training-block"
+INBOX_SKILL_NAME: Final[str] = "fitdocs-workouts"
+PACKAGED_SKILLS: Final[tuple[str, ...]] = (BLOCK_SKILL_NAME, INBOX_SKILL_NAME)
+
+
+def _resolved_directory(name: str) -> Path | None:
+    """Return the filesystem directory for ``name``'s package resource, or ``None``.
+
+    Converts the :class:`importlib.resources.abc.Traversable` returned by
+    ``files()`` to a :class:`~pathlib.Path` via ``str()`` -- the documented way
+    to obtain a filesystem path for an unzipped install, which every supported
+    fitdocs install is -- and guards that the result both exists and is a
+    directory before returning it.
+    """
+    traversable = files("fitdocs") / SKILLS_DIR / name
+    candidate = Path(str(traversable))
+    if not candidate.is_dir():
+        return None
+    return candidate
+
+
+def skill_root(name: str) -> Path | None:
+    """The installed directory for the packaged skill ``name``, or ``None``.
+
+    Present iff ``name`` resolves to a real directory that itself holds
+    :data:`SKILL_FILENAME`. Never raises: an unregistered name, a packaging
+    defect that dropped the directory or the file, or a zipped import all
+    resolve as absent.
+    """
+    directory = _resolved_directory(name)
+    if directory is None:
+        return None
+    if not (directory / SKILL_FILENAME).is_file():
+        return None
+    return directory
+
+
+def skill_file(name: str) -> Path | None:
+    """``skill_root(name) / SKILL_FILENAME``, or ``None`` when the root is absent."""
+    root = skill_root(name)
+    if root is None:
+        return None
+    return root / SKILL_FILENAME
+
+
+def skill_files(name: str) -> tuple[Path, ...]:
+    """Every regular file under ``name``'s root, sorted by relative POSIX path.
+
+    ``()`` when the root is absent. This is the one source of truth for "the
+    skill's files": the wheel-membership test and the installation copy
+    recipe both read it.
+    """
+    root = skill_root(name)
+    if root is None:
+        return ()
+    return tuple(
+        sorted(
+            (path for path in root.rglob("*") if path.is_file()),
+            key=lambda path: path.relative_to(root).as_posix(),
+        )
+    )

fitdocs/athlete.py

@@ -0,0 +1,183 @@
+"""Read-only athlete-inputs reader (Req 8.3).
+
+This module maps an *optional* ``<data_root>/athlete.toml`` onto the fit-ingest
+:class:`~fitdocs.AthleteInputs` / :class:`~fitdocs.ZoneSpec` contract (design:
+AthleteInputsReader). The athlete-inputs source is what unlocks the zone strip
+(Req 8.1) and the threshold-dependent metrics -- intensity factor, training
+stress, TRIMP (Req 8.4) -- downstream; this layer only *reads* it.
+
+Two invariants shape the contract:
+
+* **Optional.** An absent file yields ``None`` -- not an error. The whole
+  feature set that depends on athlete inputs simply degrades to omission.
+* **Loud, never lossy.** A file that exists but is malformed -- invalid TOML, a
+  wrong value type, a boolean where a number is expected, or non-ascending /
+  empty zone dividers -- raises :class:`AthleteFileError`. Silently dropping a
+  bad zone would change the rendered document invisibly, so nothing is swallowed.
+
+The reader is read-only *by construction* (Req 8.3): it never creates the file,
+never prompts, and writes nothing on any path. Profile creation, prompting, and
+the file's lifecycle belong to the downstream training-load feature, which may
+add keys -- so **unknown keys are ignored** for forward compatibility.
+
+Types are validated strictly. Because Python's ``bool`` is a subclass of
+``int``, a TOML boolean would otherwise sneak through as ``0``/``1``; it is
+rejected everywhere a number is required. Integer thresholds (``resting_hr_bpm``,
+``max_hr_bpm``) require a TOML integer; ``ftp_watts`` accepts a TOML integer or
+float and is normalized to ``float``.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Final
+
+from fitdocs import AthleteInputs, ZoneSpec
+
+ATHLETE_FILE: Final[str] = "athlete.toml"
+
+ATHLETE_SCHEMA_VERSION: Final[int] = 2
+"""Schema version stamped into and required of ``athlete.toml``.
+
+1 = flat athlete-input keys only (the shipped shape); 2 adds ``[benchmarks]``.
+"""
+
+VERSION_KEY: Final[str] = "profile_version"
+"""The existing on-disk key name, kept unchanged for file compatibility."""
+
+
+class AthleteFileError(Exception):
+    """The ``athlete.toml`` file exists but cannot be read as valid inputs.
+
+    Raised for malformed TOML, a wrong value type (including a boolean where a
+    number is required), non-ascending / empty zone dividers, or a declared
+    schema version this fitdocs does not recognize. An *absent* file is never
+    an error -- it yields ``None`` instead. The message names the file and the
+    offending key so a user can correct the configuration.
+    """
+
+
+def check_schema_version(document: Mapping[str, object], path: Path) -> int:
+    """Read and validate the declared schema version of a decoded ``athlete.toml``.
+
+    An absent :data:`VERSION_KEY` is treated as version 1, the earliest schema
+    (Req 1.8), and any benchmarks present are still read regardless of the
+    declared version, so long as it is one this fitdocs supports (Req 1.6) --
+    the version gates *forward* only.
+
+    Raises :class:`AthleteFileError` naming *path*, the declared version and
+    the supported version when the value is not a plain integer (a TOML
+    boolean is rejected even though ``bool`` subclasses ``int``), is below 1,
+    or is greater than :data:`ATHLETE_SCHEMA_VERSION` (Req 1.7).
+    """
+    if VERSION_KEY not in document:
+        return 1
+
+    value = document[VERSION_KEY]
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise AthleteFileError(
+            f"{path}: {VERSION_KEY} must be an integer between 1 and "
+            f"{ATHLETE_SCHEMA_VERSION} (the version this fitdocs supports), "
+            f"got {value!r} ({type(value).__name__})"
+        )
+    if value > ATHLETE_SCHEMA_VERSION:
+        raise AthleteFileError(
+            f"{path} declares {VERSION_KEY} = {value}, which is newer than "
+            f"the schema version this fitdocs supports "
+            f"({ATHLETE_SCHEMA_VERSION}); install a newer fitdocs to read it"
+        )
+    return value
+
+
+def load_athlete_inputs(data_root: Path) -> AthleteInputs | None:
+    """Read ``<data_root>/athlete.toml`` into :class:`AthleteInputs`, or ``None``.
+
+    Returns ``None`` when the file is absent -- the inputs are optional (Req
+    8.3). Otherwise every recognized key is mapped onto the corresponding
+    :class:`AthleteInputs` field (present keys only; the rest stay ``None``), and
+    unknown keys are ignored for forward compatibility with training-load.
+
+    Raises :class:`AthleteFileError` when the file exists but is malformed:
+    invalid TOML, a wrong value type, a boolean where a number is expected, or
+    zone dividers that are empty or not strictly ascending (the last surfaced by
+    :class:`~fitdocs.ZoneSpec` and re-raised here). The function only ever reads;
+    it never writes, creates, or prompts.
+    """
+    path = data_root / ATHLETE_FILE
+    if not path.is_file():
+        return None
+
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except tomllib.TOMLDecodeError as exc:
+        raise AthleteFileError(f"{path} is not valid TOML: {exc}") from exc
+
+    check_schema_version(data, path)
+
+    return AthleteInputs(
+        ftp_watts=_optional_number(data, "ftp_watts", path),
+        resting_hr_bpm=_optional_int(data, "resting_hr_bpm", path),
+        max_hr_bpm=_optional_int(data, "max_hr_bpm", path),
+        hr_zones=_optional_zone(data, "hr_zones", path),
+        power_zones=_optional_zone(data, "power_zones", path),
+        pace_zones=_optional_zone(data, "pace_zones", path),
+    )
+
+
+def _optional_number(data: dict[str, Any], key: str, path: Path) -> float | None:
+    """Map an optional numeric threshold to ``float``; reject non-numbers/bools."""
+    if key not in data:
+        return None
+    value = data[key]
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise AthleteFileError(
+            f"{path}: {key} must be a number, got {value!r} ({type(value).__name__})"
+        )
+    return float(value)
+
+
+def _optional_int(data: dict[str, Any], key: str, path: Path) -> int | None:
+    """Map an optional integer threshold; reject floats and bools strictly."""
+    if key not in data:
+        return None
+    value = data[key]
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise AthleteFileError(
+            f"{path}: {key} must be an integer, got {value!r} ({type(value).__name__})"
+        )
+    return value
+
+
+def _optional_zone(data: dict[str, Any], key: str, path: Path) -> ZoneSpec | None:
+    """Map an optional list of ascending dividers to a :class:`ZoneSpec`.
+
+    Every element must be a number (a boolean is rejected, never coerced to
+    ``0``/``1``); the ascending / non-empty guarantee is delegated to
+    :class:`ZoneSpec`, whose :class:`ValueError` is re-raised as
+    :class:`AthleteFileError` so a bad list fails loudly instead of vanishing.
+    """
+    if key not in data:
+        return None
+    value = data[key]
+    if not isinstance(value, list):
+        raise AthleteFileError(
+            f"{path}: {key} must be a list of ascending numbers, "
+            f"got {value!r} ({type(value).__name__})"
+        )
+    dividers: list[float] = []
+    for element in value:
+        if isinstance(element, bool) or not isinstance(element, (int, float)):
+            raise AthleteFileError(
+                f"{path}: every {key} divider must be a number, "
+                f"got {element!r} ({type(element).__name__})"
+            )
+        dividers.append(float(element))
+    try:
+        return ZoneSpec(dividers=tuple(dividers))
+    except ValueError as exc:
+        raise AthleteFileError(
+            f"{path}: {key} must be non-empty and strictly ascending ({exc})"
+        ) from exc