activity-parser 0.9.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,12 @@
1
+ """Parser for loading FIT, TCX and GPX files into Pandas DataFrames."""
2
+
3
+ from .parse_activity import ActivityParser
4
+ from .parse_fit_file import parse_fit
5
+ from .parse_tcx_gpx import parse_gpx, parse_tcx
6
+
7
+ __all__ = [
8
+ "ActivityParser",
9
+ "parse_fit",
10
+ "parse_gpx",
11
+ "parse_tcx",
12
+ ]
@@ -0,0 +1,281 @@
1
+ """Class for parsing FIT, TCX and GPX files into Pandas DataFrames."""
2
+
3
+ from collections.abc import Mapping, Sequence
4
+ from os import PathLike
5
+ from pathlib import Path
6
+ from typing import IO, Any
7
+
8
+ import pandas as pd
9
+
10
+ from .parse_fit_file import parse_fit
11
+ from .parse_tcx_gpx import parse_gpx, parse_tcx
12
+
13
+
14
+ def select_and_rename_cols(
15
+ df: pd.DataFrame,
16
+ selector: Sequence[str],
17
+ mapper: Mapping[str, str],
18
+ ) -> pd.DataFrame:
19
+ """Select and rename columns from a DataFrame."""
20
+ cols = [col for col in selector if col in df.columns]
21
+ return df.loc[:, cols].rename(columns=mapper)
22
+
23
+
24
+ def normalize_extension(ext: str) -> str:
25
+ """Normalize an extension string to one of: fit, tcx, gpx."""
26
+ normalized = ext.lower().lstrip(".")
27
+ if normalized == "gz":
28
+ raise ValueError("Ambiguous extension: .gz without base extension.")
29
+ return normalized
30
+
31
+
32
+ def infer_extension(file: str | PathLike[str]) -> str:
33
+ """Infer normalized extension from a path-like input."""
34
+ p = Path(file)
35
+ ext = p.suffix
36
+ if ext.lower() == ".gz":
37
+ ext = Path(p.stem).suffix
38
+ return normalize_extension(ext)
39
+
40
+
41
+ class ActivityParser:
42
+ """Parser for FIT, GPX and TCX files.
43
+
44
+ Each instance of this class is a parser object that can be used to import FIT, GPX
45
+ and TCX files into DataFrames. During parsing, the column names in the resulting
46
+ DataFrames are normalized to a standard set of names to allow for more
47
+ interchangeable use of DataFrames from the different activity file types.
48
+ """
49
+
50
+ def __init__(self, strict_xml: bool = False) -> None:
51
+ """Initialize parser settings, selectors, and mappers.
52
+
53
+ Args:
54
+ strict_xml: If True, TCX/GPX XML parsing fails on malformed input.
55
+ If False, parser recovery is enabled.
56
+ """
57
+ self.strict_xml = strict_xml
58
+
59
+ # 'Selectors' specify the list and order of columns to be copied from each
60
+ # DataFrame (records and laps for each file type), and 'mappers' translate the
61
+ # imported column names into canonical names
62
+
63
+ self.fit_records_selector = [
64
+ "position_lat",
65
+ "position_long",
66
+ "altitude",
67
+ "distance",
68
+ "speed",
69
+ "cadence",
70
+ "fractional_cadence",
71
+ "heart_rate",
72
+ "power",
73
+ "left_right_balance",
74
+ "accumulated_power",
75
+ "temperature",
76
+ ]
77
+
78
+ self.tcx_records_selector = [
79
+ "LatitudeDegrees",
80
+ "LongitudeDegrees",
81
+ "AltitudeMeters",
82
+ "DistanceKm",
83
+ "Speed",
84
+ "Cadence",
85
+ "HeartRateBpm",
86
+ "Watts",
87
+ ]
88
+
89
+ self.gpx_records_selector = [
90
+ "lat",
91
+ "lon",
92
+ "ele",
93
+ "speed",
94
+ "cad",
95
+ "hr",
96
+ "power",
97
+ "atemp",
98
+ ]
99
+
100
+ self.fit_records_mapper = {
101
+ "position_lat": "latitude",
102
+ "position_long": "longitude",
103
+ "altitude": "altitude",
104
+ "distance": "distance",
105
+ "speed": "speed",
106
+ "cadence": "cadence",
107
+ "fractional_cadence": "fractional_cadence",
108
+ "heart_rate": "heart_rate",
109
+ "power": "power",
110
+ "left_right_balance": "left_right_balance",
111
+ "accumulated_power": "accumulated_power",
112
+ "temperature": "temperature",
113
+ }
114
+
115
+ self.tcx_records_mapper = {
116
+ "LatitudeDegrees": "latitude",
117
+ "LongitudeDegrees": "longitude",
118
+ "AltitudeMeters": "altitude",
119
+ "DistanceKm": "distance",
120
+ "Speed": "speed",
121
+ "Cadence": "cadence",
122
+ "HeartRateBpm": "heart_rate",
123
+ "Watts": "power",
124
+ }
125
+
126
+ self.gpx_records_mapper = {
127
+ "lat": "latitude",
128
+ "lon": "longitude",
129
+ "ele": "altitude",
130
+ "speed": "speed",
131
+ "cad": "cadence",
132
+ "hr": "heart_rate",
133
+ "power": "power",
134
+ "atemp": "temperature",
135
+ }
136
+
137
+ self.fit_laps_selector = [
138
+ "event",
139
+ "event_type",
140
+ "lap_trigger",
141
+ "start_time",
142
+ "total_elapsed_time",
143
+ "total_timer_time",
144
+ "start_position_lat",
145
+ "start_position_long",
146
+ "end_position_lat",
147
+ "end_position_long",
148
+ "total_distance",
149
+ "total_ascent",
150
+ "total_descent",
151
+ "avg_vam",
152
+ "avg_speed",
153
+ "max_speed",
154
+ "avg_cadence",
155
+ "max_cadence",
156
+ "avg_fractional_cadence",
157
+ "max_fractional_cadence",
158
+ "total_strokes",
159
+ "avg_heart_rate",
160
+ "max_heart_rate",
161
+ "time_in_hr_zone",
162
+ "avg_power",
163
+ "max_power",
164
+ "normalized_power",
165
+ "left_right_balance",
166
+ "time_in_power_zone",
167
+ "total_work",
168
+ "avg_temperature",
169
+ "max_temperature",
170
+ "total_calories",
171
+ "total_fat_calories",
172
+ "sport",
173
+ "sub_sport",
174
+ ]
175
+
176
+ self.tcx_laps_selector = [
177
+ "TriggerMethod",
178
+ "StartTime",
179
+ "TotalTimeSeconds",
180
+ "DistanceKm",
181
+ "AvgSpeed",
182
+ "MaximumSpeed",
183
+ "Cadence",
184
+ "MaxBikeCadence",
185
+ "AverageHeartRateBpm",
186
+ "MaximumHeartRateBpm",
187
+ "AvgWatts",
188
+ "MaxWatts",
189
+ "Calories",
190
+ ]
191
+
192
+ # Just use the FIT names for lap data as canonical
193
+ self.fit_laps_mapper = {}
194
+
195
+ self.tcx_laps_mapper = {
196
+ "TriggerMethod": "lap_trigger",
197
+ "StartTime": "start_time",
198
+ "TotalTimeSeconds": "total_elapsed_time",
199
+ "DistanceKm": "total_distance",
200
+ "AvgSpeed": "avg_speed",
201
+ "MaximumSpeed": "max_speed",
202
+ "Cadence": "avg_cadence",
203
+ "MaxBikeCadence": "max_cadence",
204
+ "AverageHeartRateBpm": "avg_heart_rate",
205
+ "MaximumHeartRateBpm": "max_heart_rate",
206
+ "AvgWatts": "avg_power",
207
+ "MaxWatts": "max_power",
208
+ "Calories": "total_calories",
209
+ }
210
+
211
+ def parse(
212
+ self,
213
+ file: str | PathLike[str] | IO[bytes],
214
+ ext: str | None = None,
215
+ ) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
216
+ """Loads a FIT, TCX or GPX activity into Pandas DataFrames.
217
+
218
+ During import, column names in ``records`` and ``laps`` are normalized into a
219
+ canonical set of names. Note this function does not guarantee that all canonical
220
+ columns appear in the output, it only renames the columns that are present in
221
+ the activity file.
222
+
223
+ Args:
224
+ file: Binary file-like or path-like object. A path-like argument ending in
225
+ ``.gz`` will be unzipped before processing.
226
+ ext: File type, case-insensitive: ``fit``, ``tcx``, or ``gpx``. Required for
227
+ a file-like ``file``; optional for a path-like ``file`` (inferred from
228
+ the name).
229
+
230
+ Returns:
231
+ Tuple containing records, laps, and selected extra metadata.
232
+ """
233
+ if ext is not None:
234
+ ext_normalized = normalize_extension(ext)
235
+ elif isinstance(file, (str, PathLike)):
236
+ ext_normalized = infer_extension(file)
237
+ else:
238
+ raise ValueError("ext must be provided when file is a file-like object.")
239
+
240
+ if ext_normalized == "fit":
241
+ records, laps, extra = parse_fit(file)
242
+ records = select_and_rename_cols(
243
+ records,
244
+ self.fit_records_selector,
245
+ self.fit_records_mapper,
246
+ )
247
+ records.rename_axis("time", inplace=True)
248
+ laps = select_and_rename_cols(
249
+ laps,
250
+ self.fit_laps_selector,
251
+ self.fit_laps_mapper,
252
+ )
253
+
254
+ elif ext_normalized == "tcx":
255
+ records, laps, extra = parse_tcx(file, strict_xml=self.strict_xml)
256
+ records = select_and_rename_cols(
257
+ records,
258
+ self.tcx_records_selector,
259
+ self.tcx_records_mapper,
260
+ )
261
+ records.rename_axis("time", inplace=True)
262
+ laps = select_and_rename_cols(
263
+ laps,
264
+ self.tcx_laps_selector,
265
+ self.tcx_laps_mapper,
266
+ )
267
+
268
+ elif ext_normalized == "gpx":
269
+ records, laps, extra = parse_gpx(file, strict_xml=self.strict_xml)
270
+ records = select_and_rename_cols(
271
+ records,
272
+ self.gpx_records_selector,
273
+ self.gpx_records_mapper,
274
+ )
275
+ records.rename_axis("time", inplace=True)
276
+ # Note GPX files have no lap information
277
+
278
+ else:
279
+ raise ValueError(f"File type not supported: {ext_normalized}")
280
+
281
+ return records, laps, extra
@@ -0,0 +1,105 @@
1
+ """Functions for parsing FIT files into Pandas DataFrames."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import gzip
6
+ from collections.abc import Iterator
7
+ from os import PathLike
8
+ from pathlib import Path
9
+ from typing import IO, TYPE_CHECKING, Any
10
+
11
+ import fitdecode
12
+ import pandas as pd
13
+
14
+ if TYPE_CHECKING:
15
+ from _typeshed import SupportsRead
16
+
17
+
18
+ def copy_fit_frames(
19
+ fit_file: SupportsRead[bytes],
20
+ ) -> Iterator[fitdecode.FitDataMessage]:
21
+ """Yields FIT data frames from a file-like object."""
22
+ processor = fitdecode.StandardUnitsDataProcessor()
23
+ for frame in fitdecode.FitReader(fit_file, processor=processor):
24
+ if isinstance(frame, fitdecode.FitDataMessage) and frame.mesg_type is not None:
25
+ yield frame
26
+
27
+
28
+ def frame_to_dict(frame: fitdecode.FitDataMessage) -> dict[str, Any]:
29
+ """Convert one FIT frame to a dict, dropping unknown fields."""
30
+ return {field.name: field.value for field in frame.fields if field.field is not None}
31
+
32
+
33
+ def parse_fit_frames(
34
+ fit_file: SupportsRead[bytes],
35
+ ) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
36
+ """Parse FIT frames from an open file object."""
37
+ records_rows: list[dict[str, Any]] = []
38
+ laps_rows: list[dict[str, Any]] = []
39
+ extra_rows: dict[str, list[dict[str, Any]]] = {}
40
+
41
+ for frame in copy_fit_frames(fit_file):
42
+ row = frame_to_dict(frame)
43
+ if frame.name == "record":
44
+ records_rows.append(row)
45
+ elif frame.name == "lap":
46
+ laps_rows.append(row)
47
+ else:
48
+ extra_rows.setdefault(frame.name, []).append(row)
49
+
50
+ records = pd.DataFrame(records_rows)
51
+
52
+ # None-valued fields cause object dtype; coerce numeric columns to float64.
53
+ for col in records.select_dtypes(include="object").columns:
54
+ coerced = pd.to_numeric(records[col], errors="coerce")
55
+ if coerced.notna().sum() == records[col].notna().sum():
56
+ records[col] = coerced
57
+
58
+ # FIT files occasionally have duplicate timestamps.
59
+ if "timestamp" in records.columns:
60
+ records = records.set_index("timestamp")
61
+ else:
62
+ records.index = pd.Index(records.index, name="timestamp")
63
+
64
+ records = records[records.index.notna()]
65
+ records = records[~records.index.duplicated()]
66
+
67
+ laps = pd.DataFrame(laps_rows)
68
+
69
+ extra: dict[str, Any] = {}
70
+ for name, rows in extra_rows.items():
71
+ if len(rows) == 1:
72
+ extra[name] = rows[0]
73
+ else:
74
+ extra[name] = pd.DataFrame(rows)
75
+
76
+ return records, laps, extra
77
+
78
+
79
+ def parse_fit(
80
+ file: str | PathLike[str] | IO[bytes],
81
+ ) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
82
+ """Loads a FIT activity into Pandas DataFrames.
83
+
84
+ FIT frames and data fields that are marked as 'unknown' by fitdecode are dropped
85
+ during import. Assumes that the FIT file is all one activity, i.e. chained FIT files
86
+ will be merged into one set of return values.
87
+
88
+ Args:
89
+ file: File-like or path-like object. A path-like argument ending in ``.gz`` will
90
+ be unzipped before processing.
91
+
92
+ Returns:
93
+ Tuple containing records, laps, and additional metadata.
94
+ """
95
+ is_path = isinstance(file, (str, PathLike))
96
+
97
+ if is_path:
98
+ ext = Path(file).suffix
99
+ opener = gzip.open if ext.lower() == ".gz" else open
100
+ with opener(file, "rb") as fit_file:
101
+ records, laps, extra = parse_fit_frames(fit_file)
102
+ else:
103
+ records, laps, extra = parse_fit_frames(file)
104
+
105
+ return records, laps, extra
@@ -0,0 +1,201 @@
1
+ """Functions for parsing TCX and GPX files into Pandas DataFrames."""
2
+
3
+ from collections.abc import Iterator
4
+ from os import PathLike
5
+ from typing import IO, cast
6
+
7
+ import pandas as pd
8
+ from lxml import etree
9
+
10
+ NUMERIC_EXACT_COLUMNS = {
11
+ "lat",
12
+ "lon",
13
+ "ele",
14
+ "hr",
15
+ "cad",
16
+ "power",
17
+ "atemp",
18
+ "speed",
19
+ "Watts",
20
+ "DistanceMeters",
21
+ "AltitudeMeters",
22
+ "HeartRateBpm",
23
+ "Cadence",
24
+ "LatitudeDegrees",
25
+ "LongitudeDegrees",
26
+ "TotalTimeSeconds",
27
+ }
28
+
29
+ NUMERIC_SUBSTRINGS = (
30
+ "Distance",
31
+ "Speed",
32
+ "Altitude",
33
+ "Cadence",
34
+ "HeartRate",
35
+ "Watts",
36
+ "Power",
37
+ "Calories",
38
+ )
39
+
40
+
41
+ def should_coerce_numeric(column_name: str) -> bool:
42
+ """Return True when an XML-derived column should be numeric."""
43
+ if column_name in NUMERIC_EXACT_COLUMNS:
44
+ return True
45
+ return any(token in column_name for token in NUMERIC_SUBSTRINGS)
46
+
47
+
48
+ def remove_elements(root: etree._Element, *tags: str) -> None:
49
+ """Remove all elements matching ``tags`` from the tree."""
50
+ for element in root.iter(*tags):
51
+ parent = element.getparent()
52
+ if parent is not None:
53
+ parent.remove(element)
54
+
55
+
56
+ def extract_xml_fields(
57
+ element: etree._Element,
58
+ ) -> Iterator[tuple[str, str | None]]:
59
+ """Yields (name, value) pairs recursively through an XML element."""
60
+ # Iterating with "*" matches only true elements and drops e.g. comments
61
+ for el in element.iter("*"):
62
+ # Some (name, value) pairs are stored as XML attributes
63
+ for key, value in el.attrib.items():
64
+ localname = etree.QName(key).localname
65
+ if localname != "type":
66
+ yield localname, cast(str, value)
67
+
68
+ # In a TCX file, some values are buried in a 'Value' element
69
+ if el.text is None or el.text.isspace():
70
+ try:
71
+ child = next(el.iterchildren("*"))
72
+ parent_localname = etree.QName(el).localname
73
+ child_localname = etree.QName(child).localname
74
+ if child_localname == "Value":
75
+ yield parent_localname, child.text
76
+ except StopIteration:
77
+ pass
78
+
79
+ # But most values are recorded as leaf element text
80
+ else:
81
+ localname = etree.QName(el).localname
82
+ if localname != "Value":
83
+ yield localname, el.text
84
+
85
+
86
+ def cleanup_xml_dataframe(df: pd.DataFrame, time_col: str) -> pd.DataFrame:
87
+ """Common post-processing for DataFrames extracted from XML elements."""
88
+ for col in df.columns:
89
+ if col == time_col or not should_coerce_numeric(str(col)):
90
+ continue
91
+
92
+ values = df[col]
93
+ non_null = values.notna().sum()
94
+ if non_null == 0:
95
+ continue
96
+
97
+ numeric_values = pd.to_numeric(values, errors="coerce")
98
+ if numeric_values.notna().sum() == non_null:
99
+ df[col] = numeric_values
100
+
101
+ if time_col in df.columns:
102
+ # Without format="ISO8601", timestamps mixing naive and UTC-offset values in
103
+ # the same column silently become NaT instead of parsing.
104
+ df[time_col] = pd.to_datetime(df[time_col], errors="coerce", utc=True, format="ISO8601")
105
+ else:
106
+ df[time_col] = pd.NaT
107
+
108
+ # Conversion from meters and m/s to km and kph is done to align with processing done
109
+ # by fitdecode.StandardUnitsDataProcessor
110
+ for col in df.columns:
111
+ # Columns that failed numeric coercion above are still strings; leave them as-is
112
+ if not pd.api.types.is_numeric_dtype(df[col]):
113
+ continue
114
+ if "distance" in col.lower():
115
+ df[col] = df[col] / 1000.0
116
+ df = df.rename(columns={col: col.replace("Meters", "Km")})
117
+ if "speed" in col.lower():
118
+ df[col] = df[col] * 60.0 * 60.0 / 1000.0
119
+
120
+ return df
121
+
122
+
123
+ def parse_tcx(
124
+ file: str | PathLike[str] | IO[str] | IO[bytes],
125
+ strict_xml: bool = False,
126
+ ) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, str | None]]:
127
+ """Loads a TCX activity into Pandas DataFrames.
128
+
129
+ Assumes that the TCX file is all one activity. Files with multiple activities will
130
+ be merged into one set of return values, possibly over-writing some fields.
131
+
132
+ Args:
133
+ file: File-like or path-like object. A path-like argument ending in ``.gz`` will
134
+ be transparently unzipped before processing.
135
+ strict_xml: If True, fail on XML parsing errors instead of recovering.
136
+
137
+ Returns:
138
+ Tuple containing records, laps, and additional metadata.
139
+ """
140
+ # lxml takes care of identifying and handling a gzipped file
141
+ parser = etree.XMLParser(recover=not strict_xml)
142
+ root = etree.parse(file, parser).getroot()
143
+
144
+ # TCX files occasionally have duplicate timestamps, just drop those
145
+ records = pd.DataFrame(
146
+ dict(extract_xml_fields(element)) for element in root.iter("{*}Trackpoint")
147
+ )
148
+ records = cleanup_xml_dataframe(records, "Time").set_index("Time")
149
+ records = records[records.index.notna()]
150
+ records = records[~records.index.duplicated()]
151
+
152
+ remove_elements(root, "{*}Track")
153
+
154
+ laps = pd.DataFrame(dict(extract_xml_fields(element)) for element in root.iter("{*}Lap"))
155
+ laps = cleanup_xml_dataframe(laps, "StartTime")
156
+
157
+ remove_elements(root, "{*}Lap")
158
+
159
+ extra = dict(extract_xml_fields(root))
160
+ extra.pop("schemaLocation", None)
161
+
162
+ return records, laps, extra
163
+
164
+
165
+ def parse_gpx(
166
+ file: str | PathLike[str] | IO[str] | IO[bytes],
167
+ strict_xml: bool = False,
168
+ ) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, str | None]]:
169
+ """Loads a GPX activity into a Pandas DataFrame.
170
+
171
+ Assumes that the GPX file is all one activity. Files with multiple tracks will be
172
+ merged into one set of return values, possibly over-writing some fields. Waypoints
173
+ and routes in the GPX file are ignored.
174
+
175
+ Args:
176
+ file: File-like or path-like object. A path-like argument ending in ``.gz`` will
177
+ be transparently unzipped before processing.
178
+ strict_xml: If True, fail on XML parsing errors instead of recovering.
179
+
180
+ Returns:
181
+ Tuple containing records, laps, and additional metadata. Note GPX files don't
182
+ have lap information, so the laps DataFrame will be empty.
183
+ """
184
+ # Note there is a 'gpxpy' library that provides comprehensive handling of GPX files.
185
+ # Parsing the XML directly works for our purposes and keeps this consistent with
186
+ # how we handle TCX files above.
187
+
188
+ parser = etree.XMLParser(recover=not strict_xml)
189
+ root = etree.parse(file, parser).getroot()
190
+
191
+ records = pd.DataFrame(dict(extract_xml_fields(element)) for element in root.iter("{*}trkpt"))
192
+ records = cleanup_xml_dataframe(records, "time").set_index("time")
193
+ records = records[records.index.notna()]
194
+ records = records[~records.index.duplicated()]
195
+
196
+ remove_elements(root, "{*}trkseg", "{*}rte", "{*}wpt")
197
+
198
+ extra = dict(extract_xml_fields(root))
199
+ extra.pop("schemaLocation", None)
200
+
201
+ return records, pd.DataFrame(), extra
File without changes
@@ -0,0 +1,97 @@
1
+ Metadata-Version: 2.4
2
+ Name: activity-parser
3
+ Version: 0.9.0
4
+ Summary: Parser for loading FIT, TCX and GPX files into Pandas DataFrames.
5
+ Project-URL: Repository, https://github.com/tabishm52/activity_parser
6
+ Project-URL: Issues, https://github.com/tabishm52/activity_parser/issues
7
+ Author-email: Tabish Mustufa <tabishm@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: fit,fitness,gps,gpx,pandas,parser,tcx
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Topic :: Scientific/Engineering :: GIS
18
+ Requires-Python: >=3.11
19
+ Requires-Dist: fitdecode
20
+ Requires-Dist: lxml
21
+ Requires-Dist: pandas
22
+ Description-Content-Type: text/markdown
23
+
24
+ # activity-parser
25
+
26
+ [![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)
27
+
28
+ Parser for loading FIT, TCX and GPX activity files into Pandas DataFrames.
29
+
30
+ Provides a parser object for reading (optionally gzipped) FIT, TCX, and GPX activity files and converting them into Pandas DataFrames.
31
+ During import, column names extracted from activity files are normalized into a canonical set of output column names.
32
+
33
+ ## Installation
34
+
35
+ ```bash
36
+ pip install activity-parser
37
+ ```
38
+
39
+ ## Usage
40
+
41
+ Create a new instance of the `ActivityParser` class to be reused for subsequent parsing of activity files:
42
+
43
+ ```python
44
+ import activity_parser
45
+ parser = activity_parser.ActivityParser()
46
+ ```
47
+
48
+ Parse FIT, TCX and GPX files into normalized DataFrames:
49
+
50
+ ```python
51
+ records, laps, extra = parser.parse('path/to/fit_file.fit')
52
+ records, laps, extra = parser.parse('path/to/gpx_file.gpx')
53
+ records, laps, extra = parser.parse('path/to/tcx_file.tcx')
54
+ ```
55
+
56
+ Regardless of source format, `records` and `laps` use a canonical set of column names (see [Output columns](#output-columns) below), e.g.:
57
+
58
+ ```
59
+ distance speed cadence heart_rate
60
+ time
61
+ 2026-01-05 08:00:00+00:00 0.00 36.0 80 100
62
+ 2026-01-05 08:00:01+00:00 0.01 36.0 81 101
63
+ ```
64
+
65
+ `extra` is not canonicalized like `records` and `laps`: it's a dict of leftover, format-specific metadata passed through with its native field names, and its shape differs by format.
66
+ For FIT, it's keyed by FIT message name (e.g. `session`, `device_info`).
67
+ For TCX/GPX, it's a single dict of the root element's attributes/fields (e.g. `Creator`, `Id`).
68
+ Treat it as raw metadata to inspect per-format rather than something to consume generically.
69
+
70
+ ## Output columns
71
+
72
+ Units are aligned to FIT's standard units (via `fitdecode.StandardUnitsDataProcessor`), and columns are renamed/converted where needed so the same name means the same unit regardless of source format:
73
+
74
+ | Column | Unit | FIT | TCX | GPX |
75
+ |---|---|:-:|:-:|:-:|
76
+ | `latitude`, `longitude` | degrees | Yes | Yes | Yes |
77
+ | `altitude` | meters | Yes | Yes | Yes |
78
+ | `distance` | km | Yes | Yes | — |
79
+ | `speed` | km/h | Yes | Yes | (\*) |
80
+ | `cadence` | rpm | Yes | Yes | Yes |
81
+ | `heart_rate` | bpm | Yes | Yes | Yes |
82
+ | `power` | watts | Yes | Yes | Yes |
83
+ | `temperature` | °C | Yes | — | Yes |
84
+
85
+ Not every column appears in every file: `parse()` only includes columns actually present in the source.
86
+ Two of these gaps are structural (GPX has no field for cumulative distance, in the base spec or in Garmin's `TrackPointExtension`, and TCX has no field for temperature, in the base spec or in Garmin's `ActivityExtension`), so those will never appear regardless of exporter.
87
+ GPX files also have no lap data, so `laps` will always be an empty DataFrame.
88
+
89
+ (\*) `speed` for GPX is exporter-dependent, not a format limitation: it's defined in Garmin's `TrackPointExtension/v2` schema.
90
+ Any exporter that emits `v2` (or another extension exposing a `speed`-named field) will have it picked up and normalized.
91
+
92
+ `laps` follows the same convention for shared metrics (`total_distance`, `avg_speed`, `max_speed`, `avg_heart_rate`, `avg_power`, `total_calories`, etc.).
93
+ FIT also exposes FIT-specific fields not available from TCX/GPX (e.g. `fractional_cadence`, `left_right_balance`, `accumulated_power`) under their native FIT names.
94
+
95
+ ## License
96
+
97
+ MIT
@@ -0,0 +1,9 @@
1
+ activity_parser/__init__.py,sha256=R2vu04z59TPQaLvmV3AmNJfHf5ubsOMca0krvhECfm8,290
2
+ activity_parser/parse_activity.py,sha256=OonQJcEDvHj-mVQH8cbqFyeJMmImCZCo7u6A4YIDho8,9076
3
+ activity_parser/parse_fit_file.py,sha256=aoi9qKRIH0cHRobMk0rIK9ASq53aLoh-vwJVS5zUHuI,3475
4
+ activity_parser/parse_tcx_gpx.py,sha256=59pYLBwBJ3-v-FmjMQd8PJPVUQW8YDUMkaOh2_nc8x0,6965
5
+ activity_parser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ activity_parser-0.9.0.dist-info/METADATA,sha256=i0E9CSrJXT438b6IBo0F0LtbuMK4n3G-yIJ-xVoy3dI,4374
7
+ activity_parser-0.9.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
8
+ activity_parser-0.9.0.dist-info/licenses/LICENSE,sha256=33omZljNc_oQyuSppalWHYKCj-axXx8R05aPvPWf6Z4,1076
9
+ activity_parser-0.9.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.30.1
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,20 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023-2026 Tabish Mustufa
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
6
+ this software and associated documentation files (the "Software"), to deal in
7
+ the Software without restriction, including without limitation the rights to
8
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9
+ the Software, and to permit persons to whom the Software is furnished to do so,
10
+ subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17
+ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.