sweatstack 0.84.0__tar.gz → 0.86.0__tar.gz

{sweatstack-0.84.0 → sweatstack-0.86.0}/CHANGELOG.md

@@ -6,6 +6,24 @@ 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.86.0] - 2026-06-18
+
+### Changed
+
+- **Breaking:** renamed the adaptive-sampling parameters to NLEC (near-lossless effort codec). `adaptive_sampling_on` is now `nlec_on` (on `get_activity_data`, `get_latest_activity_data`, `get_longitudinal_data`) and `adaptive_sampling` is now `nlec` (on `get_activity_mean_max`, `get_latest_activity_mean_max`). No backwards-compatible aliases; requires the SweatStack server 0.107.0 or later.
+
+
+## [0.85.0] - 2026-06-17
+
+### Changed
+
+- `get_longitudinal_mean_max(by=...)` now defaults to `None`: the `by` parameter is omitted from the request so the server picks the orientation. For `after` (fatigue) with `metric="power"` the server now defaults to `by="duration"`; every other case stays `by="intensity"`. The returned frame is indexed on whichever orientation the server used. Passing `by` explicitly still works.
+
+### Deprecated
+
+- `by="intensity"` for the `after` (fatigue) case is deprecated and now raises a `DeprecationWarning`; `by="duration"` is the default and only supported orientation going forward. Pass `by="duration"` or leave `by` unset. (`by="intensity"` remains the only orientation for `metric="speed"`.)
+
+
 ## [0.84.0] - 2026-06-17
 
 ### Added

{sweatstack-0.84.0 → sweatstack-0.86.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.84.0
+Version: 0.86.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.84.0 → sweatstack-0.86.0}/pyproject.toml

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

{sweatstack-0.84.0 → sweatstack-0.86.0}/src/sweatstack/client.py

@@ -1219,18 +1219,18 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
     def get_activity_data(
         self,
         activity_id: str,
-        adaptive_sampling_on: Literal["power", "speed"] | None = None,
+        nlec_on: Literal["power", "speed"] | None = None,
         metrics: list[Metric | str] | None = None,
     ) -> pd.DataFrame:
         """Gets the raw data for a specific activity.
 
-        This method retrieves the time-series data for a given activity, with optional
-        adaptive sampling to reduce data points for visualization.
+        This method retrieves the time-series data for a given activity, with optional NLEC
+        (near-lossless effort codec) downsampling to reduce data points for visualization.
 
         Args:
             activity_id: The unique identifier of the activity.
-            adaptive_sampling_on: Optional parameter to apply adaptive sampling on 
-                either "power" or "speed" data. If None, no adaptive sampling is applied.
+            nlec_on: Downsample with NLEC (near-lossless effort codec), keyed on 
+                either "power" or "speed" data. If None, no NLEC is applied.
             metrics: Optional list of metrics to include in the results. Can be a list of Metric enums or strings.
 
         Returns:
@@ -1241,8 +1241,8 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             SweatStackAPIError: If the API request fails for any other reason.
         """
         params = {}
-        if adaptive_sampling_on is not None:
-            params["adaptive_sampling_on"] = adaptive_sampling_on
+        if nlec_on is not None:
+            params["nlec_on"] = nlec_on
         if metrics is not None:
             params["metrics"] = self._enums_to_strings(metrics)
 
@@ -1260,7 +1260,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         self,
         activity_id: str,
         metric: Literal[Metric.power, Metric.speed] | Literal["power", "speed"],
