New features and refactoring

Author: firefly-cpp

tcx2ics/__init__.py

@@ -1,3 +1,3 @@
-from .tcx2ics import Tcx2Ics
+from .tcx2ics import Tcx2Ics, TcxData
 
-__all__ = ["Tcx2Ics"]
+__all__ = ["Tcx2Ics", "TcxData"]

tcx2ics/tcx2ics.py

@@ -1,54 +1,174 @@
+import os
+import uuid
+from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
-from pathlib import Path
-from tcxreader.tcxreader import TCXReader
+from xml.etree import ElementTree as ET
+
+TCX_NS = "http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2"
+
+@dataclass
+class TcxData:
+    """Structured result from parsing a TCX file."""
+
+    start_time: datetime
+    duration_seconds: float
+    distance_km: float
+    sport: str
+
+    @property
+    def end_time(self) -> datetime:
+        return self.start_time + timedelta(seconds=self.duration_seconds)
 
 
 class Tcx2Ics:
-    def __init__(self):
-        self.reader = TCXReader()
-
-    def convert(self, tcx_file: str, ics_file: str):
-        ex = self.reader.read(tcx_file)
-
-        sport = getattr(ex, "activity_type", None) or getattr(ex, "sport", None) or "Workout"
-        start = getattr(ex, "start_time", None)
-        duration = float(getattr(ex, "duration", 0) or 0)   # seconds
-        distance = float(getattr(ex, "distance", 0) or 0)   # meters
-
-        if not isinstance(start, datetime):
-            raise ValueError("No start_time found in TCX")
-
-        if start.tzinfo is None:
-            start = start.replace(tzinfo=timezone.utc)
-        else:
-            start = start.astimezone(timezone.utc)
-
-        end = start + timedelta(seconds=duration)
-
-        dist_km = distance / 1000.0
-        dur_h = int(duration) // 3600
-        dur_m = (int(duration) % 3600) // 60
-        dur_s = int(duration) % 60
-
-        summary = f"{sport} - {dist_km:.2f} km"
-        desc = f"Sport: {sport}\\nTotal duration: {dur_h}:{dur_m:02d}:{dur_s:02d}\\nDistance: {dist_km:.2f} km"
-
-        uid = f"{Path(tcx_file).stem}-{start.strftime('%Y%m%dT%H%M%SZ')}@tcx2ics"
-        now = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-
-        ics = (
-            "BEGIN:VCALENDAR\r\n"
-            "VERSION:2.0\r\n"
-            "PRODID:-//tcx2ics//EN\r\n"
-            "BEGIN:VEVENT\r\n"
-            f"UID:{uid}\r\n"
-            f"DTSTAMP:{now}\r\n"
-            f"DTSTART:{start.strftime('%Y%m%dT%H%M%SZ')}\r\n"
-            f"DTEND:{end.strftime('%Y%m%dT%H%M%SZ')}\r\n"
-            f"SUMMARY:{summary}\r\n"
-            f"DESCRIPTION:{desc}\r\n"
-            "END:VEVENT\r\n"
-            "END:VCALENDAR\r\n"
+    """Convert a TCX workout file to an ICS calendar event."""
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def convert(self, tcx_path: str, ics_path: str) -> None:
+        """
+        Parse *tcx_path* and write a calendar event to *ics_path*.
+
+        Raises
+        ------
+        FileNotFoundError
+            If *tcx_path* does not exist on disk.
+        ValueError
+            If *tcx_path* does not have a .tcx extension.
+        """
+        self._validate_input(tcx_path)
+        data = self._parse(tcx_path)
+        self._write_ics(data, ics_path)
+
+    def parse(self, tcx_path: str) -> TcxData:
+        """
+        Parse *tcx_path* and return a :class:`TcxData` instance.
+
+        Raises
+        ------
+        FileNotFoundError
+            If *tcx_path* does not exist on disk.
+        ValueError
+            If *tcx_path* does not have a .tcx extension.
+        """
+        self._validate_input(tcx_path)
+        return self._parse(tcx_path)
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _validate_input(tcx_path: str) -> None:
+        """Raise early with clear messages on bad input."""
+        if not tcx_path.lower().endswith(".tcx"):
+            raise ValueError(
+                f"Expected a .tcx file, got: '{tcx_path}'. "
+                "Please supply a Garmin TCX file."
+            )
+        if not os.path.isfile(tcx_path):
+            raise FileNotFoundError(
+                f"TCX file not found: '{tcx_path}'. "
+                "Check that the path is correct."
+            )
+
+    # ------------------------------------------------------------------
+    # Parsing
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _ns(tag: str) -> str:
+        return f"{{{TCX_NS}}}{tag}"
+
+    def _parse(self, tcx_path: str) -> TcxData:
+        tree = ET.parse(tcx_path)
+        root = tree.getroot()
+
+        activity = root.find(f".//{self._ns('Activity')}")
+        if activity is None:
+            raise ValueError("No <Activity> element found in TCX file.")
+
+        sport = activity.get("Sport", "Workout")
+
+        # Start time from the first Lap's StartTime attribute
+        lap = activity.find(self._ns("Lap"))
+        if lap is None:
+            raise ValueError("No <Lap> element found in TCX file.")
+
+        start_time_str = lap.get("StartTime") or ""
+        start_time = self._parse_datetime(start_time_str)
+
+        total_seconds = float(
+            self._find_text(lap, "TotalTimeSeconds") or "0"
+        )
+
+        distance_m = float(
+            self._find_text(lap, "DistanceMeters") or "0"
+        )
+        distance_km = distance_m / 1000.0
+
+        return TcxData(
+            start_time=start_time,
+            duration_seconds=total_seconds,
+            distance_km=distance_km,
+            sport=sport,
         )
 
-        Path(ics_file).write_text(ics, encoding="utf-8")
+    def _find_text(self, parent: ET.Element, tag: str) -> str | None:
+        el = parent.find(self._ns(tag))
+        return el.text if el is not None else None
+
+    @staticmethod
+    def _parse_datetime(value: str) -> datetime:
+        """Parse ISO-8601 string to timezone-aware datetime."""
+        value = value.rstrip("Z")
+        dt = datetime.fromisoformat(value)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt
+
+    # ------------------------------------------------------------------
+    # ICS output
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _fmt_dt(dt: datetime) -> str:
+        """Format datetime as iCalendar UTC timestamp (YYYYMMDDTHHMMSSZ)."""
+        utc = dt.astimezone(timezone.utc)
+        return utc.strftime("%Y%m%dT%H%M%SZ")
+
+    def _write_ics(self, data: TcxData, ics_path: str) -> None:
+        summary = (
+            f"{data.sport} — "
+            f"{data.distance_km:.1f} km, "
+            f"{int(data.duration_seconds // 60)} min"
+        )
+        description = (
+            f"Sport: {data.sport}\\n"
+            f"Distance: {data.distance_km:.2f} km\\n"
+            f"Duration: {int(data.duration_seconds // 60)} min"
+        )
+        uid = str(uuid.uuid4())
+        now = self._fmt_dt(datetime.now(tz=timezone.utc))
+
+        lines = [
+            "BEGIN:VCALENDAR",
+            "VERSION:2.0",
+            "PRODID:-//tcx2ics//tcx2ics//EN",
+            "CALSCALE:GREGORIAN",
+            "METHOD:PUBLISH",
+            "BEGIN:VEVENT",
+            f"UID:{uid}",
+            f"DTSTAMP:{now}",
+            f"DTSTART:{self._fmt_dt(data.start_time)}",
+            f"DTEND:{self._fmt_dt(data.end_time)}",
+            f"SUMMARY:{summary}",
+            f"DESCRIPTION:{description}",
+            "END:VEVENT",
+            "END:VCALENDAR",
+        ]
+
+        with open(ics_path, "w", encoding="utf-8") as fh:
+            fh.write("\r\n".join(lines) + "\r\n")

tests/conftest.py

@@ -0,0 +1,16 @@
+import pytest
+import pathlib
+
+FIXTURES_DIR = pathlib.Path(__file__).parent / "fixtures"
+
+
+@pytest.fixture
+def sample_tcx():
+    """Path to a minimal but valid TCX fixture file."""
+    return str(FIXTURES_DIR / "sample.tcx")
+
+
+@pytest.fixture
+def sample_tcx_content():
+    """Raw text content of the sample TCX fixture."""
+    return (FIXTURES_DIR / "sample.tcx").read_text()