sweatstack 0.54.0__tar.gz → 0.56.0__tar.gz

{sweatstack-0.54.0 → sweatstack-0.56.0}/.claude/settings.local.json

@@ -2,8 +2,9 @@
   "permissions": {
     "allow": [
       "Bash(python:*)",
-      "WebFetch(domain:app.sweatstack.no)"
+      "WebFetch(domain:app.sweatstack.no)",
+      "Bash(cat:*)"
     ],
     "deny": []
   }
-}
+}

{sweatstack-0.54.0 → sweatstack-0.56.0}/.gitignore

@@ -8,3 +8,6 @@ wheels/
 
 # Virtual environments
 .venv
+
+# Documentation
+docs/_build/

{sweatstack-0.54.0 → sweatstack-0.56.0}/CHANGELOG.md

@@ -6,6 +6,19 @@ 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.56.0] - 2025-11-21
+
+### Fixed
+- Fixed an issue where refreshing the token would not succeed with the Streamlit integration.
+
+
+## [0.55.0] - 2025-10-24
+
+### Added
+- Added a new `get_activity_awd()` method to the `ss.Client` class that allows for getting the accumulated work duration (AWD) data for a specific activity.
+- Added a new `get_longitudinal_awd()` method to the `ss.Client` class that allows for getting the AWD data for a specific date range.
+
+
 ## [0.54.0] - 2025-09-11
 
 ### Added

sweatstack-0.56.0/Makefile

