activity-parser 0.9.0__tar.gz → 0.11.0__tar.gz

{activity_parser-0.9.0 → activity_parser-0.11.0}/.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
         name: ruff format
         entry: uv run ruff format
         language: system
-        types: [python]
+        types_or: [python, markdown]
 
       - id: pyright
         name: pyright

activity_parser-0.11.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: activity-parser
+Version: 0.11.0
+Summary: Parser for loading FIT, TCX and GPX files into Pandas DataFrames.
+Project-URL: Repository, https://github.com/tabishm52/activity_parser
+Project-URL: Issues, https://github.com/tabishm52/activity_parser/issues
+Author-email: Tabish Mustufa <tabishm@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fit,fitness,gps,gpx,pandas,parser,tcx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.11
+Requires-Dist: garmin-fit-sdk
+Requires-Dist: lxml
+Requires-Dist: pandas
+Description-Content-Type: text/markdown
+
+# activity-parser
+
+[![CI](https://github.com/tabishm52/activity_parser/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tabishm52/activity_parser/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/activity-parser)](https://pypi.org/project/activity-parser/)
+[![Python versions](https://img.shields.io/pypi/pyversions/activity-parser)](https://pypi.org/project/activity-parser/)
+[![License](https://img.shields.io/pypi/l/activity-parser)](https://pypi.org/project/activity-parser/)
+
+Parser for loading FIT, TCX and GPX activity files into Pandas DataFrames.
+
+Provides a parser object for reading (optionally gzipped) FIT, TCX, and GPX activity files and converting them into Pandas DataFrames.
+During import, field names extracted from activity files are normalized into a canonical set of output column names with consistent units to allow for standardized downstream data processing.
+
+## Installation
+
+```bash
+pip install activity-parser
+```
+
+## Usage
+
+Create a new instance of the `ActivityParser` class to be reused for subsequent parsing of activity files:
+
+```python
+import activity_parser
+
+parser = activity_parser.ActivityParser()
+```
+
+Parse FIT, TCX and GPX files into normalized DataFrames:
+
+```python
+from activity_parser import ParseError
+
+try:
+    records, laps, activity = parser.parse("path/to/fit_file.fit")
+    records, laps, activity = parser.parse("path/to/gpx_file.gpx")
+    records, laps, activity = parser.parse("path/to/tcx_file.tcx")
+except ParseError as e:
+    ...
+```
+
+Each file is assumed to contain a single activity.
+Multiple activities/tracks (chained FIT files, multi-activity TCX, multi-track GPX) have their records/laps merged into one set of results.
+In those cases, the returned `Activity` summary reflects only the first activity/session in the file.
+
+`parse()` raises `ParseError` (`FitError` for FIT files, `XmlError` for TCX/GPX) when a file fails to parse.
+It raises `ValueError` for an unrecognized or ambiguous file type.
+
+## Output data
+
+`records` and `laps` are each a DataFrame of normalized data, e.g.:
+
+```
+                           distance  speed  cadence  heart_rate
+time
+2026-01-05 08:00:00+00:00      0.00   36.0       80         100
+2026-01-05 08:00:01+00:00      0.01   36.0       81         101
+```
+
+A few notes on column handling:
+
+- Column names and units are standardized across source formats for known field types.
+- Unknown fields are omitted by default; customize columns via `record_columns`, `lap_columns`, and `include_all_columns` on `ActivityParser` — see its docstring for details.
+- Not every column appears in every file: `parse()` only includes columns actually present.
+
+### Records
+
+Not all fields are available in all source formats.
+Fields marked with (\*) are exporter-dependent.
+
+| Column | Unit | FIT | TCX | GPX |
+|---|---|:-:|:-:|:-:|
+| `latitude`, `longitude` | degrees | Yes | Yes | Yes |
+| `altitude` | meters | Yes | Yes | Yes |
+| `distance` | km | Yes | Yes | (\*) |
+| `speed` | km/h | Yes | (\*) | (\*) |
+| `cadence` | rpm | Yes | Yes | (\*) |
+| `heart_rate` | bpm | Yes | Yes | (\*) |
+| `power` | watts | Yes | (\*) | (\*) |
+| `left_balance`, `right_balance` | percent | Yes | — | — |
+| `accumulated_power` | watts | Yes | — | — |
+| `temperature` | °C | Yes | — | (\*) |
+| `water_temperature` | °C | — | — | (\*) |
+| `depth` | meters | — | — | (\*) |
+| `course`, `bearing` | degrees | — | — | (\*) |
+
+### Laps
+
+GPX files have no lap data, so `laps` is always an empty DataFrame for GPX.
+Fields marked with (\*) are exporter-dependent.
+
+| Column | Unit | FIT | TCX |
+|---|---|:-:|:-:|
+| `start_time` | timestamp | Yes | Yes |
+| `total_elapsed_time` | seconds | Yes | Yes |
+| `total_timer_time` | seconds | Yes | — |
+| `start_position_lat`, `start_position_long` | degrees | Yes | — |
+| `end_position_lat`, `end_position_long` | degrees | Yes | — |
+| `total_distance` | km | Yes | Yes |
+| `total_ascent`, `total_descent` | meters | Yes | — |
+| `avg_vam` | m/s | Yes | — |
+| `avg_speed` | km/h | Yes | (\*) |
+| `max_speed` | km/h | Yes | Yes |
+| `avg_cadence` | rpm | Yes | Yes |
+| `max_cadence` | rpm | Yes | (\*) |
+| `total_strokes` | count | Yes | — |
+| `steps` | count | — | (\*) |
+| `avg_heart_rate`, `max_heart_rate` | bpm | Yes | Yes |
+| `time_in_hr_zone` | seconds | Yes | — |
+| `avg_power`, `max_power` | watts | Yes | (\*) |
+| `normalized_power` | watts | Yes | — |
+| `left_balance`, `right_balance` | percent | Yes | — |
+| `time_in_power_zone` | seconds | Yes | — |
+| `total_work` | joules | Yes | — |
+| `avg_temperature`, `max_temperature` | °C | Yes | — |
+| `total_calories` | kcal | Yes | Yes |
+| `total_fat_calories` | kcal | Yes | — |
+
+### Activity
+
+`activity` is an `Activity` dataclass instance: a small file-level summary.
+Fields are `None` when the source format/file doesn't record them.
+Values come from the file's own summary fields, never computed/derived from records or laps.
+
+| Field | Unit | FIT | TCX | GPX |
+|---|---|:-:|:-:|:-:|
+| `sport` | — | Yes | Yes | — |
+| `start_time` | — | Yes | Yes | Yes (\*) |
+| `total_elapsed_time` | seconds | Yes | — | — |
+| `total_distance` | km | Yes | — | — |
+| `total_calories` | kcal | Yes | — | — |
+| `avg_heart_rate`, `max_heart_rate` | bpm | Yes | — | — |
+| `avg_speed`, `max_speed` | km/h | Yes | — | — |
+| `creator` | — | Yes | Yes | Yes |
+| `notes` | — | — | Yes | Yes |
+
+(\*) GPX's `start_time` comes from `metadata/time`, which is technically the file's export time rather than the activity's start.
+
+## Parser notes
+
+### FIT files
+
+FIT parsing wraps [`garmin-fit-sdk`](https://pypi.org/project/garmin-fit-sdk/), Garmin's official SDK, which decodes against the public FIT SDK profile.
+
+`parse()` transforms certain FIT fields beyond decoding:
+
+- Positions are converted to degrees, distances to km, and speeds to km/h.
+  Vertical rates (`avg_vam`, `vertical_speed`, and similar) stay in m/s.
+- For fields with lower- and higher-precision versions, only the higher-precision value is returned, under the base field's name.
+- For fields with sub-integer precision in a separate field, the precision is added into the base field.
+- `left_right_balance` (a bit-packed field) is decoded into `left_balance`/`right_balance`.
+- `heart_rate` is merged with a higher-rate `hr` stream when the file has one.
+  Records outside its coverage keep their own device value.
+
+Messages/fields that can't be resolved against the FIT profile (e.g. proprietary extensions) are kept as raw values under `unknown_<n>` names.
+Developer fields are resolved to their file-embedded names and flattened into ordinary columns alongside built-in fields.
+
+`parse_fit` and `parse_fit_raw` are the lower-level functions `ActivityParser.parse()` wraps for FIT files.
+`parse_fit` returns the same canonical `(records, laps, activity)` shape, but without column curation.
+`parse_fit_raw` returns every message type in the file as its own uncurated DataFrame, in FIT-native units (semicircles, meters, m/s).
+
+### TCX & GPX files
+
+TCX and GPX files are parsed natively in this package using [`lxml`](https://pypi.org/project/lxml/).
+Recognized elements and attributes are mapped onto the same canonical column names as FIT, with the same unit conventions.
+
+The parser supports the following schema versions and extensions:
+
+| Format | Schema version | Extensions |
+|---|---|---|
+| TCX | v2 | Garmin `ActivityExtension` v2 |
+| GPX | 1.0 / 1.1 | Garmin `TrackPointExtension` v1/v2, Cluetrust `gpxdata` |
+
+Unrecognized elements and attributes are exported as string columns named with their XML namespace in Clark notation.
+
+`parse_gpx` and `parse_tcx` are the lower-level functions `ActivityParser.parse()` wraps for these formats.
+They return the same canonical `(records, laps, activity)` shape, but without column curation.

activity_parser-0.11.0/README.md

@@ -0,0 +1,177 @@
+# activity-parser
+
+[![CI](https://github.com/tabishm52/activity_parser/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tabishm52/activity_parser/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/activity-parser)](https://pypi.org/project/activity-parser/)
+[![Python versions](https://img.shields.io/pypi/pyversions/activity-parser)](https://pypi.org/project/activity-parser/)
+[![License](https://img.shields.io/pypi/l/activity-parser)](https://pypi.org/project/activity-parser/)
+
+Parser for loading FIT, TCX and GPX activity files into Pandas DataFrames.
+
+Provides a parser object for reading (optionally gzipped) FIT, TCX, and GPX activity files and converting them into Pandas DataFrames.
+During import, field names extracted from activity files are normalized into a canonical set of output column names with consistent units to allow for standardized downstream data processing.
+
+## Installation
+
+```bash
+pip install activity-parser
+```
+
+## Usage
+
+Create a new instance of the `ActivityParser` class to be reused for subsequent parsing of activity files:
+
+```python
+import activity_parser
+
+parser = activity_parser.ActivityParser()
+```
+
+Parse FIT, TCX and GPX files into normalized DataFrames:
+
+```python
+from activity_parser import ParseError
+
+try:
+    records, laps, activity = parser.parse("path/to/fit_file.fit")
+    records, laps, activity = parser.parse("path/to/gpx_file.gpx")
+    records, laps, activity = parser.parse("path/to/tcx_file.tcx")
+except ParseError as e:
+    ...
+```
+
+Each file is assumed to contain a single activity.
+Multiple activities/tracks (chained FIT files, multi-activity TCX, multi-track GPX) have their records/laps merged into one set of results.
+In those cases, the returned `Activity` summary reflects only the first activity/session in the file.
+
+`parse()` raises `ParseError` (`FitError` for FIT files, `XmlError` for TCX/GPX) when a file fails to parse.
+It raises `ValueError` for an unrecognized or ambiguous file type.
+
+## Output data
+
+`records` and `laps` are each a DataFrame of normalized data, e.g.:
+
+```
+                           distance  speed  cadence  heart_rate
+time
+2026-01-05 08:00:00+00:00      0.00   36.0       80         100
+2026-01-05 08:00:01+00:00      0.01   36.0       81         101
+```
+
+A few notes on column handling:
+
+- Column names and units are standardized across source formats for known field types.
+- Unknown fields are omitted by default; customize columns via `record_columns`, `lap_columns`, and `include_all_columns` on `ActivityParser` — see its docstring for details.
+- Not every column appears in every file: `parse()` only includes columns actually present.
+
+### Records
+
+Not all fields are available in all source formats.
+Fields marked with (\*) are exporter-dependent.
+
+| Column | Unit | FIT | TCX | GPX |
+|---|---|:-:|:-:|:-:|
+| `latitude`, `longitude` | degrees | Yes | Yes | Yes |
+| `altitude` | meters | Yes | Yes | Yes |
+| `distance` | km | Yes | Yes | (\*) |
+| `speed` | km/h | Yes | (\*) | (\*) |
+| `cadence` | rpm | Yes | Yes | (\*) |
+| `heart_rate` | bpm | Yes | Yes | (\*) |
+| `power` | watts | Yes | (\*) | (\*) |
+| `left_balance`, `right_balance` | percent | Yes | — | — |
+| `accumulated_power` | watts | Yes | — | — |
+| `temperature` | °C | Yes | — | (\*) |
+| `water_temperature` | °C | — | — | (\*) |
+| `depth` | meters | — | — | (\*) |
+| `course`, `bearing` | degrees | — | — | (\*) |
+
+### Laps
+
+GPX files have no lap data, so `laps` is always an empty DataFrame for GPX.
+Fields marked with (\*) are exporter-dependent.
+
+| Column | Unit | FIT | TCX |
+|---|---|:-:|:-:|
+| `start_time` | timestamp | Yes | Yes |
+| `total_elapsed_time` | seconds | Yes | Yes |
+| `total_timer_time` | seconds | Yes | — |
+| `start_position_lat`, `start_position_long` | degrees | Yes | — |
+| `end_position_lat`, `end_position_long` | degrees | Yes | — |
+| `total_distance` | km | Yes | Yes |
+| `total_ascent`, `total_descent` | meters | Yes | — |
+| `avg_vam` | m/s | Yes | — |
+| `avg_speed` | km/h | Yes | (\*) |
+| `max_speed` | km/h | Yes | Yes |
+| `avg_cadence` | rpm | Yes | Yes |
+| `max_cadence` | rpm | Yes | (\*) |
+| `total_strokes` | count | Yes | — |
+| `steps` | count | — | (\*) |
+| `avg_heart_rate`, `max_heart_rate` | bpm | Yes | Yes |
+| `time_in_hr_zone` | seconds | Yes | — |
+| `avg_power`, `max_power` | watts | Yes | (\*) |
+| `normalized_power` | watts | Yes | — |
+| `left_balance`, `right_balance` | percent | Yes | — |
+| `time_in_power_zone` | seconds | Yes | — |
+| `total_work` | joules | Yes | — |
+| `avg_temperature`, `max_temperature` | °C | Yes | — |
+| `total_calories` | kcal | Yes | Yes |
+| `total_fat_calories` | kcal | Yes | — |
+
+### Activity
+
+`activity` is an `Activity` dataclass instance: a small file-level summary.
+Fields are `None` when the source format/file doesn't record them.
+Values come from the file's own summary fields, never computed/derived from records or laps.
+
+| Field | Unit | FIT | TCX | GPX |
+|---|---|:-:|:-:|:-:|
+| `sport` | — | Yes | Yes | — |
+| `start_time` | — | Yes | Yes | Yes (\*) |
+| `total_elapsed_time` | seconds | Yes | — | — |
+| `total_distance` | km | Yes | — | — |
+| `total_calories` | kcal | Yes | — | — |
+| `avg_heart_rate`, `max_heart_rate` | bpm | Yes | — | — |
+| `avg_speed`, `max_speed` | km/h | Yes | — | — |
+| `creator` | — | Yes | Yes | Yes |
+| `notes` | — | — | Yes | Yes |
+
+(\*) GPX's `start_time` comes from `metadata/time`, which is technically the file's export time rather than the activity's start.
+
+## Parser notes
+
+### FIT files
+
+FIT parsing wraps [`garmin-fit-sdk`](https://pypi.org/project/garmin-fit-sdk/), Garmin's official SDK, which decodes against the public FIT SDK profile.
+
+`parse()` transforms certain FIT fields beyond decoding:
+
+- Positions are converted to degrees, distances to km, and speeds to km/h.
+  Vertical rates (`avg_vam`, `vertical_speed`, and similar) stay in m/s.
+- For fields with lower- and higher-precision versions, only the higher-precision value is returned, under the base field's name.
+- For fields with sub-integer precision in a separate field, the precision is added into the base field.
+- `left_right_balance` (a bit-packed field) is decoded into `left_balance`/`right_balance`.
+- `heart_rate` is merged with a higher-rate `hr` stream when the file has one.
+  Records outside its coverage keep their own device value.
+
+Messages/fields that can't be resolved against the FIT profile (e.g. proprietary extensions) are kept as raw values under `unknown_<n>` names.
+Developer fields are resolved to their file-embedded names and flattened into ordinary columns alongside built-in fields.
+
+`parse_fit` and `parse_fit_raw` are the lower-level functions `ActivityParser.parse()` wraps for FIT files.
+`parse_fit` returns the same canonical `(records, laps, activity)` shape, but without column curation.
+`parse_fit_raw` returns every message type in the file as its own uncurated DataFrame, in FIT-native units (semicircles, meters, m/s).
+
+### TCX & GPX files
+
+TCX and GPX files are parsed natively in this package using [`lxml`](https://pypi.org/project/lxml/).
+Recognized elements and attributes are mapped onto the same canonical column names as FIT, with the same unit conventions.
+
+The parser supports the following schema versions and extensions:
+
+| Format | Schema version | Extensions |
+|---|---|---|
+| TCX | v2 | Garmin `ActivityExtension` v2 |
+| GPX | 1.0 / 1.1 | Garmin `TrackPointExtension` v1/v2, Cluetrust `gpxdata` |
+
+Unrecognized elements and attributes are exported as string columns named with their XML namespace in Clark notation.
+
+`parse_gpx` and `parse_tcx` are the lower-level functions `ActivityParser.parse()` wraps for these formats.
+They return the same canonical `(records, laps, activity)` shape, but without column curation.

{activity_parser-0.9.0 → activity_parser-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "activity-parser"
-version = "0.9.0"
+version = "0.11.0"
 description = "Parser for loading FIT, TCX and GPX files into Pandas DataFrames."
 readme = "README.md"
 license = "MIT"
@@ -26,7 +26,7 @@ requires-python = ">=3.11"
 dependencies = [
     "pandas",
     "lxml",
-    "fitdecode",
+    "garmin-fit-sdk",
 ]
 
 [project.urls]

{activity_parser-0.9.0 → activity_parser-0.11.0}/src/activity_parser/__init__.py

@@ -1,12 +1,19 @@
 """Parser for loading FIT, TCX and GPX files into Pandas DataFrames."""
 
+from .exceptions import FitError, ParseError, XmlError
+from .output import Activity
 from .parse_activity import ActivityParser
-from .parse_fit_file import parse_fit
+from .parse_fit_file import parse_fit, parse_fit_raw
 from .parse_tcx_gpx import parse_gpx, parse_tcx
 
 __all__ = [
+    "Activity",
     "ActivityParser",
+    "FitError",
+    "ParseError",
+    "XmlError",
     "parse_fit",
+    "parse_fit_raw",
     "parse_gpx",
     "parse_tcx",
 ]

activity_parser-0.11.0/src/activity_parser/exceptions.py

@@ -0,0 +1,13 @@
+"""Parsing exceptions, decoupled from the decoding backend."""
+
+
+class ParseError(Exception):
+    """Base for parsing failures across FIT, TCX, and GPX activity files."""
+
+
+class FitError(ParseError):
+    """Raised when a FIT file fails to parse (e.g. invalid header, CRC mismatch)."""
+
+
+class XmlError(ParseError):
+    """Raised when a TCX or GPX file fails to parse due to malformed XML."""

activity_parser-0.11.0/src/activity_parser/fit_fields.py

@@ -0,0 +1,128 @@
+"""Unit conversions applied to known FIT fields, and the tables driving them.
+
+FIT stores positions in semicircles, distances in meters and speeds in m/s. This
+package normalizes those to degrees, km and km/h. Vertical rates (``avg_vam``,
+``vertical_speed``, ...) are left in m/s.
+
+The tables are transcribed from the FIT profile in garmin-fit-sdk 21.212.0, covering
+the ``record``, ``lap`` and ``session`` message types. ``tests/test_fit_fields.py``
+checks that the installed profile's fields are covered.
+"""
+
+import math
+from collections.abc import Mapping
+from typing import Any
+
+import pandas as pd
+
+from .postprocess import coerce_numeric_all_or_nothing
+
+SEMICIRCLES_TO_DEGREES = 180.0 / 2**31
+M_TO_KM = 1 / 1000
+MPS_TO_KMH = 3.6
+
+RECORD_UNITS: dict[str, float] = {
+    "position_lat": SEMICIRCLES_TO_DEGREES,
+    "position_long": SEMICIRCLES_TO_DEGREES,
+    "distance": M_TO_KM,
+    "ball_speed": MPS_TO_KMH,
+    "enhanced_speed": MPS_TO_KMH,
+    "speed": MPS_TO_KMH,
+    "speed_1s": MPS_TO_KMH,
+}
+
+LAP_UNITS: dict[str, float] = {
+    "end_position_lat": SEMICIRCLES_TO_DEGREES,
+    "end_position_long": SEMICIRCLES_TO_DEGREES,
+    "start_position_lat": SEMICIRCLES_TO_DEGREES,
+    "start_position_long": SEMICIRCLES_TO_DEGREES,
+    "avg_stroke_distance": M_TO_KM,
+    "total_distance": M_TO_KM,
+    "avg_speed": MPS_TO_KMH,
+    "enhanced_avg_speed": MPS_TO_KMH,
+    "enhanced_max_speed": MPS_TO_KMH,
+    "max_speed": MPS_TO_KMH,
+}
+
+SESSION_UNITS: dict[str, float] = {
+    "end_position_lat": SEMICIRCLES_TO_DEGREES,
+    "end_position_long": SEMICIRCLES_TO_DEGREES,
+    "nec_lat": SEMICIRCLES_TO_DEGREES,
+    "nec_long": SEMICIRCLES_TO_DEGREES,
+    "start_position_lat": SEMICIRCLES_TO_DEGREES,
+    "start_position_long": SEMICIRCLES_TO_DEGREES,
+    "swc_lat": SEMICIRCLES_TO_DEGREES,
+    "swc_long": SEMICIRCLES_TO_DEGREES,
+    "avg_stroke_distance": M_TO_KM,
+    "total_distance": M_TO_KM,
+    "avg_ball_speed": MPS_TO_KMH,
+    "avg_speed": MPS_TO_KMH,
+    "enhanced_avg_speed": MPS_TO_KMH,
+    "enhanced_max_speed": MPS_TO_KMH,
+    "max_ball_speed": MPS_TO_KMH,
+    "max_speed": MPS_TO_KMH,
+}
+
+
+def _scale_value(value: Any, factor: float) -> Any:
+    """Scales one value by ``factor``, recursing into tuples elementwise.
+
+    Missing values pass through unchanged. Raises ``TypeError`` for a value that can't
+    be scaled (e.g. a string).
+    """
+    if value is None or (isinstance(value, float) and math.isnan(value)):
+        return value
+    if isinstance(value, tuple):
+        return tuple(_scale_value(v, factor) for v in value)
+    return value * factor
+
+
+def _scale_column_elementwise(values: pd.Series, factor: float) -> pd.Series:
+    """Scales ``values`` elementwise via ``_scale_value``, all-or-nothing.
+
+    If any value in the column can't be scaled, the column is returned unchanged.
+    """
+    try:
+        return values.map(lambda v: _scale_value(v, factor))
+    except TypeError:
+        return values
+
+
+def convert_units(df: pd.DataFrame, table: Mapping[str, float]) -> pd.DataFrame:
+    """Scales each of ``df``'s columns named in ``table`` by its factor.
+
+    Columns absent from ``table`` are left untouched, as are columns whose values don't
+    all coerce to numeric or scale cleanly. A column that decodes to tuples (an
+    array-typed FIT field) is scaled elementwise.
+    """
+    df = df.copy()
+
+    for column, factor in table.items():
+        if column not in df.columns:
+            continue
+
+        values = df[column]
+        if not pd.api.types.is_numeric_dtype(values):
+            values = coerce_numeric_all_or_nothing(values)
+        if pd.api.types.is_numeric_dtype(values):
+            df[column] = values * factor
+        else:
+            df[column] = _scale_column_elementwise(values, factor)
+
+    return df
+
+
+def convert_units_mapping(row: Mapping[str, Any], table: Mapping[str, float]) -> dict[str, Any]:
+    """Scales each of ``row``'s values named in ``table`` by its factor.
+
+    The mapping counterpart of ``convert_units``, for messages consumed as plain dicts
+    rather than as DataFrames. Non-numeric and missing values are left as they are.
+    """
+    converted = dict(row)
+
+    for field, factor in table.items():
+        value = converted.get(field)
+        if isinstance(value, (int, float)):
+            converted[field] = value * factor
+
+    return converted

activity_parser-0.11.0/src/activity_parser/output.py

@@ -0,0 +1,79 @@
+"""Defines the shape of ``parse()``'s return values, shared across FIT/TCX/GPX."""
+
+from dataclasses import dataclass
+
+import pandas as pd
+
+DEFAULT_RECORD_COLUMNS: tuple[str, ...] = (
+    "latitude",
+    "longitude",
+    "altitude",
+    "distance",
+    "speed",
+    "cadence",
+    "heart_rate",
+    "power",
+    "left_balance",
+    "right_balance",
+    "accumulated_power",
+    "temperature",
+    "water_temperature",
+    "depth",
+    "course",
+    "bearing",
+)
+
+DEFAULT_LAP_COLUMNS: tuple[str, ...] = (
+    "start_time",
+    "total_elapsed_time",
+    "total_timer_time",
+    "start_position_lat",
+    "start_position_long",
+    "end_position_lat",
+    "end_position_long",
+    "total_distance",
+    "total_ascent",
+    "total_descent",
+    "avg_vam",
+    "avg_speed",
+    "max_speed",
+    "avg_cadence",
+    "max_cadence",
+    "total_strokes",
+    "steps",
+    "avg_heart_rate",
+    "max_heart_rate",
+    "time_in_hr_zone",
+    "avg_power",
+    "max_power",
+    "normalized_power",
+    "left_balance",
+    "right_balance",
+    "time_in_power_zone",
+    "total_work",
+    "avg_temperature",
+    "max_temperature",
+    "total_calories",
+    "total_fat_calories",
+)
+
+
+@dataclass(frozen=True)
+class Activity:
+    """File-level summary, present across FIT/TCX/GPX.
+
+    Fields are ``None`` when the source format/file doesn't record them. Values come
+    from the file's own summary fields, never computed/derived from records or laps.
+    """
+
+    sport: str | None = None
+    start_time: pd.Timestamp | None = None
+    total_elapsed_time: float | None = None  # seconds
+    total_distance: float | None = None  # km
+    total_calories: float | None = None
+    avg_heart_rate: float | None = None
+    max_heart_rate: float | None = None
+    avg_speed: float | None = None  # kph
+    max_speed: float | None = None  # kph
+    creator: str | None = None  # device/app that recorded or wrote the file
+    notes: str | None = None