-        adaptive_sampling: bool = False,
+        nlec: bool = False,
     ) -> pd.DataFrame:
         """Gets the mean-max data for a specific activity.
 
@@ -1270,7 +1270,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         Args:
             activity_id: The unique identifier of the activity.
             metric: The metric to calculate mean-max values for, either "power" or "speed".
-            adaptive_sampling: Whether to apply adaptive sampling to reduce data points
+            nlec: Downsample with NLEC (near-lossless effort codec) to reduce data points
                 for visualization. Defaults to False.
 
         Returns:
@@ -1286,7 +1286,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                 url=f"/api/v1/activities/{activity_id}/mean-max",
                 params={
                     "metric": metric,
-                    "adaptive_sampling": adaptive_sampling,
+                    "nlec": nlec,
                 },
             )
             self._raise_for_status(response)
@@ -1332,7 +1332,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
     def get_latest_activity_data(
         self,
         sport: Sport | str | None = None,
-        adaptive_sampling_on: Literal["power", "speed"] | None = None,
+        nlec_on: Literal["power", "speed"] | None = None,
         metrics: list[Metric | str] | None = None,
     ) -> pd.DataFrame:
         """Gets the data for the latest activity of a specific sport.
@@ -1342,7 +1342,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
 
         Args:
             sport: Optional sport to filter by. Can be a Sport enum or string.
-            adaptive_sampling_on: Optional metric to apply adaptive sampling for visualization.
+            nlec_on: Metric to downsample on with NLEC (near-lossless effort codec); omit to disable.
                 Can be either "power" or "speed". Defaults to None.
             metrics: Optional list of metrics to include in the results. Can be a list of Metric enums or strings.
 
@@ -1353,13 +1353,13 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             SweatStackAPIError: If the API request fails.
         """
         activity = self.get_latest_activity(sport=sport)
-        return self.get_activity_data(activity.id, adaptive_sampling_on, metrics=metrics)
+        return self.get_activity_data(activity.id, nlec_on, metrics=metrics)
 
     def get_latest_activity_mean_max(
         self,
         metric: Literal[Metric.power, Metric.speed] | Literal["power", "speed"],
         sport: Sport | str | None = None,
-        adaptive_sampling: bool = False,
+        nlec: bool = False,
     ) -> pd.DataFrame:
         """Gets the mean-max curve for the latest activity of a specific sport.
 
@@ -1369,7 +1369,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         Args:
             metric: The metric to calculate the mean-max curve for. Can be either "power" or "speed".
             sport: Optional sport to filter by. Can be a Sport enum or string.
-            adaptive_sampling: Whether to apply adaptive sampling to the mean-max curve data.
+            nlec: Downsample the mean-max curve with NLEC (near-lossless effort codec).
                 Defaults to False.
 
         Returns:
@@ -1379,7 +1379,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             SweatStackAPIError: If the API request fails.
         """
         activity = self.get_latest_activity(sport=sport)
-        return self.get_activity_mean_max(activity.id, metric, adaptive_sampling)
+        return self.get_activity_mean_max(activity.id, metric, nlec)
 
     def get_longitudinal_data(
         self,
@@ -1389,7 +1389,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         start: date | str,
         end: date | str | None = None,
         metrics: list[Metric | str] | None = None,
-        adaptive_sampling_on: Literal[Metric.power, Metric.speed] | Literal["power", "speed"] | None = None,
+        nlec_on: Literal[Metric.power, Metric.speed] | Literal["power", "speed"] | None = None,
     ) -> pd.DataFrame:
         """Gets longitudinal data for activities within a specified date range.
 
@@ -1402,7 +1402,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             start: The start date for the data range. Can be a date object or string in ISO format.
             end: Optional end date for the data range. Can be a date object or string in ISO format.
             metrics: Optional list of metrics to include in the results. Can be a list of Metric enums or strings.
-            adaptive_sampling_on: Optional metric to apply adaptive sampling for visualization.
+            nlec_on: Metric to downsample on with NLEC (near-lossless effort codec); omit to disable.
                 Can be either "power" or "speed". Defaults to None.
 
         Returns:
@@ -1431,8 +1431,8 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             params["end"] = end
         if metrics is not None:
             params["metrics"] = self._enums_to_strings(metrics)
