sweatstack 0.70.0__tar.gz → 0.71.0__tar.gz

{sweatstack-0.70.0 → sweatstack-0.71.0}/.claude/skills/sweatstack-python/client.md

@@ -102,23 +102,31 @@ Aggregated time-series across multiple activities. One request instead of loopin
 
 ```python
 df = client.get_longitudinal_data(
-    sport=Sport.cycling,                # single sport
+    sports=[Sport.cycling_road],        # list of Sport enum or strings
     start=date(2025, 1, 1),             # required
     end=date(2025, 12, 31),             # optional (defaults to today)
     metrics=[Metric.power, Metric.heart_rate],  # optional
 )
 
-# Or filter by multiple sports
+# Multiple sports
 df = client.get_longitudinal_data(
     sports=[Sport.cycling_road, Sport.cycling_gravel],
     start=date(2025, 1, 1),
 )
 
 # Longitudinal mean-max (best efforts across time range)
-df = client.get_longitudinal_mean_max(sport=Sport.cycling, start=date(2025, 1, 1))
+df = client.get_longitudinal_mean_max(
+    sports=[Sport.cycling_road],
+    metric="power",
+    start=date(2025, 1, 1),
+)
 
 # Longitudinal AWD
-df = client.get_longitudinal_awd(sport=Sport.cycling, start=date(2025, 1, 1))
+df = client.get_longitudinal_awd(
+    sports=[Sport.cycling_road],
+    metric="power",
+    start=date(2025, 1, 1),
+)
 ```
 
 The DataFrame has a timezone-aware datetime index and includes an `activity_id` column — group by it for per-activity aggregation.
@@ -128,7 +136,7 @@ The DataFrame has a timezone-aware datetime index and includes an `activity_id`
 import os
 os.environ["SWEATSTACK_LOCAL_CACHE"] = "true"
 # Use fixed end dates (not "today") to get stable cache hits
