sweatstack 0.87.0__tar.gz → 0.88.0__tar.gz

{sweatstack-0.87.0 → sweatstack-0.88.0}/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.88.0] - 2026-08-06
+
+### Changed
+
+- **Breaking:** `create_trace`, `update_trace`, `create_test`, and `update_test` now require timezone-aware datetimes for `timestamp`, `start`, and `end`. A naive datetime raises `ValueError` before the request is sent. Attach a zone, e.g. `datetime(..., tzinfo=ZoneInfo("Europe/Amsterdam"))` or `datetime.now(timezone.utc)`; the offset is stored alongside the instant.
+- `start`, `end`, and `timestamp` on responses are absolute UTC instants (ISO 8601 with a `Z` suffix), no longer a fixed per-record local offset. For wall-clock display use the companion `start_local` / `end_local` / `timestamp_local` fields, which are always present. The Streamlit activity selector now labels activities by their local date.
+- Requires a SweatStack server with offset-based timezone handling (plan 033). Against an older server the aware-datetime writes still work, but responses keep the previous fixed-offset `start`/`end`/`timestamp`.
+
+### Removed
+
+- Token refresh no longer sends a `tz` field. The server derives all timezone information from the offsets stored with each record, so the client has nothing to pass.
+
 ## [0.87.0] - 2026-06-30
 
 ### Changed

