PyPI - sweatstack - Versions diffs - 0.54.0__py3-none-any.whl → 0.55.0__py3-none-any.whl - Mend

sweatstack 0.54.0py3-none-any.whl → 0.55.0py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

sweatstack/client.py CHANGED Viewed

@@ -51,8 +51,16 @@ AUTH_SUCCESSFUL_RESPONSE = """<!DOCTYPE html>
 OAUTH2_CLIENT_ID = "5382f68b0d254378"
-class LocalCacheMixin:
-    """Mixin for handling local filesystem caching of API responses."""
+class _LocalCacheMixin:
+    """Mixin for handling local filesystem caching of API responses.
+    Caching is controlled via environment variables:
+    - :envvar:`SWEATSTACK_LOCAL_CACHE` - Enable/disable caching
+    - :envvar:`SWEATSTACK_CACHE_DIR` - Custom cache directory location
+    Use :meth:`clear_cache` to remove all cached data for the current user.
+    """
     def _cache_enabled(self) -> bool:
         """Check if local caching is enabled."""
@@ -155,7 +163,7 @@ class LocalCacheMixin:
             self._log_cache_error("clear", e)
-class TokenStorageMixin:
+class _TokenStorageMixin:
     """Mixin for handling persistent token storage using platformdirs."""
     def _get_token_file_path(self) -> Path:
@@ -200,7 +208,9 @@ except ImportError:
     __version__ = "unknown"
-class OAuth2Mixin:
+class _OAuth2Mixin:
+    """OAuth2 authentication methods for the Client class."""
     def generate_pkce_params(self) -> tuple[str, str]:
         """Generate PKCE parameters for OAuth2 authorization.
@@ -436,7 +446,9 @@ class OAuth2Mixin:
         self.login(persist_api_key=persist_api_key)
-class DelegationMixin:
+class _DelegationMixin:
+    """User delegation methods for accessing data on behalf of other users."""
     def _validate_user(self, user: str | UserSummary):
         if isinstance(user, UserSummary):
             return user.id
@@ -639,7 +651,18 @@ class DelegationMixin:
         )
-class Client(OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin):
+class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixin):
+    """SweatStack API client for accessing activities, traces, and user data.
+    The Client handles authentication, API requests, and data retrieval from SweatStack.
+    You can initialize it with credentials or use authenticate()/login() for OAuth2.
+    Example:
+        client = Client()
+        client.authenticate()
+        activities = client.get_activities(limit=10)
+    """
     def __init__(
         self,
         api_key: str | None = None,
@@ -647,6 +670,14 @@ class Client(OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin):
         url: str | None = None,
         streamlit_compatible: bool = False,
     ):
+        """Initialize a SweatStack client.
+        Args:
+            api_key: Optional API access token. If not provided, will check environment or storage.
+            refresh_token: Optional refresh token for automatic token renewal.
+            url: Optional SweatStack instance URL. Defaults to production.
+            streamlit_compatible: Set to True when using in Streamlit apps.
+        """
         self.api_key = api_key
         self.refresh_token = refresh_token
         self.url = url
@@ -684,6 +715,11 @@ class Client(OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin):
     @property
     def api_key(self) -> str:
+        """The current API access token.
+        Automatically loads from instance, environment (SWEATSTACK_API_KEY),
+        or persistent storage. Refreshes expired tokens automatically.
+        """
         if self._api_key is not None:
             value = self._api_key
         elif value := os.getenv("SWEATSTACK_API_KEY"):
@@ -703,6 +739,10 @@ class Client(OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin):
     @property
     def refresh_token(self) -> str:
+        """The refresh token used for automatic token renewal.
+        Loads from instance, environment (SWEATSTACK_REFRESH_TOKEN), or persistent storage.
+        """
         if self._refresh_token is not None:
             return self._refresh_token
         elif value := os.getenv("SWEATSTACK_REFRESH_TOKEN"):
@@ -1042,6 +1082,41 @@ class Client(OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin):
             df = pd.read_parquet(BytesIO(response.content))
             return self._postprocess_dataframe(df)