-        if adaptive_sampling_on is not None:
-            params["adaptive_sampling_on"] = self._enums_to_strings([adaptive_sampling_on])[0]
+        if nlec_on is not None:
+            params["nlec_on"] = self._enums_to_strings([nlec_on])[0]
 
         if self._cache_enabled():
             cache_key = self._generate_cache_key("longitudinal_data", **params)
@@ -1465,7 +1465,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         date: date | str | None = None,
         window_days: int | None = None,
         after: list[float] | float | None = None,
-        by: Literal["intensity", "duration"] = "intensity",
+        by: Literal["intensity", "duration"] | None = None,
     ) -> pd.DataFrame:
         """Gets the mean-max curve for one or more sports and a metric.
 
@@ -1483,9 +1483,14 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                 enveloped across rides. The returned DataFrame then has an ``after``
                 column (one curve per value). Max 5 values; the date range is capped at
                 1 year when ``after`` is used.
-            by: Axis to index the curve on. ``"intensity"`` (default) indexes by the metric
-                value (unchanged). ``"duration"`` indexes by duration via the fast segment
-                kernel; currently requires ``after`` and ``metric="power"``.
+            by: Axis to index the curve on, only meaningful with ``after``. ``"duration"``
+                indexes by duration via the fast segment kernel (requires ``metric="power"``);
+                ``"intensity"`` indexes by the metric value and is **deprecated**. For the
+                ``after`` case ``"duration"`` will become the only supported orientation, and
+                more generally ``"duration"`` is set to become the default and only option, so
+                we recommend passing ``by="duration"`` explicitly. When left as ``None``
+                (default), the server picks: ``after`` with ``metric="power"`` resolves to
+                ``"duration"``, every other case to ``"intensity"``.
 
         Returns:
             pd.DataFrame: A pandas DataFrame containing the mean-max curve data, indexed by
@@ -1509,11 +1514,31 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             raise ValueError("'sports' is required.")
         metric = self._enums_to_strings([metric])[0]
 
+        # For the fatigue ('after') case, by='duration' is the default and the only
+        # orientation going forward; by='intensity' is deprecated there. (For metric='speed'
+        # it is still the only option, so no warning.)
+        if by == "intensity" and after is not None and metric == "power":
+            warnings.warn(
+                "by='intensity' is deprecated for 'after' (fatigue) mean-max; by='duration' "
+                "is the default and only supported orientation going forward. Pass "
+                "by='duration' or leave 'by' unset.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        # Mirror the server's default resolution so the returned frame is indexed on the
+        # orientation the server actually used. ``by=None`` omits the param (the server
+        # decides and the deprecated value-indexed path is not forced).
+        effective_by = by if by is not None else (
+            "duration" if (after is not None and metric == "power") else "intensity"
+        )
+
         params = {
             "sport": self._enums_to_strings(sports),
             "metric": metric,
-            "by": by,
         }
+        if by is not None:
+            params["by"] = by
         if start is not None:
             params["start"] = start
             if end is not None:
@@ -1536,7 +1561,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             cache_key = self._generate_cache_key("mean_max", **params)
             cached = self._read_cache("mean_max", cache_key)
             if cached is not None:
-                return self._shape_mean_max(pd.read_parquet(BytesIO(cached)), metric, after, by)
+                return self._shape_mean_max(pd.read_parquet(BytesIO(cached)), metric, after, effective_by)
 
         with self._http_client() as client:
             response = client.get(
@@ -1548,7 +1573,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             if self._cache_enabled():
                 self._write_cache("mean_max", cache_key, response.content)
 
-            return self._shape_mean_max(pd.read_parquet(BytesIO(response.content)), metric, after, by)
+            return self._shape_mean_max(pd.read_parquet(BytesIO(response.content)), metric, after, effective_by)
 
     def _shape_mean_max(self, df: pd.DataFrame, metric: str, after, by: str = "intensity") -> pd.DataFrame:
         """Standard post-processing for mean-max responses. The ``after`` response is

{sweatstack-0.84.0 → sweatstack-0.86.0}/uv.lock

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