@@ -0,0 +1,12 @@
+.PHONY: build publish docs
+
+
+build:
+	rm -rf dist
+	uvx --from build pyproject-build --installer uv
+
+publish: build
+	uvx twine upload dist/*
+
+docs:
+	uv run sphinx-build -b markdown docs docs/_build/markdown

{sweatstack-0.54.0 → sweatstack-0.56.0}/PKG-INFO

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

sweatstack-0.56.0/docs/conf.py

@@ -0,0 +1,26 @@
+import os
+import sys
+
+# So autodoc can import your package
+sys.path.insert(0, os.path.abspath(".."))  # adjust if needed
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",        # if you use Google/NumPy docstrings
+    "sphinx_markdown_builder",    # <-- this is the important one
+    "myst_parser",                # optional, for .md sources
+]
+
+autosummary_generate = True
+
+# Autodoc configuration
+autodoc_default_options = {
+    'private-members': False,  # Don't document private members (starting with _)
+    'special-members': False,  # Don't document special members (like __init__ unless specified)
+}
+
+# Optional nice-to-haves for markdown builder:
+markdown_anchor_sections = True   # add anchors to each section/function/class
+markdown_anchor_signatures = True # add anchors to signatures
+markdown_bullet = "*"

sweatstack-0.56.0/docs/everything.rst

@@ -0,0 +1,260 @@
+Complete API Reference
+======================
+
+Environment Variables
+=====================
+
+The SweatStack client library uses environment variables for configuration.
+These variables provide defaults for authentication, caching, and Streamlit integration.
+
+Authentication
+--------------
+
+.. envvar:: SWEATSTACK_API_KEY
+
+   API access token for authenticating with SweatStack.
+
+   Automatically loaded by the Client if not provided during initialization.
+   Falls back to persistent storage if not found in environment.
+
+   Example::
+
+      export SWEATSTACK_API_KEY="your_token_here"
+
+.. envvar:: SWEATSTACK_REFRESH_TOKEN
+
+   Refresh token used for automatic token renewal.
+
+   Loaded from environment, instance, or persistent storage. Used by the Client
+   to automatically refresh expired access tokens.
+
+.. envvar:: SWEATSTACK_URL
+
+   Custom SweatStack instance URL.
+
+   Override the default SweatStack API URL. Useful for testing or
+   connecting to self-hosted instances.
+
+   Default: ``https://app.sweatstack.no``
+
+Caching
+-------
+
+.. envvar:: SWEATSTACK_LOCAL_CACHE
+
+   Enable local filesystem caching of API responses.
+
+   Set to any truthy value (``1``, ``true``, ``yes``) to enable caching
+   of longitudinal data requests. Cached data persists across sessions.
+   Use ``client.clear_cache()`` to remove cached data.
+
+   Default: Disabled
+
+   Example::
+
+      export SWEATSTACK_LOCAL_CACHE=1
+
+.. envvar:: SWEATSTACK_CACHE_DIR
+
+   Custom directory location for cached data.
+
+   Specify where to store cached API responses. If not set, defaults to
+   the system temp directory with a ``sweatstack/{user_id}`` subdirectory.
+
+   Default: System temp directory (e.g., ``/tmp/sweatstack/{user_id}``)
+
+   Example::
+
+      export SWEATSTACK_CACHE_DIR=/path/to/cache
+
+Streamlit OAuth2
+----------------
+
+These environment variables are used by :class:`sweatstack.streamlit.StreamlitAuth`
+for OAuth2 authentication in Streamlit applications.
+
+.. envvar:: SWEATSTACK_CLIENT_ID
+
+   OAuth2 application client ID.
+
+   The client ID from your registered SweatStack OAuth2 application.
+   Required for Streamlit authentication if not provided to StreamlitAuth.
+
+.. envvar:: SWEATSTACK_CLIENT_SECRET
+
+   OAuth2 application client secret.
+
+   The client secret from your registered SweatStack OAuth2 application.
+   Required for Streamlit authentication if not provided to StreamlitAuth.
+
+.. envvar:: SWEATSTACK_SCOPES
+
+   Comma-separated list of OAuth2 scopes.
+
+   Specify which permissions to request during OAuth2 authorization.
+
+   Default: ``data:read,profile``
+
+   Example::
+
+      export SWEATSTACK_SCOPES="data:read,data:write,profile"
+
+.. envvar:: SWEATSTACK_REDIRECT_URI
+
+   OAuth2 redirect URI.
+
+   The URI where users are redirected after OAuth2 authorization.
+   Must match a redirect URI registered in your OAuth2 application.
+
+   Example::
+
+      export SWEATSTACK_REDIRECT_URI="http://localhost:8501"
+
+Modules
+=======
+
+sweatstack
+----------
+
+.. automodule:: sweatstack
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sweatstack.client
+-----------------
+
+.. automodule:: sweatstack.client
+    :members:
+    :undoc-members:
+    :inherited-members:
+    :show-inheritance:
+    :exclude-members: _LocalCacheMixin, _TokenStorageMixin, _OAuth2Mixin, _DelegationMixin
+
+
+sweatstack.streamlit
+--------------------
+
+.. automodule:: sweatstack.streamlit
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sweatstack.schemas
+------------------
+
+.. automodule:: sweatstack.schemas
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Sport
+~~~~~
+
+.. autoclass:: sweatstack.schemas.Sport
+    :members: root_sport, parent_sport, is_sub_sport_of, is_root_sport, display_name
+    :undoc-members:
+
+Metric
+~~~~~~
+
+.. autoclass:: sweatstack.schemas.Metric
+    :members: display_name
+    :undoc-members:
+
+sweatstack.openapi_schemas
+--------------------------
+
+Core Data Models
+~~~~~~~~~~~~~~~~
+
+.. autoclass:: sweatstack.openapi_schemas.ActivitySummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.ActivityDetails
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.TraceDetails
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.Lap
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Activity Summaries
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: sweatstack.openapi_schemas.ActivitySummarySummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.PowerSummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.SpeedSummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.DistanceSummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.ElevationSummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.HeartRateSummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.TemperatureSummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.CoreTemperatureSummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.Smo2Summary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+User & Authentication
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: sweatstack.openapi_schemas.UserSummary
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.UserInfoResponse
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.TokenResponse
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sweatstack.openapi_schemas.BackfillStatus
+    :members:
+    :undoc-members:
+    :show-inheritance:

{sweatstack-0.54.0 → sweatstack-0.56.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sweatstack"
-version = "0.54.0"
+version = "0.56.0"
 description = "The official Python client for SweatStack"
 readme = "README.md"
 authors = [
@@ -33,6 +33,10 @@ build-backend = "hatchling.build"
 [dependency-groups]
 dev = [
     "datamodel-code-generator>=0.26.5",
+    "myst-parser>=4.0.1",
+    "sphinx>=8.2.3",
+    "sphinx-markdown-builder>=0.6.8",
+    "streamlit>=1.42.0",
 ]
 
 [tool.uv.workspace]

{sweatstack-0.54.0 → sweatstack-0.56.0}/src/sweatstack/client.py

@@ -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,30 +651,61 @@ 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,
         refresh_token: str | None = None,
         url: str | None = None,
         streamlit_compatible: bool = False,
+        client_id: str | None = None,
+        client_secret: str | None = None,
     ):
+        """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
         self.streamlit_compatible = streamlit_compatible
+        self.client_id = client_id or OAUTH2_CLIENT_ID
+        self.client_secret = client_secret
 
     def _do_token_refresh(self, tz: str) -> str:
-        with self._http_client() as client:
+        refresh_token = self.refresh_token
+        if refresh_token is None:
+            raise ValueError(
+                "Cannot refresh token: no refresh_token available. "
+                "If using Streamlit, ensure you're using StreamlitAuth which handles token refresh automatically."
+            )
+
+        with self._http_client(skip_token_check=True) as client:
             response = client.post(
                 "/api/v1/oauth/token",
-                json={
+                data={
                     "grant_type": "refresh_token",
-                    "refresh_token": self.refresh_token,
+                    "refresh_token": refresh_token,
                     "tz": tz,
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
                 },
             )
-
             self._raise_for_status(response)
             return response.json()["access_token"]
 
@@ -670,12 +713,13 @@ class Client(OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin):
         try:
             body = decode_jwt_body(token)
             # Margin in seconds to account for time to token validation of the next request
-            TOKEN_EXPIRY_MARGIN = 5
+            TOKEN_EXPIRY_MARGIN = 5  # 5 seconds. Meaning that if the token is within 5 seconds of expiring, it will be refreshed.
             if body["exp"] - TOKEN_EXPIRY_MARGIN < time.time():
                 # Token is (almost) expired, refresh it
                 token = self._do_token_refresh(body["tz"])
                 self._api_key = token
-        except Exception:
+        except Exception as exception:
+            logging.warning("Exception checking token expiry: %s", exception)
             # If token can't be decoded, just return as-is
             # @TODO: This probably should be handled differently
             pass
@@ -684,6 +728,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 +752,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"):
@@ -736,16 +789,27 @@ class Client(OAuth2Mixin, DelegationMixin, TokenStorageMixin, LocalCacheMixin):
         self._url = value
     
     @contextlib.contextmanager
-    def _http_client(self):
+    def _http_client(self, skip_token_check: bool = False):
         """
         Creates an httpx client with the base URL and authentication headers pre-configured.
+
+        Args:
+            skip_token_check: If True, uses the raw _api_key without triggering token expiry check.
+                              This prevents recursive token refresh attempts.
         """
         headers = {
             "User-Agent": f"python-sweatstack/{__version__}",
         }
-        if self.api_key:
-            headers["Authorization"] = f"Bearer {self.api_key}"
-        
+        if skip_token_check:
+            # Use raw token without triggering expiry check (used during refresh)
+            token = self._api_key
+        else:
+            # Normal path: may trigger token refresh
+            token = self.api_key
+
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+
         with httpx.Client(base_url=self.url, headers=headers, timeout=60) as client:
             yield client
 
@@ -1042,6 +1106,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 +1314,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 +1771,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 +1779,7 @@ _generate_singleton_methods(
 
         "get_longitudinal_data",
         "get_longitudinal_mean_max",
+        "get_longitudinal_awd",
 
         "get_traces",
         "create_trace",