-df = client.get_longitudinal_data(sport=Sport.cycling, start=date(2025, 1, 1), end=date(2025, 3, 31))
+df = client.get_longitudinal_data(sports=[Sport.cycling], start=date(2025, 1, 1), end=date(2025, 3, 31))
 ```
 
 ## Traces
@@ -252,7 +260,7 @@ df = sweatstack.get_latest_activity_data()
 
 - **Sport enum uses underscores:** `Sport.cycling_road`, not `Sport("road")` or `Sport.cycling.road`. String values use dots: `"cycling.road"`.
 - **`start` is required for longitudinal endpoints.** Unlike `get_activities()` where all filters are optional.
-- **`sport` (singular) vs `sports` (list):** `get_latest_activity(sport=...)` takes one. `get_activities(sports=[...])` and `get_longitudinal_data(sports=[...])` take a list.
+- **`sport` (singular) vs `sports` (list):** `get_latest_activity(sport=...)` and `create_trace(sport=...)` take a single sport. All other methods that filter by sport use `sports=[...]` (list). The singular `sport` parameter on longitudinal methods is deprecated.
 - **DataFrames have standard dtypes.** The library converts API-optimized types (Int16, float16) to float64/datetime64[ns] automatically.
 - **`as_dataframe=True`** is available on `get_activities()` and `get_traces()`. Time-series methods (`get_activity_data`, `get_longitudinal_data`, etc.) always return DataFrames.
 - **`summary` fields are optional.** Always null-check: `activity.summary.power.mean if activity.summary and activity.summary.power else None`.

{sweatstack-0.70.0 → sweatstack-0.71.0}/CHANGELOG.md

@@ -6,6 +6,20 @@ 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.71.0] - 2026-03-13
+
+### Added
+- `sports` (list) parameter on `get_longitudinal_mean_max()` and `get_longitudinal_awd()` for multi-sport support. The existing `sport` (single) parameter remains for backwards compatibility.
+- `start` and `end` date-range parameters on `get_longitudinal_mean_max()` and `get_longitudinal_awd()`.
+
+### Changed
+- `get_activities()`, `get_traces()`, and `get_longitudinal_data()` now send the `sport` query key to the API instead of `sports`.
+
+### Deprecated
+- `sport` (singular) parameter on `get_longitudinal_mean_max()`, `get_longitudinal_awd()`, and `get_longitudinal_data()`. Use `sports` (list) instead.
+- `date` and `window_days` parameters on `get_longitudinal_mean_max()` and `get_longitudinal_awd()`. Use `start`/`end` instead.
+
+
 ## [0.70.0] - 2026-03-13
 
 ### Added

{sweatstack-0.70.0 → sweatstack-0.71.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.70.0
+Version: 0.71.0
 Summary: The official Python client for SweatStack
 Author-email: Aart Goossens <aart@gssns.io>
 Requires-Python: >=3.9

{sweatstack-0.70.0 → sweatstack-0.71.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sweatstack"
-version = "0.70.0"
+version = "0.71.0"
 description = "The official Python client for SweatStack"
 readme = "README.md"
 authors = [

{sweatstack-0.70.0 → sweatstack-0.71.0}/src/sweatstack/client.py

@@ -10,6 +10,7 @@ import shutil
 import tempfile
 import time
 import urllib
+import warnings
 import webbrowser
 from datetime import date, datetime
 from enum import Enum
@@ -1002,7 +1003,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         if end is not None:
             params["end"] = end.isoformat()
         if sports is not None:
-            params["sports"] = self._enums_to_strings(sports)
+            params["sport"] = self._enums_to_strings(sports)
         if tags is not None:
             params["tags"] = tags
 
@@ -1336,8 +1337,8 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
     def get_longitudinal_data(
         self,
         *,
-        sport: Sport | str | None = None,
         sports: list[Sport | str] | None = None,
+        sport: Sport | str | None = None,
         start: date | str,
         end: date | str | None = None,
         metrics: list[Metric | str] | None = None,
@@ -1349,10 +1350,8 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         including sport type and date range. The data is returned as a pandas DataFrame.
 
         Args:
-            sport: Optional single sport to filter by. Can be a Sport enum or string.
-                Cannot be used together with 'sports'.
             sports: Optional list of sports to filter by. Can be a list of Sport enums or strings.
-                Cannot be used together with 'sport'.
+            sport: Deprecated. Use ``sports`` instead.
             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.
@@ -1366,15 +1365,19 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             ValueError: If both 'sport' and 'sports' parameters are provided.
             HTTPStatusError: If the API request fails.
         """
-        if sport and sports:
-            raise ValueError("Cannot specify both sport and sports")
+        if sport is not None and sports is not None:
+            raise ValueError("Cannot specify both 'sport' and 'sports'.")
         if sport is not None:
+            warnings.warn(
+                "'sport' is deprecated, use 'sports' instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
             sports = [sport]
-        elif sports is None:
-            sports = []
+        resolved = sports if sports is not None else []
 
         params = {
-            "sports": self._enums_to_strings(sports),
+            "sport": self._enums_to_strings(resolved),
             "start": start
         }
         if end is not None:
@@ -1407,42 +1410,64 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
     def get_longitudinal_mean_max(
         self,
         *,
-        sport: Sport | str,
+        sports: list[Sport | str] | None = None,
+        sport: Sport | str | None = None,
         metric: Literal[Metric.power, Metric.speed] | Literal["power", "speed"],
+        start: date | str | None = None,
+        end: date | str | None = None,
         date: date | str | None = None,
         window_days: int | None = None,
     ) -> pd.DataFrame:
-        """Gets the mean-max curve for a specific sport and metric.
-
-        This method retrieves the mean-max curve data for a given sport and metric,
-        optionally filtered by date and window size.
+        """Gets the mean-max curve for one or more sports and a metric.
 
         Args:
-            sport: The sport to get mean-max data for. Can be a Sport enum or string ID.
+            sports: List of sports to get mean-max data for. Can be Sport enums or strings.
+            sport: Deprecated. Use ``sports`` instead.
             metric: The metric to calculate mean-max for. Must be either "power" or "speed".
-            date: Optional reference date for the mean-max calculation. If provided,
-                the mean-max curve will be calculated up to this date. Can be a date object
-                or string in ISO format.
-            window_days: Optional number of days to include in the calculation window
-                before the reference date. If None, all available data is used.
+            start: Start of the date range. Preferred over ``date``/``window_days``.
+            end: End of the date range (defaults to today). Used with ``start``.
+            date: Deprecated. Use ``start`` and ``end`` instead.
+            window_days: Deprecated. Use ``start`` and ``end`` instead.
 
         Returns:
             pd.DataFrame: A pandas DataFrame containing the mean-max curve data.
 
         Raises:
+            ValueError: If both ``sport`` and ``sports`` are provided, or neither is provided.
             HTTPStatusError: If the API request fails.
         """
-        sport = self._enums_to_strings([sport])[0]
+        if sport is not None and sports is not None:
+            raise ValueError("Cannot specify both 'sport' and 'sports'.")
+        if sport is not None:
+            warnings.warn(
+                "'sport' is deprecated, use 'sports' instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            sports = [sport]
+        if sports is None:
+            raise ValueError("'sports' is required.")
         metric = self._enums_to_strings([metric])[0]
 
         params = {
-            "sport": sport,
+            "sport": self._enums_to_strings(sports),
             "metric": metric,
         }
-        if date is not None:
-            params["date"] = date
-        if window_days is not None:
-            params["window_days"] = window_days
+        if start is not None:
+            params["start"] = start
+            if end is not None:
+                params["end"] = end
+        else:
+            if date is not None or window_days is not None:
+                warnings.warn(
+                    "'date' and 'window_days' are deprecated, use 'start' and 'end' instead",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            if date is not None:
+                params["date"] = date
+            if window_days is not None:
+                params["window_days"] = window_days
 
         with self._http_client() as client:
             response = client.get(
@@ -1457,12 +1482,15 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
     def get_longitudinal_awd(
         self,
         *,
-        sport: Sport | str,
+        sports: list[Sport | str] | None = None,
+        sport: Sport | str | None = None,
         metric: Literal[Metric.power, Metric.speed] | Literal["power", "speed"],
+        start: date | str | None = None,
+        end: date | str | None = None,
         date: date | str | None = None,
         window_days: int | None = None,
     ) -> pd.DataFrame:
-        """Gets the longitudinal accumulated work duration (AWD) for a specific sport and metric.
+        """Gets the longitudinal accumulated work duration (AWD) for one or more sports.
 
         This method retrieves AWD values across four intensity levels: max (highest daily AWD),
         hard, medium, and easy (sustainable durations for respective workout intensities).
@@ -1470,31 +1498,53 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         Note: This endpoint is in development and subject to change.
 
         Args:
-            sport: The sport to get AWD data for. Can be a Sport enum or string ID.
+            sports: List of sports to get AWD data for. Can be Sport enums or strings.
+            sport: Deprecated. Use ``sports`` instead.
             metric: The metric to calculate AWD for. Must be either "power" or "speed".
-            date: Optional reference date for the AWD calculation. If provided,
-                the AWD will be calculated up to this date. Can be a date object
-                or string in ISO format.
-            window_days: Optional number of days to include in the calculation window
-                before the reference date. If None, all available data is used.
+            start: Start of the date range. Preferred over ``date``/``window_days``.
+            end: End of the date range (defaults to today). Used with ``start``.
+            date: Deprecated. Use ``start`` and ``end`` instead.
+            window_days: Deprecated. Use ``start`` and ``end`` instead.
 
         Returns:
             pd.DataFrame: A pandas DataFrame containing the longitudinal AWD data with intensity levels.
 
         Raises:
+            ValueError: If both ``sport`` and ``sports`` are provided, or neither is provided.
             HTTPStatusError: If the API request fails.
         """
-        sport = self._enums_to_strings([sport])[0]
+        if sport is not None and sports is not None:
+            raise ValueError("Cannot specify both 'sport' and 'sports'.")
+        if sport is not None:
+            warnings.warn(
+                "'sport' is deprecated, use 'sports' instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            sports = [sport]
+        if sports is None:
+            raise ValueError("'sports' is required.")
         metric = self._enums_to_strings([metric])[0]
 
         params = {
-            "sport": sport,
+            "sport": self._enums_to_strings(sports),
             "metric": metric,
         }
-        if date is not None:
-            params["date"] = date
-        if window_days is not None:
-            params["window_days"] = window_days
+        if start is not None:
+            params["start"] = start
+            if end is not None:
+                params["end"] = end
+        else:
+            if date is not None or window_days is not None:
+                warnings.warn(
+                    "'date' and 'window_days' are deprecated, use 'start' and 'end' instead",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            if date is not None:
+                params["date"] = date
+            if window_days is not None:
+                params["window_days"] = window_days
 
         with self._http_client() as client:
             response = client.get(
@@ -1526,7 +1576,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         if end is not None:
             params["end"] = end.isoformat()
         if sports is not None:
-            params["sports"] = self._enums_to_strings(sports)
+            params["sport"] = self._enums_to_strings(sports)
         if tags is not None:
             params["tags"] = tags