{sweatstack-0.87.0 → sweatstack-0.88.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.87.0
+Version: 0.88.0
 Summary: The official Python client for SweatStack
 Project-URL: Homepage, https://sweatstack.no
 Project-URL: Documentation, https://docs.sweatstack.no/getting-started/

{sweatstack-0.87.0 → sweatstack-0.88.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sweatstack"
-version = "0.87.0"
+version = "0.88.0"
 description = "The official Python client for SweatStack"
 readme = "README.md"
 license = "MIT"

{sweatstack-0.87.0 → sweatstack-0.88.0}/src/sweatstack/client.py

@@ -780,11 +780,10 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
 
         return access_token, refresh_token
 
-    def _do_token_refresh(self, tz: str, refresh_token: str) -> str:
+    def _do_token_refresh(self, refresh_token: str) -> str:
         """Exchange refresh token for a new access token.
 
         Args:
-            tz: Timezone from the expired token's JWT claims.
             refresh_token: The refresh token to use.
 
         Returns:
@@ -799,7 +798,6 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                 data={
                     "grant_type": "refresh_token",
                     "refresh_token": refresh_token,
-                    "tz": tz,
                     "client_id": self.client_id,
                     "client_secret": self._client_secret.get_secret_value() if self._client_secret else None,
                 },
@@ -845,8 +843,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                 "Call client.authenticate(force=True) to re-authenticate."
             )
 
-        tz = payload.get("tz", "UTC")
-        new_access_token = self._do_token_refresh(tz, refresh_token)
+        new_access_token = self._do_token_refresh(refresh_token)
 
         # Update instance state
         self._api_key = SecretStr(new_access_token)
@@ -1025,6 +1022,26 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                 out.append(value)
         return out
 
+    @staticmethod
+    def _require_aware(value: datetime, param: str) -> datetime:
+        """Guard a write timestamp: it must carry an explicit UTC offset.
+
+        The API stores each timestamp as an absolute instant paired with its
+        local offset, so it rejects naive datetimes with HTTP 422. Failing fast
+        here names the offending argument and shows how to fix it, which the raw
+        server error does not.
+
+        Raises:
+            ValueError: If ``value`` is timezone-naive.
+        """
+        if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
+            raise ValueError(
+                f"{param} must be timezone-aware; got naive {value!r}. "
+                f"Attach a zone, e.g. datetime(..., tzinfo=ZoneInfo('Europe/Amsterdam')) "
+                f"or datetime.now(timezone.utc)."
+            )
+        return value
+
     def _get_activities_generator(
         self,
         *,
@@ -1805,7 +1822,8 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         measurement values.
 
         Args:
-            timestamp: The date and time when the trace was recorded.
+            timestamp: The date and time when the trace was recorded. Must be
+                timezone-aware; the offset is stored alongside the instant.
             lactate: Optional blood lactate concentration in mmol/L.
             rpe: Optional rating of perceived exertion (typically on a scale of 1-10).
             notes: Optional text notes associated with this trace.
@@ -1815,7 +1833,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             tags: Optional list of tags to associate with this trace.
             sport: Optional sport to associate with this trace.
             test_id: Optional ID of a test to explicitly link this trace to.
-                The link is independent of timestamp — a linked trace appears
+                The link is independent of timestamp: a linked trace appears
                 in the test's traces list regardless of whether its timestamp
                 falls inside the test window.
 
@@ -1823,10 +1841,12 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             TraceDetails: The created trace object with all details.
 
         Raises:
+            ValueError: If ``timestamp`` is timezone-naive.
             SweatStackNotFoundError: If ``test_id`` references a test that
                 does not exist.
             SweatStackAPIError: If the API request fails for any other reason.
         """
+        self._require_aware(timestamp, "timestamp")
         sport = self._enums_to_strings([sport])[0] if sport else None
         with self._http_client() as client:
             response = client.post(
@@ -1874,7 +1894,8 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
 
         Args:
             trace_id: The unique identifier of the trace to update.
-            timestamp: The date and time when the trace was recorded.
+            timestamp: The date and time when the trace was recorded. Must be
+                timezone-aware; the offset is stored alongside the instant.
             lactate: Optional blood lactate concentration in mmol/L.
             rpe: Optional rating of perceived exertion (typically on a scale of 1-10).
             notes: Optional text notes associated with this trace.
@@ -1887,10 +1908,12 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                 Pass ``None`` (or omit) to leave the trace unlinked.
 
         Raises:
+            ValueError: If ``timestamp`` is timezone-naive.
             SweatStackNotFoundError: If ``trace_id`` does not exist, or if
                 ``test_id`` references a test that does not exist.
             SweatStackAPIError: If the API request fails for any other reason.
         """
+        self._require_aware(timestamp, "timestamp")
         sport = self._enums_to_strings([sport])[0] if sport else None
         with self._http_client() as client:
             response = client.put(
@@ -2082,9 +2105,11 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
 
         Args:
             sport: The sport for this test. Can be a Sport enum or string ID.
-            start: The start time of the test.
+            start: The start time of the test. Must be timezone-aware; the
+                offset is stored alongside the instant.
             title: Optional title for the test.
-            end: Optional end time. Defaults to start + 3 hours server-side.
+            end: Optional end time. Must be timezone-aware when given. Defaults
+                to start + 3 hours server-side.
             results: Optional structured test results (thresholds, capacities, etc.).
             tags: Optional list of tags to associate with this test.
 
@@ -2092,8 +2117,12 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             TestSummary: The created test.
 
         Raises:
+            ValueError: If ``start`` or ``end`` is timezone-naive.
             SweatStackAPIError: If the API request fails.
         """
+        self._require_aware(start, "start")
+        if end is not None:
+            self._require_aware(end, "end")
         sport = self._enums_to_strings([sport])[0]
         with self._http_client() as client:
             response = client.post(
@@ -2130,16 +2159,22 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         Args:
             test_id: The unique identifier of the test to update.
             sport: The sport for this test. Can be a Sport enum or string ID.
-            start: The start time of the test.
+            start: The start time of the test. Must be timezone-aware; the
+                offset is stored alongside the instant.
             title: Optional title for the test.
-            end: Optional end time. Defaults to start + 3 hours server-side.
+            end: Optional end time. Must be timezone-aware when given. Defaults
+                to start + 3 hours server-side.
             results: Optional structured test results (thresholds, capacities, etc.).
             tags: Optional list of tags to associate with this test.
 
         Raises:
+            ValueError: If ``start`` or ``end`` is timezone-naive.
             SweatStackNotFoundError: If the test does not exist.
             SweatStackAPIError: If the API request fails for any other reason.
         """
+        self._require_aware(start, "start")
+        if end is not None:
+            self._require_aware(end, "end")
         sport = self._enums_to_strings([sport])[0]
         with self._http_client() as client:
             response = client.put(
@@ -2613,8 +2648,9 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         """Uploads activity files (CSV or FIT).
 
         CSV files require the ``sport`` parameter and must contain a ``timestamp``
-        column with ISO 8601 datetimes.  FIT files include sport metadata so
-        ``sport`` is optional for them.
+        column with **offset-aware** ISO 8601 datetimes (e.g. ``...+02:00`` or
+        ``...Z``); naive timestamps are rejected during processing. FIT files
+        include sport metadata so ``sport`` is optional for them.
 
         Args:
             files: A file path, or a list of file paths, to upload.

{sweatstack-0.87.0 → sweatstack-0.88.0}/src/sweatstack/fastapi/dependencies.py

@@ -102,17 +102,10 @@ def _extract_expiry(access_token: str) -> datetime:
     return datetime.fromtimestamp(body["exp"], tz=timezone.utc)
 
 
-def _extract_timezone(access_token: str) -> str:
-    """Extract timezone from JWT access token."""
-    body = decode_jwt_body(access_token)
-    return body.get("tz", "UTC")
-
-
 def _refresh_access_token(
     refresh_token: str,
     client_id: str,
     client_secret: str,
-    tz: str,
 ) -> tuple[str, str | None]:
     """Exchange a refresh token for a new access token.
 
@@ -133,7 +126,6 @@ def _refresh_access_token(
             "refresh_token": refresh_token,
             "client_id": client_id,
             "client_secret": client_secret,
-            "tz": tz,
         },
         timeout=REFRESH_HTTP_TIMEOUT,
     )
@@ -217,7 +209,6 @@ def _resolve_access_token(
                 refresh_token=refresh_token,
                 client_id=config.client_id,
                 client_secret=config.client_secret.get_secret_value(),
-                tz=_extract_timezone(access_token),
             )
         except Exception:
             # Don't let a failed refresh strand a stale token in the cache.

{sweatstack-0.87.0 → sweatstack-0.88.0}/src/sweatstack/streamlit.py

@@ -74,7 +74,7 @@ class StreamlitAuth:
         # Use the authenticated client
         st.write("Welcome to SweatStack")
         latest_activity = auth.client.get_latest_activity()
-        st.write(f"Latest activity: {latest_activity.sport} on {latest_activity.start}")
+        st.write(f"Latest activity: {latest_activity.sport} on {latest_activity.start_local}")
 
         # Switch between accessible users (admin feature)
         with st.sidebar:
@@ -466,7 +466,7 @@ class StreamlitAuth:
         selected_activity = st.selectbox(
             "Select an activity",
             activities,
-            format_func=lambda activity: f"{activity.start.date().isoformat()} {activity.sport.label}",
+            format_func=lambda activity: f"{activity.start_local.date().isoformat()} {activity.sport.label}",
         )
         return selected_activity
 

{sweatstack-0.87.0 → sweatstack-0.88.0}/tests/test_access_token_cache.py

@@ -69,14 +69,14 @@ def configure_app():
 # ---------------------------------------------------------------------------
 
 
-def _jwt(*, exp: float, tz: str = "UTC", sub: str = "user_1") -> str:
+def _jwt(*, exp: float, sub: str = "user_1") -> str:
     """Build a JWT-shaped string whose body decodes to the given claims.
 
-    The signature segment is unused — ``decode_jwt_body`` only reads the
-    body — but we include a non-empty value so the token shape is
+    The signature segment is unused (``decode_jwt_body`` only reads the
+    body), but we include a non-empty value so the token shape is
     realistic.
     """
-    body = {"exp": int(exp), "tz": tz, "sub": sub}
+    body = {"exp": int(exp), "sub": sub}
     encoded = base64.urlsafe_b64encode(json.dumps(body).encode()).rstrip(b"=").decode()
     return f"header.{encoded}.signature"
 
@@ -360,7 +360,7 @@ class TestResolveAccessToken:
         call_count = 0
         call_count_lock = threading.Lock()
 
-        def slow_refresh(*, refresh_token, client_id, client_secret, tz):
+        def slow_refresh(*, refresh_token, client_id, client_secret):
             nonlocal call_count
             with call_count_lock:
                 call_count += 1

{sweatstack-0.87.0 → sweatstack-0.88.0}/tests/test_longitudinal_mean_max_after.py

@@ -47,16 +47,16 @@ def _call(client, **kwargs):
     return result, http.get.call_args.kwargs["params"]
 
 
-def test_after_list_is_sent_and_shape_is_metric_indexed(client):
+def test_after_list_is_sent_and_default_power_is_duration_indexed(client):
     result, params = _call(client, after=[0, 500])
     # repeated query param
     assert params["after"] == [0, 500]
-    # shape parallels the no-after curve: metric value is the index, `after` a column
-    assert result.index.name == "power"
+    # `by` unset for after+power resolves to `duration` server-side (0.85.0+): the frame is
+    # duration-indexed, with `after` a column (mirroring the no-after curve's index).
+    assert result.index.name == "duration"
+    assert "power" in result.columns
     assert "after" in result.columns
     assert set(result["after"].unique()) == {0.0, 500.0}
-    # postprocessed to standard dtypes
-    assert result["duration"].dtype == "timedelta64[ns]"
 
 
 def test_single_after_is_normalised_to_a_list(client):
@@ -94,9 +94,22 @@ def _index_free_by_duration_response() -> bytes:
     return buf.getvalue()
 
 
-def test_by_defaults_to_intensity_and_is_sent(client):
+def test_by_defaults_to_none_and_is_omitted(client):
+    # `by` unset -> omitted from the request so the server picks the orientation (0.85.0+),
+    # rather than the client forcing the deprecated value-indexed path.
     _result, params = _call(client, after=[0, 500])
+    assert "by" not in params
+
+
+def test_after_with_explicit_intensity_is_metric_indexed_and_warns(client):
+    # The deprecated value-indexed orientation stays metric-indexed, is sent explicitly,
+    # and warns (preserves the coverage the old default-intensity test used to give).
+    with pytest.warns(DeprecationWarning):
+        result, params = _call(client, after=[0, 500], by="intensity")
     assert params["by"] == "intensity"
+    assert result.index.name == "power"
+    assert "after" in result.columns
+    assert result["duration"].dtype == "timedelta64[ns]"
 
 
 def test_by_duration_is_sent_and_duration_indexed(client):

sweatstack-0.88.0/tests/test_write_timezone_validation.py

@@ -0,0 +1,72 @@
+"""The write methods reject timezone-naive datetimes before hitting the API.
+
+The server stores every timestamp as an absolute instant plus its local offset
+and rejects naive datetimes with HTTP 422. The client guards the same contract
+at the call site (``Client._require_aware``) so callers get a clear, immediate
+error naming the offending argument instead of an opaque server response.
+
+All offline: the guard runs before ``_http_client`` is ever touched, so a bare
+``Client.__new__(Client)`` instance is enough.
+"""
+
+from datetime import datetime, timezone
+from zoneinfo import ZoneInfo
+
+import pytest
+
+from sweatstack import Sport
+from sweatstack.client import Client
+
+
+NAIVE = datetime(2026, 3, 15, 9, 0)
+AWARE_UTC = datetime(2026, 3, 15, 9, 0, tzinfo=timezone.utc)
+AWARE_ZONE = datetime(2026, 3, 15, 9, 0, tzinfo=ZoneInfo("Europe/Amsterdam"))
+
+
+class TestRequireAware:
+    def test_naive_rejected_with_helpful_message(self):
+        with pytest.raises(ValueError) as excinfo:
+            Client._require_aware(NAIVE, "timestamp")
+        message = str(excinfo.value)
+        assert "timestamp" in message
+        assert "timezone-aware" in message
+
+    @pytest.mark.parametrize("value", [AWARE_UTC, AWARE_ZONE])
+    def test_aware_passes_through_unchanged(self, value: datetime):
+        assert Client._require_aware(value, "timestamp") is value
+
+
+class TestTraceWritesRejectNaive:
+    def test_create_trace_rejects_naive_timestamp(self):
+        client = Client.__new__(Client)
+        with pytest.raises(ValueError, match="timestamp must be timezone-aware"):
+            client.create_trace(timestamp=NAIVE, lactate=2.0)
+
+    def test_update_trace_rejects_naive_timestamp(self):
+        client = Client.__new__(Client)
+        with pytest.raises(ValueError, match="timestamp must be timezone-aware"):
+            client.update_trace("trace_1", timestamp=NAIVE, lactate=2.0)
+
+
+class TestTestWritesRejectNaive:
+    def test_create_test_rejects_naive_start(self):
+        client = Client.__new__(Client)
+        with pytest.raises(ValueError, match="start must be timezone-aware"):
+            client.create_test(sport=Sport("cycling"), start=NAIVE)
+
+    def test_create_test_rejects_naive_end(self):
+        client = Client.__new__(Client)
+        with pytest.raises(ValueError, match="end must be timezone-aware"):
+            client.create_test(sport=Sport("cycling"), start=AWARE_UTC, end=NAIVE)
+
+    def test_update_test_rejects_naive_start(self):
+        client = Client.__new__(Client)
+        with pytest.raises(ValueError, match="start must be timezone-aware"):
+            client.update_test("test_1", sport=Sport("cycling"), start=NAIVE)
+
+    def test_update_test_rejects_naive_end(self):
+        client = Client.__new__(Client)
+        with pytest.raises(ValueError, match="end must be timezone-aware"):
+            client.update_test(
+                "test_1", sport=Sport("cycling"), start=AWARE_UTC, end=NAIVE
+            )

{sweatstack-0.87.0 → sweatstack-0.88.0}/uv.lock

@@ -2600,7 +2600,7 @@ wheels = [
 
 [[package]]
 name = "sweatstack"
-version = "0.87.0"
+version = "0.88.0"
 source = { editable = "." }
 dependencies = [
     { name = "email-validator" },