sweatstack 0.69.0__tar.gz → 0.71.0__tar.gz

{sweatstack-0.69.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
@@ -176,6 +184,7 @@ user = client.create_user(first_name="John", last_name="Doe")
 
 # Team management
 team_users = client.get_team_users(team_id="team_abc")
+athlete = client.get_team_user(team_id="team_abc", user="john")  # by name or ID
 client.authorize_team(team_id="team_abc", scopes=[Scope.data_read])
 ```
 
@@ -187,9 +196,12 @@ Operate on behalf of another user (requires appropriate permissions).
 
 ```python
 other = client.delegated_client("john")
-other = client.delegated_client("john", team_id="team_abc")  # via team
 other_activities = other.get_activities()
 # original client is unchanged
+
+# Via team membership
+athlete = client.get_team_user(team_id="team_abc", user="john")
+other = client.delegated_client(athlete, team_id="team_abc")
 ```
 
 `switch_user()` modifies the client in-place — useful in interactive/notebook contexts but avoid in scripts:
@@ -248,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.69.0 → sweatstack-0.71.0}/CHANGELOG.md

@@ -6,6 +6,29 @@ 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
+- Added `get_team_user(*, team_id, user, search_mode)` method to find a single team-authorized user by ID or name.
+
+### Changed
+- Refactored internal user lookup into reusable `_find_user()`, `_find_user_by_name()`, and `_find_user_by_id()` helpers shared by `get_user()` and `get_team_user()`.
+
+
 ## [0.69.0] - 2026-03-12
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.69.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.69.0 → sweatstack-0.71.0}/pyproject.toml

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

{sweatstack-0.69.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
@@ -498,72 +499,77 @@ class _DelegationMixin:
 
         return len(user) in (16, 26) and user.isalnum()
 
-    def _get_user_by_name(self, name: str) -> UserSummary:
-        """Get a user by name.
+    def _find_user_by_name(self, name: str, users: list) -> UserSummary:
+        """Find a user by name from a list of users.
 
         Args:
-            name: The name of the user to get.
+            name: The (partial) display name to search for.
+            users: The list of UserSummary objects to search.
 
         Returns:
-            UserSummary: The user object.
+            UserSummary: The matching user.
 
         Raises:
-            ValueError: If the user is not found.
-            ValueError: If multiple users are found with the same name.
+            ValueError: If no match or multiple matches found.
         """
-        matches = []
-        for user in self.get_users():
-            if name in user.display_name.lower():
-                matches.append(user)
+        matches = [u for u in users if name in u.display_name.lower()]
 
         if len(matches) == 0:
             raise ValueError(f"User with name {name} not found")
         elif len(matches) > 1:
-            raise ValueError(f"Multiple users found with name {name}: {', '.join([user.display_name for user in matches])}")
+            raise ValueError(f"Multiple users found with name {name}: {', '.join([u.display_name for u in matches])}")
         return matches[0]
 
-    def _get_user_by_id(self, id: str) -> UserSummary:
-        """Get a user by ID.
+    def _find_user_by_id(self, id: str, users: list) -> UserSummary:
+        """Find a user by ID from a list of users.
 
         Args:
-            id: The ID of the user to get.
+            id: The user ID to search for.
+            users: The list of UserSummary objects to search.
 
         Returns:
-            UserSummary: The user object.
+            UserSummary: The matching user, or None if not found.
+        """
+        return next((u for u in users if u.id == id), None)
 
-        Raises:
-            HTTPStatusError: If the user is not found.
+    def _find_user(self, user: str, users: list, search_mode: Literal["auto", "id", "name"] = "auto") -> UserSummary:
+        """Find a user by ID or name from a list of users.
+
+        Args:
+            user: User ID or (part of) display name.
+            users: The list of UserSummary objects to search.
+            search_mode: "auto" (detect), "id", or "name".
+
+        Returns:
+            UserSummary: The matching user.
         """
-        # TODO: Implement this using a user detail endpoint
-        return next((user for user in self.get_users() if user.id == id), None)
+        if search_mode == "auto":
+            if self._is_user_id(user):
+                return self._find_user_by_id(user, users)
+            else:
+                return self._find_user_by_name(user, users)
+        elif search_mode == "id":
+            return self._find_user_by_id(user, users)
+        elif search_mode == "name":
+            return self._find_user_by_name(user, users)
 
     def get_user(self, user: str, *, search_mode: Literal["auto", "id", "name"] = "auto") -> UserSummary:
         """Get a user by ID or name.
         This method will always authenticate as the principal user.
 
         Args:
-            user: Either a UserSummary object or a string representing the user id or (part of) the user name to get.
-            search_mode: The mode to use when searching for the user.
-                - "auto": Automatically determine the search mode based on the type of user argument.
-                - "id": Search for the user by ID.
-                - "name": Search for the user by name.
+            user: User ID or (part of) display name.
+            search_mode: "auto" (detect), "id", or "name".
 
         Returns:
             UserSummary: The user object.
 
         Raises:
-            HTTPStatusError: If the user is not found.
+            ValueError: If no match or multiple matches found.
         """
         client = self.principal_client()
-        if search_mode == "auto":
-            if client._is_user_id(user):
-                return client._get_user_by_id(user)
-            else:
-                return client._get_user_by_name(user)
-        elif search_mode == "id":
-            return client._get_user_by_id(user)
-        elif search_mode == "name":
-            return client._get_user_by_name(user)
+        users = client.get_users()
+        return client._find_user(user, users, search_mode)
 
     def switch_user(
         self,
@@ -997,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
 
@@ -1331,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,
@@ -1344,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.
@@ -1361,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:
@@ -1402,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(
@@ -1452,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).
@@ -1465,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(
@@ -1521,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
 
@@ -1787,6 +1842,30 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             self._raise_for_status(response)
             return [UserSummary.model_validate(user) for user in response.json()]
 
+    def get_team_user(
+        self,
+        *,
+        team_id: str,
+        user: str,
+        search_mode: Literal["auto", "id", "name"] = "auto",
+    ) -> UserSummary:
+        """Get a team-authorized user by ID or name.
+
+        Args:
+            team_id: The team's ID.
+            user: User ID or (part of) display name.
+            search_mode: "auto" (detect), "id", or "name".
+
+        Returns:
+            UserSummary: The matching user.
+
+        Raises:
+            ValueError: If no match or multiple matches found.
+            HTTPStatusError: If the API request fails.
+        """
+        users = self.get_team_users(team_id)
+        return self._find_user(user, users, search_mode)
+
     def authorize_team(self, team_id: str, scopes: list[Scope | str] | None = None):
         """Authorizes a team to access the current user's data.
 
@@ -2018,6 +2097,7 @@ _generate_singleton_methods(
         "get_users",
         "create_user",
         "get_team_users",
+        "get_team_user",
         "authorize_team",
         "get_userinfo",
         "whoami",