+    def get_activity_awd(
+        self,
+        activity_id: str,
+        metric: Literal[Metric.power, Metric.speed] | Literal["power", "speed"] | None = None,
+    ) -> pd.DataFrame:
+        """Gets the accumulated work duration (AWD) for a specific activity.
+        This method retrieves accumulated work duration metrics for a specific activity.
+        AWD represents the total duration spent at each intensity level by sorting
+        activity data by intensity.
+        Args:
+            activity_id: The unique identifier of the activity.
+            metric: Optional metric type. Defaults to power for cycling, speed for other sports.
+                Can be either "power" or "speed".
+        Returns:
+            pd.DataFrame: A pandas DataFrame containing the AWD data.
+        Raises:
+            HTTPStatusError: If the API request fails.
+        """
+        params = {}
+        if metric is not None:
+            params["metric"] = self._enums_to_strings([metric])[0]
+        with self._http_client() as client:
+            response = client.get(
+                url=f"/api/v1/activities/{activity_id}/accumulated-work-duration",
+                params=params,
+            )
+            self._raise_for_status(response)
+            df = pd.read_parquet(BytesIO(response.content))
+            return self._postprocess_dataframe(df)
     def get_latest_activity_data(
         self,
         sport: Sport | str | None = None,
@@ -1215,6 +1290,57 @@ class Client(OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin):
             df = pd.read_parquet(BytesIO(response.content))
             return self._postprocess_dataframe(df)
+    def get_longitudinal_awd(
+        self,
+        *,
+        sport: Sport | str,
+        metric: Literal[Metric.power, Metric.speed] | Literal["power", "speed"],
+        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.
+        This method retrieves AWD values across four intensity levels: max (highest daily AWD),
+        hard, medium, and easy (sustainable durations for respective workout intensities).
+        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.
+            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.
+        Returns:
+            pd.DataFrame: A pandas DataFrame containing the longitudinal AWD data with intensity levels.
+        Raises:
+            HTTPStatusError: If the API request fails.
+        """
+        sport = self._enums_to_strings([sport])[0]
+        metric = self._enums_to_strings([metric])[0]
+        params = {
+            "sport": sport,
+            "metric": metric,
+        }
+        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(
+                url="/api/v1/activities/longitudinal-accumulated-work-duration",
+                params=params,
+            )
+            self._raise_for_status(response)
+            df = pd.read_parquet(BytesIO(response.content))
+            return self._postprocess_dataframe(df)
     def _get_traces_generator(
         self,
         *,
@@ -1621,6 +1747,7 @@ _generate_singleton_methods(
         "get_activity",
         "get_activity_data",
         "get_activity_mean_max",
+        "get_activity_awd",
         "get_latest_activity",
         "get_latest_activity_data",
@@ -1628,6 +1755,7 @@ _generate_singleton_methods(
         "get_longitudinal_data",
         "get_longitudinal_mean_max",
+        "get_longitudinal_awd",
         "get_traces",
         "create_trace",

sweatstack/schemas.py CHANGED Viewed

@@ -1,3 +1,15 @@
+"""SweatStack data schemas and utilities.
+This module re-exports Pydantic models from openapi_schemas and extends
+the Sport and Metric enums with convenient utility methods.
+Example:
+    sport = Sport.cycling_road
+    print(sport.display_name())  # "cycling (road)"
+    print(sport.root_sport())    # Sport.cycling
+    print(sport.is_root_sport())  # False
+    print(sport.is_sub_sport_of(Sport.cycling))  # True
+"""
 from enum import Enum
 from typing import List, Union
@@ -7,7 +19,7 @@ from .openapi_schemas import (
 )
-def parent_sport(sport: Sport) -> Sport:
+def _parent_sport(sport: Sport) -> Sport:
     """Returns the parent sport of a given sport.
     For sports with a hierarchical structure (e.g., 'cycling.road'), returns the parent sport
@@ -25,7 +37,7 @@ def parent_sport(sport: Sport) -> Sport:
     return sport.__class__(".".join(parts[:-1]))
-def root_sport(sport: Sport) -> Sport:
+def _root_sport(sport: Sport) -> Sport:
     """Returns the root sport of a given sport.
     For sports with a hierarchical structure (e.g., 'cycling.road' or 'cycling.road.gravel'),
@@ -40,7 +52,7 @@ def root_sport(sport: Sport) -> Sport:
     return sport.__class__(sport.value.split(".")[0])
-def is_root_sport(sport: Sport) -> bool:
+def _is_root_sport(sport: Sport) -> bool:
     """Determines if a sport is a root sport.
     A root sport is one that doesn't have a parent sport in the hierarchy
@@ -52,10 +64,10 @@ def is_root_sport(sport: Sport) -> bool:
     Returns:
         bool: True if the sport is a root sport, False otherwise.
     """
-    return sport == root_sport(sport)
+    return sport == _root_sport(sport)
-def is_sub_sport_of(sport: Sport, sport_or_sports: Union[Sport, List[Sport]]) -> bool:
+def _is_sub_sport_of(sport: Sport, sport_or_sports: Union[Sport, List[Sport]]) -> bool:
     """Determines if a sport is a sub-sport of another sport or list of sports.
     For example, 'cycling.road' is a sub-sport of 'cycling', but not of 'running'.
@@ -73,12 +85,12 @@ def is_sub_sport_of(sport: Sport, sport_or_sports: Union[Sport, List[Sport]]) ->
     if isinstance(sport_or_sports, Sport):
         return sport.value.startswith(sport_or_sports.value)
     elif isinstance(sport_or_sports, (list, tuple)):
-        return any(is_sub_sport_of(sport, sport) for sport in sport_or_sports)
+        return any(_is_sub_sport_of(sport, s) for s in sport_or_sports)
     else:
         raise ValueError(f"Invalid type for sport_or_sports: {type(sport_or_sports)}")
-def display_name(sport: Sport) -> str:
+def _display_name(sport: Sport) -> str:
     """Returns a human-readable display name for a sport.
     This function converts a Sport enum value into a formatted string suitable for display.
@@ -98,13 +110,23 @@ def display_name(sport: Sport) -> str:
     return f"{base_sport} ({the_rest})"
-Sport.root_sport = root_sport
-Sport.parent_sport = parent_sport
-Sport.is_sub_sport_of = is_sub_sport_of
-Sport.display_name = display_name
+Sport.root_sport = _root_sport
+Sport.root_sport.__doc__ = _root_sport.__doc__
+Sport.parent_sport = _parent_sport
+Sport.parent_sport.__doc__ = _parent_sport.__doc__
-def metric_display_name(metric: Metric) -> str:
+Sport.is_sub_sport_of = _is_sub_sport_of
+Sport.is_sub_sport_of.__doc__ = _is_sub_sport_of.__doc__
+Sport.is_root_sport = _is_root_sport
+Sport.is_root_sport.__doc__ = _is_root_sport.__doc__
+Sport.display_name = _display_name
+Sport.display_name.__doc__ = _display_name.__doc__
+def _metric_display_name(metric: Metric) -> str:
     """Returns a human-readable display name for a metric.
     This function converts a Metric enum value into a formatted string suitable for display.
@@ -112,4 +134,5 @@ def metric_display_name(metric: Metric) -> str:
     return metric.value.replace("_", " ")
-Metric.display_name = metric_display_name
+Metric.display_name = _metric_display_name
+Metric.display_name.__doc__ = _metric_display_name.__doc__

sweatstack/streamlit.py CHANGED Viewed

@@ -1,3 +1,29 @@
+"""Streamlit integration for SweatStack authentication and UI components.
+This module provides authentication and UI helper components for building
+Streamlit applications with SweatStack. The StreamlitAuth class handles
+OAuth2 authentication flow and provides convenient selector components.
+Example:
+    import streamlit as st
+    from sweatstack.streamlit import StreamlitAuth
+    auth = StreamlitAuth(
+        client_id="YOUR_APPLICATION_ID",
+        client_secret="YOUR_APPLICATION_SECRET",
+        redirect_uri="http://localhost:8501",
+    )
+    with st.sidebar:
+        auth.authenticate()
+    if not auth.is_authenticated():
+        st.stop()
+    st.write("Welcome!")
+    latest = auth.client.get_latest_activity()
+    st.write(f"Latest: {latest.sport}")
+"""
 import os
 import urllib.parse
 from datetime import date
@@ -18,6 +44,46 @@ from .schemas import Metric, Scope, Sport
 class StreamlitAuth:
+    """Handles SweatStack authentication and provides UI components for Streamlit apps.
+    This class manages OAuth2 authentication flow for Streamlit applications and provides
+    convenient selector components for activities, sports, tags, and metrics. Once authenticated,
+    the client property provides access to the SweatStack API.
+    Example:
+        import streamlit as st
+        from sweatstack.streamlit import StreamlitAuth
+        # Initialize authentication
+        auth = StreamlitAuth(
+            client_id="YOUR_APPLICATION_ID",
+            client_secret="YOUR_APPLICATION_SECRET",
+            redirect_uri="http://localhost:8501",
+        )
+        # Add authentication to sidebar
+        with st.sidebar:
+            auth.authenticate()
+        # Check authentication
+        if not auth.is_authenticated():
+            st.write("Please log in to continue")
+            st.stop()
+        # 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}")
+        # Switch between accessible users (admin feature)
+        with st.sidebar:
+            auth.select_user()
+    Attributes:
+        client: The SweatStack Client instance for API access.
+        api_key: The current API access token.
+    """
     def __init__(
         self,
         client_id=None,
@@ -25,12 +91,13 @@ class StreamlitAuth:
         scopes: List[Union[str, Scope]]=None,
         redirect_uri=None,
     ):
-        """
+        """Initialize the StreamlitAuth component.
         Args:
-            client_id: The client ID to use. If not provided, the SWEATSTACK_CLIENT_ID environment variable will be used.
-            client_secret: The client secret to use. If not provided, the SWEATSTACK_CLIENT_SECRET environment variable will be used.
-            scopes: The scopes to use. If not provided, the SWEATSTACK_SCOPES environment variable will be used. Defaults to data:read, profile.
-            redirect_uri: The redirect URI to use. If not provided, the SWEATSTACK_REDIRECT_URI environment variable will be used.
+            client_id: OAuth2 client ID. Falls back to SWEATSTACK_CLIENT_ID env var.
+            client_secret: OAuth2 client secret. Falls back to SWEATSTACK_CLIENT_SECRET env var.
+            scopes: OAuth2 scopes. Falls back to SWEATSTACK_SCOPES env var. Defaults to data:read, profile.
+            redirect_uri: OAuth2 redirect URI. Falls back to SWEATSTACK_REDIRECT_URI env var.
         """
         self.client_id = client_id or os.environ.get("SWEATSTACK_CLIENT_ID")
         self.client_secret = client_secret or os.environ.get("SWEATSTACK_CLIENT_SECRET")
@@ -51,6 +118,11 @@ class StreamlitAuth:
         self.client = Client(self.api_key, streamlit_compatible=True)
     def logout_button(self):
+        """Displays a logout button and handles user logout.
+        When clicked, this button clears the stored API key from session state,
+        resets the client, and triggers a Streamlit rerun to update the UI.
+        """
         if st.button("Logout"):
             self.api_key = None
             self.client = Client(streamlit_compatible=True)
@@ -58,9 +130,15 @@ class StreamlitAuth:
             st.rerun()
     def _running_on_streamlit_cloud(self):
+        """Detects if the app is running on Streamlit Cloud."""
         return os.environ.get("HOSTNAME") == "streamlit"
     def _show_sweatstack_login(self, login_label: str | None = None):
+        """Displays the SweatStack login button with appropriate styling.
+        Args:
+            login_label: Text to display on the login button.
+        """
         authorization_url = self.get_authorization_url()
         login_label = login_label or "Connect with SweatStack"
         if not self._running_on_streamlit_cloud():
@@ -96,6 +174,14 @@ class StreamlitAuth:
             st.link_button(login_label, authorization_url)
     def get_authorization_url(self):
+        """Generates the OAuth2 authorization URL for SweatStack.
+        This method constructs the URL users will be redirected to for OAuth2 authorization.
+        It includes the client ID, redirect URI, scopes, and other OAuth2 parameters.
+        Returns:
+            str: The complete authorization URL.
+        """
         params = {
             "client_id": self.client_id,
             "redirect_uri": self.redirect_uri,
@@ -108,11 +194,24 @@ class StreamlitAuth:
         return authorization_url
     def _set_api_key(self, api_key):
+        """Sets the API key in instance and session state, then refreshes the client.
+        Args:
+            api_key: The API access token to set.
+        """
         self.api_key = api_key
         st.session_state["sweatstack_api_key"] = api_key
         self.client = Client(self.api_key, streamlit_compatible=True)
     def _exchange_token(self, code):
+        """Exchanges an authorization code for an access token.
+        Args:
+            code: The authorization code from the OAuth2 callback.
+        Raises:
+            Exception: If the token exchange fails.
+        """
         token_data = {
             "grant_type": "authorization_code",
             "client_id": self.client_id,

{sweatstack-0.54.0.dist-info → sweatstack-0.55.0.dist-info}/METADATA RENAMED Viewed

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

{sweatstack-0.54.0.dist-info → sweatstack-0.55.0.dist-info}/RECORD RENAMED Viewed

@@ -1,17 +1,17 @@
 sweatstack/__init__.py,sha256=tiVfgKlswRPaDMEy0gA7u8rveqEYZTA_kyB9lJ3J6Sc,21
 sweatstack/cli.py,sha256=N1NWOgEZR2yaJvIXxo9qvp_jFlypZYb0nujpbVNYQ6A,720
-sweatstack/client.py,sha256=rqK9MAe-gzxO3v2xPAjQhsZSNBO23GvUZ4rUtzyucyQ,60050
+sweatstack/client.py,sha256=1JW7c_yPR4YARYBo6E_mx6iN13pU0zyl8rs6oTxdiUc,65126
 sweatstack/constants.py,sha256=fGO6ksOv5HeISv9lHRoYm4besW1GTveXS8YD3K0ljg0,41
 sweatstack/ipython_init.py,sha256=OtBB9dQvyLXklD4kA2x1swaVtU9u73fG4V4-zz4YRAg,139
 sweatstack/jupyterlab_oauth2_startup.py,sha256=YcjXvzeZ459vL_dCkFi1IxX_RNAu80ZX9rwa0OXJfTM,1023
 sweatstack/openapi_schemas.py,sha256=VvquBdbssdB9D1KeJYQCx51hy1Df4SS0PjzGWXcUaew,46221
 sweatstack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sweatstack/schemas.py,sha256=MLC41p1iGA1HxmZSLuGifHra3r_o0pHIQzZ4ejRrYug,3698
-sweatstack/streamlit.py,sha256=AaVFkNN0iO3oFBMTBWra4pkaQbSZQnrgHqsab50Zm48,13295
+sweatstack/schemas.py,sha256=Xh9E8DjFx5NIEBnVqS6ixFVb0E06ANZbdOlnMofCpZw,4481
+sweatstack/streamlit.py,sha256=sJSVWRAY-CT3FuEPKA41h4S0BsaVFChs0M_oVIj0VFQ,16520
 sweatstack/sweatshell.py,sha256=MYLNcWbOdceqKJ3S0Pe8dwHXEeYsGJNjQoYUXpMTftA,333
 sweatstack/utils.py,sha256=AwHRdC1ziOZ5o9RBIB21Uxm-DoClVRAJSVvgsmSmvps,1801
 sweatstack/Sweat Stack examples/Getting started.ipynb,sha256=k2hiSffWecoQ0VxjdpDcgFzBXDQiYEebhnAYlu8cgX8,6335204
-sweatstack-0.54.0.dist-info/METADATA,sha256=PzZy2wDb6CqOrSn6XhxEGn7AZGrl9X7odS_QP6FZqx4,852
-sweatstack-0.54.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sweatstack-0.54.0.dist-info/entry_points.txt,sha256=kCzOUQI3dqbTpEYqtgYDeiKFaqaA7BMlV6D24BMzCFU,208
-sweatstack-0.54.0.dist-info/RECORD,,
+sweatstack-0.55.0.dist-info/METADATA,sha256=sRtgay1gBJG-kQVB0InAV0tnAPbZKFZaPl0NS5sQvpk,852
+sweatstack-0.55.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sweatstack-0.55.0.dist-info/entry_points.txt,sha256=kCzOUQI3dqbTpEYqtgYDeiKFaqaA7BMlV6D24BMzCFU,208
+sweatstack-0.55.0.dist-info/RECORD,,

{sweatstack-0.54.0.dist-info → sweatstack-0.55.0.dist-info}/WHEEL RENAMED Viewed

File without changes

{sweatstack-0.54.0.dist-info → sweatstack-0.55.0.dist-info}/entry_points.txt RENAMED Viewed

File without changes

sweatstack 0.54.0__py3-none-any.whl → 0.55.0__py3-none-any.whl

sweatstack 0.54.0py3-none-any.whl → 0.55.0py3-none-any.whl